409 lines
15 KiB
Markdown
409 lines
15 KiB
Markdown
# 项目管理系统 API 文档
|
||
|
||
**依据**：《产品文档》《交互文档》《初始需求》
|
||
**读者**：后端/前端工程师
|
||
**版本**：v1
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
- **基础路径**：`/api`（按实际部署约定）
|
||
- **请求方式**：**全部采用 POST**
|
||
- **认证方式**：登录后使用 Token（如 Bearer Token 或 Session），请求头携带，具体与现有账号体系对齐
|
||
- **数据格式**：请求体与响应体均为 JSON，编码 UTF-8，Content-Type: application/json
|
||
- **角色**：管理员、市场部、工程部、技经部、财务部、物贸部；新建项目仅市场部可调，查看/修改所有角色可调
|
||
|
||
---
|
||
|
||
## 2. 认证
|
||
|
||
### 2.1 登录
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /api/auth/login` |
|
||
| **说明** | 用户登录，成功返回 Token 及用户信息（含角色） |
|
||
| **权限** | 无需登录 |
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| username | string | 是 | 账号 |
|
||
| password | string | 是 | 密码 |
|
||
|
||
#### 响应参数（成功，HTTP 200）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| token | string | 登录凭证，后续请求需携带 |
|
||
| user | object | 当前用户信息 |
|
||
| user.id | string | 用户 ID |
|
||
| user.username | string | 账号 |
|
||
| user.role | string | 角色：管理员 / 市场部 / 工程部 / 技经部 / 财务部 / 物贸部 |
|
||
| user.displayName | string | 显示名称 |
|
||
|
||
#### 响应参数（失败，HTTP 401）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | 错误码，401 |
|
||
| message | string | 错误信息，如「账号或密码错误」 |
|
||
|
||
---
|
||
|
||
## 3. 项目列表
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /api/projects/list` |
|
||
| **说明** | 分页获取项目列表，支持按名称/合同编号搜索、按进度/费用/合同金额筛选、时间筛选、日期异常筛选 |
|
||
| **权限** | 已登录，所有角色可访问 |
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | number | 否 | 页码，从 1 开始，默认 1 |
|
||
| pageSize | number | 否 | 每页条数，默认 50 |
|
||
| searchType | string | 否 | 搜索维度：`name`（项目名称）、`code`（合同编号） |
|
||
| keyword | string | 否 | 搜索关键词，与 searchType 配合使用 |
|
||
| progress | string | 否 | 项目进度筛选，取值与业务枚举一致 |
|
||
| cost | string | 否 | 项目费用筛选，取值与业务枚举一致 |
|
||
| dateFilterType | string | 否 | 时间筛选维度：`signDate`（签订日期）、`startDate`（开工日期）、`plannedCompletionDate`（计划竣工日期）、`actualCompletionDate`（实际竣工日期）；仅对「日期正常」项目按 DATE 筛选 |
|
||
| dateFrom | string | 否 | 时间范围起（YYYY-MM-DD），与 dateFilterType 配合 |
|
||
| dateTo | string | 否 | 时间范围止（YYYY-MM-DD），与 dateFilterType 配合 |
|
||
| dateAbnormal | boolean | 否 | 为 true 时只返回「日期异常」项目（四个日期中任意一个非「日期正常」） |
|
||
| amountMin | number | 否 | 合同金额（万元）下限，按中标合同金额筛选 |
|
||
| amountMax | number | 否 | 合同金额（万元）上限，按中标合同金额筛选 |
|
||
|
||
#### 响应参数（成功，HTTP 200）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| list | array | 项目列表，无数据时为空数组 |
|
||
| list[].id | string | 项目 ID |
|
||
| list[].projectName | string | 项目名称 |
|
||
| list[].contractCode | string | 合同编号 |
|
||
| list[].progress | string | 项目进度 |
|
||
| list[].cost | string | 项目费用 |
|
||
| list[].updatedAt | string | 最后更新时间，ISO8601 |
|
||
| list[].bidContractAmount | string | 中标合同金额（万元） |
|
||
| list[].ownerUnit | string | 业主单位 |
|
||
| list[].signDate | string | 签订日期（原文或 YYYY-MM-DD） |
|
||
| list[].projectDepartment | string | 所属项目部 |
|
||
| list[].totalCost | string | 总体成本 |
|
||
| list[].projectLeaderContact | string | 项目负责人及电话 |
|
||
| total | number | 总条数，无数据时为 0 |
|
||
| page | number | 当前页码 |
|
||
| pageSize | number | 每页条数 |
|
||
|
||
---
|
||
|
||
## 4. 项目详情
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /api/projects/detail` |
|
||
| **说明** | 获取单个项目完整信息（5 个分类） |
|
||
| **权限** | 已登录，所有角色可访问 |
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | string | 是 | 项目 ID |
|
||
|
||
#### 响应参数（成功，HTTP 200）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | string | 项目 ID |
|
||
| contract | object | 合同信息，字段见第 8.1 节 |
|
||
| costControl | object | 成本控制，字段见第 8.2 节 |
|
||
| receivable | object | 应收款，字段见第 8.3 节 |
|
||
| payable | object | 应付款，字段见第 8.4 节 |
|
||
| other | object | 其他，字段见第 8.5 节 |
|
||
| createdAt | string | 创建时间，ISO8601 |
|
||
| updatedAt | string | 更新时间，ISO8601 |
|
||
|
||
#### 响应参数（失败，HTTP 404）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | 错误码，404 |
|
||
| message | string | 错误信息，如「项目不存在」 |
|
||
|
||
---
|
||
|
||
## 5. 新建项目
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /api/projects/create` |
|
||
| **说明** | 新建项目，仅市场部可调用 |
|
||
| **权限** | 已登录，角色为市场部；非市场部返回 403 |
|
||
|
||
#### 请求参数
|
||
|
||
请求体为项目 5 个分类的完整或部分数据，未传字段由后端赋默认值。结构见第 8 节「项目信息字段（5 个分类）」；**新建时合同编号、项目名称为必填项**。
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| contract | object | 是 | 合同信息，字段见 8.1；其中 contractCode、projectName 必填 |
|
||
| contract.contractCode | string | 是 | 合同编号 |
|
||
| contract.projectName | string | 是 | 项目名称 |
|
||
| costControl | object | 否 | 成本控制，字段见 8.2 |
|
||
| receivable | object | 否 | 应收款，字段见 8.3 |
|
||
| payable | object | 否 | 应付款，字段见 8.4 |
|
||
| other | object | 否 | 其他，字段见 8.5 |
|
||
|
||
#### 响应参数（成功，HTTP 201）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | string | 新创建的项目 ID |
|
||
| message | string | 固定为「创建成功」 |
|
||
|
||
#### 响应参数（失败，HTTP 400）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | 错误码，400 |
|
||
| message | string | 错误信息，如「合同编号不能为空」「项目名称不能为空」 |
|
||
| errors | array | 可选，见第 10 节 |
|
||
|
||
#### 响应参数（失败，HTTP 403）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | 错误码，403 |
|
||
| message | string | 错误信息，如「无权限」 |
|
||
|
||
---
|
||
|
||
## 6. 更新项目
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /api/projects/update` |
|
||
| **说明** | 更新项目全部或部分信息；每次保存由后端记录一条操作日志 |
|
||
| **权限** | 已登录，所有角色可访问 |
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | string | 是 | 项目 ID |
|
||
| contract | object | 否 | 合同信息，传则按约定全量/合并更新，字段见 8.1 |
|
||
| costControl | object | 否 | 成本控制，字段见 8.2 |
|
||
| receivable | object | 否 | 应收款，字段见 8.3 |
|
||
| payable | object | 否 | 应付款，字段见 8.4 |
|
||
| other | object | 否 | 其他，字段见 8.5 |
|
||
|
||
#### 响应参数（成功，HTTP 200）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | string | 项目 ID |
|
||
| message | string | 固定为「保存成功」 |
|
||
|
||
#### 响应参数（失败）
|
||
|
||
| HTTP 状态 | 参数名 | 类型 | 说明 |
|
||
|-----------|--------|------|------|
|
||
| 404 | code | number | 错误码，404 |
|
||
| 404 | message | string | 如「项目不存在」 |
|
||
|
||
---
|
||
|
||
## 7. 操作日志
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /api/projects/logs` |
|
||
| **说明** | 获取某项目的修改记录（操作人、时间、修改摘要） |
|
||
| **权限** | 已登录，所有角色可访问 |
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | string | 是 | 项目 ID |
|
||
| page | number | 否 | 页码，从 1 开始，默认 1 |
|
||
| pageSize | number | 否 | 每页条数，默认 20 |
|
||
|
||
#### 响应参数（成功，HTTP 200）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| list | array | 操作日志列表，无记录时为空数组 |
|
||
| list[].id | string | 日志 ID |
|
||
| list[].operatorId | string | 操作人 ID |
|
||
| list[].operatorName | string | 操作人姓名 |
|
||
| list[].operatedAt | string | 操作时间，ISO8601 |
|
||
| list[].summary | string | 修改摘要，如「合同信息」「成本控制」 |
|
||
| list[].detail | string | 可选，修改内容详情 |
|
||
| total | number | 总条数，无记录时为 0 |
|
||
| page | number | 当前页码 |
|
||
| pageSize | number | 每页条数 |
|
||
|
||
#### 响应参数（失败，HTTP 404）
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | 错误码，404 |
|
||
| message | string | 如「项目不存在」 |
|
||
|
||
---
|
||
|
||
## 8. 项目信息字段（5 个分类）
|
||
|
||
以下为各分类在 **请求/响应** 中使用的字段定义；单位、是否必填、校验规则由后端统一规定，前端与后端对齐。
|
||
|
||
### 8.1 合同信息 `contract`
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| serialNo | string | 序号 |
|
||
| contractCode | string | 合同编号 |
|
||
| powerBureauContractCode | string | 供电局项目合同编号 |
|
||
| projectName | string | 项目名称 |
|
||
| subItemCount | number | 子项个数 |
|
||
| subItemCode | string | 子项编码 |
|
||
| totalInvestment | number | 项目总投资（万元） |
|
||
| bidContractAmount | string | 中标合同金额（万元，字符串存储） |
|
||
| warrantyRatio | string \| number | 质保金比例 |
|
||
| settlementAmount | number | 结算金额（万元） |
|
||
| totalCostEstimate | number | 总成本测算 |
|
||
| voltageLevel | string | 工程电压等级 |
|
||
| projectCategory | string | 工程类别 |
|
||
| ownerUnit | string | 业主单位 |
|
||
| ownerContact | string | 业主联系人及电话 |
|
||
| bidType | string | 中标形式 |
|
||
| signDate | string | 签订日期：有有效日期时返回 YYYY-MM-DD，否则返回原文（如「在建中」「未开工」） |
|
||
| startDate | string | 开工日期：同上 |
|
||
| plannedCompletionDate | string | 计划竣工日期：同上 |
|
||
| actualCompletionDate | string | 实际竣工日期：同上 |
|
||
| warrantyAmount | number | 质保金（万元） |
|
||
| warrantyEndDate | string | 质保期截止日（字符串存储） |
|
||
| actualWarrantyRefundDate | string | 实际退质保金日期 |
|
||
| projectDepartment | string | 所属项目部 |
|
||
| projectLeaderContact | string | 项目负责人及电话 |
|
||
| paymentMethod | string | 工程款拨付方式 |
|
||
|
||
### 8.2 成本控制 `costControl`
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| totalCost | number | 总体成本 |
|
||
| isAdjusted | string | 是否调整：是/否 |
|
||
| migrantWorkerPlan | string \| number | 农民工工资（按进度计划） |
|
||
| migrantWorkerActual | number | 农民工工资（实付） |
|
||
| selfSupplyMaterialControl | number | 乙供材料费（控制） |
|
||
| materialPayableByRatio | number | 应付材料费（按收款比例） |
|
||
| materialActualOccurred | number | 实际发生材料费 |
|
||
| materialActualPaid | number | 实际支付材料费 |
|
||
| otherCostControl | number | 其他费用（控制） |
|
||
| otherPayable | number | 应付其他费 |
|
||
| otherActual | number | 实际其他费用 |
|
||
| tax | number | 税金 |
|
||
| profit | number | 利润（万元） |
|
||
| actualProfit | number | 实际利润（万元） |
|
||
| costSettlementAmount | number | 成本结算金额（万元） |
|
||
|
||
### 8.3 应收款 `receivable`
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| receivableProgress | number | 应收款（完成进度款） |
|
||
| invoiceAmount | number | 开票金额（万元） |
|
||
| actualReceiptAmount | number | 实际收款金额（万元） |
|
||
| actualReceiptRate | string \| number | 实际收款完成率 |
|
||
|
||
### 8.4 应付款 `payable`
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| payableAmount | number | 应付款金额（万元） |
|
||
| actualPaymentAmount | number | 实际付款金额（万元） |
|
||
| unreceivedAmount | number | 未收款（万元） |
|
||
| actualPaymentRate | string \| number | 实际付款完成率 |
|
||
| migrantWorkerArrears | number | 民工工资清欠金额（万元） |
|
||
|
||
### 8.5 其他 `other`
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| settlementCostEstimate | number | 结算后成本测算金额 |
|
||
| settlementLaborCost | number | 结算人工费 |
|
||
| settlementMaterialCost | number | 结算材料费 |
|
||
| settlementOtherCost | number | 结算其他费 |
|
||
| dueSettlementCount | number | 到期应结算项目个数 |
|
||
| overdueSettlementCount | number | 到期未完成结算个数 |
|
||
| existingProblems | string | 存在的问题 |
|
||
| suggestions | string | 建议措施 |
|
||
| cumulativeProgress | string \| number | 累计进度 |
|
||
| remark | string | 备注 |
|
||
|
||
---
|
||
|
||
## 9. 项目列表/筛选枚举
|
||
|
||
以下由后端定义并提供给前端（如通过配置接口或文档约定）：
|
||
|
||
- **项目进度 progress**：枚举值列表，如「未开始 / 进行中 / 已竣工」等
|
||
- **项目费用 cost**：枚举值列表，如按金额区间的选项
|
||
|
||
具体取值以实际业务与后端实现为准。
|
||
|
||
---
|
||
|
||
## 10. 统一错误响应
|
||
|
||
| HTTP 状态 | 说明 |
|
||
|-----------|------|
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未登录或 Token 无效 |
|
||
| 403 | 无权限（如非市场部调用新建项目） |
|
||
| 404 | 资源不存在（如项目 ID 不存在） |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
#### 错误响应体参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | HTTP 状态码或业务错误码 |
|
||
| message | string | 错误描述 |
|
||
| errors | array | 可选，参数校验详情 |
|
||
| errors[].field | string | 出错字段名 |
|
||
| errors[].message | string | 该字段错误说明 |
|
||
|
||
**示例**
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "参数校验失败",
|
||
"errors": [
|
||
{ "field": "projectName", "message": "项目名称不能为空" }
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 接口一览
|
||
|
||
| 接口 | 方法 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| /api/auth/login | POST | 登录 | 公开 |
|
||
| /api/projects/list | POST | 项目列表（搜索、筛选、分页） | 已登录 |
|
||
| /api/projects/detail | POST | 项目详情 | 已登录 |
|
||
| /api/projects/create | POST | 新建项目 | 已登录且市场部 |
|
||
| /api/projects/update | POST | 更新项目（记操作日志） | 已登录 |
|
||
| /api/projects/logs | POST | 操作日志列表 | 已登录 |
|
||
|
||
字段命名采用驼峰；日期格式建议 ISO8601 或 `YYYY-MM-DD`，前后端约定一致。
|