xsl/ocean_project_manager

Fork 0

Files

T

xsl 0895398138 save code

2026-01-25 15:05:03 +08:00

18 KiB

Raw Blame History

海洋项目管理系统 - 后端API文档

1. API基础信息

1.1 基础规范

Base URL: http://localhost:5000/api/v1
Content-Type: application/json
认证方式: JWT Token
- Header: Authorization: Bearer <token>
API文档地址: http://localhost:5000/docs (Swagger UI)

1.2 统一响应格式

成功响应

{
  "success": true,
  "message": "操作成功",
  "data": {},
  "error_code": null
}

错误响应

{
  "success": false,
  "message": "错误描述",
  "data": null,
  "error_code": "错误码"
}

1.3 错误码列表

错误码	说明	HTTP状态码
1001	参数验证失败	400
1002	用户名或密码错误	401
1003	Token无效或过期	401
2001	资源不存在	404
2002	资源已存在	409
3001	权限不足	403
5000	服务器内部错误	500

1.4 分页参数

所有列表接口都支持分页：

page: 页码，默认1
page_size: 每页数量，默认10，最大100

2. 认证相关API

2.1 用户登录

接口: POST /auth/login

请求体:

{
  "username": "admin",
  "password": "password123"
}

响应:

{
  "success": true,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "user": {
      "id": 1,
      "username": "admin",
      "real_name": "系统管理员",
      "department": "管理部",
      "role": "admin",
      "email": "admin@example.com"
    }
  },
  "error_code": null
}

错误示例:

{
  "success": false,
  "message": "用户名或密码错误",
  "data": null,
  "error_code": "1002"
}

2.2 获取当前用户信息

接口: GET /auth/me

请求头:

Authorization: Bearer <token>

响应:

{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "real_name": "系统管理员",
    "department": "管理部",
    "role": "admin",
    "email": "admin@example.com",
    "phone": "13800000000",
    "is_active": true
  },
  "error_code": null
}

2.3 登出

接口: POST /auth/logout

请求头:

Authorization: Bearer <token>

响应:

{
  "success": true,
  "message": "登出成功",
  "data": null,
  "error_code": null
}

3. 用户管理API

3.1 获取用户列表

接口: GET /users

权限: 仅管理员 (admin)

请求头:

Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认10
department	string	否	部门筛选
role	string	否	角色筛选
keyword	string	否	关键词搜索（用户名、真实姓名、邮箱）

响应:

{
  "success": true,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "username": "admin",
        "real_name": "系统管理员",
        "department": "管理部",
        "role": "admin",
        "email": "admin@example.com",
        "phone": "13800000000",
        "is_active": true,
        "created_at": "2026-01-25T10:00:00",
        "updated_at": "2026-01-25T10:00:00"
      },
      {
        "id": 2,
        "username": "zhangsan",
        "real_name": "张三",
        "department": "市场部",
        "role": "market",
        "email": "zhangsan@example.com",
        "phone": "13900139000",
        "is_active": true,
        "created_at": "2026-01-25T11:00:00",
        "updated_at": "2026-01-25T11:00:00"
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 10
  },
  "error_code": null
}

3.2 创建用户

接口: POST /users

权限: 仅管理员 (admin)

请求头:

Authorization: Bearer <token>

请求体:

{
  "username": "lisi",
  "password": "password123",
  "real_name": "李四",
  "department": "技术部",
  "role": "other",
  "email": "lisi@example.com",
  "phone": "13700137000"
}

字段说明:

字段	类型	必填	说明
username	string	是	用户名，唯一
password	string	是	密码，最少6位
real_name	string	是	真实姓名
department	string	是	部门
role	string	是	角色：admin/market/other
email	string	否	邮箱，唯一
phone	string	否	电话

响应:

{
  "success": true,
  "message": "用户创建成功",
  "data": {
    "id": 3,
    "username": "lisi",
    "real_name": "李四",
    "department": "技术部",
    "role": "other"
  },
  "error_code": null
}

3.3 获取用户详情

接口: GET /users/{id}

权限: 仅管理员 (admin)

请求头:

Authorization: Bearer <token>

路径参数:

参数	类型	说明
id	int	用户ID

响应:

{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 2,
    "username": "zhangsan",
    "real_name": "张三",
    "department": "市场部",
    "role": "market",
    "email": "zhangsan@example.com",
    "phone": "13900139000",
    "is_active": true,
    "created_at": "2026-01-25T11:00:00",
    "updated_at": "2026-01-25T11:00:00"
  },
  "error_code": null
}

