docs(patrol): 2026-06-14 文档维护 — admin-api.md 同步 1:1 约束

[aaronwong1989]

Summary

变更驱动巡逻：自 fb857af1(PR #730)以来 4 个提交，映射到文档影响分析。

修复 docs/reference/admin-api.md，同步 PR #741 fix(security): enforce 1:1 user_id to API key mapping 引入的行为变更：

• 节首补充 user_id ↔ API Key 1:1 映射约束 + 409 Conflict 说明
• POST /admin/api-keys 补充 409 Conflict 响应（user_id 已存在）
• PATCH /admin/api-keys/{id} 补充 409 Conflict 响应（user_id 冲突）
• 顺带修正数据库后缀：SQLite → SQLite 或 PostgreSQL（migration 016 双方言）

影响判定（变更窗口其他提交）

提交	类型	文档动作
5f84b7b5 release v1.29.0	版本号	无需
5c1ebc00 docs(patrol) #740	文档自身	已处理
10763824 config 拆分 + DRY #742	纯内部重构（零逻辑/配置项变更）	无需
8dd4faa8 security 1:1 #741	行为变更	✅ 本次修复

security-model.md / security-hardening.md 描述的是 resolver 机制（未声明映射基数），对 1:1 约束仍准确，不需修改。

Closes #743

🤖 Generated with Claude Code

[hotplex-ai]

Code Review — hotplex-ai

Verdict: APPROVE | P0:0 P1:0 P2:0 P3:2

本次 PR 核心改动（user_id ↔ API Key 1:1 映射约束 + 409 Conflict + DB 双后端）经双 agent 逐项核验，与代码实现精确一致：

• ✅ 1:1 约束 + 409 — requireUniqueUserID + ErrUserIDExists → http.StatusConflict，POST/PATCH 均触发 (apikey_handlers.go:425)
• ✅ POST 201 / 无 DB resolver 时 501 — handler 状态码精确匹配 (apikey_handlers.go:293,323,343,383,443)
• ✅ user_id ≤128 / description ≤512 — 长度校验数值一致 (apikey_handlers.go:301,305,396,400)
• ✅ 脱敏「前 8 + 后 4 位」 — maskAPIKey 实现匹配 (apikey_handlers.go:25-30)
• ✅ DELETE 清除 resolver 缓存 — inv.Invalidate() 调用确认 (apikey_handlers.go:464)
• ✅ DB「SQLite 或 PostgreSQL」 — 双 backend 实现确认（apiKeyUserStore + pgStore，按 cfg.DB.Driver 分发）
• ✅ 端点表 — routes.go:172-176 注册的 5 个路由（方法/路径/Scope）与文档逐一匹配，无遗漏端点
• ✅ 1:1 方向措辞 — 代码用 getByUserID 按 user_id 查重，文档「一个 user_id 仅能关联一个 API Key」方向正确无歧义

---

2 条 pre-existing 友情提示（均非本次 diff 引入，不影响合并，可后续清理）：

• [P3] API Key 生成长度：文档称「32 字节随机 hex」，代码实际 make([]byte, 24) = 24 字节（hpk_ 前缀 + 48 hex 字符，总长 52）。见 apikey_handlers.go:58-62。建议顺带修正为「24 字节随机」。
• [P3] PATCH/DELETE 行反引号不闭合（**PATCH /admin/api-keys/{id}``** 缺闭背引号）。已核对 HEAD~1 确认 pre-existing，非本 PR 引入。

文档与代码一致性审查通过，LGTM 🚀