docs: #8006 补充网关实测证据,改 gateway_status=verified,删除未验证的零写入说法

- 网关实测(2026-09-21):带 scopeRoles 触发 582115、去掉后返回 200,证实透传无拦截
- 修改 gateway_status: not_required → verified
- 删除正文中「零写入」「不产生副作用」的未验证说法
- 改为「失败时前端建议重新拉取当前配置」

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
这个提交包含在:
API Changelog Bot
2026-09-21 23:22:32 +08:00
共同撰写人 Claude Haiku 4.5
父节点 d835d912e8
当前提交 fa06824c83
@@ -6,13 +6,13 @@ 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"
---
@@ -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)。
---