# 中尚鹏管理系统 - 后端 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`：服务器内部错误