3.4 更新用户

接口: PUT /users/{id}

权限: 仅管理员 (admin)

请求头:

Authorization: Bearer <token>

路径参数:

参数	类型	说明
id	int	用户ID

请求体:

{
  "real_name": "张三三",
  "email": "zhangsan_new@example.com",
  "phone": "13900139001",
  "is_active": false
}

字段说明: 所有字段都是可选的，至少提供一个字段

响应:

{
  "success": true,
  "message": "用户更新成功",
  "data": {
    "id": 2,
    "username": "zhangsan",
    "real_name": "张三三",
    "department": "市场部",
    "role": "market",
    "email": "zhangsan_new@example.com",
    "phone": "13900139001",
    "is_active": false
  },
  "error_code": null
}

3.5 删除用户

接口: DELETE /users/{id}

权限: 仅管理员 (admin)

请求头:

Authorization: Bearer <token>

路径参数:

参数	类型	说明
id	int	用户ID

响应:

{
  "success": true,
  "message": "用户删除成功",
  "data": null,
  "error_code": null
}

3.6 重置用户密码

接口: POST /users/{id}/reset-password

权限: 仅管理员 (admin)

请求头:

Authorization: Bearer <token>

路径参数:

参数	类型	说明
id	int	用户ID

请求体:

{
  "new_password": "newpassword123"
}

响应:

{
  "success": true,
  "message": "密码重置成功",
  "data": null,
  "error_code": null
}

4. 项目管理API

4.1 获取项目列表

接口: GET /projects

权限: 所有用户

请求头:

Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认10，最大100
project_no	string	否	合同编号筛选
engineering_type	string	否	工程类别筛选
project_department	string	否	所属项目部筛选
signing_date_start	string	否	签订日期开始（YYYY-MM-DD）
signing_date_end	string	否	签订日期结束（YYYY-MM-DD）
contract_amount_min	decimal	否	合同金额最小值（万元）
contract_amount_max	decimal	否	合同金额最大值（万元）
keyword	string	否	关键词搜索（项目名称、业主单位）
sort_by	string	否	排序字段：signing_date/contract_amount/created_at
sort_order	string	否	排序方向：asc/desc，默认desc

注意：所有筛选条件都是AND关系，必须同时满足。

响应:

{
  "success": true,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "project_no": "PRJ2026001",
        "power_contract_no": "GD2026001",
        "name": "某电力基建工程项目",
        "subitem_count": 5,
        "subitem_code": "SUB001",
        "total_investment": 1000.00,
        "contract_amount": 950.00,
        "warranty_ratio": 5.00,
        "settlement_amount": null,
        "total_cost_estimated": 800.00,
        "voltage_level": "110kV",
        "engineering_type": "基建",
        "owner_unit": "XX电力公司",
        "owner_contact": "张三 13800000001",
        "bidding_type": "公开招标",
        "signing_date": "2026-01-01",
        "start_date": "2026-01-15",
        "planned_end_date": "2026-12-31",
        "actual_end_date": null,
        "warranty_amount": 47.50,
        "warranty_expiry_date": "2028-12-31",
        "actual_warranty_refund_date": null,
        "project_department": "项目部一",
        "project_leader": "李四 13900000001",
        "payment_method": "按进度付款",
        "total_cost_control": 800.00,
        "is_adjusted": "否",
        "labor_cost_control": 300.00,
        "labor_cost_planned": 280.00,
        "labor_cost_paid": 200.00,
        "material_cost_control": 400.00,
        "material_cost_payable": 320.00,
        "material_cost_actual": 310.00,
        "material_cost_paid": 280.00,
        "other_cost_control": 100.00,
        "other_cost_payable": 80.00,
        "other_cost_actual": 75.00,
        "tax_amount": 95.00,
        "profit": 55.00,
        "actual_profit": null,
        "cost_settlement_amount": null,
        "cumulative_progress": 60.00,
        "receivable_amount": 570.00,
        "invoice_amount": 570.00,
        "actual_receipt_amount": 475.00,
        "receipt_completion_rate": 50.00,
        "payable_amount": 480.00,
        "actual_payment_amount": 390.00,
        "unpaid_amount": 95.00,
        "payment_completion_rate": 81.25,
        "labor_debt_amount": 80.00,
        "settlement_cost_amount": null,
        "settlement_labor_cost": null,
        "settlement_material_cost": null,
        "settlement_other_cost": null,
        "due_settlement_count": 0,
        "unsettlement_count": 0,
        "problems": null,
        "suggestions": null,
        "remarks": "备注信息",
        "created_by": 2,
        "created_by_name": "张三",
        "created_at": "2026-01-25T10:00:00",
        "updated_at": "2026-01-25T12:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  },
  "error_code": null
}

