865 lines
18 KiB
Markdown
865 lines
18 KiB
Markdown
# 海洋项目管理系统 - 后端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 统一响应格式
|
||
|
||
#### 成功响应
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "操作成功",
|
||
"data": {},
|
||
"error_code": null
|
||
}
|
||
```
|
||
|
||
#### 错误响应
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "password123"
|
||
}
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
```
|
||
|
||
**错误示例**:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "用户名或密码错误",
|
||
"data": null,
|
||
"error_code": "1002"
|
||
}
|
||
```
|
||
|
||
### 2.2 获取当前用户信息
|
||
|
||
**接口**: `GET /auth/me`
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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>
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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 | 否 | 关键词搜索（用户名、真实姓名、邮箱） |
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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>
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"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 | 否 | 电话 |
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"real_name": "张三三",
|
||
"email": "zhangsan_new@example.com",
|
||
"phone": "13900139001",
|
||
"is_active": false
|
||
}
|
||
```
|
||
|
||
**字段说明**: 所有字段都是可选的，至少提供一个字段
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "用户删除成功",
|
||
"data": null,
|
||
"error_code": null
|
||
}
|
||
```
|
||
|
||
### 3.6 重置用户密码
|
||
|
||
**接口**: `POST /users/{id}/reset-password`
|
||
|
||
**权限**: 仅管理员 (admin)
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**路径参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 用户ID |
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"new_password": "newpassword123"
|
||
}
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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关系，必须同时满足。
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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>
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"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: 合同金额
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"name": "更新后的项目名称",
|
||
"contract_amount": 600.00,
|
||
"actual_receipt_amount": 300.00,
|
||
"actual_payment_amount": 250.00,
|
||
"cumulative_progress": 50.00,
|
||
"remarks": "更新备注"
|
||
}
|
||
```
|
||
|
||
**字段说明**: 所有字段都是可选的，至少提供一个字段
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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组合筛选
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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 | 否 | 签订日期结束 |
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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 | 否 | 结束日期 |
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"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`
|