docs: #8006 改 base=main（hl-api-changelog 仓无 dev-v3 分支）

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
docs: #8006 补充网关实测证据，改 gateway_status=verified，删除未验证的零写入说法
2026-09-21 23:22:32 +08:00 · 2026-09-21 23:22:32 +08:00 · 2026-09-21 23:22:32 +08:00
@@ -6,15 +6,15 @@ consumer: "admin"
 author: "wx(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
-gateway_status: "not_required"
+gateway_status: "verified"
 frontend_status: "pending"
 frontend_owner: ""
 frontend_ref: ""
 target_release: ""
 verified_at: ""
-status_note: "gateway_status: not_required 待确认——新增入参 scopeRoles 可能涉网关字段白名单，但无网关实测数据；错误码/响应体改动对网关无影响。PR #8117 已合入 dev-v3（合并提交 094521f0b），当前测试环境部署 commit d30cd9561，本次变更已在线。"
+status_note: "2026-09-21 于网关 https://api.test.1814.love:9443 经验证：带 scopeRoles 的请求触发错误码 582115 并返回预期报文（「提交的人员角色（GUIDE）超出本次保存声明的角色范围（PHOTOGRAPHER）」），去掉 scopeRoles 同一笔请求返回 200 走全量覆盖；这证实网关透传了新增字段 scopeRoles 无拦截或裁剪，后端校验正常执行。PR #8117 已合入 dev-v3（合并提交 094521f0b），当前测试环境部署 commit d30cd9561。"
 updated_at: "2026-09-21"
-base: "dev-v3"
+base: "main"
 ---

 # 团期人员配置：保存接口新增角色范围声明，支持按配置位分部分保存
@@ -31,7 +31,7 @@ base: "dev-v3"

 **现在可选择：不传 `scopeRoles` 时行为不变（整期全量覆盖），传了则只覆盖指定的几个角色，别的角色既有人员保持不动。导游位与摄影位终于能互不干扰地维护。**

-同时新增一个拒绝条件：提交的人员角色如果落在 `scopeRoles` 声明的范围之外，后端拒绝（错误码 `582115`）且**零写入**，不会把超出范围的人员静默插进数据库。
+同时新增一个拒绝条件：提交的人员角色如果落在 `scopeRoles` 声明的范围之外，后端拒绝（错误码 `582115`），不会接受超出范围的人员配置。

 ---

@@ -255,7 +255,7 @@ base: "dev-v3"
 #### 业务边界

 - **覆盖范围不校验完整性**：你可以只传 `scopeRoles=["GUIDE"]` 而保存时含有领队，后端照做。只覆盖 GUIDE 那一行，领队那一行在范围外。这个设计缺口（没有校验"GUIDE+LEADER 必须同时出现"）已在工单 #8122 记录，**前端若需保证配置位完整性，当前需自己在前端侧把关**。
- **范围外人员拒绝率 100%**：如果 staffList 里有任何一项的 `staffRole` 不在 `scopeRoles` 声明的范围内，整个请求 `582115` 拒绝，**零写入**（既不删旧行、也不插新行、既不扇出）。
+- **范围外人员拒绝率 100%**：如果 staffList 里有任何一项的 `staffRole` 不在 `scopeRoles` 声明的范围内，整个请求 `582115` 拒绝。失败时前端建议重新拉取当前配置以确保数据一致性。
 - **导游位的特殊性**：导游位由 `GUIDE` 和 `LEADER` 两个角色共同维护。保存导游位配置时，`scopeRoles` 必须同时包含 `["GUIDE", "LEADER"]`。只传其中一个（如 `["GUIDE"]`）会导致另一个角色的人员被拒（582115）。

 ---
@@ -12,7 +12,7 @@ frontend_owner: ""
 frontend_ref: ""
 target_release: ""
 verified_at: ""
-status_note: "本条无任何接口出入参或错误码变化，变的是同一请求的副作用：共用关系现在会在成员失去占用时自动收缩、剩余不足 2 人时自动解除。gateway_status=verified 的依据是 2026-09-21 经网关 https://api.test.1814.love:9443 的真实调用（建关系 + 两次 soft-clear-assignment），调用流水与库内终态逐条对照一致，不是只看部署登记。frontend_status 取 pending 而非 not_required：本条会让共用关系『自己消失』，前端是否需要改代码取决于它有没有缓存 activeShareGroupId 或假设关系只能人工解除——那是我无法从后端查证的事实，所以不替前端下 not_required 的结论；mmg 评估后若确认零改动，再由前端侧改为 not_required。⚠️ 存量收敛已于 2026-09-21 执行完毕（AC-5）：经应用路径点名收敛，摘除成员行 10 条、整体释放关系 4 条；另有 2 条关系在摘除成员后仍保持 ACTIVE——那是正确终态，收缩规则是「剩余成员 < 2 时才整体释放」，这 2 条原各 3 名成员、摘 1 名后仍剩 2 名。本轮为点名执行而非全库扫，名单外可能仍存在同类历史数据，前端展示逻辑该兜的仍要兜。前端实证 not_required(mmg 2026-09-21):按「四、前端要做什么」逐项自查——activeShareGroupId/shareGroup/share-groups/shareEligible 前端 src 全仓零命中(共用关系属 #7444 未接入挂起域,同 #8051/#8061 实证口径),前端无任何共用关系状态缓存、无「关系只能人工解除」的假设;未来接入时均为操作后实时拉取,自动收缩不产生前端脏读。"
+status_note: "本条无任何接口出入参或错误码变化，变的是同一请求的副作用：共用关系现在会在成员失去占用时自动收缩、剩余不足 2 人时自动解除。gateway_status=verified 的依据是 2026-09-21 经网关 https://api.test.1814.love:9443 的真实调用（建关系 + 两次 soft-clear-assignment），调用流水与库内终态逐条对照一致，不是只看部署登记。本条会让共用关系『自己消失』，前端是否需要改代码取决于两点：有没有缓存 activeShareGroupId、有没有「关系只能人工解除」的假设。这两点后端查证不了，已由前端侧自查确认（见下文 mmg 的实证）。⚠️ 存量收敛已于 2026-09-21 执行完毕（AC-5）：经应用路径点名收敛，摘除成员行 10 条、整体释放关系 4 条；另有 2 条关系在摘除成员后仍保持 ACTIVE——那是正确终态，收缩规则是「剩余成员 < 2 时才整体释放」，这 2 条原各 3 名成员、摘 1 名后仍剩 2 名。本轮为点名执行而非全库扫，名单外可能仍存在同类历史数据，前端展示逻辑该兜的仍要兜。前端实证 not_required(mmg 2026-09-21):按「四、前端要做什么」逐项自查——activeShareGroupId/shareGroup/share-groups/shareEligible 前端 src 全仓零命中(共用关系属 #7444 未接入挂起域,同 #8051/#8061 实证口径),前端无任何共用关系状态缓存、无「关系只能人工解除」的假设;未来接入时均为操作后实时拉取,自动收缩不产生前端脏读。"
 updated_at: "2026-09-21"
 base: "dev-v3"
 ---