wx/hl-api-changelog

派生 0

文件

T

Mimingguang c399b3b0f1

changelog-filename-gate / validate (push) Failing after 2s

详情

chore(changelog): 回写 #7101 前端 verified

2026-09-05 11:35:01 +08:00

11 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	7101	供应商合作中资料变更接入企微审批	admin	lc(GIT)	修改接口	deployed	verified	verified	mmg	fbed9101		2026-09-05	后端已部署并通过 TEST；前端需将合作中资料保存结果按企微异步审批处理，并展示审核中。	2026-09-05	dev-v3

供应商模块：合作中资料变更接入企微审批

服务: hl-resource-service、hl-user-service Issue: #7101 PR: #7125、#7128 日期: 2026-09-05 影响范围: 管理后台供应商资料保存与新增收款账户结果展示

⚠️ 关键变化

合作中（ACTIVE）供应商保存资料不再直接更新正式资料：接口先返回企微审批受理结果，待审批时统一显示“审核中”；驳回不更新，通过后才应用本次申请。新增账户仍独立审批，本次补充中文审批状态字段。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	更新供应商	PUT	`/admin/supplier/items/{supplierId}/update`	行为与响应修改	`ACTIVE` 改为企微审批后生效，响应新增 `approval`
2	批量新增收款账户	POST	`/admin/supplier/items/{supplierId}/bank-accounts/add`	响应字段扩展	每项新增 `approvalStatusName`

三、接口详情

1. 更新供应商 `PUT /admin/supplier/items/{supplierId}/update`

VO: SupplierUpdateReqVO → SupplierWriteRespVO

使用场景

保存合作中供应商的主体资料、联系人或资质；草稿保存语义不变。

入参

字段	位置	类型	必填	约束	说明
`supplierId`	Path	String	是	正整数	供应商 ID
`expectedUpdateTime`	Body	String	是	`yyyy-MM-dd HH:mm:ss`	当前供应商版本
`changeReason`	Body	String	`ACTIVE` 必填	最长 500	变更原因
资料字段	Body	原类型	否	沿用原契约	至少产生一项实际变化
`contacts`	Body	Array	否	完整快照	已有联系人带 `contactId`、`expectedUpdateTime`；新增联系人省略 `contactId`

出参 `Result<SupplierWriteRespVO>`

字段	类型	说明
`data.status`	String	审批期间仍为 `ACTIVE`
`data.statusName`	String	待审批时为“审核中”
`data.approval.approvalLogId`	String	资料变更审批记录 ID
`data.approval.approvalStatus`	String	初次受理为 `PENDING`
`data.approval.approvalStatusName`	String	初次受理为“审核中”
`data.approval.spNo`	String	企业微信审批单号
`data.approval.syncStatus`	String	审批同步状态
`data.updateTime`	String	审核中仍返回正式资料当前版本

请求示例

{
  "remark": "更新合作备注",
  "changeReason": "业务资料更新",
  "expectedUpdateTime": "2026-09-05 09:00:00"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "supplierId": "2095000000000000001",
    "status": "ACTIVE",
    "statusName": "审核中",
    "approval": {
      "approvalLogId": "2095000000000000002",
      "provider": "WECOM",
      "approvalStatus": "PENDING",
      "approvalStatusName": "审核中",
      "spNo": "202609050001",
      "syncStatus": "REQUESTING"
    },
    "updateTime": "2026-09-05 09:00:00"
  }
}

空数据 / 降级响应

成功受理时 data.approval 不为空；企微结果不确定时保留审批事实，前端不得自动重复提交。草稿直接保存时 data.approval=null。

错误响应

{
  "code": 395014,
  "message": "数据已被他人修改，请刷新后重试",
  "success": false,
  "data": null
}

400 表示字段、联系人快照或变更原因不合法；395005 表示当前状态不允许；395019～395022 表示企微未配置、账号未绑定、提交失败或状态待对账。未新增错误码。

