补充供应商账户驳回终态（#7094）

2026-09-04 23:19:02 +08:00
@@ -0,0 +1,284 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7094"
+title: "供应商账户驳回终态"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端已部署并通过 TEST；前端需将 REJECTED 映射为已驳回且不可用。"
+updated_at: "2026-09-04"
+base: "dev-v3"
+---
+
+# 供应商模块：账户驳回返回明确不可用终态
+
+企微驳回后，后续新增账户由 `PENDING` 改为 `REJECTED`；只有 `ACTIVE` 账户可用于收款或设为默认。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 账户列表 | GET | `/admin/supplier/items/{supplierId}/account-info/list` | 响应枚举扩展 | `bankAccounts[].status` 新增 `REJECTED` |
+| 2 | 账户详情 | GET | `/admin/supplier/bank-accounts/{accountId}/view` | 响应枚举扩展 | `status` 新增 `REJECTED` |
+| 3 | 新增账户 | POST | `/admin/supplier/items/{supplierId}/bank-accounts/add` | 重放结果修正 | 已驳回请求重放返回 `accountStatus=REJECTED` |
+| 4 | 审批变更记录 | GET | `/admin/supplier/items/{supplierId}/approval-records/page` | 查询枚举扩展 | 账户记录支持按 `REJECTED` 筛选并显示“已驳回” |
+
+## 三、接口详情
+
+### 1. 账户列表 `GET /admin/supplier/items/{supplierId}/account-info/list`
+
+**VO**: `SupplierAccountInfoRespVO`
+
+#### 使用场景
+
+账户管理弹窗刷新企微审批后的账户状态。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `supplierId` | Path | String | 是 | 正整数 | 供应商 ID |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data.bankAccounts[].status` | String | 新增 `REJECTED`，表示已驳回且不可用 |
+| `data.bankAccounts[].isDefault` | String | 驳回账户为 `NO` |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/2095000000000000001/account-info/list
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","success":true,"data":{"supplierId":"2095000000000000001","bankAccounts":[{"accountId":"2095000000000000002","status":"REJECTED","isDefault":"NO"}]}}
+```
+
+#### 空数据 / 降级响应
+
+供应商没有可见账户时返回 `bankAccounts=[]`；接口不提供降级成功。
+
+#### 错误响应
+
+```json
+{"code":395001,"message":"供应商不存在","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 前端只有在 `status=ACTIVE` 时才允许选择账户或显示默认操作。
+
+### 2. 账户详情 `GET /admin/supplier/bank-accounts/{accountId}/view`
+
+**VO**: `SupplierBankAccountDetailRespVO`
+
+#### 使用场景
+
+打开单个账户详情时展示当前终态。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `accountId` | Path | String | 是 | 正整数 | 账户 ID |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data.status` | String | 新增 `REJECTED`，表示已驳回且不可用 |
+| `data.isDefault` | String | 驳回账户为 `NO` |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/bank-accounts/2095000000000000002/view
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","success":true,"data":{"accountId":"2095000000000000002","status":"REJECTED","isDefault":"NO"}}
+```
+
+#### 空数据 / 降级响应
+
+账户不存在或不可见时返回业务失败，不返回空成功详情。
+
+#### 错误响应
+
+```json
+{"code":395001,"message":"供应商不存在","data":null,"success":false}
+```
+
+#### 业务边界
+
+- `REJECTED` 只读可见，但不能设为默认账户。
+
+### 3. 新增账户 `POST /admin/supplier/items/{supplierId}/bank-accounts/add`
+
+**VO**: `SupplierBankAccountBatchCreateReqVO → List<BankAccountSubmitResultRespVO>`
+
+#### 使用场景
+
+新增账户提交企微审批，或以同一请求重放已完成结果。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `supplierId` | Path | String | 是 | 正整数 | 已生效供应商 ID |
+| `accounts` | Body | Array | 是 | 1～50 项 | 请求结构不变 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data[].approvalStatus` | String | 已驳回终态为 `REJECTED` |
+| `data[].accountStatus` | String | 已驳回终态由 `PENDING` 修正为 `REJECTED` |
+
+#### 请求示例
+
+```json
+{"accounts":[{"accountType":"CORPORATE","bankName":"示例银行","accountNo":"6222000012345678"}]}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","success":true,"data":[{"accountId":"2095000000000000002","approvalStatus":"REJECTED","accountStatus":"REJECTED","isDefault":"NO"}]}
+```
+
+#### 空数据 / 降级响应
+
+写接口不返回空成功列表；新提交在企微完成前仍返回 `PENDING`。
+
+#### 错误响应
+
+```json
+{"code":395010,"message":"请先完成供应商注册","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 仅已完成驳回的请求返回 `REJECTED`；企微撤销继续沿用既有 `PENDING` 语义。
+
+### 4. 审批变更记录 `GET /admin/supplier/items/{supplierId}/approval-records/page`
+
+**VO**: `SupplierApprovalRecordPageReqVO → PageResult<SupplierApprovalRecordRespVO>`
+
+#### 使用场景
+
+查询账户审批关联的状态变更记录。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `supplierId` | Path | String | 是 | 正整数 | 供应商 ID |
+| `targetType` | Query | String | 否 | 查询账户时传 `ACCOUNT` | 目标类型 |
+| `status` | Query | String | 否 | 新增 `REJECTED` | 变更后状态 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data.records[].status` | String | 驳回记录为 `REJECTED` |
+| `data.records[].statusName` | String | 驳回记录为“已驳回” |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/2095000000000000001/approval-records/page?targetType=ACCOUNT&status=REJECTED&page=1&pageSize=20
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","success":true,"data":{"records":[{"targetType":"ACCOUNT","status":"REJECTED","statusName":"已驳回"}],"total":1}}
+```
+
+#### 空数据 / 降级响应
+
+无匹配记录时返回 `records=[]`；接口不提供降级成功。
+
+#### 错误响应
+
+```json
+{"code":400,"message":"变更目标状态不合法","data":null,"success":false}
+```
+
+#### 业务边界
+
+- `status=REJECTED` 配合 `targetType=ACCOUNT` 使用，不作为供应商主体生命周期筛选值。
+
+## 四、契约约束与正确调用方式
+
+1. 企微处理完成后刷新账户列表，以 `status` 判断账户是否可用。
+2. 将 `REJECTED` 映射为“已驳回”，按不可用样式展示；只有 `ACTIVE` 可设为默认。
+3. 必须检查统一响应的 `code` 和 `success`，不能只判断 HTTP 状态。
+
+## 五、数据库行为
+
+企微驳回完成后，账户最终可观察状态为 `REJECTED`；历史同类异常会同步收敛。将 `REJECTED` 账户设为默认会失败且不改变账户或原默认账户。
+
+## 六、边界行为
+
+- `PENDING`、`REJECTED`、`DISABLED` 均不可用，`ACTIVE` 才可用于收款。
+- 企微撤销仍保留 `PENDING`；本次未新增错误码，也未改变请求字段。
+
+## 六.6、修改前后对比
+
+| 场景 | 修改前 | 修改后 |
+|---|---|---|
+| 企微驳回 | 账户仍返回 `PENDING` | 账户返回 `REJECTED` |
+| 已驳回请求重放 | `accountStatus=PENDING` | `accountStatus=REJECTED` |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 响应枚举扩展；前端需增加未知值处理。
+- **前端是否必须同步上线**: 是。
+- **前端 workaround 清理点**: 删除把企微驳回账户继续显示为“待审批”的兜底逻辑。
+
+## 七、不影响范围
+
+- 不改变供应商注册随单账户的驳回退草稿语义。
+- 不改变企微撤销、审批通过、默认账户或停用流程。
+- 不影响小程序接口；没有新增错误码。
+
+## 八、测试环境已验证
+
+- 列表和详情均返回业务成功，目标账户为 `status=REJECTED`、`isDefault=NO`。
+- 将该账户设为默认返回 `code=395005`、`success=false`，账户与原默认账户均未变化。
+- 企微已驳回且仍为 `PENDING` 的精确异常计数为 0。
+
+## 十、相关文档
+
+- [Issue #7094](https://git.1814.love:8443/wx/HL/issues/7094)
+- [补充 Issue #7119](https://git.1814.love:8443/wx/HL/issues/7119)
+- [PR #7118](https://git.1814.love:8443/wx/HL/pulls/7118)
+- [补充 PR #7121](https://git.1814.love:8443/wx/HL/pulls/7121)
+
+## 前端动作与当前状态
+
+- 将 `REJECTED` 显示为“已驳回”且不可用，只为 `ACTIVE` 显示默认操作。
+- **当前状态：待前端处理。**
+
+## 关联 / 联系人
+
+- **部署提交**: [f861074a84b50eb83fd67729b77f8208747a2095](https://git.1814.love:8443/wx/HL/commit/f861074a84b50eb83fd67729b77f8208747a2095)
+- **后端负责人**: @lc