@@ -0,0 +1,392 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "6397"
|
||||
title: "供应商注册合同聚合信息"
|
||||
consumer: "admin"
|
||||
author: "lc(GIT)"
|
||||
change_type: "修改接口"
|
||||
backend_status: "deployed"
|
||||
gateway_status: "verified"
|
||||
frontend_status: "pending"
|
||||
frontend_owner: ""
|
||||
frontend_ref: ""
|
||||
target_release: ""
|
||||
verified_at: "2026-08-26"
|
||||
status_note: "PR #6405 已合并 dev-v3；Deploy Panel 任务 af3f205b 成功发布 Resource 双实例，合同接口已完成 23 项真实 Gateway 验收。TEST 工作副本存在服务器本地提交导致精确提交回读仍被阻塞，后端工单保持开启；本条只交接已经实测存在的接口契约。"
|
||||
updated_at: "2026-08-26"
|
||||
base: "dev-v3"
|
||||
---
|
||||
|
||||
# 🔧 供应商注册合同聚合信息
|
||||
|
||||
供应商创建草稿、提交注册和基础信息详情现统一支持合同完整快照。管理端应把“合同信息”放在“资质证照”之后、现有账户区域之前，并把原“初始账户”展示标题改为“结算信息”。
|
||||
|
||||
展示名调整不改变接口字段：原请求字段仍为 `initialAccounts`，不得改成 `settlementInfo` 或其他名称。
|
||||
|
||||
## 变更接口清单
|
||||
|
||||
| # | 接口 | 方法 | 路径 | 变化 |
|
||||
|---:|---|---|---|---|
|
||||
| 1 | 创建供应商注册草稿 | POST | `/admin/supplier/items/add` | 请求可选增加 `contracts` 完整集合 |
|
||||
| 2 | 提交供应商注册 | POST | `/admin/supplier/items/{supplierId}/submit` | 请求可选增加 `contracts` 完整快照 |
|
||||
| 3 | 查询供应商基本信息 | GET | `/admin/supplier/items/{supplierId}/basic-info/view` | 响应增加 `contracts` 列表 |
|
||||
|
||||
统一响应均为 `Result<T>`。业务失败可能仍为 HTTP 200，调用方必须同时判断 `code`、`success`、`message` 和 `data`。
|
||||
|
||||
## 公共合同字段
|
||||
|
||||
### 请求字段 `contracts[]`
|
||||
|
||||
| 字段 | 类型 | 创建必填 | 提交既有项必填 | 约束与说明 |
|
||||
|---|---|---:|---:|---|
|
||||
| `contractId` | String | 否，且禁止传入 | 是 | 正整数 ID 字符串；必须属于当前供应商，同一快照不得重复 |
|
||||
| `contractName` | String | 是 | 是 | 非空白，最长 500 字符 |
|
||||
| `contractNo` | String | 否 | 否 | 最长 100 字符 |
|
||||
| `contractType` | String | 是 | 是 | `FRAME`、`SINGLE_TRIP`、`PURCHASE` |
|
||||
| `signDate` | String | 否 | 否 | `yyyy-MM-dd` |
|
||||
| `startDate` | String | 是 | 是 | `yyyy-MM-dd` |
|
||||
| `endDate` | String | 是 | 是 | `yyyy-MM-dd`，不得早于 `startDate` |
|
||||
| `amount` | Number | 否 | 否 | 大于等于 0，最多 10 位整数和 2 位小数 |
|
||||
| `pricingMode` | String | 否 | 否 | 计价方式说明，最长 100 字符 |
|
||||
| `settleCycle` | String | 否 | 否 | 结算周期说明，最长 32 字符 |
|
||||
| `status` | String | 是 | 是 | 写接口允许 `DRAFT`、`ACTIVE`、`EXPIRED` |
|
||||
| `scanFileUrl` | String | 否 | 否 | 合同扫描件永久地址，最长 1000 字符 |
|
||||
| `remark` | String | 否 | 否 | 最长 500 字符 |
|
||||
|
||||
### 响应字段 `contracts[]`
|
||||
|
||||
详情返回上述全部业务字段，并额外返回：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `contractId` | String | 合同 ID，始终按字符串处理，不得转 JavaScript Number |
|
||||
| `updateTime` | String | 合同当前版本，格式 `yyyy-MM-dd HH:mm:ss` |
|
||||
|
||||
历史数据可能返回只读状态 `TERMINATED`；创建和提交请求不得发送该状态。
|
||||
|
||||
## 1. 创建供应商注册草稿
|
||||
|
||||
`POST /admin/supplier/items/add`
|
||||
|
||||
### 使用场景与边界
|
||||
|
||||
- `contracts` 可省略、为 `null` 或空数组，旧客户端行为不变。
|
||||
- 非空时最多 100 项，合同与供应商主体、资质和 `initialAccounts` 一起成功或一起失败。
|
||||
- 创建请求中的每个合同都是新合同，禁止携带 `contractId`。
|
||||
- 写入仍要求现有供应商创建权限；仅可信 `FINANCE`、`SUPER_ADMIN` 且拥有对应平台权限的身份可执行。
|
||||
|
||||
### 典型请求
|
||||
|
||||
```http
|
||||
POST /admin/supplier/items/add
|
||||
Authorization: Bearer <admin-token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"fullName": "示例供应商有限公司",
|
||||
"shortName": "示例供应商",
|
||||
"taxNo": "91350211M000100Y46",
|
||||
"types": [
|
||||
{
|
||||
"typeCode": "SCENIC"
|
||||
}
|
||||
],
|
||||
"mainCooperation": "景区资源合作",
|
||||
"licenseImageUrl": "https://files.example.com/license.png",
|
||||
"qualifications": [
|
||||
{
|
||||
"qualType": "BUSINESS_LICENSE",
|
||||
"certNo": "LIC-2026-001",
|
||||
"imageUrl": "https://files.example.com/license.png",
|
||||
"permanentValid": true
|
||||
}
|
||||
],
|
||||
"contracts": [
|
||||
{
|
||||
"contractName": "2026 年度框架合同",
|
||||
"contractNo": "HT-2026-001",
|
||||
"contractType": "FRAME",
|
||||
"signDate": "2026-08-26",
|
||||
"startDate": "2026-09-01",
|
||||
"endDate": "2027-08-31",
|
||||
"amount": 1200.50,
|
||||
"pricingMode": "按团结算",
|
||||
"settleCycle": "MONTHLY",
|
||||
"status": "DRAFT",
|
||||
"scanFileUrl": "https://files.example.com/contracts/HT-2026-001.pdf",
|
||||
"remark": "年度合作"
|
||||
}
|
||||
],
|
||||
"initialAccounts": []
|
||||
}
|
||||
```
|
||||
|
||||
### 成功响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"supplierId": "2090300000000063970",
|
||||
"supplierNo": null,
|
||||
"status": "DRAFT",
|
||||
"onboardingStage": "PROFILE_DRAFT",
|
||||
"initialAccounts": [],
|
||||
"updateTime": "2026-08-26 11:10:00"
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### 失败响应：创建携带合同 ID
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "创建草稿不能携带合同ID",
|
||||
"data": null,
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
失败时不会留下供应商主体或部分合同。
|
||||
|
||||
## 2. 提交供应商注册
|
||||
|
||||
`POST /admin/supplier/items/{supplierId}/submit`
|
||||
|
||||
### 使用场景与快照语义
|
||||
|
||||
- `contracts` 省略或为 `null`：本次不处理合同，保留草稿当前合同。
|
||||
- `contracts: []`：明确清空当前全部合同。
|
||||
- 非空数组：作为完整快照；带 `contractId` 的项覆盖当前合同，不带 ID 的项新增，当前已有但数组中遗漏的合同删除。
|
||||
- 带 ID 的合同必须属于路径中的供应商；不属于当前供应商、重复 ID、非法枚举、负金额或日期逆序均失败。
|
||||
- `expectedUpdateTime` 仍是供应商聚合并发版本；发生并发修改时调用方应刷新详情后重新组装完整表单。
|
||||
- 合同快照会进入本次审批资料，但提交注册不会自动改写合同自身的 `status`。
|
||||
|
||||
### 典型请求
|
||||
|
||||
```http
|
||||
POST /admin/supplier/items/2090300000000063970/submit
|
||||
Authorization: Bearer <admin-token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"fullName": "示例供应商有限公司",
|
||||
"shortName": "示例供应商",
|
||||
"taxNo": "91350211M000100Y46",
|
||||
"types": [
|
||||
{
|
||||
"typeCode": "SCENIC"
|
||||
}
|
||||
],
|
||||
"mainCooperation": "景区资源合作",
|
||||
"licenseImageUrl": "https://files.example.com/license.png",
|
||||
"qualifications": [
|
||||
{
|
||||
"qualType": "BUSINESS_LICENSE",
|
||||
"certNo": "LIC-2026-001",
|
||||
"imageUrl": "https://files.example.com/license.png",
|
||||
"permanentValid": true
|
||||
}
|
||||
],
|
||||
"contracts": [
|
||||
{
|
||||
"contractId": "2090300000000063971",
|
||||
"contractName": "2026 年度框架合同",
|
||||
"contractNo": "HT-2026-001",
|
||||
"contractType": "FRAME",
|
||||
"signDate": "2026-08-26",
|
||||
"startDate": "2026-09-01",
|
||||
"endDate": "2027-08-31",
|
||||
"amount": 1200.50,
|
||||
"pricingMode": "按团结算",
|
||||
"settleCycle": "MONTHLY",
|
||||
"status": "ACTIVE",
|
||||
"scanFileUrl": "https://files.example.com/contracts/HT-2026-001.pdf",
|
||||
"remark": "提交审批"
|
||||
}
|
||||
],
|
||||
"initialAccounts": [],
|
||||
"expectedUpdateTime": "2026-08-26 11:10:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 成功响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"approvalLogId": "2090300000000063972",
|
||||
"requestNo": "SUP-REQ-7b8c9d00112233445566778899aabbccddeeff00112233445566778899aabbcc",
|
||||
"provider": "LOCAL_AUTO",
|
||||
"approvalStatus": "APPROVED",
|
||||
"spNo": null,
|
||||
"spStatus": null,
|
||||
"syncStatus": "APPLIED",
|
||||
"submittedAt": "2026-08-26 11:11:00",
|
||||
"finishedAt": "2026-08-26 11:11:00"
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### 失败响应：合同不属于当前供应商
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "合同不属于当前供应商",
|
||||
"data": null,
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
该失败会回滚本次提交表单中的主体、资质、合同和审计变化，供应商仍保持原状态和原版本。
|
||||
|
||||
## 3. 查询供应商基本信息
|
||||
|
||||
`GET /admin/supplier/items/{supplierId}/basic-info/view`
|
||||
|
||||
### 请求
|
||||
|
||||
```http
|
||||
GET /admin/supplier/items/2090300000000063970/basic-info/view
|
||||
Authorization: Bearer <admin-token>
|
||||
```
|
||||
|
||||
无请求体。读取继续要求可信读角色和 `supplier:view` 平台权限。
|
||||
|
||||
### 成功响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"supplierId": "2090300000000063970",
|
||||
"supplierNo": null,
|
||||
"fullName": "示例供应商有限公司",
|
||||
"shortName": "示例供应商",
|
||||
"tax_no": "9135**********0Y46",
|
||||
"legalRepresentative": null,
|
||||
"legalRepresentativeIdNoMask": null,
|
||||
"legalRepresentativeIdCardFrontUrl": null,
|
||||
"legalRepresentativeIdCardBackUrl": null,
|
||||
"contactPhoneMask": null,
|
||||
"establishDate": null,
|
||||
"registeredCapital": null,
|
||||
"businessScope": null,
|
||||
"staffScale": null,
|
||||
"mainCooperation": "景区资源合作",
|
||||
"status": "DRAFT",
|
||||
"creditLevel": "B",
|
||||
"totalScore": null,
|
||||
"types": [
|
||||
{
|
||||
"typeCode": "SCENIC",
|
||||
"typeName": "景区"
|
||||
}
|
||||
],
|
||||
"contacts": [],
|
||||
"qualifications": [
|
||||
{
|
||||
"qualificationId": "2090300000000063973",
|
||||
"qualType": "BUSINESS_LICENSE",
|
||||
"qualTypeName": "营业执照",
|
||||
"certNoMask": "LI*********01",
|
||||
"imageUrl": "https://files.example.com/license.png",
|
||||
"expiryDate": null,
|
||||
"permanentValid": true,
|
||||
"daysUntilExpiry": null,
|
||||
"validityStatus": "VALID",
|
||||
"validityStatusName": "有效",
|
||||
"isRequired": false,
|
||||
"expired": false,
|
||||
"updateTime": "2026-08-26 11:10:00"
|
||||
}
|
||||
],
|
||||
"contracts": [
|
||||
{
|
||||
"contractId": "2090300000000063971",
|
||||
"contractName": "2026 年度框架合同",
|
||||
"contractNo": "HT-2026-001",
|
||||
"contractType": "FRAME",
|
||||
"signDate": "2026-08-26",
|
||||
"startDate": "2026-09-01",
|
||||
"endDate": "2027-08-31",
|
||||
"amount": 1200.50,
|
||||
"pricingMode": "按团结算",
|
||||
"settleCycle": "MONTHLY",
|
||||
"status": "DRAFT",
|
||||
"scanFileUrl": "https://files.example.com/contracts/HT-2026-001.pdf",
|
||||
"remark": "年度合作",
|
||||
"updateTime": "2026-08-26 11:10:00"
|
||||
}
|
||||
],
|
||||
"updateTime": "2026-08-26 11:10:00"
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
合同按 `contractId` 升序返回，只包含当前有效合同。没有合同时返回空数组 `[]`，不返回 `null`。
|
||||
|
||||
### 常见失败
|
||||
|
||||
| 场景 | `code` | 前端处理 |
|
||||
|---|---:|---|
|
||||
| 未登录或 Token 失效 | `401` | 跳转登录，不展示空详情 |
|
||||
| 可信角色或 `supplier:view` 平台权限不足 | `403` | 展示无权限状态 |
|
||||
| 供应商不存在或已删除 | `395001` | 返回列表并刷新 |
|
||||
|
||||
## 修改前后对比
|
||||
|
||||
| 场景 | 修改前 | 修改后 |
|
||||
|---|---|---|
|
||||
| 创建草稿 | 请求不能携带合同 | 可选携带完整 `contracts`，与草稿一起成功或失败 |
|
||||
| 提交注册 | 提交表单不能维护合同 | 可省略保留、空数组清空或提交完整合同快照 |
|
||||
| 基础信息 | 不返回合同列表 | 返回完整 `contracts[]` 及字符串 ID、版本 |
|
||||
| 账户区域标题 | 页面显示“初始账户” | 页面应显示“结算信息”，接口字段仍为 `initialAccounts` |
|
||||
| 页面区块顺序 | 资质后直接进入账户区域 | 资质证照 → 合同信息 → 结算信息 |
|
||||
|
||||
## 兼容性与管理端接入事项
|
||||
|
||||
1. 在“资质证照”区域之后新增“合同信息”表格，在合同之后显示原账户表格。
|
||||
2. 原账户表格标题改为“结算信息”；所有请求和响应继续使用 `initialAccounts`，不要改字段名。
|
||||
3. 创建草稿时合同为完整新项，不发送 `contractId`；编辑后提交时，既有合同必须原样带回字符串 `contractId`。
|
||||
4. 提交表单是完整快照。用户明确删除全部合同时发送 `contracts: []`；未加载合同或不处理合同时省略字段，不要误发空数组。
|
||||
5. 所有 ID 均作为字符串保存、比较和回传，不经过 Number 转换。
|
||||
6. 本次不新增接口路径、权限点或业务错误码；旧客户端省略 `contracts` 时继续可用。
|
||||
7. 管理端源码不在本后端工单中修改，前端状态保持 `pending`，直至完成页签、标题和表格接入并提供前端引用。
|
||||
|
||||
## TEST 验证证据
|
||||
|
||||
- 自动化：供应商定向测试 115 项通过；`hl-resource-service` 全量 2,111 项，0 失败、0 错误，38 项条件跳过；`hl-verify` 与差异检查通过。
|
||||
- 部署：Deploy Panel API 任务 `af3f205b` 终态 `success`、退出码 0、`has_build_error=false`，未发现 Maven、编译或滚动发布错误。
|
||||
- 健康：`hl-resource-service` 的 8082、8182 双实例运行；Nacos `test` 命名空间两实例均 `healthy=true`、`enabled=true`。
|
||||
- 真实 Gateway：23 项断言通过，覆盖合同随草稿创建、详情完整回显、字符串 ID、创建携带 ID 失败、普通 ADMIN 越权、提交外部合同 ID 完整回滚、日期逆序零写入和旧客户端省略 `contracts`。
|
||||
- 清理：两个临时 DRAFT 均通过业务删除接口软删除并回读为不存在；仅保留不可逆的 CREATE/DELETE 操作审计。
|
||||
- 环境限制：部署前锁定 `origin/dev-v3=1a16a5aec7d0b95ec87e6fb222581060a3135984`，但面板 Git API 回读到服务器本地短提交 `6f7d3ca78`，Gitea 无法解析该对象。接口行为已真实验证，后端工单仍等待测试环境恢复精确远端提交后复验，不能据此宣称最终交付完成。
|
||||
|
||||
## 撤回
|
||||
|
||||
1. 从最新 `dev-v3` 创建回退分支，执行 `git revert -m 1 --no-edit 1a16a5aec7d0b95ec87e6fb222581060a3135984`，经独立 PR 合入。
|
||||
2. 重新滚动部署 `hl-resource-service`；无需执行数据库结构、配置、Redis 或 MQ 恢复。
|
||||
3. 管理端停止发送和读取 `contracts`，恢复原页面结构；`initialAccounts` 契约始终不变。
|
||||
4. 已保存的合同资料保留，不做破坏性批量清理；回退后旧客户端继续按省略 `contracts` 的路径工作。
|
||||
5. 经 Gateway 复测创建、提交、基础信息、未认证、越权、非法合同 ID、失败零写入和旧客户端兼容，并确认双实例与 Nacos 健康。
|
||||
|
||||
## 关联 / 联系人
|
||||
|
||||
- **Issue**: [#6397](https://git.1814.love:8443/wx/HL/issues/6397)
|
||||
- **PR**: [#6405](https://git.1814.love:8443/wx/HL/pulls/6405)
|
||||
- **合并提交**: [1a16a5aec](https://git.1814.love:8443/wx/HL/commit/1a16a5aec7d0b95ec87e6fb222581060a3135984)
|
||||
- **后端负责人**: @lc
|
||||
在新工单中引用
屏蔽一个用户