业务边界

审核中正式资料保持原值；驳回不更新，通过后一次性应用申请中的冻结值。
新增联系人必须省略 contactId，不得发送 contactId:null；只修正内部审批快照兼容，不放宽外部显式空 ID 校验。
企微表单的变更明细只列实际差异，身份证号和个人电话完整展示；相关附件和当前正式资料为选填。

2. 批量新增收款账户 `POST /admin/supplier/items/{supplierId}/bank-accounts/add`

VO: SupplierBankAccountBatchCreateReqVO → List<BankAccountSubmitResultRespVO>

使用场景

为合作中供应商新增一至五十个收款账户，每个账户独立提交企微审批。

入参

字段	位置	类型	必填	约束	说明
`supplierId`	Path	String	是	正整数	合作中供应商 ID
`accounts`	Body	Array	是	1～50 项	账户列表，原请求结构不变

出参 `Result<List<BankAccountSubmitResultRespVO>>`

字段	类型	说明
`data[].approvalStatus`	String	`PENDING` / `APPROVED` / `REJECTED`
`data[].approvalStatusName`	String	“审核中” / “已通过” / “已驳回”
`data[].accountStatus`	String	审核中为 `PENDING`，通过为 `ACTIVE`，驳回为 `REJECTED`
`data[].spNo`	String	企业微信审批单号

请求示例

{
  "accounts": [{
    "accountType": "PERSONAL",
    "bankName": "示例银行",
    "bankBranch": "示例支行",
    "accountNo": "6222000012345678",
    "proofFileUrls": [],
    "settleMode": "SINGLE",
    "invoiceType": "NONE"
  }]
}

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [{
    "accountId": "2095000000000000003",
    "approvalLogId": "2095000000000000004",
    "provider": "WECOM",
    "approvalStatus": "PENDING",
    "approvalStatusName": "审核中",
    "spNo": "202609050002",
    "syncStatus": "REQUESTING",
    "accountStatus": "PENDING",
    "isDefault": "NO"
  }]
}

空数据 / 降级响应

写接口不返回空成功列表；结果不确定时账户保持不可用，前端不得自动重提。

错误响应

{
  "code": 395011,
  "message": "该账户正在审批中，请勿重复提交",
  "success": false,
  "data": null
}

400 表示账户字段或组合规则不合法；395010 表示供应商尚未生效；其他企微错误沿用现有 395019～395022。

业务边界

每个账户独立审批；审核中保持 PENDING 且不可收款、不可设为默认。
企微驳回后为 REJECTED，通过后为 ACTIVE；前端只把 ACTIVE 当作生效账户。

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

更新接口返回成功后，若 data.approval.approvalStatus=PENDING，展示“审核中”并保留正式资料页面值，不做本地乐观覆盖。
通过详情、审批记录或账户列表刷新终态；审批只能在企业微信处理，管理端不发送通过或驳回命令。
联系人数组是完整快照；新增项省略 contactId，已有项同时传 contactId 与 expectedUpdateTime。
所有接口同时检查 HTTP 状态和响应体 code/success。

五、数据库行为

本次无数据库结构或迁移变化。
资料审批中不写正式资料；通过后应用冻结申请，驳回后正式版本和值均不变。
新账户审批中为 PENDING，通过后为 ACTIVE，驳回后为 REJECTED。

六、边界行为

模板审批节点由企业微信配置决定，后端不校验“恰好一级”。
表单固定使用已配置的八个 Text 控件；相关附件与当前正式资料允许为空。
企微回调或轮询完成前，前端只展示受理状态，不推断最终结果。

六.5、枚举 / 数据字典

字段	值	中文	说明
`approvalStatus`	`PENDING`	审核中	尚未终结
`approvalStatus`	`APPROVED`	已通过	业务变更已应用
`approvalStatus`	`REJECTED`	已驳回	业务变更未应用
`accountStatus`	`PENDING`	待审批	账户不可用
`accountStatus`	`ACTIVE`	生效中	账户可用
`accountStatus`	`REJECTED`	已驳回	账户不可用

