API 第一版定型

backend/API.md

@@ -0,0 +1,396 @@
+# 项目管理系统 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 | 否 | 每页条数，默认 20 |
+| searchType | string | 否 | 搜索维度：`name`（项目名称）、`code`（项目编号） |
+| keyword | string | 否 | 搜索关键词，与 searchType 配合使用 |
+| progress | string | 否 | 项目进度筛选，取值与业务枚举一致 |
+| cost | string | 否 | 项目费用筛选，取值与业务枚举一致 |
+
+#### 响应参数（成功，HTTP 200）
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| list | array | 项目列表，无数据时为空数组 |
+| list[].id | string | 项目 ID |
+| list[].projectName | string | 项目名称 |
+| list[].contractCode | string | 合同编号 |
+| list[].progress | string | 项目进度 |
+| list[].cost | string | 项目费用 |
+| list[].updatedAt | string | 最后更新时间，ISO8601 |
+| 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 | number | 中标合同金额（万元） |
+| 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`，前后端约定一致。