wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
docs/6438-region-changelog-code-sync
hl-api-changelog/changelogs-v2/2026-08/26_6391_供应商法人证件号与身份证正反面-修改接口-管理后台.md
T
Mimingguang 3e8ea93caf
changelog-filename-gate / validate (push) Failing after 2s
详情
chore(changelog): #6391 管理端 verified (ref=74b3d8bf)
2026-08-26 14:53:22 +08:00

12 KiB
原始文件 永久链接 Blame 文件历史

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 6391 供应商法人证件号与身份证正反面 admin lc(GIT) 修改接口 deployed verified verified mmg 74b3d8bf 2026-08-26 PR #6401 已合并 dev-v3 并部署 TEST；供应商创建、更新、提交新增法人身份证号及正反面永久地址，详情仅返回脱敏证件号。旧客户端省略三字段时保持兼容，前端待接入输入与双面上传。 2026-08-26 dev-v3

🔧 供应商法人证件号与身份证正反面

供应商“基本信息－法定代表人”新增身份证号、人像面和国徽面三个字段。身份证图片继续使用既有文件上传能力，本次接口只接收上传完成后的永久 HTTPS 地址，不新增上传或 OCR 接口。

变更接口

方法 路径 权限 变化
POST /admin/supplier/items/add supplier:create 创建草稿可保存三个法人证件字段
PUT /admin/supplier/items/{supplierId}/update supplier:update 增量更新三个法人证件字段
POST /admin/supplier/items/{supplierId}/submit supplier:update、supplier:approval:submit 完整注册表单可提交三个法人证件字段
GET /admin/supplier/items/{supplierId}/basic-info/view supplier:view 返回脱敏证件号及身份证正反面地址

通用字段与校验

字段 类型 必填 规则
legalRepresentativeIdNo string 条件必填 18 位中国大陆居民身份证号；校验长度、出生日期、顺序码及校验位；末位小写 x 会规范为大写 X
legalRepresentativeIdCardFrontUrl string 条件必填 身份证人像面永久地址，最长 1000 字符；必须为公网 HTTPS 地址，且不能含账号密码、查询串或片段
legalRepresentativeIdCardBackUrl string 条件必填 身份证国徽面永久地址，规则同人像面

三个字段必须“全部省略”或“同时提供”：

  • 全部省略：兼容旧客户端和没有法人证件数据的存量供应商。
  • 任意一个有值：三个字段必须同时有值，不能只保存证件号或单面图片。
  • 法定代表人可能对应多个供应商，证件号不作为供应商之间的唯一键。
  • 写接口的成功响应不回传证件号；需要展示时调用详情接口。
  • 统一响应可能以 HTTP 200 承载业务失败，必须同时判断 code、success 和 data。

1. 创建供应商草稿

使用场景

在新建供应商基本信息时，同时保存法定代表人身份证号及正反面扫描件地址。

请求

POST /admin/supplier/items/add
Authorization: Bearer <管理员令牌>
Content-Type: application/json

本次新增的三个字段遵循上方通用规则；创建草稿的既有最低必填字段仍为 fullName、taxNo、mainCooperation。

典型成功请求：

{
  "fullName": "法人证件联调示例供应商",
  "taxNo": "L6391EXAMPLE001",
  "legalRepresentative": "示例法人",
  "legalRepresentativeIdNo": "11010519491231002x",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.com/supplier/id/front.jpg",
  "legalRepresentativeIdCardBackUrl": "https://files.example.com/supplier/id/back.jpg",
  "mainCooperation": "旅游资源供应"
}

典型成功响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "supplierId": "1900000000000000001",
    "supplierNo": null,
    "status": "DRAFT",
    "onboardingStage": "PROFILE_DRAFT",
    "initialAccounts": [],
    "updateTime": "2026-08-26 11:40:00"
  }
}

兼容边界：旧客户端可完全省略三个新字段，其余请求保持原样。

异常请求（仅传人像面）：

{
  "fullName": "法人证件联调示例供应商",
  "taxNo": "L6391EXAMPLE001",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.com/supplier/id/front.jpg",
  "mainCooperation": "旅游资源供应"
}

