# 项目管理系统 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 | 否 | 项目费用筛选，取值与业务枚举一致 |
| dateFilterType | string | 否 | 时间筛选维度：`signDate`（签订日期）、`startDate`（开工日期）、`plannedCompletionDate`（计划竣工日期）、`actualCompletionDate`（实际竣工日期）；仅对「日期正常」项目按 DATE 筛选 |
| dateFrom | string | 否 | 时间范围起（YYYY-MM-DD），与 dateFilterType 配合 |
| dateTo | string | 否 | 时间范围止（YYYY-MM-DD），与 dateFilterType 配合 |
| dateAbnormal | boolean | 否 | 为 true 时只返回「日期异常」项目（四个日期中任意一个非「日期正常」） |

#### 响应参数（成功，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 | 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`，前后端约定一致。