12 KiB
Executable File
中尚鹏管理系统 - 后端 API 文档（合同管理 + 提货管理）
作者: rovina
最近修订: 2026/3/2
说明: 含合同管理、中尚鹏合同、公司信息、提货管理（我要提货/提货明细/库存/货权转移）。
一、基础说明
- Base URL：
http://{host}:8080/api - 数据格式：JSON（除文件上传为 multipart/form-data）
- 通用响应：
{ "success": boolean, "message": string, "data"?: T } - 认证方式：除
/auth/login、/auth/register及静态文件路由外，所有 API 需在请求头中携带Authorization: Bearer <token>（JWT token 从登录接口获取）
二、业务合同管理 API（/api/contract）
2.1 单合同 CRUD
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /contract |
获取合同列表 |
| GET | /contract/:id |
获取单个合同详情 |
| POST | /contract/upload |
上传合同（表单 + 文件） |
| PUT | /contract/:id |
更新合同（仅表单字段） |
| DELETE | /contract/:id |
删除合同 |
GET /contract
Query 参数：contractType（可选）：1=采购 2=上游 3=下游
响应示例：
{
"success": true,
"data": [
{
"id": 1,
"name": "合同名称",
"contractType": "1",
"contractCode": "HT001",
"buyParty": "甲方",
"sellParty": "乙方",
"commodity": "商品",
"count": 100,
"unitPrice": 10.5,
"blNumber": "BL001;BL002",
"deliveryTime": "",
"pickUpTime": "",
"packaging": "",
"remarks": "",
"createTime": "2026-03-02T10:00:00Z",
"updateTime": "2026-03-02T10:00:00Z",
"files": [
{ "id": 1, "name": "合同.pdf", "url": "uploads/123_合同.pdf" }
]
}
]
}
文件 URL 说明：url 为相对路径，完整访问地址为 GET /api/contract-files/{url}，例如 /api/contract-files/uploads/123_合同.pdf。
POST /contract/upload
Content-Type：multipart/form-data
表单字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 合同名称 |
| contractType | string | 是 | 1/2/3 |
| contractCode | string | 是 | 合同编号 |
| buyParty | string | 是 | 甲方 |
| sellParty | string | 是 | 乙方 |
| commodity | string | 是 | 商品 |
| count | string | 是 | 数量 |
| unitPrice | string | 是 | 单价 |
| BLNumber | string | 是 | 提单号，最多 15 个，分号分隔 |
| deliveryTime | string | 否 | 交货时间 |
| pickUpTime | string | 否 | 提货时间 |
| packaging | string | 否 | 包装 |
| remarks | string | 否 | 备注 |
| files | File[] | 是 | 合同扫描件（PDF/图片，单文件≤10MB） |
2.2 批量归档（文件夹 + 批量记录）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /contract/folders |
获取批量归档文件夹列表 |
| POST | /contract/folders |
新建文件夹 |
| GET | /contract/folders/:id |
获取单个文件夹 |
| PUT | /contract/folders/:id |
更新文件夹 |
| DELETE | /contract/folders/:id |
删除文件夹 |
| GET | /contract/batches |
获取批量记录列表 |
| POST | /contract/batches |
批量上传 |
| GET | /contract/batches/:id |
获取批量记录详情 |
| DELETE | /contract/batches/:id |
删除批量记录 |
POST /contract/folders
请求体：
{
"name": "文件夹名称",
"description": "描述（可选）"
}
GET /contract/batches
Query 参数：folderId（可选）：按文件夹筛选
POST /contract/batches
Content-Type：multipart/form-data
表单字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| folderId | string | 是 | 归档文件夹 ID |
| batchName | string | 是 | 批次名称 |
| remark | string | 否 | 备注 |
| files | File[] | 是 | 批量文件 |
2.3 合同文件静态资源（供前端预览/下载）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/contract-files/uploads/{filename} |
单合同附件 |
| GET | /api/contract-files/batch_archive/{filename} |
批量归档文件 |
| GET | /api/zsp-contract-files/files/{filename} |
中尚鹏合同文件 |
三、中尚鹏合同管理 API（/api/zsp-contract）
与业务合同管理为两套独立体系，用于公司合同（上游/下游/外商采购/货代物流等）。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /zsp-contract/folders |
获取合同文件夹列表 |
| POST | /zsp-contract/folders |
创建文件夹 |
| GET | /zsp-contract/folders/:id |
获取单个文件夹 |
| PUT | /zsp-contract/folders/:id |
更新文件夹 |
| DELETE | /zsp-contract/folders/:id |
删除文件夹 |
| GET | /zsp-contract/contracts |
获取合同列表（含详情，可选 folderId） |
| POST | /zsp-contract/contracts |
上传合同文件 |
| GET | /zsp-contract/contracts/:id |
获取单个合同详情 |
| DELETE | /zsp-contract/contracts/:id |
删除合同 |
| POST | /zsp-contract/contracts/:id/details |
创建合同详情 |
| GET | /zsp-contract/contracts/:id/details |
获取合同详情列表 |
| PUT | /zsp-contract/details/:id |
更新合同详情 |
| DELETE | /zsp-contract/details/:id |
删除合同详情 |
| POST | /zsp-contract/details/batch |
批量创建合同详情 |
| POST | /zsp-contract/contracts/:id/details/import |
Excel 导入合同详情 |
| GET | /zsp-contract/contracts/:id/details/export |
导出合同详情到 Excel |
四、公司信息管理 API（/api/company）
管理公司相关文件（营业执照、开票信息等）。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /company/folders |
获取文件夹列表 |
| POST | /company/folders |
创建文件夹 |
| PUT | /company/folders/:id |
更新文件夹 |
| DELETE | /company/folders/:id |
删除文件夹 |
| GET | /company/files |
获取文件列表（可选 folderId） |
| POST | /company/files/upload |
上传公司文件 |
| DELETE | /company/files/:id |
删除文件 |
POST /company/files/upload
Content-Type：multipart/form-data
表单字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| files | File[] | 是 | 文件列表 |
| data | string | 否 | JSON 字符串，含 companyName、fileCategory、expireDate、description、folderId |
文件访问：GET /api/company-files/{fileUrl}，其中 fileUrl 为接口返回的 fileUrl 字段（如 files/xxx.pdf）。
五、提货管理 API
提货管理包含四块：我要提货（提货委托）、提货明细（出库单）、库存（仓库/入库单/库存汇总）、货权转移。以下路径均需在 Base URL 下加 /api 前缀（与合同等接口一致），且需登录态。
5.1 我要提货（/api/apply-delivery）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /apply-delivery/list |
分页列表 |
| GET | /apply-delivery/detail/:id |
单条详情 |
| POST | /apply-delivery/create |
新增 |
| PUT | /apply-delivery/update/:id |
更新 |
| PUT | /apply-delivery/cancel/:id |
取消（状态改为 cancelled） |
| DELETE | /apply-delivery/:id |
删除 |
GET /apply-delivery/list
Query：page、pageSize、orderNumber、blNumber、status（可选）。
响应：data: { items: DeliveryApply[], total, page, pageSize }。
单条字段：id, orderNumber, blNumber, licensePlate, driverName, driverPhone, driverIdCard, commodity, quantity, unit, deliveryDate, deliveryAddress, warehouse, status, remark, createTime, updateTime。
status：pending / approved / in_progress / completed / cancelled。
POST /apply-delivery/create
Body（JSON）：blNumber, licensePlate, driverName, driverPhone, driverIdCard, commodity, quantity, unit, deliveryDate, deliveryAddress, warehouse, remark。
服务端自动生成 orderNumber、status=pending、createTime/updateTime。
5.2 提货明细（/api/delivery-details）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /delivery-details/list |
分页列表 |
| GET | /delivery-details/detail/:id |
单条详情 |
| POST | /delivery-details/create |
新增出库单 |
| PUT | /delivery-details/update/:id |
更新 |
| DELETE | /delivery-details/:id |
删除 |
GET /delivery-details/list
Query：page、pageSize、outboundNumber、blNumber、outboundStatus（可选）。
响应：data: { items: DeliveryOutbound[], total, page, pageSize }。
单条字段：id, outboundNumber, deliveryOrderNumber, blNumber, licensePlate, driverName, driverPhone, commodity, commodityCode, quantity, unit, outboundDate, warehouse, operator, outboundStatus, receiptStatus, remark, createTime, updateTime。
5.3 库存（/api/inventory）
仓库
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /inventory/warehouses |
仓库列表（不分页） |
| POST | /inventory/warehouses/create |
新增仓库 |
| PUT | /inventory/warehouses/update/:id |
更新 |
| DELETE | /inventory/warehouses/delete/:id |
删除 |
仓库字段：id, code, name, address, contactPerson, contactPhone, status, remark, createTime, updateTime。
入库单
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /inventory/inbound/list |
分页列表 |
| POST | /inventory/inbound/create |
新增入库单 |
| PUT | /inventory/inbound/update/:id |
更新 |
| DELETE | /inventory/inbound/delete/:id |
删除 |
GET /inventory/inbound/list
Query：page、pageSize、warehouse、commodity（可选）。
入库单字段：id, inboundNumber, warehouse, commodity, commodityCode, blNumber, blWeight, inboundWeight, owner, contractNumber, inboundDate, operator, remark, createTime, updateTime。
库存汇总
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /inventory/summary |
按仓库+商品汇总：入库 - 出库 - 货权转移 = 当前库存 |
Query：warehouse、commodity（可选）。
响应：data 为汇总列表，含仓库、商品、入库量、出库量、货权转移量、当前库存等。
5.4 货权转移（/api/ownership-transfer）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /ownership-transfer/list |
分页列表 |
| GET | /ownership-transfer/detail/:id |
单条详情（含附件列表） |
| POST | /ownership-transfer/create |
新增（仅表单） |
| POST | /ownership-transfer/create-with-files |
新增（表单 + 附件） |
| DELETE | /ownership-transfer/:id |
删除 |
GET /ownership-transfer/list
Query：分页及筛选（如 transferNumber, blNumber, status, transferor, transferee, startDate, endDate 等，以实际后端为准）。
POST /ownership-transfer/create-with-files
Content-Type：multipart/form-data。
表单字段：transferDate, blNumber, quantity, commodity, warehouse, transferor, transferee, remark；files：附件。
货权转移单字段：id, transferNumber, transferDate, blNumber, quantity, commodity, warehouse, transferor, transferee, status, remark, fileList, createTime, updateTime。
附件存于服务端 ./data/ownership/，返回的 fileList 中 url 为相对路径（如 ownership/xxx）。若需通过 HTTP 访问，可配置静态路由（如 /api/ownership-files/ 指向该目录），并在文档中说明。
六、错误码与状态
200：成功400：请求参数错误404：资源不存在500：服务器内部错误