307 lines
12 KiB
Markdown
Executable File
307 lines
12 KiB
Markdown
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=下游
|
||
|
||
**响应示例**：
|
||
```json
|
||
{
|
||
"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
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"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`：服务器内部错误
|