docs: design interception optimistic concurrency contract

docs/feature/tool-guard-conflict-detection.md

@@ -19,3 +19,13 @@ Lifecycle Report：F0–F6；影响 handler、调用拦截 JS 和文档；权限
 - REQ-003 / AC-003：输入校验、权限、试匹配、落盘失败保持原策略行为继续成立。
 - 范围解释：现接口提交整个列表，按整份配置保护，避免不同规则的旧快照相互覆盖。无需等待用户退出编辑，正常刷新后的后续修改允许保存。
 - 非目标：编辑期间占用租约、多实例共享配置支持、发布或部署。
+
+## F2 Design
+
+GET /api/tool-guard 的 JSON 不变，提供强 ETag 和 Cache-Control: no-store。版本由随机 nonce 和当前有效配置摘要组成；每次成功保存更换 nonce（包括无变化保存），直接更新 manager 也会改变摘要，防止 ABA 旧版本恢复。版本状态归 ConfigHandler，读取/比较/推进由 h.mu 保护。
+
+PUT 必须携带完整精确匹配的 If-Match；未提供返回 428/tool_guard_version_required，不匹配返回 409/tool_guard_conflict。校验、落盘、策略发布、版本推进在同一个保存临界区，失败不推进版本、不返回成功；成功返回新 ETag。星号、弱标签不作为覆盖保护绕过方式。服务重启后旧版本失效。
+
+前端将 ETag 独立保存，PUT 携带读取时版本，成功才更新；冲突不采用错误响应上的新版本、不自动重试，保留原输入。中英俄文提示：配置已被其他用户修改，本次修改未保存，请刷新后重试。试匹配不带 If-Match，不更新版本。缺少响应版本不能静默发无条件写入。
+
+兼容：旧 API 客户端需先 GET 再使用返回 ETag 提交 PUT；前后端同时升级，更新脚本缓存版本。整个列表任意编辑触发版本变化，不同规则同时保存也会冲突。仅保证当前服务实例内协调；多实例共享配置需另行引入持久化条件更新。