From ded9289d984fda8c1a29d0565ec651611d57fb9b Mon Sep 17 00:00:00 2001
From: lc <liuchang@1814.love>
Date: Tue, 25 Aug 2026 12:39:57 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BE=9B=E5=BA=94=E5=95=86=E6=95=8F=E6=84=9F?=
 =?UTF-8?q?=E5=AD=97=E6=AE=B5=E6=A0=A1=E9=AA=8C=E6=94=B6=E7=B4=A7=E4=BA=A4?=
 =?UTF-8?q?=E4=BB=98=EF=BC=88#6312=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...�感字段与数值格�校验收紧-修改接�-管���.md | 454 ++++++++++++++++++
 1 file changed, 454 insertions(+)
 create mode 100644 changelogs-v2/2026-08/25_6312_供应商�感字段与数值格�校验收紧-修改接�-管���.md

diff --git a/changelogs-v2/2026-08/25_6312_供应商�感字段与数值格�校验收紧-修改接�-管���.md b/changelogs-v2/2026-08/25_6312_供应商�感字段与数值格�校验收紧-修改接�-管���.md
new file mode 100644
index 00000000..56f2d977
--- /dev/null
+++ b/changelogs-v2/2026-08/25_6312_供应商�感字段与数值格�校验收紧-修改接�-管���.md
@@ -0,0 +1,454 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6312"
+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: "PR #6322 已�并 dev-v3，�并�交 52a61a88 已由部署任务 b5d27d2b �布到 TEST。供应商新增�修改�注册�交和独立新增收款账户现统一校验税��电���照编��银行账��税率�金��评分�枚举�业务 ID；接�路径�字段�和�功�应结构��。"
+updated_at: "2026-08-25"
+base: "dev-v3"
+---
+
+# 供应商�感字段与数值格�校验收紧
+
+供应商新增�修改�注册�交和独立新增收款账户的输入契约现统一收紧。管�端必须在�交�按本文校验税��电���照编��银行账��税率�金��评分和枚举，并将供应商�表的 `Long` ID 作为规范正整数字符串��。
+
+本次没有新增�删除或�命�字段，也没有改��功�应结构；但以��能被接�的错误格�现在会返回�数错误，因此属于请求兼容性收紧。
+
+## 🔧 关键�化
+
+| 项目 | 修改� | 修改� |
+|---|---|---|
+| �感字段格� | 部分入�仅校验�空或宽�长度，Controller 与 Service �径�能�一致 | Controller 与 Service 使用�一业务�径，绕过 Controller 也�能写入�法值 |
+| 银行账� | 展示格�和规范化�的数字长度缺少完整门� | 去除空格�连字符�必须为 8 至 32 �数字 |
+| 税率�金��评分 | 个别入��进入�续�程��失败 | 请求入��校验范围和�数� |
+| �表业务 ID | `null`�数字令牌�零或溢出值�能被错误解释为新增或类型错误 | �有字段�略表示新增；显� ID 必须是规范正整数字符串 |
+| 枚举 | DTO 与直接 Service 调用的�径�能�一致 | 人员规模�账户�结算��票���类型和��状���层校验 |
+
+业务失败�能�返回 HTTP 200。管�端必须�时判断统一�应中的 `code`�`success`�`message` 和 `data`。
+
+## �更接�清�
+
+| # | 方法 | 路径 | �� | �化 |
+|---:|---|---|---|---|
+| 1 | POST | `/admin/supplier/items/add` | `supplier:create` | 收紧主体��系人�资质和�始账户输入 |
+| 2 | PUT | `/admin/supplier/items/{supplierId}/update` | `supplier:update` | 收紧主体��表 ID���和评价输入 |
+| 3 | POST | `/admin/supplier/items/{supplierId}/submit` | `supplier:update` + `supplier:approval:submit` | 完整注册表��用与新增一致的字段规则 |
+| 4 | POST | `/admin/supplier/items/{supplierId}/bank-accounts/add` | `supplier:account:manage` + `supplier:approval:submit` | 独立账户�用�始账户的账��结算和开票规则 |
+
+## 通用字段规则
+
+### 主体��系人和资质
+
+| 字段 | JSON 类型 | 空值语义 | 当�约� |
+|---|---|---|---|
+| `taxNo` | String | 新增��交必填；修改时�略表示�改 | 原始文本 6 至 64 �，��许字��数字�空格和连字符；�务端移除空格�连字符并转大写��须为 6 至 64 �字�或数字；�识别的统一社会信用代��居民身份��时校验日期或校验� |
+| `contactPhone` | String / null | 公�电���略 | 原始文本 7 至 20 �；去除空格�括��连字符� `+86`/`0086` �，须为中国大陆手机��带 `0` 的座机或 400/800 �务� |
+| `contacts[].contactPhone` | String | 新增�完整�交的�系人必填；修改既有�系人时�略表示�改 | 与公�电�使用�一规范化和��类型规则 |
+| `qualifications[].certNo` | String / null | �稿�空；�交是�必填继续按资质规则判断 | 最大 128 个 UTF-8 字节；超过长度直接拒�，读���返回脱�值 |
+| `staffScale` | String / null | �略表示�改或�设置 | 仅�许 `LT50`�`R50_200`�`R200_500`�`GT500`，区分大�写 |
+
+电�示例：
+
+| 输入 | 结果 |
+|---|---|
+| `+86 138-0013-8000` | 接�，按境内手机�规范化 |
+| `010-12345678` | 接�，按境内座机规范化 |
+| `1234567` | 拒�，消�为 `公��系电�格���法` 或 `�系人电�格���法` |
+| `13800ABC000` | 拒�，电��能包�字� |
+
+### 收款账户�结算和开票
+
+`initialAccounts[]` 与独立账户接� `accounts[]` 使用�一规则：
+
+| 字段 | 必填 | 当�约� |
+|---|---|---|
+| `accountType` | 是 | `CORPORATE`（对公）或 `PERSONAL`（对�） |
+| `bankName` | 是 | �空，最大 500 字符 |
+| `bankBranch` | � | 最大 500 字符 |
+| `accountNo` | 是 | ��许数字�空格和连字符；去除展示分隔符�必须为 8 至 32 �数字 |
+| `settleMode` | � | `PREPAY`�`MONTHLY`�`SINGLE` |
+| `accountPeriod` | �件必填 | �有 `MONTHLY` 必须填写；其他结算方�必须为空 |
+| `invoiceType` | � | `SPECIAL`�`NORMAL`�`NONE` |
+| `taxRate` | �件必填 | `SPECIAL`/`NORMAL` 必填，`NONE` 必须为空；格�为 `0%` 至 `100%`，最多两��数 |
+
+�法税率包括 `0%`�`6%`�`6.5%`�`6.50%`�`100%`�`100.00%`。`5.123%`�`100.01%`�缺少 `%` 或负数�拒�。
+
+### ���评价和枚举
+
+| 字段 | 当�约� |
+|---|---|
+| `contracts[].amount` | `0` 至 `9999999999.99`，最多两��数 |
+| `contracts[].contractType` | `FRAME`�`SINGLE_TRIP`�`PURCHASE` |
+| `contracts[].status` | `DRAFT`�`ACTIVE`�`EXPIRED` |
+| `evaluations[].score` | `0` 至 `5`，最多两��数 |
+
+枚举�区分大�写。空值是�表示“�修改�继续由对应修改字段语义决定；显��交未知值一律拒�。
+
+### 路径和�表业务 ID
+
+路径中的 `{supplierId}` 必须大于 0。JSON 中以下�选�表 ID 使用�一严格规则：
+
+- `contacts[].contactId`
+- `qualifications[].qualificationId`
+- `contracts[].contractId`
+- `evaluations[].evaluationId`
+- `evaluations[].orderId`
+- `evaluations[].resourceId`
+- `evaluations[].evaluator`
+
+| ��值 | 结果 |
+|---|---|
+| 字段�略 | 接�，表示新增�项或未建立�选关� |
+| `"1"` 至 `"9223372036854775807"` | 接�，必须是 1 至 19 �且在 Java `Long` 正整数范围内 |
+| `null`�`""`�`"0"`�`"-1"` | 拒� |
+| `"01"`�`" 1"` | 拒�，��许�导零或空白 |
+| `1` | 拒�，数字 JSON 令牌�能替代字符串 |
+| `"9223372036854775808"` 或 20 �以上数字 | 拒�，超出范围或长度 |
+
+管�端更新已有�项时，应原样回传详情接�返回的字符串 ID；新增�项必须�略 ID 字段，�能传 `null`。
+
+## 接�详情
+
+### 1. 创建供应商�稿 `POST /admin/supplier/items/add`
+
+请求头：
+
+```text
+Authorization: Bearer <accessToken>
+Content-Type: application/json
+```
+
+典型�法请求：
+
+```json
+{
+  "fullName": "示例旅行�务有�公�",
+  "shortName": "示例旅行",
+  "taxNo": "91350211M000100Y46",
+  "contactPhone": "010-12345678",
+  "staffScale": "R50_200",
+  "mainCooperation": "�宿与地接�务",
+  "types": [
+    { "typeCode": "HOTEL" }
+  ],
+  "contacts": [
+    {
+      "contactName": "示例�系人",
+      "contactPhone": "+86 138-0013-8000",
+      "contactRole": "contentBus",
+      "isPrimary": true
+    }
+  ],
+  "initialAccounts": [
+    {
+      "accountType": "CORPORATE",
+      "bankName": "示例银行",
+      "accountNo": "6222 0212 3456 7890",
+      "settleMode": "SINGLE",
+      "invoiceType": "SPECIAL",
+      "taxRate": "6.00%"
+    }
+  ]
+}
+```
+
+�功�应结构��：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "supplierId": "2092000000000000001",
+    "supplierNo": null,
+    "status": "DRAFT",
+    "onboardingStage": "PROFILE_DRAFT",
+    "initialAccounts": [
+      {
+        "accountId": "2092000000000000002",
+        "accountNoMask": "6222********7890",
+        "status": "DRAFT"
+      }
+    ],
+    "updateTime": "2026-08-25 12:35:00"
+  }
+}
+```
+
+无效税��电���照编�或�始账户会在供应商��系人�账户和审批写入�失败。
+
+### 2. 修改供应商 `PUT /admin/supplier/items/{supplierId}/update`
+
+请求头：
+
+```text
+Authorization: Bearer <accessToken>
+Content-Type: application/json
+```
+
+更新已有�系人时，`contactId` 必须使用字符串；新增�系人则�略该字段：
+
+```json
+{
+  "contactPhone": "+86 138-0013-8000",
+  "staffScale": "R200_500",
+  "contacts": [
+    {
+      "contactId": "2092000000000000010",
+      "contactPhone": "010-87654321",
+      "expectedUpdateTime": "2026-08-25 12:35:00"
+    },
+    {
+      "contactName": "新增�系人",
+      "contactPhone": "13900139000",
+      "contactRole": "contentMoney",
+      "isPrimary": false
+    }
+  ],
+  "contracts": [
+    {
+      "contractName": "年度�作框架",
+      "contractType": "FRAME",
+      "amount": 1000000.50,
+      "status": "DRAFT"
+    }
+  ],
+  "evaluations": [
+    {
+      "orderId": "2092000000000000020",
+      "score": 4.75,
+      "content": "履约正常"
+    }
+  ],
+  "changeReason": "更新�系方�与�作资料",
+  "expectedUpdateTime": "2026-08-25 12:35:00"
+}
+```
+
+�功�应�为 `Result<SupplierWriteRespVO>`：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "supplierId": "2092000000000000001",
+    "supplierNo": null,
+    "status": "DRAFT",
+    "onboardingStage": "PROFILE_DRAFT",
+    "initialAccounts": [],
+    "updateTime": "2026-08-25 12:40:00"
+  }
+}
+```
+
+任一�项 ID�金��评分或枚举�法时，整个更新失败，既有主体与�表快照��。
+
+### 3. �交供应商注册 `POST /admin/supplier/items/{supplierId}/submit`
+
+请求头：
+
+```text
+Authorization: Bearer <accessToken>
+Content-Type: application/json
+```
+
+�交接�接收完整注册表�，主体��系人�资质和 `initialAccounts` �用创建接�的全部规则，并�求 `expectedUpdateTime`：
+
+```json
+{
+  "fullName": "示例旅行�务有�公�",
+  "taxNo": "91350211M000100Y46",
+  "contactPhone": "010-12345678",
+  "mainCooperation": "�宿与地接�务",
+  "types": [
+    { "typeCode": "HOTEL" }
+  ],
+  "contacts": [
+    {
+      "contactName": "示例�系人",
+      "contactPhone": "13800138000",
+      "contactRole": "contentBus",
+      "isPrimary": true
+    }
+  ],
+  "qualifications": [
+    {
+      "qualType": "BUSINESS_LICENSE",
+      "certNo": "LIC-2026-000001",
+      "imageUrl": "https://files.example.com/supplier/license.png"
+    }
+  ],
+  "expectedUpdateTime": "2026-08-25 12:40:00"
+}
+```
+
+�功�应结构��：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "approvalLogId": "2092000000000000030",
+    "requestNo": "SUPPLIER-PROFILE-EXAMPLE",
+    "provider": "LOCAL_AUTO",
+    "approvalStatus": "APPROVED",
+    "spNo": null,
+    "spStatus": null,
+    "syncStatus": "APPLIED",
+    "submittedAt": "2026-08-25 12:41:00",
+    "finishedAt": "2026-08-25 12:41:00"
+  }
+}
+```
+
+格�错误会在创建审批事实�失败；必备资质�并�版本���主体和状�机规则��既有语义。
+
+### 4. 独立新增收款账户 `POST /admin/supplier/items/{supplierId}/bank-accounts/add`
+
+请求头：
+
+```text
+Authorization: Bearer <accessToken>
+Content-Type: application/json
+```
+
+请求示例：
+
+```json
+{
+  "accounts": [
+    {
+      "accountType": "CORPORATE",
+      "bankName": "示例银行",
+      "bankBranch": "示例支行",
+      "accountNo": "6222-0212-3456-7890",
+      "settleMode": "MONTHLY",
+      "accountPeriod": "月结30天",
+      "invoiceType": "NORMAL",
+      "taxRate": "6%",
+      "proofFileUrls": [
+        "https://files.example.com/supplier/account-proof.png"
+      ]
+    }
+  ]
+}
+```
+
+�功�应�为按请求顺�返回的数组：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": [
+    {
+      "accountId": "2092000000000000040",
+      "approvalLogId": "2092000000000000041",
+      "requestNo": "SUPPLIER-ACCOUNT-EXAMPLE",
+      "provider": "LOCAL_AUTO",
+      "approvalStatus": "APPROVED",
+      "spNo": null,
+      "spStatus": null,
+      "syncStatus": "APPLIED",
+      "accountStatus": "ACTIVE",
+      "isDefault": "NO",
+      "submittedAt": "2026-08-25 12:45:00",
+      "finishedAt": "2026-08-25 12:45:00"
+    }
+  ]
+}
+```
+
+账��结算或开票组��法时整批在账户和审批写入�失败。供应商尚未完�注册时，�法格��返回既有业务错误 `395010`（`请先完�供应商注册`）。
+
+## 典型错误�应
+
+字段格�失败统一使用业务� `400`，例如：
+
+```json
+{
+  "code": 400,
+  "message": "收款账�规范化�必须为8到32�数字",
+  "success": false,
+  "data": null
+}
+```
+
+| 场景 | `code` | 典型消� |
+|---|---:|---|
+| `{supplierId}` 为 0 | `400` | `供应商ID必须为正数` |
+| 路径 ID 超出 `Long` 范围 | `400` | `�数 supplierId 格�错误，请检查��试` |
+| �识别的统一社会信用代�校验�错误 | `400` | `主体�件�的统一社会信用代�校验���法` |
+| 公�或�系人电��符�境内��规则 | `400` | `公��系电�格���法` / `�系人电�格���法` |
+| �表 ID 显�为 `null`�空�数字令牌�零或溢出 | `400` | `请求数�格�错误：字段 [...] 格�错误` |
+| 账�规范化�少于 8 �或超过 32 � | `400` | `收款账�规范化�必须为8到32�数字` |
+| 税率超过 100% 或多于两��数 | `400` | `税率必须为0%至100%且最多两��数` |
+| ��金�超过范围或多于两��数 | `400` | `��金�最多10�整数和2��数` |
+| 评价分数超过 5 或多于两��数 | `400` | `评分�能大于5` / `评分最多1�整数和2��数` |
+| 未认� | `401` | 统一认�失败；HTTP 状��能�为 200 |
+
+本次没有新增业务错误�；既有���供应商�存在�未注册�必备资质��观�和审批状�错误继续使用原错误�。
+
+## 管�端接入事项
+
+1. 新建�编辑和�交表�按本文在�端�步�制长度�数字格��范围��数�和枚举，��用户�交��看到�端错误。
+2. 银行账�输入��留空格或连字符用于展示，但�交�应确认去除分隔符�为 8 至 32 �数字；��使用 JavaScript `Number` �存账�。
+3. 税率必须�留 `%`；根� `invoiceType` �动必填和清空，根� `settleMode` �动 `accountPeriod`。
+4. 所有�表业务 ID 使用字符串�存和�交。新增项�略 ID，�能传 `null`；�止用 `Number(...)` 转�雪花 ID。
+5. ��金�和评分使用�进制定点输入，分别�制两��数和对应范围。
+6. 接�失败时�留用户表�，展示�端 `message`；�能�判断 HTTP 状�。
+
+## 影�评估与未�化范围
+
+- **是�破���兼容**：对�法请求兼容；对以��能被接�的�法格��兼容。
+- **�端是�需��步**：需�。请求字段和�应结构未�，但表�校验�ID �列化�结算/开票�动应对�。
+- **历�数�**：��移��批��写；存�数�读���影�，下次显�修改相关字段时按新规则校验。
+- **��与状�机**：��，�使用既有管�端角色�平�����观版本�����幂等�审批�审计和软删除规则。
+- **基础设施**：无数�库 migration��置�Redis Key�MQ Topic�Feign 或 Gateway 路由�化。
+- **�应与脱�**：�功�应结构��；税��电���照�和账�读���返回脱�值。
+
+## 验���
+
+- 自动化：12 个供应商�焦测试类全部通过；Resource ��赖模�全� 2018 项测试零失败�零错误，38 项仓库既有�件跳过，13 个 Maven 模�构建�功。
+- 独立审查：�并�交的补�等价�字段边界�Controller/Service 入�一致性和失败零副作用测试�通过，未�现确定性缺�。
+- TEST 部署：部署任务 `b5d27d2b` �功，`hl-resource-service` 的 8182�8082 �实例�次�动；�务器�行�交确认包��并�交 `52a61a88c`，Nacos 两实例�为 healthy�enabled。
+- 真实 Gateway：使用真实有效 SUPER_ADMIN 登录完� 35 项验收，覆盖未认��路径 ID�税��公�电���系人电���照长度��始/独立账户�税率��表 ID���金��评价分数�枚举��法创建�脱�读���法更新和业务状�失败。
+- 零写入：�法�稿建立�的数�库快照为 `1` 个主体�`1` 个类型�`1` 个�系人�`1` 个�始账户�`0` 个审批；全部失败用例执行�快照完全一致。
+- 清�：���稿通过既有删除接��功清�，活动主体�类型��系人�账户�评价和审批�为 0；按审计�求�留 3 �主体�更事实和 2 �账户�更事实，��真实个人或�业数�。
+- �行�康：验收� 8082�8182 ��康，Gateway �达，两实例本次�动日志 `ERROR=0`；未触�文件��置或 MQ 副作用，未生�需�清�的��确认令牌。
+
+## 撤回
+
+1. 从最新 `dev-v3` 创建回退分支，执行 `git revert -m 1 --no-edit 52a61a88c906395d5cafd72cbda2390ad31a02a3`，�新的独立 PR �入。
+2. �新构建并滚动部署 `hl-resource-service`，确认部署�交��包�本工��更。
+3. 无数�库 migration�数�改写��置�Redis�MQ 或跨�务契约�更，�需�执行 DDL�DML�缓存清��消�补�或�置��；现有业务和审计数�����。
+4. 回退�接�路径�字段�和�功�应结构���，但输入接�范围��为本工��的宽��径；管�端若已上线严格校验�继续��，���新接�明显�法值。
+5. � Gateway �跑�法新增�修改��交�独立账户�未认��失败零写入和脱�读�用例，并确认 Nacos �实例�康��务日志无新增错误。
+6. 若撤回本 Changelog，以新的文档�交删除本文件或标记撤回，��写已�布历�。
+
+## 关� / �系人
+
+### 链接
+
+- **Issue**: [#6312](https://git.1814.love:8443/wx/HL/issues/6312)
+- **PR**: [#6322](https://git.1814.love:8443/wx/HL/pulls/6322)
+- **�并�交**: [52a61a88c](https://git.1814.love:8443/wx/HL/commit/52a61a88c906395d5cafd72cbda2390ad31a02a3)
+
+### �系人
+
+- **�端负责人**: @lc