wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
main
hl-api-changelog/changelogs-v2/2026-09/08_7318_供应商删除账期并必填证照图片-修改接口-管理后台.md
T
Mimingguang 0081bc5682
changelog-filename-gate / validate (push) Failing after 2s
详情
docs(changelog): 回写 #7318 前端 verified(edefb5c4)
2026-09-08 18:17:57 +08:00

20 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 7318 供应商删除账期并必填证照图片 admin lc(GIT) 修改接口 deployed verified verified mmg edefb5c4 2026-09-08 前端已删除账户账期全链路(表单/预填/清洗/payload/列表/详情),新增资质行证照图片必填行内拦截,已有资质留空保留原图;合同域 settleCycle 未动。提交 edefb5c4 2026-09-08 dev-v3

⚠️ 供应商：删除账期并必填证照图片

前端删除账户账期输入、提交和展示；新增资质及完整提交时要求上传证照图片。当前状态：后端已部署并验证，前端待适配。

二、变更接口清单

# 接口 方法 路径 变更类型 说明
1 新增供应商 POST /admin/supplier/items/add 修改 移除账期请求；证照图片必填
2 修改供应商 PUT /admin/supplier/items/{supplierId}/update 修改 移除账期请求；证照图片必填
3 提交供应商 POST /admin/supplier/items/{supplierId}/submit 修改 移除账期请求；证照图片必填
4 新增收款账户 POST /admin/supplier/items/{supplierId}/bank-accounts/add 修改 移除账期请求
5 修改收款账户 PUT /admin/supplier/bank-accounts/{accountId}/update 修改 移除账期请求
6 账户列表 GET /admin/supplier/items/{supplierId}/account-info/list 修改 账户响应不再含账期
7 账户详情 GET /admin/supplier/bank-accounts/{accountId}/view 修改 账户响应不再含账期
8 设置默认账户 PUT /admin/supplier/bank-accounts/{accountId}/default/update 修改 账户响应不再含账期

三、接口详情

以下仅列本次变更及调用关键字段；审批响应示意省略未变更的提供方明细。示例 ID 与版本仅用于说明，实际使用页面最新值。

1. 新增供应商 POST /admin/supplier/items/add

VO: SupplierDraftSaveReqVO → SupplierWriteRespVO

使用场景

供应商管理页面新增供应商。

入参

字段 位置 类型 必填 约束 说明
qualifications[].imageUrl Body String 每项必填 非空，最长 1000 字符 证照图片地址
initialAccounts[].accountPeriod Body 已删除 否 不再提交 账期输入已移除

出参

字段 类型 说明
code / message Number / String 检查业务结果；成功 code=200
data Object 原有写入/审批结果；初始账户摘要原本就没有账期

请求示例

POST https://api.test.1814.love:9443/admin/supplier/items/add
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "fullName": "测试供应商7318",
  "taxNo": "91350211M000100Y46",
  "types": [
    {
      "typeCode": "SCENIC"
    }
  ],
  "legalRepresentative": "测试法人",
  "legalRepresentativeIdNo": "11010519491231002X",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.test/front.png",
  "legalRepresentativeIdCardBackUrl": "https://files.example.test/back.png",
  "contactPhone": "01012345678",
  "establishDate": "2020-01-01",
  "address": "测试地址",
  "mainCooperation": "景区服务",
  "licenseImageUrl": "https://files.example.test/license.png",
  "contacts": [
    {
      "contactName": "测试联系人",
      "contactPhone": "13800138000",
      "contactRole": "contentMoney"
    }
  ],
  "qualifications": [
    {
      "qualType": "GZZRX_LICENSE",
      "certNo": "TEST-7318",
      "permanentValid": true,
      "imageUrl": "https://files.example.test/7318/permit.png"
    }
  ],
  "initialAccounts": [
    {
      "accountType": "CORPORATE",
      "bankName": "测试银行",
      "accountNo": "7318123456789012"
    }
  ]
}

响应示例

{"code":200,"message":"成功","data":{"supplierId":"731801","supplierNo":"SUP731801","status":"DRAFT","statusName":"草稿","onboardingStage":"PROFILE_DRAFT","initialAccounts":[{"accountId":"731802","accountNo":"7318123456789012","accountNoMask":"7318123456789012","status":"DRAFT"}],"approval":null,"updateTime":"2026-09-08 17:00:00"}}

空数据 / 降级响应

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

错误响应