4.2 获取项目详情

接口: GET /projects/{id}

权限: 所有用户

请求头:

Authorization: Bearer <token>

路径参数:

参数	类型	说明
id	int	项目ID

响应:

{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "project_no": "PRJ2026001",
    "name": "某电力基建工程项目",
    "engineering_type": "基建",
    "contract_amount": 950.00,
    "created_by": 2,
    "created_by_name": "张三",
    "created_at": "2026-01-25T10:00:00",
    "updated_at": "2026-01-25T12:00:00"
    // ... 完整项目信息（60+字段）
  },
  "error_code": null
}

4.3 创建项目

接口: POST /projects

权限: admin, market

请求头:

Authorization: Bearer <token>

请求体:

{
  "project_no": "PRJ2026002",
  "power_contract_no": "GD2026002",
  "name": "新电力工程项目",
  "engineering_type": "业扩",
  "owner_unit": "XX供电局",
  "contract_amount": 500.00,
  "signing_date": "2026-01-25",
  "start_date": "2026-02-01",
  "planned_end_date": "2026-12-31",
  "project_department": "项目部二",
  "project_leader": "王五 13800000002",
  "payment_method": "按进度付款",
  "total_cost_control": 400.00,
  "labor_cost_control": 150.00,
  "material_cost_control": 200.00,
  "other_cost_control": 50.00
}

必填字段:

project_no: 合同编号（唯一）
name: 项目名称
engineering_type: 工程类别
contract_amount: 合同金额

响应:

{
  "success": true,
  "message": "项目创建成功",
  "data": {
    "id": 2,
    "project_no": "PRJ2026002",
    "name": "新电力工程项目",
    "engineering_type": "业扩"
  },
  "error_code": null
}

4.4 更新项目

接口: PUT /projects/{id}

权限: 所有用户

admin: 可更新所有字段
market: 只能更新自己创建的项目
other: 可更新项目的财务、成本、进度等信息（不能修改基础信息）

请求头:

Authorization: Bearer <token>

路径参数:

参数	类型	说明
id	int	项目ID

请求体:

{
  "name": "更新后的项目名称",
  "contract_amount": 600.00,
  "actual_receipt_amount": 300.00,
  "actual_payment_amount": 250.00,
  "cumulative_progress": 50.00,
  "remarks": "更新备注"
}

字段说明: 所有字段都是可选的，至少提供一个字段

响应:

{
  "success": true,
  "message": "项目更新成功",
  "data": {
    "id": 1,
    "project_no": "PRJ2026001",
    "name": "更新后的项目名称"
  },
  "error_code": null
}

4.5 删除项目

接口: DELETE /projects/{id}

权限: admin, market

admin: 可删除所有项目
market: 只能删除自己创建的项目

请求头:

Authorization: Bearer <token>

路径参数:

参数	类型	说明
id	int	项目ID

响应:

{
  "success": true,
  "message": "项目删除成功",
  "data": null,
  "error_code": null
}

4.6 项目统计API

4.6.1 基础统计

接口: GET /projects/statistics

权限: 所有用户

请求头:

Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
engineering_type	string	否	工程类别筛选
signing_date_start	string	否	签订日期开始
signing_date_end	string	否	签订日期结束
contract_amount_min	decimal	否	合同金额最小值
contract_amount_max	decimal	否	合同金额最大值

说明: 筛选参数与列表查询相同，支持AND组合筛选

响应:

{
  "success": true,
  "message": "统计成功",
  "data": {
    "total_count": 100,
    "total_investment": 50000.00,
    "total_contract_amount": 48000.00,
    "total_settlement_amount": 45000.00,
    "total_receipt_amount": 42000.00,
    "total_payment_amount": 40000.00,
    "avg_receipt_completion_rate": 87.50,
    "avg_payment_completion_rate": 83.33,
    "avg_cumulative_progress": 75.00
  },
  "error_code": null
}

4.6.2 分组统计