{
  "code": 400,
  "message": "法定代表人证件号、人像面和国徽面必须同时提供",
  "success": false,
  "data": null
}

失败不会创建供应商草稿。

2. 更新供应商

使用场景

在供应商基本信息编辑页补录或替换完整的法人证件三字段。

请求

PUT /admin/supplier/items/1900000000000000001/update
Authorization: Bearer <管理员令牌>
Content-Type: application/json

changeReason 和 expectedUpdateTime 沿用原接口必填约束；三个法人证件字段作为一组增量字段处理。典型成功请求：

{
  "legalRepresentative": "示例法人",
  "legalRepresentativeIdNo": "11010519491231002X",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.com/supplier/id/front-v2.jpg",
  "legalRepresentativeIdCardBackUrl": "https://files.example.com/supplier/id/back-v2.jpg",
  "changeReason": "补录法人身份证扫描件",
  "expectedUpdateTime": "2026-08-26 11:40:00"
}

典型成功响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "supplierId": "1900000000000000001",
    "supplierNo": null,
    "status": "DRAFT",
    "onboardingStage": "PROFILE_DRAFT",
    "initialAccounts": [],
    "updateTime": "2026-08-26 11:42:00"
  }
}

兼容边界：三个新字段全部省略时，不修改现有法人证件数据。若请求中出现任一新字段，服务端会与当前值合并后再次检查三字段是否完整。

异常请求（身份证校验位错误）：

{
  "legalRepresentativeIdNo": "110105194912310021",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.com/supplier/id/front-v2.jpg",
  "legalRepresentativeIdCardBackUrl": "https://files.example.com/supplier/id/back-v2.jpg",
  "changeReason": "补录法人身份证扫描件",
  "expectedUpdateTime": "2026-08-26 11:40:00"
}

{
  "code": 400,
  "message": "法定代表人证件号的日期或校验位不合法",
  "success": false,
  "data": null
}

失败时主体版本、法人证件数据和变更记录均保持原状。

3. 提交供应商注册审批

使用场景

提交草稿的完整注册表单时，将法人证件三字段一并纳入审批内容。

请求

POST /admin/supplier/items/1900000000000000001/submit
Authorization: Bearer <管理员令牌>
Content-Type: application/json

本接口继续要求完整注册表单和当前 expectedUpdateTime。典型成功请求：

{
  "fullName": "法人证件联调示例供应商",
  "taxNo": "L6391EXAMPLE001",
  "legalRepresentative": "示例法人",
  "legalRepresentativeIdNo": "11010519491231002X",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.com/supplier/id/front.jpg",
  "legalRepresentativeIdCardBackUrl": "https://files.example.com/supplier/id/back.jpg",
  "mainCooperation": "旅游资源供应",
  "expectedUpdateTime": "2026-08-26 11:42:00"
}

典型成功响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "approvalLogId": "1900000000000000101",
    "requestNo": "SUP-REQ-20260826-0001",
    "provider": "LOCAL_AUTO",
    "approvalStatus": "APPROVED",
    "spNo": null,
    "spStatus": null,
    "syncStatus": "APPLIED",
    "submittedAt": "2026-08-26 11:43:00",
    "finishedAt": "2026-08-26 11:43:00"
  }
}

兼容边界：没有法人证件数据的旧草稿仍可按旧请求提交；若提交法人证件，则三字段必须完整。

异常请求（图片地址带查询串）：

{
  "fullName": "法人证件联调示例供应商",
  "taxNo": "L6391EXAMPLE001",
  "legalRepresentativeIdNo": "11010519491231002X",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.com/supplier/id/front.jpg?token=temporary",
  "legalRepresentativeIdCardBackUrl": "https://files.example.com/supplier/id/back.jpg",
  "mainCooperation": "旅游资源供应",
  "expectedUpdateTime": "2026-08-26 11:42:00"
}

{
  "code": 400,
  "message": "法人证件人像面地址不在允许范围",
  "success": false,
  "data": null
}

失败时不会创建审批或改变供应商状态。

4. 查询供应商基本信息

