ocean/backend/API.md

项目管理系统 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	该字段错误说明

示例

{
  "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，前后端约定一致。