lty/qy-lty-admin/.planning/REQUIREMENTS.md

Requirements — 洛天依应用管理后台（qy-lty-admin）

初始化日期: 2026-05-07 类型: Brownfield 文档化（从 .planning/codebase/ 推断） 状态: 已落地能力归档完成；Milestone v1.0「通用凭据槽位前端集成」已生成 ROADMAP.md（3 个 phase，coarse 粒度）

---

Validated（已交付能力）

以下需求均为 2026-05-07 之前已上线 的能力，从代码与 docs/ 推断而来。任何修改都需要走完整 phase 流程，不要直接动。

鉴权与会话（AUTH）

• AUTH-01 邮箱 + 密码登录页（app/login/page.tsx、lib/api/auth.ts:emailLogin）
• AUTH-02 注册 / 找回密码占位页（app/register/、app/forgot-password/）
• AUTH-03 Bearer token 拦截器自动注入(lib/api/client.ts 请求拦截器)
• AUTH-04 401 响应统一处理（清空 token + 重定向 /login）
• AUTH-05 Cookie 镜像 token（js-cookie，7 天有效期，供 middleware 读取）
• AUTH-06 退出登录调后端 logout 接口并清空双存储

RBAC 权限体系（PERM）

• PERM-01 5 角色 × 13 模块 PERMISSION_MATRIX（lib/permissions.ts）
• PERM-02 hasPermission() / hasPathPermission() / getModuleFromPath() 工具集
• PERM-03 DashboardShell 路径级权限校验 + 访问拒绝 UI
• PERM-04 Sidebar 按角色过滤可见菜单项
• PERM-05 middleware.ts 受保护路径 token 校验 + 重定向
• PERM-06 后端独立权限校验闭环 — ⚠️ 客户端校验仅是 UI 礼貌，CONCERNS.md 标极高严重级；需要审计 qy_lty 后端 /api/v1/admin/* 是否对每个接口重新校验角色，并在 CLAUDE.md 中明文文档化

仪表盘（DASH）

• DASH-01 仪表盘首页（KPI 卡片 + 概览图表 + 最近活动）
• DASH-02 Recharts 数据可视化集成

AI 管理（AI）

• AI-01 AI 模型 / Bot 管理（app/ai-model/page.tsx、lib/api/ai-models.ts）

内容管理（CONT）

• CONT-01 服饰模块 CRUD（app/outfits/）
• CONT-02 道具模块 CRUD（app/props/）
• CONT-03 家居装饰模块 CRUD（app/home-decor/）
• CONT-04 食物模块 CRUD（app/food/）
• CONT-05 歌曲模块 CRUD（app/songs/）
• CONT-06 舞蹈模块 CRUD（app/dances/）
• CONT-07 成就模块管理（app/achievements/）
• CONT-08 好感度系统管理页（app/affinity/page.tsx，1005 行）
• CONT-09 后端响应到前端类型的适配器层（lib/api/adapters.ts + 各模块 mapBackend*）

系统管理（SYS）

• SYS-01 用户管理模块（app/users/）
• SYS-02 权限/角色管理模块（app/permissions/）
• SYS-03 系统设置页（app/settings/）

文件上传（UPL）

• UPL-01 后端代理上传接口封装（lib/api/upload.ts，image / avatar / audio / animation）
• UPL-02 上传进度回调（Axios onUploadProgress）

通用 UI 基础设施（UI）

• UI-01 shadcn 风格原子组件库（components/ui/，30+ 组件）
• UI-02 表单层（React Hook Form + Zod + @hookform/resolvers）
• UI-03 Toast 通知（Sonner + Radix Toast，hooks/use-toast.ts）
• UI-04 暗黑/明亮主题切换（next-themes + Tailwind CSS 变量）
• UI-05 移动端断点检测 hook（hooks/use-mobile.tsx）
• UI-06 二次确认对话框（删除 / 发布）

部署（DEP）

• DEP-01 Docker 多阶段构建（builder + runner）
• DEP-02 Next.js standalone 输出
• DEP-03 Yarn + 淘宝镜像源（仅 Dockerfile）
• DEP-04 端口 3000 + yarn start 入口

---

Active（当前 milestone 目标）

Milestone v1.0：通用凭据槽位前端集成 启动日期：2026-05-07 联动：qy_lty 后端 Milestone v1.0（3 个 phase，API 契约已锁定）；端到端验收依赖后端 Phase 2「管理端读写接口」落地 目标：在 /ai-model 页面集成 APP ID + Access Token 录入/编辑窗口，调用后端管理接口完成读写。

通用凭据槽位前端集成（CRED-FE）

• CRED-FE-01 API 客户端 lib/api/credential-slot.ts：导出 getCredentialSlot()、updateCredentialSlot({ app_id, access_token })；含响应适配器 mapBackendCredentialSlot()（snake_case → camelCase）；共享类型 CredentialSlot { appId, accessTokenMasked, updatedAt }；从 lib/api/index.ts 导出
• CRED-FE-02 RBAC 模块声明：lib/permissions.ts 加入 credential-slot 模块 key（PermissionModule 类型扩充）；PERMISSION_MATRIX 把该模块分配给"超级管理员"和"AI模型管理员"两个角色；getModuleFromPath() 不需要新映射（凭据槽位是内嵌于 /ai-model 的子能力，不占独立路由）
• CRED-FE-03 /ai-model 页面入口：在合适位置（如页头工具栏 / Header 右侧）渲染"凭据槽位"按钮或卡片；仅当 hasPermission('credential-slot') 为 true 时可见；点击触发对话框打开
• CRED-FE-04 编辑对话框组件 components/ai-model/credential-slot-dialog.tsx（kebab-case，191 行）：基于 components/ui/dialog.tsx；表单 React Hook Form + Zod 校验；预填态显示后端返回的 app_id 明文 + access_token 末 4 位掩码（仅 placeholder）+ 不可改的 updated_at（toLocaleString('zh-CN')）；表单语义改为"access_token 强制输入"（CONTEXT D-提交逻辑 锁定 — 后端 PUT 全字段覆写 + 前端无法识别脱敏掩码格式，「留空保留旧值」需后端配合，记入下一周期 milestone）；提交触发 updateCredentialSlot() 全字段覆写
• CRED-FE-05 提交反馈：Sonner 命令式 import { toast } from "sonner" — 成功 toast.success("凭据槽位已更新", { description: "配置已生效" }) + 自动 handleOpenChange(false)；失败 import { handleApiError } from "@/lib/api/error-handler" 显式路径 → toast.error("保存失败", { description: handleApiError(e) }) + 对话框保持打开 + 表单值不丢；GET 加载失败 toast.error("加载失败", ...)

候选优先级（已转移自 brownfield 文档化阶段，本期不消化）

下面是从 CONCERNS.md 转过来的潜在 milestone 候选，本期 v1.0 不处理，留作下一周期参考：

1. 极高 验证 qy_lty 后端是否对所有 /api/v1/admin/* 接口独立校验角色（PERM-06）— 否则当前 RBAC 仅是 UI 礼貌，是真实安全漏洞
2. 高 移除 lib/api/client.ts、lib/api/upload.ts 等的 console.log/warn/error 调试残留（暴露 token 前缀）
3. 高 关闭 next.config.mjs 中 eslint.ignoreDuringBuilds 与 typescript.ignoreBuildErrors，并修干净存量类型/lint 错误
4. 高 收敛多 lockfile 冲突（保留 yarn.lock，删除 package-lock.json + pnpm-lock.yaml + CI 校验）
5. 高 Token 存储方案重构（移到 HttpOnly cookie + 后端登出黑名单 + 短/长 token 刷新机制）
6. 中 拆分 app/affinity/page.tsx（1005 行）与 components/ui/sidebar.tsx（763 行）等大文件
7. 中 引入测试基础设施（Vitest + 关键路径测试，先覆盖 lib/permissions.ts + lib/api/client.ts）
8. 中 把 "latest" 依赖改为具体 caret 范围（@hookform/resolvers、react-hook-form、recharts、zod）
9. 中 Husky pre-commit hook + lint-staged（强制 lint / type-check / 修改记录提醒）
10. 低 添加 app/error.tsx 与各模块 error.tsx（Next.js 错误边界）
11. 低 权限校验 hook 化 + useMemo 记忆化
12. 低 客户端登录失败节流（30 秒禁用按钮 + 后端账户锁定）

---

Out of Scope

（理由详见 PROJECT.md，此处不重复）

• 后端实现 — 在 ../qy_lty/ 独立项目（Django）
• Unity 客户端业务逻辑 — 在 LTY_App_Project_URP / LTY_Project 独立项目
• 国际化（i18n） — 当前中文硬编码，运营群体不需要
• 移动端原生体验 — 仅响应式 Web
• 跨项目混合修改记录 — 各自维护
• Sentry / APM 客户端错误追踪 — 暂不引入

---

Traceability

Milestone v1.0 通用凭据槽位前端集成（2026-05-07 ROADMAP 落地）

Requirement	Phase	UI hint	Status
CRED-FE-01 API 客户端 lib/api/credential-slot.ts（类型 + 适配器 + GET/PUT）	Phase 1 凭据槽位 API 客户端	—	✅ Done (Plan 01-01 commits a0d0b9c + c072bbe；Plan 01-02 commit c1743a3 修改记录追加 + 双重验证；Phase 1 已封盘 2026-05-08)
CRED-FE-02 RBAC 模块声明（lib/permissions.ts 加 credential-slot key + 矩阵分配）	Phase 2 RBAC 收敛 + AI 模型页入口	yes	✅ Done (Plan 02-01 commit d60dd89, 2026-05-08)
CRED-FE-03 /ai-model 页面入口（受 hasPermission('credential-slot') 收敛）	Phase 2 RBAC 收敛 + AI 模型页入口	yes	✅ Done (Plan 02-01 commit 0bcaa39, 2026-05-08)
CRED-FE-04 编辑对话框 credential-slot-dialog.tsx（RHF + Zod，access_token 强制输入语义）	Phase 3 编辑对话框 + 提交反馈	yes	✅ Done (Plan 03-02 commit d719891, 2026-05-08)
CRED-FE-05 提交反馈（Sonner toast 成功 + error-handler.ts 失败映射）	Phase 3 编辑对话框 + 提交反馈	yes	✅ Done (Plan 03-02 commit d719891 + 03-01 commit 7065d73 Toaster 前置, 2026-05-08)

覆盖率：5/5 Active 需求映射到 phase ✓（无孤儿，无重复）

跨项目依赖：Phase 3 success criteria #5（端到端串联）依赖 qy_lty 后端 Milestone v1.0 Phase 2「管理端读写接口」落地；前端代码层工作（Phase 1-3）本身不阻塞、可与后端并行推进。

---

Last updated: 2026-05-07 — Milestone v1.0「通用凭据槽位前端集成」ROADMAP 生成，Traceability 回填 5/5 2026-05-08 更新：Plan 01-01 落地，CRED-FE-01 状态切到 ✅ Done（Active 段已自动勾选 [x]） 2026-05-08 更新：Plan 01-02 落地（修改记录追加 + 双重验证 commit c1743a3），Phase 1 全部交付（2/2 plan），等待 /gsd-plan-phase 2 启动 Phase 2 2026-05-08 更新：Plan 02-01 落地（commits d60dd89 + 0bcaa39），CRED-FE-02 + CRED-FE-03 状态切到 ✅ Done；Phase 2 进度 1/2，等待 Plan 02-02 收尾 2026-05-08 更新：Plan 02-02 落地（commit 2be1f1d 修改记录追加 + plan 级双重验证），Phase 2 全部交付（2/2 plan）；Milestone 进度 2/3 phase（67%），等待 /gsd-plan-phase 3 启动 Phase 3 2026-05-08 更新：Plan 03-01 落地（commit 7065d73 — RootLayout 挂载 Sonner Toaster，修复仓库 9 处 toast pre-existing dead code，CRED-FE-05 反馈通道前置打通；CRED-FE-05 完整闭环仍依赖 03-02 接入）；Phase 3 进度 1/3 2026-05-08 更新：Plan 03-02 落地（commits d719891 + 7872840 — 新建 CredentialSlotDialog 组件 191 行 RHF+Zod+Sonner+handleApiError + page.tsx 删占位 Dialog 接入新组件），CRED-FE-04 + CRED-FE-05 状态切到 ✅ Done；Phase 3 进度 2/3，等待 Plan 03-03 收尾（修改记录追加 + plan 级双重验证） 2026-05-08 更新：Plan 03-03 落地（commit 892b0b1 — docs/修改记录.md 顶部追加 [2026-05-08] Phase 3 条目 + Plan 级整体双重验证 4 段全过）；Milestone v1.0「通用凭据槽位前端集成」100% 交付 — 3/3 phase + 7/7 plan + 11/11 需求 + 5/5 ROADMAP success criteria 全部确认通过；Active 段 5 项 CRED-FE-01~05 全部勾选完成；Traceability 表 5/5 Done；等待启动下一周期 milestone（候选清单 L100-112）