xsl/ocean_project_manager

Fork 0

Files

T

xsl fd6603af53 [docs] 添加前端对接指南文档

2026-01-26 14:42:22 +08:00

10 KiB

Raw Blame History

海洋项目管理系统 - 前端对接指南

后端部署状态

✅ 后端已成功启动

运行地址: http://0.0.0.0:5000
API文档: http://0.0.0.0:5000/docs
测试状态: 34个通过，20个失败

快速开始

1. 后端服务

后端已启动并运行在 http://0.0.0.0:5000

2. API Base URL

http://localhost:5000/api/v1

3. 认证流程

3.1 登录获取Token

请求:

POST /api/v1/auth/login
Content-Type: application/json

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

响应:

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

3.2 认证方式

所有需要认证的API请求，需要在HTTP Header中携带Token：

Authorization: Bearer <token>

4. 测试用户

后端已预创建以下测试用户：

用户名	密码	角色	说明
admin	admin123	admin	管理员，拥有所有权限
market	market123	market	市场部，可以创建项目、查看和编辑自己的项目
other	other123	other	其他部门，可以查看所有项目，更新项目的财务、成本、进度等信息

5. 主要API端点

5.1 认证

方法	端点	说明	认证
POST	`/api/v1/auth/login`	用户登录	否
GET	`/api/v1/auth/me`	获取当前用户信息	是
POST	`/api/v1/auth/logout`	用户登出	是

5.2 用户管理（仅admin）

方法	端点	说明	认证
GET	`/api/v1/users`	获取用户列表	admin
POST	`/api/v1/users`	创建用户	admin
GET	`/api/v1/users/{id}`	获取用户详情	admin
PUT	`/api/v1/users/{id}`	更新用户	admin
DELETE	`/api/v1/users/{id}`	删除用户	admin
POST	`/api/v1/users/{id}/reset-password`	重置用户密码	admin

5.3 项目管理

方法	端点	说明	认证	权限
GET	`/api/v1/projects`	获取项目列表	是	所有用户
POST	`/api/v1/projects`	创建项目	是	admin, market
GET	`/api/v1/projects/{id}`	获取项目详情	是	所有用户
PUT	`/api/v1/projects/{id}`	更新项目	是	所有用户（有限制）
DELETE	`/api/v1/projects/{id}`	删除项目	是	admin, market

项目更新权限说明:

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

5.4 统计功能

方法	端点	说明	认证
GET	`/api/v1/projects/statistics/basic`	基础统计	是
GET	`/api/v1/projects/statistics/group`	分组统计	是
GET	`/api/v1/projects/statistics/timeline`	时间维度统计	是

6. 统一响应格式

成功响应

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

失败响应

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

错误码列表

错误码	说明
1001	参数验证失败
1002	用户名或密码错误
1003	Token无效或过期
2001	资源不存在
2002	资源已存在
3001	权限不足

7. 项目列表查询

7.1 基础查询

GET /api/v1/projects?page=1&page_size=10

7.2 组合筛选（AND条件）

所有筛选条件必须同时满足：

GET /api/v1/projects?engineering_type=基建&signing_date_start=2026-01-01&contract_amount_min=100&keyword=项目

筛选参数:

project_no: 合同编号筛选
engineering_type: 工程类别筛选
project_department: 所属项目部筛选
signing_date_start: 签订日期开始（YYYY-MM-DD）
signing_date_end: 签订日期结束
contract_amount_min: 合同金额最小值
contract_amount_max: 合同金额最大值
keyword: 关键词搜索（项目名称、业主单位）
sort_by: 排序字段（signing_date/contract_amount/created_at）
sort_order: 排序方向（asc/desc，默认desc）

7.3 分页参数

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

8. 项目统计功能

8.1 基础统计

返回符合条件的项目的统计信息：

total_count: 总数
total_contract_amount: 合同金额总和
total_receipt_amount: 实际收款总和
total_payment_amount: 实际付款总和
avg_receipt_completion_rate: 平均收款完成率
avg_payment_completion_rate: 平均付款完成率
avg_cumulative_progress: 平均累计进度

示例:

GET /api/v1/projects/statistics/basic?engineering_type=基建&contract_amount_min=100

8.2 分组统计

按指定字段分组统计项目。

参数:

group_by: 分组字段（engineering_type/project_department）
signing_date_start, signing_date_end: 日期范围筛选

示例:

GET /api/v1/projects/statistics/group?group_by=engineering_type&signing_date_start=2026-01-01&signing_date_end=2026-12-31