{"code":400,"message":"证照图片不能为空","data":null}

业务边界

  • 上传成功取得非空图片地址后再提交；缺图拒绝当前请求。

2. 修改供应商 PUT /admin/supplier/items/{supplierId}/update

VO: SupplierUpdateReqVO → SupplierWriteRespVO

使用场景

供应商管理页面修改供应商。以下请求示例用于 DRAFT 草稿；非草稿不允许通过 initialAccounts 维护账户，资料修改沿用必填 changeReason。

入参

字段 位置 类型 必填 约束 说明
supplierId Path String 是 正整数 ID 当前记录
qualifications[].imageUrl Body String 新增项必填；已有 qualificationId 的项省略/null 保留原图 非空，最长 1000 字符 证照图片地址
initialAccounts[].accountPeriod Body 已删除 否 不再提交 账期输入已移除
expectedUpdateTime Body String 是 yyyy-MM-dd HH:mm:ss 使用最新详情的 updateTime

出参

字段 类型 说明
code / message Number / String 检查业务结果；成功 code=200
data Object 原有写入/审批结果；初始账户摘要原本就没有账期

请求示例

PUT https://api.test.1814.love:9443/admin/supplier/items/731801/update
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "expectedUpdateTime": "2026-09-08 17:00:00",
  "qualifications": [
    {
      "qualificationId": "731804",
      "imageUrl": "https://files.example.test/7318/permit.png"
    }
  ],
  "initialAccounts": [
    {
      "accountType": "CORPORATE",
      "bankName": "测试银行",
      "accountNo": "7318123456789012"
    }
  ]
}

响应示例

{"code":200,"message":"成功","data":{"supplierId":"731801","supplierNo":"SUP731801","status":"DRAFT","statusName":"草稿","onboardingStage":"PROFILE_DRAFT","initialAccounts":[{"accountId":"731802","accountNo":"7318123456789012","accountNoMask":"7318123456789012","status":"DRAFT"}],"approval":null,"updateTime":"2026-09-08 17:00:00"}}

空数据 / 降级响应

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

错误响应

{"code":400,"message":"证照图片不能为空","data":null}

业务边界

  • qualifications 提交完整保留集合，未包含的既有项会被删除；项内 imageUrl 省略/null 才保留原图。空白及归一化后为空的图片均拒绝。整个数组未提交时不强制补齐历史图片。

3. 提交供应商 POST /admin/supplier/items/{supplierId}/submit

VO: SupplierSubmitReqVO → SupplierApprovalCommandRespVO

使用场景

供应商管理页面提交供应商。

入参

字段 位置 类型 必填 约束 说明
supplierId Path String 是 正整数 ID 当前记录
qualifications[].imageUrl Body String 每项必填 非空，最长 1000 字符 证照图片地址
initialAccounts[].accountPeriod Body 已删除 否 不再提交 账期输入已移除
expectedUpdateTime Body String 是 yyyy-MM-dd HH:mm:ss 使用最新详情的 updateTime

出参

字段 类型 说明
code / message Number / String 检查业务结果；成功 code=200
data Object 原有写入/审批结果；初始账户摘要原本就没有账期

请求示例

POST https://api.test.1814.love:9443/admin/supplier/items/731801/submit
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "fullName": "测试供应商7318",
  "taxNo": "91350211M000100Y46",
  "types": [
    {
      "typeCode": "SCENIC"
    }
  ],
  "legalRepresentative": "测试法人",
  "legalRepresentativeIdNo": "11010519491231002X",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.test/front.png",
  "legalRepresentativeIdCardBackUrl": "https://files.example.test/back.png",
  "contactPhone": "01012345678",
  "establishDate": "2020-01-01",
  "address": "测试地址",
  "mainCooperation": "景区服务",
  "licenseImageUrl": "https://files.example.test/license.png",
  "contacts": [
    {
      "contactName": "测试联系人",
      "contactPhone": "13800138000",
      "contactRole": "contentMoney"
    }
  ],
  "qualifications": [
    {
      "qualType": "GZZRX_LICENSE",
      "certNo": "TEST-7318",
      "permanentValid": true,
      "imageUrl": "https://files.example.test/7318/permit.png"
    }
  ],
  "initialAccounts": [
    {
      "accountType": "CORPORATE",
      "bankName": "测试银行",
      "accountNo": "7318123456789012"
    }
  ],
  "expectedUpdateTime": "2026-09-08 17:00:00"
}

响应示例

