docs(changelog): 交付供应商暂停与拉黑接口（#6392）

changelogs-v2/2026-08/26_6392_供应商暂停合作与拉黑原因必填接口-新增接口-管理后台.md

@@ -0,0 +1,114 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6392"
+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 #6403 已合并 dev-v3；两个状态命令已部署 TEST，ACTIVE→SUSPENDED、ACTIVE/SUSPENDED→BLACKLIST、原因审计、权限、并发、幂等和失败零写入均经真实 Gateway 验证。前端待接入原因弹窗与并发版本。"
+updated_at: "2026-08-26"
+base: "dev-v3"
+---
+
+# 供应商暂停合作与拉黑原因必填接口
+
+供应商管理新增两个窄状态命令：暂停合作与列入黑名单。服务端强制要求业务原因和调用方读取到的并发版本，并沿用可信管理员身份、专用平台权限、聚合锁、短窗幂等、行锁、状态机及同事务审计。
+
+## 变更接口
+
+| 方法 | 路径 | 允许来源状态 | 目标状态 |
+|---|---|---|---|
+| POST | `/admin/supplier/items/{supplierId}/suspend` | `ACTIVE` | `SUSPENDED` |
+| POST | `/admin/supplier/items/{supplierId}/blacklist` | `ACTIVE`、`SUSPENDED` | `BLACKLIST` |
+
+两个接口都要求真实 `SUPER_ADMIN` 身份且拥有 `supplier:status:manage` 平台权限。前端按钮可按角色和状态控制展示，但不能替代服务端门禁。
+
+## 公共请求
+
+```json
+{
+  "reason": "供应商连续违约，暂停合作复核",
+  "expectedUpdateTime": "2026-08-26 15:40:00"
+}
+```
+
+| 字段 | 类型 | 必填 | 规则 |
+|---|---|---|---|
+| `reason` | string | 是 | 去除首尾空白后必须非空，最长 500 字符；规范化后的原因为状态审计内容 |
+| `expectedUpdateTime` | string | 是 | 调用方最近一次读取到的供应商 `updateTime`，格式 `yyyy-MM-dd HH:mm:ss` |
+
+路径参数 `supplierId` 必须为正 Long。请求体不接受角色、操作者或目标状态，身份仅来自 Gateway 验证后的可信属性。
+
+## 成功响应
+
+暂停合作成功：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "supplierId": "1900000000000000001",
+    "status": "SUSPENDED",
+    "updateTime": "2026-08-26 15:40:01"
+  }
+}
+```
+
+拉黑成功时结构相同，`status` 为 `BLACKLIST`。`supplierId` 固定为 JSON string；后续状态命令必须使用响应或详情中的新 `updateTime`，不能继续提交旧版本。
+
+每次成功迁移与一条 `supplier_change_log` 状态审计在同一本地事务内提交。审计记录包含 `fromStatus`、`toStatus`、操作者、角色、Trace ID 和规范化后的 `reason`；审计写入失败时状态整体回滚。
+
+## 失败语义
+
+| 场景 | 业务码 | 结果 |
+|---|---:|---|
+| 未登录或 Token 无效 | `401` | Gateway/服务认证拒绝，零业务写入 |
+| `reason` 缺失、空白、纯空格、超过 500 字符，或缺少版本 | `400` | 参数/服务双层拒绝，零业务写入 |
+| 供应商不存在或已软删除 | `395001` | 零业务写入 |
+| 非 `SUPER_ADMIN` 或缺少 `supplier:status:manage` | `395004` | 专用状态权限失败关闭，零业务写入 |
+| suspend 来源不是 `ACTIVE`；blacklist 来源不是 `ACTIVE/SUSPENDED` | `395005` | 状态机拒绝，零业务写入 |
+| `expectedUpdateTime` 与数据库秒级版本不一致 | `395014` | 状态和审计均不写入，调用方应刷新后重试 |
+| 5 秒内同操作者、供应商和相同请求重复提交 | `100502` | 重复请求被拒绝，不产生第二条状态审计 |
+
+统一响应可能以 HTTP 200 承载业务失败，客户端必须同时检查 `code`、`success`、`message` 和 `data`。
+
+## 前端联调事项
+
+- 在合作中供应商上提供“暂停合作”和“列入黑名单”；暂停合作供应商仅提供“列入黑名单”。其他状态不展示这两个动作。
+- 点击动作后弹出必填原因输入框，前端限制 500 字符；提交详情或列表中最近一次读取到的 `updateTime`。
+- `395014` 应提示数据已变化并刷新详情；`395005` 应刷新当前状态；`100502` 应提示不要重复提交。
+- 成功后使用响应中的 `status` 和 `updateTime` 更新页面或重新拉取详情/列表。
+- 前端显示控制不构成授权；不得从请求体传入操作者、角色或目标状态。
+
+## 验证证据
+
+- 代码：PR #6403 合并提交为 `3f3a0bf734737ca0e84ed1cfcad1801835cd46d5`；供应商目标测试 62 项通过，Resource 全量 2100 项通过、0 失败、0 错误（38 项既有条件跳过），Gateway 路由/认证 9 项通过，`hl-verify` 全部通过。
+- 部署：原规范任务 `d08c52f6` 成功，目标/实际提交均为 `4b31612aeba5c0d3ac690cc6af15b66290bd8b48`；只读恢复绑定原任务期样本，5 个可验证样本均健康、3 个本地不可验证样本、0 个故障样本，没有重复部署。
+- 当前制品：后续同服务规范任务 `da90f211` 将 TEST 更新为 `dev-v3@692547a5989ec1f8fa1b1495fc8dd501cddc0fe0`，该提交包含本工单合并提交；6/6 个任务期样本均为双进程、Nacos 双 healthy/enabled 且端口匹配，0 不可验证、0 故障样本。本工单最终业务验收在该当前制品上完成。
+- 真实 Gateway：验证 `ACTIVE→SUSPENDED→BLACKLIST` 和 `ACTIVE→BLACKLIST`，成功响应、详情状态、并发版本与同事务审计一致；原因首尾空白按规范化值入审计。
+- 失败分支：未认证、真实 `CUSTOMIZER` 越权、原因缺失/空白/超长、缺版本、旧版本、DRAFT 来源、不存在对象、重复状态与短窗重复请求全部返回预期错误，主体版本、状态和审计计数均保持不变。
+- 清理：仅创建 3 个随机 TEST 草稿，并以 ID、随机全名、当前状态三重条件设置 2 个 ACTIVE 夹具；未触碰既有供应商。验收后精确恢复 2 行为 DRAFT，再通过业务删除接口软删除全部 3 个夹具；有效供应商总量恢复为 4，`HL6392-` 活跃命名空间为 0。9 条脱敏审计按系统约定保留；两枚验收会话已注销，幂等键等待 6 秒自然过期，未手工修改 Redis。
+
+## 撤回
+
+1. 从最新 `dev-v3` 创建独立回退分支，执行 `git revert -m 1 --no-edit 3f3a0bf734737ca0e84ed1cfcad1801835cd46d5`，经评审 PR 合入；不要回退后续无关提交。
+2. 通过 Deploy Panel API 对精确回退目标执行新鲜预检和显式部署 `hl-resource-service`，复核双实例、Nacos、日志以及既有供应商查询、建档、资料更新和审批链路。
+3. 本次无 DDL、配置、Redis、MQ 或跨服务写入变更，不执行 schema、缓存或消息回退。
+4. 已实际发生的 `SUSPENDED`、`BLACKLIST` 状态和审计不会随代码回退自动反转；禁止直接改库，只能由后续合法恢复合作/解除黑名单业务流程处理。
+5. 回退后两个新增 POST 接口恢复不可用；前端在回退部署前隐藏/停用对应动作，并继续兼容既有供应商接口。
+
+## 关联 / 联系人
+
+- **Issue**: [#6392](https://git.1814.love:8443/wx/HL/issues/6392)
+- **PR**: [#6403](https://git.1814.love:8443/wx/HL/pulls/6403)
+- **合并提交**: [3f3a0bf73](https://git.1814.love:8443/wx/HL/commit/3f3a0bf734737ca0e84ed1cfcad1801835cd46d5)
+- **后端负责人**: @lc

changelogs-v2/2026-08/26_6409_行政区划响应ID固定为字符串-修改接口-管理后台.md

@@ -0,0 +1,64 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6409"
+title: "行政区划响应 ID 固定为字符串"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #6412 已合并 dev-v3；hl-user-service 已以提交 4b31612a 部署 TEST，create、children、path 经真实 Gateway 验证全部 Long ID 固定为 JSON string，空层级保持 null。"
+updated_at: "2026-08-26"
+base: "dev-v3"
+---
+
+# 行政区划响应 ID 固定为字符串
+
+行政区划创建、单级联动和父链回显接口中的 Long ID 现在始终按 JSON 字符串返回，避免小整数因全局安全整数规则被输出为 JSON number。请求参数、权限、业务校验和错误码不变。
+
+## 变更接口
+
+| 方法 | 路径 | 响应变化 |
+|---|---|---|
+| POST | `/admin/region` | 成功响应 `data` 从 JSON number 固定为 string |
+| GET | `/admin/region/children` | `parentId`、`defaultId`、`items[].id`、`items[].parentId` 固定为 string；空值保持 `null` |
+| GET | `/admin/region/{id}/path` | `selectedId`、`provinceId`、`prefectureId`、`countyId` 及 `path` 节点 ID 固定为 string；缺失层级保持 `null` |
+
+更新接口 `PUT /admin/region/{id}` 的请求和响应不变。所有请求路径、Query/Path 参数仍按原 Long 语义解析。
+
+## 兼容性与错误语义
+
+- 这是已发布接口 JSON 类型的契约修正，不新增字段，也不改变字段名称。
+- 行政区划 Redis 缓存可同时反序列化旧 JSON number 与新 JSON string，滚动部署期间兼容。
+- 根层 `parentId`、无默认节点的 `defaultId` 和父链中不存在的层级继续返回 `null`，不会变成字符串 `"null"`。
+- 未认证请求继续返回业务码 `401`；非法正整数参数、缺失节点和非法节点类型继续使用既有错误语义，失败路径零业务写入。
+- 无数据库 migration、配置、Gateway、MQ、缓存键或跨服务契约变更；无需修改前端源码，调用方按既定字符串 ID 契约消费即可。
+- 统一响应可能以 HTTP 200 承载业务失败，客户端必须同时检查 `code`、`success`、`message` 和 `data`。
+
+## TEST 验证证据
+
+- PR #6412 合并提交为 `8494028aa2dfbb4e39147c09695898d247045d4c`；TEST 目标提交 `4b31612aeba5c0d3ac690cc6af15b66290bd8b48` 包含该合并提交。
+- Deploy Panel API 任务 `b10dd2ed` 成功执行 `/opt/hulalv/scripts/deploy-backend.sh`；User 的 8081、8181 双实例和 Nacos 两个 healthy/enabled 实例通过，任务期 9 个可验证采样均有可用实例，0 个故障采样。
+- 真实 TEST 管理员经 Gateway 验证 create、children、path：创建 ID、联动列表 ID、父链 ID 和对应 Redis 缓存 ID 均为字符串，根节点和缺失层级空值保持 `null`。
+- 未认证请求返回 `401`；非法父节点、缺失节点、空创建和旧非法节点类型均按既有错误返回，并确认失败路径零写入。
+- 成功创建和 CAS 更新后，精确删除本次创建的 1 行；数据库总量恢复且测试命名空间为 0。4 个相关 Redis key 按基线值及绝对过期时间恢复，验收会话已注销；操作审计按系统约定保留。
+- 本地验证：Controller/Cache 定向 22 项通过；User 全量 3644 项通过、0 失败、0 错误，8 项条件跳过；`hl-verify` 与 `git diff --check` 通过。
+
+## 撤回
+
+1. 从最新 `dev-v3` 创建独立回退分支，执行 `git revert -m 1 --no-edit 8494028aa2dfbb4e39147c09695898d247045d4c`，经评审 PR 合入；不要回退后续无关提交。
+2. 通过 Deploy Panel API 对回退目标执行新鲜预检和显式部署 `hl-user-service`，复核双实例、Nacos、日志和精确提交。
+3. 本修复无数据库、配置或 MQ 变更，不执行 DDL、DML 或消息补偿。缓存新旧表示均可读取，通常无需清理；确需强制恢复旧表示时，仅在停止行政区划刷新后精确处理 `hl:user:region:v1:` 命名空间并由回退版本预热。
+4. 撤回前确认调用方可重新接受 JSON number ID；撤回后经 Gateway 复测 create、children、path、空层级、未认证和失败零写入。
+
+## 关联 / 联系人
+
+- **Issue**: [#6409](https://git.1814.love:8443/wx/HL/issues/6409)
+- **PR**: [#6412](https://git.1814.love:8443/wx/HL/pulls/6412)
+- **合并提交**: [8494028aa](https://git.1814.love:8443/wx/HL/commit/8494028aa2dfbb4e39147c09695898d247045d4c)
+- **后端负责人**: @lc