From e24d03a19c496cfe9e14cc8151ea1c48d3426829 Mon Sep 17 00:00:00 2001 From: lc Date: Tue, 8 Sep 2026 17:32:07 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BA=A4=E4=BB=98=E4=BE=9B=E5=BA=94?= =?UTF-8?q?=E5=95=86=E8=B4=A6=E6=9C=9F=E4=B8=8E=E8=AF=81=E7=85=A7=E5=9B=BE?= =?UTF-8?q?=E7=89=87=E5=A5=91=E7=BA=A6=EF=BC=88#7318=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...删除账期并必填证照图片-修改接口-管理后台.md | 610 ++++++++++++++++++ 1 file changed, 610 insertions(+) create mode 100644 changelogs-v2/2026-09/08_7318_供应商删除账期并必填证照图片-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/08_7318_供应商删除账期并必填证照图片-修改接口-管理后台.md b/changelogs-v2/2026-09/08_7318_供应商删除账期并必填证照图片-修改接口-管理后台.md new file mode 100644 index 00000000..e497f5c7 --- /dev/null +++ b/changelogs-v2/2026-09/08_7318_供应商删除账期并必填证照图片-修改接口-管理后台.md @@ -0,0 +1,610 @@ +--- +schema: "hl-changelog/v2" +ticket: "7318" +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: "待前端移除账期输入与展示，并将证照图片设为必填" +updated_at: "2026-09-08" +base: "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 | 原有写入/审批结果；初始账户摘要原本就没有账期 | + +#### 请求示例 + +```http +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" + } + ] +} +``` + +#### 响应示例 + +```json +{"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"}} +``` + +#### 空数据 / 降级响应 + +不存在的记录按原有业务错误返回；不会使用空成功结果兜底。 + +#### 错误响应 + +```json +{"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 | 原有写入/审批结果；初始账户摘要原本就没有账期 | + +#### 请求示例 + +```http +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" + } + ] +} +``` + +#### 响应示例 + +```json +{"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"}} +``` + +#### 空数据 / 降级响应 + +不存在的记录按原有业务错误返回；不会使用空成功结果兜底。 + +#### 错误响应 + +```json +{"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 | 原有写入/审批结果；初始账户摘要原本就没有账期 | + +#### 请求示例 + +```http +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" +} +``` + +#### 响应示例 + +```json +{"code":200,"message":"成功","data":{"approvalLogId":"731803","requestNo":"supplier-example-7318","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中"}} +``` + +#### 空数据 / 降级响应 + +不存在的记录按原有业务错误返回；不会使用空成功结果兜底。 + +#### 错误响应 + +```json +{"code":400,"message":"证照图片不能为空","data":null} +``` + +#### 业务边界 + +- 上传成功取得非空图片地址后再提交；缺图拒绝当前请求。 + +### 4. 新增收款账户 `POST /admin/supplier/items/{supplierId}/bank-accounts/add` + +**VO**: `SupplierBankAccountBatchCreateReqVO → List` + +#### 使用场景 + +供应商管理页面新增收款账户。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| 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 | 原有写入/审批结果；初始账户摘要原本就没有账期 | + +#### 请求示例 + +```http +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" + } + ] +} +``` + +#### 响应示例 + +```json +{"code":200,"message":"成功","data":[{"accountId":"731802","approvalLogId":"731803","requestNo":"supplier-example-7318","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中","accountStatus":"PENDING","isDefault":"NO"}]} +``` + +#### 空数据 / 降级响应 + +不存在的记录按原有业务错误返回；不会使用空成功结果兜底。 + +#### 错误响应 + +```json +{"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 | 原有写入/审批结果；初始账户摘要原本就没有账期 | + +#### 请求示例 + +```http +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" +} +``` + +#### 响应示例 + +```json +{"code":200,"message":"成功","data":{"accountId":"731802","approvalLogId":"731803","requestNo":"supplier-example-7318","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中","accountStatus":"ACTIVE","isDefault":"NO"}} +``` + +#### 空数据 / 降级响应 + +不存在的记录按原有业务错误返回；不会使用空成功结果兜底。 + +#### 错误响应 + +```json +{"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 | 已删除 | 字段不再返回，删除页面账期展示 | + +#### 请求示例 + +```http +GET https://api.test.1814.love:9443/admin/supplier/items/731801/account-info/list +Authorization: Bearer <当前有效登录会话> + +无请求体 +``` + +#### 响应示例 + +```json +{"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。 + +#### 错误响应 + +```json +{"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 | 已删除 | 字段不再返回，删除页面账期展示 | + +#### 请求示例 + +```http +GET https://api.test.1814.love:9443/admin/supplier/bank-accounts/731802/view +Authorization: Bearer <当前有效登录会话> + +无请求体 +``` + +#### 响应示例 + +```json +{"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"}} +``` + +#### 空数据 / 降级响应 + +不存在的记录按原有业务错误返回；不会使用空成功结果兜底。 + +#### 错误响应 + +```json +{"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 | 已删除 | 字段不再返回，删除页面账期展示 | + +#### 请求示例 + +```http +PUT https://api.test.1814.love:9443/admin/supplier/bank-accounts/731802/default/update +Authorization: Bearer <当前有效登录会话> + +无请求体 +``` + +#### 响应示例 + +```json +{"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"}} +``` + +#### 空数据 / 降级响应 + +不存在的记录按原有业务错误返回；不会使用空成功结果兜底。 + +#### 错误响应 + +```json +{"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](https://git.1814.love:8443/wx/HL/issues/7318)、[补充工单 #7350](https://git.1814.love:8443/wx/HL/issues/7350)、[PR #7349](https://git.1814.love:8443/wx/HL/pulls/7349)、[PR #7351](https://git.1814.love:8443/wx/HL/pulls/7351)。 + +## 关联 / 联系人 + +### 联系人 + +- **后端负责人**: @lc +- **当前状态**：前端待适配。