{"code":200,"message":"成功","data":{"approvalLogId":"731803","requestNo":"supplier-example-7318","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中"}}

空数据 / 降级响应

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

错误响应

{"code":400,"message":"证照图片不能为空","data":null}

业务边界

  • 上传成功取得非空图片地址后再提交；缺图拒绝当前请求。

4. 新增收款账户 POST /admin/supplier/items/{supplierId}/bank-accounts/add

VO: SupplierBankAccountBatchCreateReqVO → List<BankAccountSubmitResultRespVO>

使用场景

供应商管理页面新增收款账户。

入参

字段 位置 类型 必填 约束 说明
supplierId Path String 是 正整数 ID 当前记录
accounts Body Array 是 1–50 项 按输入顺序返回审批结果
accounts[].accountType Body String 是 CORPORATE / PERSONAL 对公 / 对私
accounts[].bankName Body String 是 最长 500 字符 开户银行
accounts[].accountNo Body String 是 去空白/连字符后 8–32 位数字 收款账号
accounts[].accountPeriod Body 已删除 否 不再提交 删除账期输入

出参

字段 类型 说明
code / message Number / String 检查业务结果；成功 code=200
data Array 原有写入/审批结果；初始账户摘要原本就没有账期

请求示例

POST https://api.test.1814.love:9443/admin/supplier/items/731801/bank-accounts/add
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "accounts": [
    {
      "accountType": "CORPORATE",
      "bankName": "测试银行",
      "accountNo": "7318123456789012"
    }
  ]
}

响应示例

{"code":200,"message":"成功","data":[{"accountId":"731802","approvalLogId":"731803","requestNo":"supplier-example-7318","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中","accountStatus":"PENDING","isDefault":"NO"}]}

空数据 / 降级响应

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

错误响应

{"code":400,"message":"开户银行不能为空","data":null}

业务边界

  • 沿用既有账户状态和权限限制；删除账期不跳过审批。

5. 修改收款账户 PUT /admin/supplier/bank-accounts/{accountId}/update

VO: SupplierAccountUpdateReqVO → BankAccountSubmitResultRespVO

使用场景

供应商管理页面修改收款账户。

入参

字段 位置 类型 必填 约束 说明
accountId Path String 是 正整数 ID 当前记录
expectedUpdateTime Body String 是 yyyy-MM-dd HH:mm:ss 使用最新详情的 updateTime
accountType Body String 是 CORPORATE / PERSONAL 对公 / 对私
bankName Body String 是 最长 500 字符 开户银行
accountNo Body String 是 去空白/连字符后 8–32 位数字 收款账号
accountPeriod Body 已删除 否 不再提交 删除账期输入

出参

字段 类型 说明
code / message Number / String 检查业务结果；成功 code=200
data Object 原有写入/审批结果；初始账户摘要原本就没有账期

请求示例

PUT https://api.test.1814.love:9443/admin/supplier/bank-accounts/731802/update
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "accountType": "CORPORATE",
  "bankName": "测试银行",
  "accountNo": "7318123456789012",
  "expectedUpdateTime": "2026-09-08 17:00:00"
}

响应示例

{"code":200,"message":"成功","data":{"accountId":"731802","approvalLogId":"731803","requestNo":"supplier-example-7318","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中","accountStatus":"ACTIVE","isDefault":"NO"}}

空数据 / 降级响应

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

错误响应

{"code":400,"message":"开户银行不能为空","data":null}

业务边界

  • 沿用既有账户状态和权限限制；删除账期不跳过审批。

6. 账户列表 GET /admin/supplier/items/{supplierId}/account-info/list

VO: SupplierAccountInfoRespVO

使用场景

供应商管理页面账户列表。

入参

字段 位置 类型 必填 约束 说明
supplierId Path String 是 正整数 ID 当前记录

出参

字段 类型 说明
code / message Number / String 检查业务结果；成功 code=200
data.bankAccounts[].accountPeriod 已删除 字段不再返回，删除页面账期展示

请求示例

GET https://api.test.1814.love:9443/admin/supplier/items/731801/account-info/list
Authorization: Bearer <当前有效登录会话>

无请求体

响应示例

{"code":200,"message":"成功","data":{"supplierId":"731801","bankAccounts":[{"accountId":"731802","accountName":"测试供应商7318","accountType":"CORPORATE","bankName":"测试银行","accountNo":"7318123456789012","bankBranch":null,"accountNoMask":"7318123456789012","status":"ACTIVE","isDefault":"YES","updateTime":"2026-09-08 17:00:00"}],"updateTime":"2026-09-08 17:00:00"}}

