docs(changelog): #8741 供应商注册提交校验证件图片地址并去掉建单失败

Refs wx/HL#8741

changelogs-v2/2026-10/04_8741_供应商注册提交校验证件图片地址并去掉建单失败-修改接口-管理后台.md

@@ -0,0 +1,531 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8741"
+title: "供应商注册提交：证件图片地址不对直接返回 395065，状态与审批记录不再出现「建单失败」"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "新增一种失败返回，前端按现有方式展示 message；状态展示名少了「建单失败」，若前端有按该文案着色或筛选的逻辑请一并去掉"
+updated_at: "2026-10-04"
+base: "dev-v3"
+---
+
+# 供应商: 注册提交校验证件图片地址，去掉「建单失败」状态
+
+> **服务**: hl-resource-service、hl-user-service
+> **PR**: #8758
+> **Issue**: #8741
+> **日期**: 2026-10-04
+> **影响范围**: 管理端供应商「提交审批」（注册审批）、供应商列表与详情的状态、供应商审批记录
+
+---
+
+## ⚠️ 关键变化
+
+- 提交注册审批时，法人身份证人像面、国徽面、营业执照三张图片中任一张的地址不是本平台图片服务器地址（各环境不同，取文件中心配置），接口当场返回 `395065`「图片地址不对」。供应商保持草稿，不产生审批记录。以前会先受理，后台建企业微信审批单失败后才退回草稿，并显示「建单失败」。
+- 供应商列表、详情的状态展示名不再出现「建单失败」，原来显示「建单失败」的供应商显示「草稿」。供应商审批记录、审批记录列表的层级与状态文案中的「建单失败」也改为「草稿」。
+- 企业微信审批单内容（不影响管理端接口）：「收款账户」显示银行名 + 完整账号；「明细 → 结算信息」每个账户显示账户名称、账户类型、开户行、支行、账号；「注册资本」为纯数字时显示为数值加「万」（如 500 → 500万）。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 提交供应商注册审批 | POST | `/admin/supplier/items/{supplierId}/submit` | 新增一种失败返回 | 证件图片地址不对时返回 395065 |
+| 2 | 供应商分页 | GET | `/admin/supplier/items/page` | 返回值文案变化 | `statusName` 不再返回「建单失败」，改为「草稿」 |
+| 3 | 供应商有界查询 | GET | `/admin/supplier/items/list` | 返回值文案变化 | 同上 |
+| 4 | 供应商基本信息 | GET | `/admin/supplier/items/{supplierId}/basic-info/view` | 返回值文案变化 | 同上 |
+| 5 | 供应商审批记录 | GET | `/admin/supplier/items/{supplierId}/approval-history/page` | 返回值文案变化 | `approvalStatusName`、`chainLevelText` 不再返回「建单失败」，改为「草稿」 |
+| 6 | 审批记录列表 | GET | `/admin/supplier/items/approval-records/page` | 返回值文案变化 | `chainLevelText` 不再返回「建单失败」，改为「草稿」 |
+
+---
+
+## 三、接口详情
+
+### 1. 提交供应商注册审批 `POST /admin/supplier/items/{supplierId}/submit`
+
+**VO**: `SupplierSubmitReqVO` → `SupplierApprovalCommandRespVO`
+
+#### 使用场景
+
+管理员把草稿供应商提交注册审批。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| supplierId | Path | Long | ✅ | 正整数 | 草稿供应商 ID |
+| expectedUpdateTime | Body | String | ✅ | `yyyy-MM-dd HH:mm:ss` | 乐观锁，取详情里的 updateTime |
+| legalRepresentativeIdCardFrontUrl | Body | String | - | 非空时须为本平台图片地址 | 法人身份证人像面 |
+| legalRepresentativeIdCardBackUrl | Body | String | - | 非空时须为本平台图片地址 | 法人身份证国徽面 |
+| licenseImageUrl | Body | String | - | 非空时须为本平台图片地址 | 营业执照 |
+| 其余注册资料字段 | Body | - | - | 同现有提交接口 | 本次未改 |
+
+本平台图片地址即管理端文件上传返回的地址（TEST 形如 `https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/...`，正式环境前缀为 `prod`）。
+
+#### 出参 `Result<SupplierApprovalCommandRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| approvalLogId | String | 审批记录 ID |
+| requestNo | String | 幂等请求号 |
+| provider | String | 审批方式，企业微信为 `WECOM` |
+| approvalStatus | String | 审批状态，提交后为 `PENDING` |
+| approvalStatusName | String | 审批状态中文名 |
+| spNo | String | 企业微信审批单号，异步建单完成前为空 |
+| syncStatus | String | 同步状态 |
+| submittedAt | String | 提交时间 |
+
+本次出参不变。
+
+#### 请求示例
+
+```json
+{
+  "expectedUpdateTime": "2026-10-03 11:31:05",
+  "fullName": "鄂温克族自治旗巴彦呼硕草原牧家乐有限公司",
+  "legalRepresentativeIdCardFrontUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/other/2026/10/03/9c21c0b068c00baa227cfd450e6706ae.png",
+  "legalRepresentativeIdCardBackUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/other/2026/10/03/a1d6e23d67830251b1fdd251c6d885ad.png",
+  "licenseImageUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/other/2026/10/03/1f287826963710fa564639f4c0de8aac.png"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "approvalLogId": "2106260000000000001",
+    "provider": "WECOM",
+    "approvalStatus": "PENDING",
+    "approvalStatusName": "审核中",
+    "syncStatus": "REQUESTING"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口没有空数据。文件中心暂不可用、取不到本平台图片地址时不放行，返回 `100903`「远程服务暂不可用: 文件中心」，供应商保持草稿、不产生审批记录，稍后重试即可。
+
+#### 错误响应
+
+```json
+{
+  "code": 395065,
+  "message": "图片地址不对",
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 鉴权、权限、乐观锁、必填校验与现有提交接口相同。
+- 三张证件图只校验非空的那几张；为空的维持现状（不上传该附件）。
+- 任一张不是本平台图片地址：返回 395065，本次提交的资料不保存、不产生审批记录、供应商仍为草稿（零写入）。
+- 已有在途注册审批时重复提交，仍按原规则返回在途结果。
+- 修正图片后可直接重新提交。
+
+### 2. 供应商分页 `GET /admin/supplier/items/page`
+
+**VO**: `SupplierPageReqVO` → `PageResult<SupplierListItemRespVO>`
+
+#### 使用场景
+
+管理端供应商列表。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| keyword | Query | String | - | - | 编号/名称关键字 |
+| status | Query | String | - | 生命周期编码 | 状态筛选，不变 |
+| typeCode | Query | String | - | - | 供应商类型 |
+| creditLevel | Query | String | - | A/B/C/D | 信用等级 |
+| creatorId | Query | Long | - | - | 创建人 |
+| page | Query | Integer | - | ≥1 | 页码 |
+| pageSize | Query | Integer | - | ≥1 | 每页条数 |
+
+本次入参不变。
+
+#### 出参 `Result<PageResult<SupplierListItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| status | String | 生命周期编码，不变 |
+| statusName | String | 展示名；明确建单失败的草稿供应商由「建单失败」改为「草稿」 |
+
+其余字段不变。
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/page?keyword=SUP260262&page=1&pageSize=20
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "data": { "list": [ { "supplierNo": "SUP260262", "status": "DRAFT", "statusName": "草稿" } ] }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+无数据时返回空列表或原有空值，本次不变。
+
+#### 错误响应
+
+本次没有新增错误码，沿用现有错误返回，例如：
+
+```json
+{ "code": 395001, "message": "供应商不存在", "success": false }
+```
+
+#### 业务边界
+
+- 鉴权与数据权限、分页与筛选不变；只有状态展示名从「建单失败」改为「草稿」，`status` 编码与按状态筛选不变。
+
+### 3. 供应商有界查询 `GET /admin/supplier/items/list`
+
+**VO**: `SupplierListReqVO` → `List<SupplierListItemRespVO>`
+
+#### 使用场景
+
+下拉或关联选择时有界查询供应商。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| keyword | Query | String | - | - | 编号/名称关键字 |
+| status | Query | String | - | 生命周期编码 | 状态筛选，不变 |
+| typeCode | Query | String | - | - | 供应商类型 |
+| resourceModule | Query | String | - | 与 resourceId 同时传 | 资源模块 |
+| resourceId | Query | Long | - | 与 resourceModule 同时传 | 资源 ID |
+| limit | Query | Integer | - | 默认 50，最多 200 | 返回条数 |
+
+本次入参不变。
+
+#### 出参 `Result<List<SupplierListItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| status | String | 生命周期编码，不变 |
+| statusName | String | 展示名；明确建单失败的草稿供应商由「建单失败」改为「草稿」 |
+
+其余字段不变。
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/list?keyword=SUP260262
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "data": [ { "supplierNo": "SUP260262", "status": "DRAFT", "statusName": "草稿" } ], "success": true }
+```
+
+#### 空数据 / 降级响应
+
+无数据时返回空列表或原有空值，本次不变。
+
+#### 错误响应
+
+本次没有新增错误码，沿用现有错误返回，例如：
+
+```json
+{ "code": 395001, "message": "供应商不存在", "success": false }
+```
+
+#### 业务边界
+
+- 鉴权与数据权限、分页与筛选不变；只有状态展示名从「建单失败」改为「草稿」，`status` 编码与按状态筛选不变。
+
+### 4. 供应商基本信息 `GET /admin/supplier/items/{supplierId}/basic-info/view`
+
+**VO**: `—（Path 参数）` → `SupplierBasicInfoRespVO`
+
+#### 使用场景
+
+供应商详情与编辑页回显。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| supplierId | Path | Long | ✅ | 正整数 | 供应商 ID |
+
+本次入参不变。
+
+#### 出参 `Result<SupplierBasicInfoRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| status | String | 生命周期编码，不变 |
+| statusName | String | 展示名；明确建单失败的草稿供应商由「建单失败」改为「草稿」 |
+
+其余字段不变。
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/2105983859848060929/basic-info/view
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "data": { "supplierNo": "SUP260262", "status": "DRAFT", "statusName": "草稿" }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+无数据时返回空列表或原有空值，本次不变。
+
+#### 错误响应
+
+本次没有新增错误码，沿用现有错误返回，例如：
+
+```json
+{ "code": 395001, "message": "供应商不存在", "success": false }
+```
+
+#### 业务边界
+
+- 鉴权与数据权限、分页与筛选不变；只有状态展示名从「建单失败」改为「草稿」，`status` 编码与按状态筛选不变。
+
+### 5. 供应商审批记录 `GET /admin/supplier/items/{supplierId}/approval-history/page`
+
+**VO**: `SupplierApprovalHistoryPageReqVO` → `PageResult<SupplierApprovalHistoryRespVO>`
+
+#### 使用场景
+
+供应商详情页的审批记录。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| supplierId | Path | Long | ✅ | 正整数 | 供应商 ID |
+| bizType | Query | String | - | - | 审批类型 |
+| approvalStatus | Query | String | - | - | 审批状态编码 |
+| action | Query | String | - | - | 业务动作 |
+| from / to | Query | String | - | `yyyy-MM-dd HH:mm:ss`，需同时传 | 提交时间范围 |
+| sortBy / sortDirection | Query | String | - | 默认 submittedAt / DESC | 排序 |
+| page | Query | Integer | - | ≥1 | 页码 |
+| pageSize | Query | Integer | - | ≥1 | 每页条数 |
+
+本次入参不变。
+
+#### 出参 `Result<PageResult<SupplierApprovalHistoryRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| approvalStatus | String | 审批状态编码，不变（如 `FAILED`） |
+| approvalStatusName | String | 注册明确未建单由「建单失败」改为「草稿」 |
+| chainLevelText | String | 注册明确未建单由「建单失败」改为「草稿」 |
+
+其余字段不变。
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/2105983859848060929/approval-history/page?page=1&pageSize=50
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "data": { "list": [ { "approvalStatus": "FAILED", "approvalStatusName": "草稿", "chainLevelText": "草稿", "actionName": "提交草稿" } ] }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+无数据时返回空列表或原有空值，本次不变。
+
+#### 错误响应
+
+本次没有新增错误码，沿用现有错误返回，例如：
+
+```json
+{ "code": 395001, "message": "供应商不存在", "success": false }
+```
+
+#### 业务边界
+
+- 鉴权、分页、筛选与行数不变；只有注册明确未建单那一行的展示文案从「建单失败」改为「草稿」，`approvalStatus` 编码不变。
+
+### 6. 审批记录列表 `GET /admin/supplier/items/approval-records/page`
+
+**VO**: `SupplierApprovalLogPageReqVO` → `PageResult<SupplierApprovalLogPageItemRespVO>`
+
+#### 使用场景
+
+跨供应商的审批记录列表。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| supplierNo | Query | String | - | - | 供应商编号 |
+| fullName | Query | String | - | - | 供应商名称 |
+| bizType | Query | String | - | - | 审批类型 |
+| approvalStatus | Query | String | - | - | 审批状态编码 |
+| from / to | Query | String | - | `yyyy-MM-dd HH:mm:ss` | 提交时间范围 |
+| page | Query | Integer | - | ≥1 | 页码 |
+| pageSize | Query | Integer | - | ≥1 | 每页条数 |
+
+本次入参不变。
+
+#### 出参 `Result<PageResult<SupplierApprovalLogPageItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| approvalStatus | String | 审批状态编码，不变 |
+| chainLevelText | String | 注册明确未建单由「建单失败」改为「草稿」 |
+
+其余字段不变。
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/approval-records/page?supplierNo=SUP260262&page=1&pageSize=50
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "data": { "list": [ { "supplierNo": "SUP260262", "approvalStatus": "FAILED", "chainLevelText": "草稿" } ] }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+无数据时返回空列表或原有空值，本次不变。
+
+#### 错误响应
+
+本次没有新增错误码，沿用现有错误返回，例如：
+
+```json
+{ "code": 395001, "message": "供应商不存在", "success": false }
+```
+
+#### 业务边界
+
+- 鉴权、分页、筛选与行数不变；只有注册明确未建单那一行的展示文案从「建单失败」改为「草稿」，`approvalStatus` 编码不变。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload |
+|------|---------|
+| ✅ 三张图都是文件上传返回的地址 | `{ "licenseImageUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/other/2026/10/03/a.png", ... }` |
+| ✅ 某张图为空 | `{ "legalRepresentativeIdCardBackUrl": null, ... }` |
+| ❌ 外站地址 | `{ "licenseImageUrl": "https://img.hlbe-travel.com/supplier/2026/1002/x.jpg" }` → 395065 |
+| ❌ 其他环境的地址（如 TEST 提交正式环境 `prod/` 前缀地址） | `{ "licenseImageUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/prod/x.png" }` → 395065 |
+
+### 切换状态时的必要动作
+
+收到 395065 时，让用户重新上传三张证件图（用管理端文件上传返回的地址），再带最新 `expectedUpdateTime` 重新提交。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+| 提交结果 | 供应商资料 | 供应商状态 | 审批记录 |
+|----------|-----------|-----------|---------|
+| 图片地址都对 | 按提交内容保存 | 进入注册审核中 | 新增 1 条 |
+| 任一张图片地址不对（395065） | 不保存（本次提交整体回滚） | 保持草稿 | 不新增 |
+| 文件中心不可用（100903） | 不保存 | 保持草稿 | 不新增 |
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）；无权限 → 沿用现有错误。
+- 图片地址为空 → 不校验该张，照原规则提交。
+- 文件中心不可用 → 100903，不放行。
+- 历史上显示「建单失败」的供应商 → 现在直接显示「草稿」，可修正图片后重新提交。
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `statusName`（列表、详情） | 明确建单失败时为「建单失败」 | 「草稿」 |
+| `approvalStatusName`、`chainLevelText`（审批记录） | 「建单失败」 | 「草稿」 |
+| `chainLevelText`（审批记录列表） | 「建单失败」 | 「草稿」 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 证件图在外站时提交注册审批 | 接口先受理，后台建企业微信审批单失败，自动重提后退回草稿并显示「建单失败」 | 接口当场返回 395065「图片地址不对」，零写入 |
+| 企业微信审批单「收款账户」 | 银行名 尾号xxxx | 银行名 完整账号 |
+| 企业微信审批单「明细 → 结算信息」 | 银行名 尾号xxxx | 每个账户：账户名称、账户类型、开户行、支行、账号 |
+| 企业微信审批单「注册资本」 | 原样（如 500） | 纯数字补「万」（如 500万），已带单位的原样 |
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**: 否（新增一种失败返回；展示文案少了「建单失败」一种取值）
+- **前端是否必须同步上线**: 否
+- **前端 workaround 清理点**: 如有按「建单失败」文案着色、筛选或提示的逻辑，可以去掉
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: 供应商注册「提交审批」接口；供应商状态展示名与审批记录文案中的「建单失败」
+- **零影响**:
+  - 供应商生命周期状态编码、状态筛选、状态机
+  - 合作中资料变更审批、状态变更审批、收款账户审批
+  - 主档注册资本存值与管理端展示（「万」只加在企业微信审批单上）
+
+---
+
+## 八、测试环境已验证
+
+TEST 已部署 dev-v3 `df99bfedf`（包含合并提交 `a73f015e7`），经 Gateway 实测：
+
+```
+SUP260262、SUP260260（证件图在外站）重新提交 → 395065「图片地址不对」，仍为草稿，审批记录仍各 3 条 ✓
+自造草稿 SUP260266 只把营业执照换成外站地址提交 → 395065，仍为草稿、营业执照未被改写、无审批记录 ✓
+两家列表与详情状态展示「草稿」，审批记录与审批记录列表无「建单失败」；供应商列表整表 256 家无「建单失败」 ✓
+SUP260266 三张图为本平台地址时提交 → 受理并生成企业微信审批单 202610040008 ✓
+```
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8741](https://git.1814.love/wx/HL/issues/8741)
+- 关联 PR: [wx/HL#8758](https://git.1814.love/wx/HL/pulls/8758)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8741](https://git.1814.love/wx/HL/issues/8741)
+- **PR**: [#8758](https://git.1814.love/wx/HL/pulls/8758)
+- **Merge commit**: [a73f015e7](https://git.1814.love/wx/HL/commit/a73f015e7)
+
+### 联系人
+
+- **后端负责人**: @lc