From fd6603af5301c26acd90fc7a9ba6d35e81876bc3 Mon Sep 17 00:00:00 2001 From: xsl Date: Mon, 26 Jan 2026 14:42:22 +0800 Subject: [PATCH] =?UTF-8?q?[docs]=20=E6=B7=BB=E5=8A=A0=E5=89=8D=E7=AB=AF?= =?UTF-8?q?=E5=AF=B9=E6=8E=A5=E6=8C=87=E5=8D=97=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/FRONTEND_INTEGRATION_GUIDE.md | 408 +++++++++++++++++++++++++++++ 1 file changed, 408 insertions(+) create mode 100644 docs/FRONTEND_INTEGRATION_GUIDE.md diff --git a/docs/FRONTEND_INTEGRATION_GUIDE.md b/docs/FRONTEND_INTEGRATION_GUIDE.md new file mode 100644 index 00000000..fe4bda0b --- /dev/null +++ b/docs/FRONTEND_INTEGRATION_GUIDE.md @@ -0,0 +1,408 @@ +# 海洋项目管理系统 - 前端对接指南 + +## 后端部署状态 + +✅ **后端已成功启动** +- 运行地址: 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 + +**请求**: +```bash +POST /api/v1/auth/login +Content-Type: application/json + +{ + "username": "admin", + "password": "admin123" +} +``` + +**响应**: +```json +{ + "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 +``` + +### 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. 统一响应格式 + +### 成功响应 +```json +{ + "success": true, + "message": "操作成功", + "data": { ... }, + "error_code": null +} +``` + +### 失败响应 +```json +{ + "success": false, + "message": "错误描述", + "data": null, + "error_code": "错误码" +} +``` + +### 错误码列表 + +| 错误码 | 说明 | +|--------|------| +| 1001 | 参数验证失败 | +| 1002 | 用户名或密码错误 | +| 1003 | Token无效或过期 | +| 2001 | 资源不存在 | +| 2002 | 资源已存在 | +| 3001 | 权限不足 | + +## 7. 项目列表查询 + +### 7.1 基础查询 +```http +GET /api/v1/projects?page=1&page_size=10 +``` + +### 7.2 组合筛选（AND条件） +所有筛选条件必须同时满足： + +```http +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: 平均累计进度 + +**示例**: +```http +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`: 日期范围筛选 + +**示例**: +```http +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`: 日期范围 + +**示例**: +```http +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 +``` + +### 10.3 检查响应格式 +所有响应都遵循统一格式，先检查 `success` 字段： +```javascript +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 登录流程 +```javascript +// 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 项目筛选示例 +```javascript +// 查询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 统计查询示例 +```javascript +// 获取基建工程的基本统计 +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` + +**祝前端开发顺利！** + +加油！！！