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

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8741	供应商注册提交：证件图片地址不对直接返回 395065，状态与审批记录不再出现「建单失败」	admin	lc(GIT)	修改接口	deployed	verified	not_required					新增一种失败返回，前端按现有方式展示 message；状态展示名少了「建单失败」，若前端有按该文案着色或筛选的逻辑请一并去掉	2026-10-04	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	提交时间

本次出参不变。

请求示例

{
  "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"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "approvalLogId": "2106260000000000001",
    "provider": "WECOM",
    "approvalStatus": "PENDING",
    "approvalStatusName": "审核中",
    "syncStatus": "REQUESTING"
  },
  "success": true
}

空数据 / 降级响应

本接口没有空数据。文件中心暂不可用、取不到本平台图片地址时不放行，返回 100903「远程服务暂不可用: 文件中心」，供应商保持草稿、不产生审批记录，稍后重试即可。

错误响应

{
  "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	展示名；明确建单失败的草稿供应商由「建单失败」改为「草稿」

其余字段不变。

请求示例

GET /admin/supplier/items/page?keyword=SUP260262&page=1&pageSize=20

响应示例

{ "code": 200, "data": { "list": [ { "supplierNo": "SUP260262", "status": "DRAFT", "statusName": "草稿" } ] }, "success": true }

空数据 / 降级响应

无数据时返回空列表或原有空值，本次不变。

错误响应

本次没有新增错误码，沿用现有错误返回，例如：

{ "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	展示名；明确建单失败的草稿供应商由「建单失败」改为「草稿」

其余字段不变。

请求示例

GET /admin/supplier/items/list?keyword=SUP260262

响应示例

{ "code": 200, "data": [ { "supplierNo": "SUP260262", "status": "DRAFT", "statusName": "草稿" } ], "success": true }

空数据 / 降级响应

无数据时返回空列表或原有空值，本次不变。

错误响应

本次没有新增错误码，沿用现有错误返回，例如：

{ "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	展示名；明确建单失败的草稿供应商由「建单失败」改为「草稿」

其余字段不变。

请求示例

GET /admin/supplier/items/2105983859848060929/basic-info/view

响应示例

{ "code": 200, "data": { "supplierNo": "SUP260262", "status": "DRAFT", "statusName": "草稿" }, "success": true }

空数据 / 降级响应

无数据时返回空列表或原有空值，本次不变。

错误响应

本次没有新增错误码，沿用现有错误返回，例如：

{ "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	注册明确未建单由「建单失败」改为「草稿」

其余字段不变。

请求示例

GET /admin/supplier/items/2105983859848060929/approval-history/page?page=1&pageSize=50

响应示例

{ "code": 200, "data": { "list": [ { "approvalStatus": "FAILED", "approvalStatusName": "草稿", "chainLevelText": "草稿", "actionName": "提交草稿" } ] }, "success": true }

空数据 / 降级响应

无数据时返回空列表或原有空值，本次不变。

错误响应

本次没有新增错误码，沿用现有错误返回，例如：

{ "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	注册明确未建单由「建单失败」改为「草稿」

其余字段不变。

请求示例

GET /admin/supplier/items/approval-records/page?supplierNo=SUP260262&page=1&pageSize=50

响应示例

{ "code": 200, "data": { "list": [ { "supplierNo": "SUP260262", "approvalStatus": "FAILED", "chainLevelText": "草稿" } ] }, "success": true }

空数据 / 降级响应

无数据时返回空列表或原有空值，本次不变。

错误响应

本次没有新增错误码，沿用现有错误返回，例如：

{ "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
• 关联 PR: wx/HL#8758

关联 / 联系人

链接

• Issue: #8741
• PR: #8758
• Merge commit: a73f015e7

联系人

• 后端负责人: @lc