docs(02): qy-lty-admin Phase 2 CONTEXT.md（RBAC + 入口控件 PRD 快速通道，--skip-ui）

qy-lty-admin/.planning/phases/02-rbac-ai/02-CONTEXT.md

@@ -0,0 +1,128 @@
+# Phase 2：RBAC 收敛 + AI 模型页入口 - Context
+
+**Gathered**: 2026-05-08
+**Status**: Ready for planning（用户选择 `--skip-ui` 跳过 UI-SPEC，直接规划）
+**Source**: 用户在 `/gsd-plan-phase 2` 调用时提供的内联约束
+
+<domain>
+## Phase 边界
+
+本 phase 是 Milestone v1.0 前端集成的**第二步**，把 Phase 1 落地的 API client 接到权限矩阵和 AI 模型页：
+- 在 `lib/permissions.ts` 声明 `credential-slot` 模块 key + 配置 RBAC 矩阵
+- 在 `app/ai-model/page.tsx` 加入入口控件（按钮）+ 占位空对话框
+- 入口控件可见性走 `hasPermission('credential-slot')`，不直接读 localStorage
+
+**不负责**（留给 Phase 3）：
+- 编辑对话框真实内容（表单 RHF + Zod + 提交逻辑 + 留空保留旧值语义）
+- Sonner toast 反馈（成功 / 失败）
+- 端到端串联（admin PUT → toast → 重新打开看到新末 4 位 + updated_at）
+
+</domain>
+
+<decisions>
+## 实现决策（锁定）
+
+### CRED-FE-02 RBAC 模块声明
+
+- **`PermissionModule` 类型扩充**：在 `lib/permissions.ts` 找到 `PermissionModule` 类型定义，在 union 中添加 `'credential-slot'` 字面量
+- **`PERMISSION_MATRIX` 矩阵**：将 `'credential-slot'` 加入到「超级管理员」+「AI模型管理员」两个角色的模块列表（researcher 必须 read 完整矩阵给出每个角色当前包含哪些模块；这两个角色的列表末尾追加即可）
+- **其他 3 个角色**（内容管理员 / 卡牌管理员 / 查看者）+ 1 个可能的「管理员」角色：**不**包含 `credential-slot`（保持原数组不变）
+- **`getModuleFromPath('/ai-model')` 行为不变**：`/ai-model` 路径已映射到 `'ai-model'` 模块（researcher 确认），凭据槽位是 `/ai-model` 的子能力，不占独立路由 → 不要给 `getModuleFromPath` 加 `'/ai-model/credential-slot'` 之类映射
+
+### CRED-FE-03 /ai-model 页面入口
+
+- **入口控件类型**：**Button**（不是 Card）—— 最简、与现有页面风格一致；样式沿用 shadcn Button 组件（`components/ui/button.tsx`），variant="outline" 或现有页面其他按钮的 variant
+- **位置**：在 `app/ai-model/page.tsx` 的 **页面顶部 / 头部 / 工具栏区域**（researcher 必须 read 现有页面结构给出具体插入点 —— 最可能是页面头部的标题旁边或现有"添加 AI 模型"之类按钮的同行右侧）
+- **图标**：**KeyRound**（Lucide）—— 凭据语义最贴切；如果不可用降级到 `Lock` / `Settings`
+- **文案**：按钮内文字 **"凭据槽位"**（中文）
+- **可见性约束**：用 `hasPermission('credential-slot')` 包裹整个 Button JSX；不渲染时 DOM 中**完全不存在**（`{hasPermission('credential-slot') && <Button>...</Button>}`）
+- **点击行为**：本 phase 触发**占位空对话框**打开（基于 `components/ui/dialog.tsx`），对话框内容仅 DialogTitle + DialogDescription（中文文案"通用凭据槽位"+ 说明"对话框真实内容由 Phase 3 落地"），无表单
+- **对话框组件位置**：在 `app/ai-model/page.tsx` 内联（不抽到独立文件 —— Phase 3 会把对话框抽到 `components/ai-model/CredentialSlotDialog.tsx`）
+- **状态管理**：用 `useState<boolean>` 控制 dialog open 状态
+
+### 兼容性 / 不引入新依赖
+
+- 沿用现有依赖：`components/ui/button.tsx`、`components/ui/dialog.tsx`、`lucide-react`、`lib/permissions.ts:hasPermission`
+- 不引入新依赖（不动 lockfile，不跑 npm install）
+- 不动 `lib/permissions.ts` 的其他函数（`getUserRole` / `hasPathPermission` 等）
+
+### 修改记录
+
+`qy-lty-admin/docs/修改记录.md` 顶部追加一条 Phase 2 条目：
+- 文件路径：`lib/permissions.ts`、`app/ai-model/page.tsx`
+- 修改类型：新增 / 修改
+- 跨项目联动：「无 — Phase 2 是纯前端 RBAC + UI 入口落地，不引入新跨项目契约；后端 commit 46d72b8 已建立的互引仍有效；Phase 3 引入实质 PUT 调用时若涉及新契约再评估」
+
+### Claude's Discretion
+
+- 入口 Button 的具体 `variant`（outline / default / secondary）—— planner 看现有页面其他按钮风格选最一致的
+- 入口 Button 的 `size`（默认 / sm / lg）—— 同上
+- 占位对话框的 DialogContent `className` 大小 —— 用默认即可
+- 是否给 Button 加 tooltip（KeyRound 图标语义不够明显时）—— 推荐加，让运营秒懂
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**下游 agent 必读**：
+
+### 项目宪法
+- `qy-lty-admin/CLAUDE.md` — 沟通中文 / 修改记录强制 / 包管理器不混用
+- `qy-lty-admin/.planning/PROJECT.md` — Milestone v1.0「关键约束」段（本 phase 重点：RBAC 收敛在 lib/permissions.ts + 入口走 hasPermission）
+- `qy-lty-admin/.planning/REQUIREMENTS.md` — Active 段 CRED-FE-02 + CRED-FE-03
+- `qy-lty-admin/.planning/ROADMAP.md` — Phase 2 详情段（4 条 Success Criteria）
+
+### Phase 1 已交付（必读，作为消费 contract）
+- `qy-lty-admin/lib/api/credential-slot.ts` — Phase 1 落地的 API client（本 phase 不直接调用，但 Phase 3 会）
+- `qy-lty-admin/.planning/phases/01-credential-slot-api/01-01-SUMMARY.md` — Phase 1 收尾摘要
+
+### RBAC + 现有页面（必读，1:1 模板候选）
+- `qy-lty-admin/lib/permissions.ts` — RBAC 矩阵 + `hasPermission` 工具（本 phase 主要改动文件之一）
+- `qy-lty-admin/app/ai-model/page.tsx` — `/ai-model` 页面（本 phase 主要改动文件之一）
+- `qy-lty-admin/components/sidebar.tsx` — 现有 `hasPermission` 调用样板（怎么用、怎么过滤）
+- `qy-lty-admin/components/dashboard-shell.tsx` — 路径级权限校验样板
+
+### UI 组件
+- `qy-lty-admin/components/ui/button.tsx` — shadcn Button
+- `qy-lty-admin/components/ui/dialog.tsx` — shadcn Dialog（含 DialogTrigger / DialogContent / DialogHeader / DialogTitle / DialogDescription / DialogFooter）
+
+### 修改记录
+- `qy-lty-admin/docs/修改记录.md` — 头部「修改格式说明」+ Phase 1 / Phase 2（后端联动）条目作模板
+
+</canonical_refs>
+
+<specifics>
+## 具体要点（Success Criteria 显式化）
+
+| # | 验证点 | 检查方式 |
+|---|--------|----------|
+| 1 | `PermissionModule` 类型含 `'credential-slot'` | grep `lib/permissions.ts` 含 `'credential-slot'` 命中 ≥1 次（在 union 类型中） |
+| 2 | `PERMISSION_MATRIX` 中超级管理员 + AI模型管理员两个角色含 `'credential-slot'` | grep + 结构化解析 |
+| 3 | 其他角色不含 `'credential-slot'` | grep 反向：只检查特定 5 角色名 + 排除分隔，确保 'credential-slot' 仅出现 2 次 |
+| 4 | `hasPermission('credential-slot')` 在两类账户下返回 true，其他角色 false | 单元测试式调用 |
+| 5 | `getModuleFromPath('/ai-model')` 行为不变 | grep 函数定义 + 对照原值 |
+| 6 | `app/ai-model/page.tsx` 含"凭据槽位"按钮 | grep "凭据槽位" 命中 + grep `KeyRound`（或备选图标）+ grep `<Button` |
+| 7 | 按钮被 `hasPermission('credential-slot') &&` 包裹 | grep 该模式命中 |
+| 8 | 占位对话框存在（DialogTitle 含中文"通用凭据槽位"）| grep + 结构化解析 |
+| 9 | 点击按钮触发 `setIsCredentialDialogOpen(true)` 或类似 useState setter | grep `useState` + `onClick` 关联 |
+| 10 | `npx tsc --noEmit` 在新增/修改文件零错误（Phase 1 已确认存量错误零指向新文件） | shell exit + filter |
+| 11 | 修改记录顶部新增 Phase 2 条目 | grep `[2026-05-08] Phase 2 (前端)` 命中 |
+
+</specifics>
+
+<deferred>
+## 推迟事项（不在 Phase 2 范围）
+
+- **编辑对话框真实表单**（RHF + Zod + 提交逻辑） — Phase 3 / CRED-FE-04
+- **Sonner toast 反馈** — Phase 3 / CRED-FE-05
+- **`components/ai-model/CredentialSlotDialog.tsx` 抽离** — Phase 3
+- **真实后端 PUT 调用** — Phase 3
+- **端到端联调** — Phase 3 后
+
+</deferred>
+
+---
+
+*Phase: 02-rbac-ai*
+*Context gathered: 2026-05-08 via inline PRD（用户在 /gsd-plan-phase 2 调用时提供完整约束 + 选择 --skip-ui）*