接口: GET /projects/statistics/group

权限: 所有用户

请求头:

Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
group_by	string	是	分组字段：engineering_type/project_department
signing_date_start	string	否	签订日期开始
signing_date_end	string	否	签订日期结束

响应:

{
  "success": true,
  "message": "统计成功",
  "data": [
    {
      "engineering_type": "基建",
      "count": 50,
      "total_contract_amount": 30000.00,
      "total_receipt_amount": 28000.00,
      "total_payment_amount": 26000.00
    },
    {
      "engineering_type": "业扩",
      "count": 30,
      "total_contract_amount": 12000.00,
      "total_receipt_amount": 10000.00,
      "total_payment_amount": 9500.00
    },
    {
      "engineering_type": "客户",
      "count": 20,
      "total_contract_amount": 6000.00,
      "total_receipt_amount": 4000.00,
      "total_payment_amount": 4500.00
    }
  ],
  "error_code": null
}

4.6.3 时间维度统计

接口: GET /projects/statistics/timeline

权限: 所有用户

请求头:

Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
time_field	string	是	时间字段：signing_date/start_date/planned_end_date
group_by	string	否	时间粒度：day/month/year，默认month
engineering_type	string	否	工程类别筛选
start_date	string	否	开始日期
end_date	string	否	结束日期

响应:

{
  "success": true,
  "message": "统计成功",
  "data": [
    {
      "month": "2026-01",
      "count": 20,
      "total_contract_amount": 8000.00
    },
    {
      "month": "2026-02",
      "count": 15,
      "total_contract_amount": 6000.00
    },
    {
      "month": "2026-03",
      "count": 25,
      "total_contract_amount": 10000.00
    }
  ],
  "error_code": null
}

5. 数据模型说明

5.1 用户角色 (role)

admin: 管理员，拥有所有权限
market: 市场部，可以创建项目、查看和编辑自己的项目
other: 其他部门，可以查看所有项目，更新项目的财务、成本、进度等信息

5.2 工程类别 (engineering_type)

基建: 基建工程
业扩: 业扩工程
客户: 客户工程
营销: 营销工程
检修: 检修、技改、应急抢修项目

5.3 项目字段说明

项目表包含60+个字段，分为以下几类：

基础信息: project_no, name, engineering_type, signing_date等
成本信息: total_cost_control, labor_cost_control, material_cost_control等
财务信息: contract_amount, actual_receipt_amount, actual_payment_amount等
质保信息: warranty_amount, warranty_expiry_date等
结算信息: settlement_amount, cost_settlement_amount等

注意：项目不使用status字段，数据本身反映了项目的真实状态。

6. 常见问题

6.1 Token过期怎么办？

Token有效期24小时，过期后需要重新登录获取新Token。

6.2 如何处理筛选结果过多？

建议使用分页参数page和page_size，每页最多返回100条记录。

6.3 日期格式是什么？

所有日期字段使用YYYY-MM-DD格式，例如：2026-01-25

6.4 金额单位是什么？

所有金额字段单位为万元，保留两位小数。

6.5 如何获取完整的API文档？

访问http://localhost:5000/docs查看Swagger UI自动生成的API文档。

文档维护: 后端程序员 更新时间: 2026-01-25 API文档地址: http://localhost:5000/docs

18 KiB Raw Blame History Unescape Escape

海洋项目管理系统 - 后端API文档

1. API基础信息

1.1 基础规范

1.2 统一响应格式

成功响应

错误响应

1.3 错误码列表

1.4 分页参数

2. 认证相关API

2.1 用户登录

2.2 获取当前用户信息

2.3 登出

3. 用户管理API

3.1 获取用户列表

3.2 创建用户

3.3 获取用户详情

3.4 更新用户

3.5 删除用户

3.6 重置用户密码

4. 项目管理API

4.1 获取项目列表

4.2 获取项目详情

4.3 创建项目

4.4 更新项目

4.5 删除项目

4.6 项目统计API

4.6.1 基础统计

4.6.2 分组统计

4.6.3 时间维度统计

5. 数据模型说明

5.1 用户角色 (role)

5.2 工程类别 (engineering_type)

5.3 项目字段说明

6. 常见问题

6.1 Token过期怎么办？

6.2 如何处理筛选结果过多？

6.3 日期格式是什么？

6.4 金额单位是什么？

6.5 如何获取完整的API文档？

18 KiB

Raw Blame History