使用场景

编辑页回显法人证件信息。证件号只返回掩码，不能用于恢复原文或再次提交；图片地址可用于有权限页面的预览。

请求

GET /admin/supplier/items/1900000000000000001/basic-info/view
Authorization: Bearer <管理员令牌>

无请求体。

典型成功响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "supplierId": "1900000000000000001",
    "supplierNo": null,
    "fullName": "法人证件联调示例供应商",
    "shortName": null,
    "tax_no": "L639****E001",
    "legalRepresentative": "示例法人",
    "legalRepresentativeIdNoMask": "110105********002X",
    "legalRepresentativeIdCardFrontUrl": "https://files.example.com/supplier/id/front.jpg",
    "legalRepresentativeIdCardBackUrl": "https://files.example.com/supplier/id/back.jpg",
    "contactPhoneMask": null,
    "establishDate": null,
    "registeredCapital": null,
    "businessScope": null,
    "staffScale": null,
    "mainCooperation": "旅游资源供应",
    "status": "DRAFT",
    "creditLevel": "B",
    "totalScore": null,
    "types": [],
    "contacts": [],
    "qualifications": [],
    "updateTime": "2026-08-26 11:42:00"
  }
}

兼容边界：存量供应商没有法人证件数据时，三个响应字段均为 null。响应中不存在 legalRepresentativeIdNo 明文字段。

未认证示例：

{
  "code": 401,
  "message": "未认证或登录已失效",
  "success": false,
  "data": null
}

错误与前端处理

响应码 触发条件 前端处理
400 身份证不是 18 位、出生日期/顺序码/校验位错误、三字段不完整、图片地址不符合规则 保留表单并定位到法人证件区域；不要自动重试
401 未登录或 Gateway 认证失效 进入统一重新登录流程
403 角色、功能权限或数据范围不足 隐藏无权操作并展示统一无权限提示
395014 expectedUpdateTime 已过期 重新读取详情，提示用户确认后再提交

本次不新增业务错误码；参数失败继续使用统一 400。

前端改造清单

  • 在“新建/编辑供应商－基本信息－法定代表人”后增加身份证号输入框、人像面上传和国徽面上传。
  • 上传完成后提交永久 HTTPS 地址；不要提交临时签名 URL、查询参数 URL、Base64 或文件二进制。
  • 前端可做 18 位长度和末位 X/x 预校验，但最终以服务端日期及校验位结果为准。
  • 三字段联动必填；旧数据三个字段均为空时允许继续按原流程操作。
  • 详情只展示 legalRepresentativeIdNoMask；不得寻找或缓存身份证号明文。
  • 写成功后如需回显，重新调用详情接口，不要从写响应读取新字段。

验证证据

  • 自动化：最新 dev-v3 的 Resource 全量测试 2111 项通过、0 失败、0 错误，38 项既有条件跳过；法人证件聚焦测试 89 项通过。
  • TEST：Deploy Panel 任务 118fcff1 将目标提交 de615b49e3ecef4be13bd6bc78b3100d08ef0bd2 部署到双实例；该提交包含 #6391 合并提交 b909c8f7dfd73712886a33b574c72030dde89d4f，服务与 Nacos 健康检查通过。
  • 真实 Gateway：7 组场景通过，覆盖合法创建、错误校验位零写入、详情脱敏与图片回显、未认证拒绝、非法更新零写入、旧客户端省略字段兼容和迁移状态。
  • 清理：本轮验收草稿已通过业务删除接口软删除并保留正常删除审计，不遗留可用测试供应商。

撤回

  1. 从最新 dev-v3 创建回退分支，revert #6401 合并提交并经独立 PR 合入。
  2. 重新部署 hl-resource-service；新增的可空数据结构保留，不执行破坏性删除。
  3. 旧客户端、存量供应商和已保存的安全数据保持兼容；无需恢复配置、Redis 或 MQ。
  4. 经 Gateway 重跑旧请求、合法/非法证件号、三字段完整性、详情脱敏和失败零写入检查。

关联 / 联系人

在新工单中引用 查看 Git Blame 复制永久链接