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

save code

Browse Source
This commit is contained in:
xsl
2026-01-25 15:05:03 +08:00
parent 29565e9dfe
commit 0895398138
23 changed files with 11859 additions and 966 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api.md
+864
View File
@@ -0,0 +1,864 @@
# 海洋项目管理系统 - 后端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`