六.6、修改前后对比

行为	修改前	修改后
`ACTIVE` 供应商保存资料	直接更新正式资料	返回企微审批；通过后更新，驳回不更新
资料保存响应	无独立资料审批结果	返回 `data.approval` 与“审核中”状态
新增账户响应	仅英文审批状态	增加 `approvalStatusName` 中文状态

六.7、影响评估

是否破坏向后兼容: 是；合作中资料保存由同步生效改为异步审批。
前端是否必须同步上线: 是。
前端 workaround 清理点: 删除保存成功后立即以请求值覆盖正式资料的逻辑，改为展示“审核中”并刷新终态。

七、不影响范围

草稿供应商直接保存、注册审批、主体状态审批、合同、默认账户和停用流程不变。
新增账户的请求路径、请求字段和独立审批语义不变。
未新增数据库、配置、Redis、MQ 或错误码。

八、测试环境已验证

PUT  /admin/supplier/items/{supplierId}/update                    → PENDING / 审核中，正式资料保持原值 ✓
企微通过资料变更                                                  → 正式资料更新，身份证号与电话完整值可见 ✓
企微驳回资料变更                                                  → 正式资料和值版本均不变 ✓
POST /admin/supplier/items/{supplierId}/bank-accounts/add         → PENDING / 审核中 ✓
企微通过新增账户                                                  → ACTIVE ✓
企微驳回新增账户                                                  → REJECTED，未激活 ✓

资料审批使用模板 3WNhaxns4i6kfVs74gz4qZQhFxy4iJY4anxMuvYw；八个 Text 控件、实际差异格式、完整身份证号/电话和两个选填项已逐项验证。部署提交为 6bc1c1262e5e4902a893f30fac875d35a65f8a76。

十、相关文档

前端动作与当前状态

合作中资料保存成功后读取 data.approval，展示“审核中”，刷新终态后再更新正式资料。
新增账户直接展示 approvalStatusName，并按 accountStatus 判断是否可用。
新增联系人省略 contactId，已有联系人继续携带 ID 与版本。
当前状态：待前端处理。

11 KiB

原始文件 Blame 文件历史

供应商模块：合作中资料变更接入企微审批

⚠️ 关键变化

二、变更接口清单

三、接口详情

1. 更新供应商 `PUT /admin/supplier/items/{supplierId}/update`

使用场景

入参

出参 `Result<SupplierWriteRespVO>`

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 批量新增收款账户 `POST /admin/supplier/items/{supplierId}/bank-accounts/add`

使用场景

入参

出参 `Result<List<BankAccountSubmitResultRespVO>>`

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

五、数据库行为

六、边界行为

六.5、枚举 / 数据字典

六.6、修改前后对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

前端动作与当前状态

关联 / 联系人

链接

联系人

11 KiB 原始文件 Blame 文件历史 Unescape Escape

供应商模块：合作中资料变更接入企微审批

⚠️ 关键变化

二、变更接口清单

三、接口详情

1. 更新供应商 PUT /admin/supplier/items/{supplierId}/update

使用场景

入参

出参 Result<SupplierWriteRespVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

出参 Result<List<BankAccountSubmitResultRespVO>>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

五、数据库行为

六、边界行为

六.5、枚举 / 数据字典

六.6、修改前后对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

前端动作与当前状态

关联 / 联系人

链接

联系人

11 KiB

原始文件 Blame 文件历史

1. 更新供应商 `PUT /admin/supplier/items/{supplierId}/update`

出参 `Result<SupplierWriteRespVO>`

2. 批量新增收款账户 `POST /admin/supplier/items/{supplierId}/bank-accounts/add`

出参 `Result<List<BankAccountSubmitResultRespVO>>`