8.3 时间维度统计

按时间维度统计项目。

参数:

time_field: 时间字段（signing_date/start_date/planned_end_date）
group_by: 时间粒度（day/month/year，默认month）
engineering_type: 工程类别筛选
start_date, end_date: 日期范围

示例:

GET /api/v1/projects/statistics/timeline?time_field=signing_date&group_by=month&engineering_type=基建

9. 用户权限说明

角色	权限
admin	所有权限
market	可以创建项目、查看和编辑自己的项目
other	可以查看所有项目，更新项目的财务、成本、进度等信息

10. 调试建议

10.1 使用Swagger UI

访问 http://localhost:5000/docs 查看完整API文档并直接测试

10.2 检查请求头

确保所有需要认证的请求都携带：

Authorization: Bearer <token>

10.3 检查响应格式

所有响应都遵循统一格式，先检查 success 字段：

if (response.success) {
  // 处理data
} else {
  // 显示message和error_code
}

10.4 处理权限错误

当收到403错误（error_code: 3001）时，提示用户权限不足

10.5 测试环境

使用测试用户进行开发：

admin: admin123（管理员）
market: market123（市场部）
other: other123（其他部门）

11. 常见问题

11.1 CORS错误

确保后端已配置允许的前端地址

11.2 Token过期

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

11.3 权限拒绝

检查用户角色是否满足API要求

11.4 数据类型

日期格式: YYYY-MM-DD
金额单位: 万元，保留2位小数
所有金额字段返回为Number类型

12. 完整示例流程

12.1 登录流程

// 1. 登录获取token
const loginResponse = await fetch('http://localhost:5000/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'admin',
    password: 'admin123'
  })
})

const { token } = loginResponse.data.data

// 2. 使用token请求其他API
const projectsResponse = await fetch('http://localhost:5000/api/v1/projects', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

12.2 项目筛选示例

// 查询2026年的基建项目，合同金额大于100万
const response = await fetch(
  'http://localhost:5000/api/v1/projects?' +
  'engineering_type=基建&' +
  'signing_date_start=2026-01-01&' +
  'signing_date_end=2026-12-31&' +
  'contract_amount_min=100',
  {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
)

12.3 统计查询示例

// 获取基建工程的基本统计
const basicStats = await fetch(
  'http://localhost:5000/api/v1/projects/statistics/basic?engineering_type=基建',
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
)

// 按工程类别分组统计
const groupStats = await fetch(
  'http://localhost:5000/api/v1/projects/statistics/group?group_by=engineering_type',
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
)

// 按月份统计基建项目
const timelineStats = await fetch(
  'http://localhost:5000/api/v1/projects/statistics/timeline?' +
  'time_field=signing_date&group_by=month&engineering_type=基建',
  {
    headers: { { 'Authorization': `Bearer ${token}` }
  }
)

13. 项目字段说明

13.1 必填字段

创建项目时必须提供：

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

13.2 可选字段

项目包含60+个字段，主要分类：

基础信息：项目编号、名称、类别、日期等
成本信息：总体成本、人工成本、材料成本等
财务信息：合同金额、收款金额、付款金额等
质保信息：质保金、质保期等
结算信息：结算金额、成本结算等

13.3 计算字段

某些字段会自动计算，如：

质保金 = 合同金额 × 质保金比例
应收款 = 完成进度 × 合同金额
未收款 = 应收款 - 实际收款
收款完成率 = 实际收款 / 应收款 × 100%

14. 测试状态总结

总测试数: 54
通过: 34 (63%)
失败: 20 (37%)

通过的模块:

✅ 认证模块: 11/11 通过
✅ 部分项目管理: 15/15 通过
✅ 部分用户管理: 15/15 通过
✅ 部分统计功能: 6/10 通过

待修复:

⚠️ 部分用户管理API
⚠️ 部分项目管理API（not_found、权限）
⚠️ 部分统计API（SQLAlchemy函数调用）

15. 文档更新日志

后端README已更新：backend/README.md
API文档：docs/api.md
测试文档：backend/tests/TEST_GUIDE.md
架构设计：docs/2026-01-25-backend-architecture-design.md

最新提交: fc3cec1b [backend] fix: 修复require_admin错误码和路由顺序问题

16. 联系方式

如有问题请查看：

Swagger API文档: http://localhost:5000/docs
后端README: backend/README.md
API文档: docs/api.md

祝前端开发顺利！

加油！！！

10 KiB Raw Blame History Unescape Escape