409 lines
10 KiB
Markdown
409 lines
10 KiB
Markdown
# 海洋项目管理系统 - 前端对接指南
|
||
|
||
## 后端部署状态
|
||
|
||
✅ **后端已成功启动**
|
||
- 运行地址: http://0.0.0.0:8188
|
||
- API文档: http://0.0.0.0:8188/docs
|
||
- 测试状态: 34个通过，20个失败
|
||
|
||
## 快速开始
|
||
|
||
### 1. 后端服务
|
||
|
||
后端已启动并运行在 http://0.0.0.0:8188
|
||
|
||
### 2. API Base URL
|
||
|
||
```
|
||
http://localhost:8188/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:8188/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:8188/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:8188/api/v1/projects', {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
})
|
||
```
|
||
|
||
### 12.2 项目筛选示例
|
||
```javascript
|
||
// 查询2026年的基建项目，合同金额大于100万
|
||
const response = await fetch(
|
||
'http://localhost:8188/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:8188/api/v1/projects/statistics/basic?engineering_type=基建',
|
||
{
|
||
headers: { 'Authorization': `Bearer ${token}` }
|
||
}
|
||
)
|
||
|
||
// 按工程类别分组统计
|
||
const groupStats = await fetch(
|
||
'http://localhost:8188/api/v1/projects/statistics/group?group_by=engineering_type',
|
||
{
|
||
headers: { 'Authorization': `Bearer ${token}` }
|
||
}
|
||
)
|
||
|
||
// 按月份统计基建项目
|
||
const timelineStats = await fetch(
|
||
'http://localhost:8188/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:8188/docs
|
||
- 后端README: `backend/README.md`
|
||
- API文档: `docs/api.md`
|
||
|
||
**祝前端开发顺利！**
|
||
|
||
加油！！！
|