空数据 / 降级响应

无账户时 bankAccounts=[]；不会补回 accountPeriod。

错误响应

{"code":395001,"message":"供应商不存在","data":null}

业务边界

  • 只移除当前账户展示的账期，历史审批记录继续按原语义展示。

7. 账户详情 GET /admin/supplier/bank-accounts/{accountId}/view

VO: SupplierBankAccountDetailRespVO

使用场景

供应商管理页面账户详情。

入参

字段 位置 类型 必填 约束 说明
accountId Path String 是 正整数 ID 当前记录

出参

字段 类型 说明
code / message Number / String 检查业务结果；成功 code=200
data.accountPeriod 已删除 字段不再返回，删除页面账期展示

请求示例

GET https://api.test.1814.love:9443/admin/supplier/bank-accounts/731802/view
Authorization: Bearer <当前有效登录会话>

无请求体

响应示例

{"code":200,"message":"成功","data":{"accountId":"731802","accountName":"测试供应商7318","accountType":"CORPORATE","bankName":"测试银行","accountNo":"7318123456789012","bankBranch":null,"accountNoMask":"7318123456789012","status":"ACTIVE","isDefault":"YES","updateTime":"2026-09-08 17:00:00"}}

空数据 / 降级响应

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

错误响应

{"code":395001,"message":"供应商不存在","data":null}

业务边界

  • 只移除当前账户展示的账期，历史审批记录继续按原语义展示。

8. 设置默认账户 PUT /admin/supplier/bank-accounts/{accountId}/default/update

VO: SupplierBankAccountRespVO

使用场景

供应商管理页面设置默认账户。

入参

字段 位置 类型 必填 约束 说明
accountId Path String 是 正整数 ID 当前记录

出参

字段 类型 说明
code / message Number / String 检查业务结果；成功 code=200
data.accountPeriod 已删除 字段不再返回，删除页面账期展示

请求示例

PUT https://api.test.1814.love:9443/admin/supplier/bank-accounts/731802/default/update
Authorization: Bearer <当前有效登录会话>

无请求体

响应示例

{"code":200,"message":"成功","data":{"accountId":"731802","accountName":"测试供应商7318","accountType":"CORPORATE","bankName":"测试银行","accountNo":"7318123456789012","bankBranch":null,"accountNoMask":"7318123456789012","status":"ACTIVE","isDefault":"YES","updateTime":"2026-09-08 17:00:00"}}

空数据 / 降级响应

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

错误响应

{"code":395001,"message":"供应商不存在","data":null}

业务边界

  • 仅支持有效供应商的 ACTIVE 账户；无请求体，响应使用 status。

四、契约约束与正确调用方式

移除 accountPeriod 的表单、请求拼装及列表/详情绑定。旧请求多传该字段会被忽略，不再写入。证照图片上传成功后使用 imageUrl；新增项和完整请求必填，qualifications 数组须传完整保留集合，未包含的既有项会被删除；只有项内 imageUrl 省略/null 才保留原图，显式空白拒绝。

五、数据库行为

历史账期与审批记录保留；本次失败的图片校验不保存业务变更。

六、边界行为

不新增错误码。缺图沿用 HTTP 200、code=400、message=证照图片不能为空；不能仅凭 HTTP 状态判断成功。

六.6、修改前后对比

字段 修改前 修改后
accountPeriod 可输入、返回 当前账户契约移除
imageUrl 可空 新增/完整请求必填；增量已有项可保留原图

六.7、影响评估

管理端需要删除账期控件和展示，并增加图片必填校验。

七、不影响范围

账户审批、默认账户条件、权限和历史记录沿用既有契约。

八、测试环境已验证

真实 TEST API 已验证：新增供应商及更新账户不保存账期，账户列表/详情不返回账期；新增、修改、提交的缺图及控制字符输入均被拒绝；有效图片可更新，既有图片省略/null 可保留。失败请求无业务写入，测试草稿已清理。独立账户审批和默认设置沿用既有流程，本次未发起新企微审批。

十、相关文档

工单 #7318、补充工单 #7350、PR #7349、PR #7351。

关联 / 联系人

联系人

  • 后端负责人: @lc
  • 当前状态：前端待适配。
在新工单中引用 查看 Git Blame 复制永久链接