xsl/ocean_project_manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
xsl
2026-01-26 14:42:22 +08:00
parent fc3cec1b1e
commit fd6603af53
1 changed files with 408 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/FRONTEND_INTEGRATION_GUIDE.md
+408
View File
@@ -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 <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. 统一响应格式
### 成功响应
```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 <token>
```
### 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`
**祝前端开发顺利！**
加油！！！