zyc/lty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
lty/qy-lty-admin/.planning/REQUIREMENTS.md
pmc cf1a777033 docs(02-02): 完成 Phase 2 Plan 02-02（修改记录追加 + plan 级双重验证） 
- 新增 .planning/phases/02-rbac-ai/02-02-SUMMARY.md（含 7 字段条目结构记录 + 4 大类验证结果汇总 + 偏离 PLAN 记录）
- 更新 STATE.md：Phase 2 由 进行中 切到 已交付（5/5 plan）；milestone 进度 67%；下一步 /gsd-plan-phase 3
- 更新 ROADMAP.md：Phase 2 行 ✅ Complete；02-02-PLAN.md 行勾选；Plans Complete 列 2/2
- 更新 REQUIREMENTS.md：尾部追加 Plan 02-02 落地会话日志
- Phase 2 5 条 success criteria 全部确认通过；CRED-FE-02 + CRED-FE-03 闭环
- 验证 A：tsc 整体 67 条存量错误 + 反向断言 0 条指向本 phase 改动文件
- 验证 B：14 条 grep 全命中（11 specifics + 4 反向断言；原 PLAN awk 在 Windows Bash 失败 → 替换为 sed 行号区间方案）
- 验证 C：4 个 manifest+lockfile 工作区 + HEAD~1 比较均 0 行 diff
- 验证 D：next lint 因项目无 .eslintrc* 跳过沿用 Phase 1 判定
2026-05-08 11:56:26 +08:00

153 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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）
- [x] **AUTH-01** 邮箱 + 密码登录页（`app/login/page.tsx`、`lib/api/auth.ts:emailLogin`）
- [x] **AUTH-02** 注册 / 找回密码占位页（`app/register/`、`app/forgot-password/`）
- [x] **AUTH-03** Bearer token 拦截器自动注入(`lib/api/client.ts` 请求拦截器)
- [x] **AUTH-04** 401 响应统一处理（清空 token + 重定向 `/login`）
- [x] **AUTH-05** Cookie 镜像 token（`js-cookie`，7 天有效期，供 middleware 读取）
- [x] **AUTH-06** 退出登录调后端 logout 接口并清空双存储
### RBAC 权限体系（PERM）
- [x] **PERM-01** 5 角色 × 13 模块 `PERMISSION_MATRIX`（`lib/permissions.ts`）
- [x] **PERM-02** `hasPermission()` / `hasPathPermission()` / `getModuleFromPath()` 工具集
- [x] **PERM-03** `DashboardShell` 路径级权限校验 + 访问拒绝 UI
- [x] **PERM-04** `Sidebar` 按角色过滤可见菜单项
- [x] **PERM-05** `middleware.ts` 受保护路径 token 校验 + 重定向
- [ ] **PERM-06** 后端独立权限校验闭环 — ⚠️ **客户端校验仅是 UI 礼貌**，CONCERNS.md 标极高严重级；需要审计 qy_lty 后端 `/api/v1/admin/*` 是否对每个接口重新校验角色，并在 CLAUDE.md 中明文文档化
### 仪表盘（DASH）
- [x] **DASH-01** 仪表盘首页（KPI 卡片 + 概览图表 + 最近活动）
- [x] **DASH-02** Recharts 数据可视化集成
### AI 管理（AI）
- [x] **AI-01** AI 模型 / Bot 管理（`app/ai-model/page.tsx`、`lib/api/ai-models.ts`）
### 内容管理（CONT）
- [x] **CONT-01** 服饰模块 CRUD（`app/outfits/`）
- [x] **CONT-02** 道具模块 CRUD（`app/props/`）
- [x] **CONT-03** 家居装饰模块 CRUD（`app/home-decor/`）
- [x] **CONT-04** 食物模块 CRUD（`app/food/`）
- [x] **CONT-05** 歌曲模块 CRUD（`app/songs/`）
- [x] **CONT-06** 舞蹈模块 CRUD（`app/dances/`）
- [x] **CONT-07** 成就模块管理（`app/achievements/`）
- [x] **CONT-08** 好感度系统管理页（`app/affinity/page.tsx`，1005 行）
- [x] **CONT-09** 后端响应到前端类型的适配器层（`lib/api/adapters.ts` + 各模块 `mapBackend*`）
### 系统管理（SYS）
- [x] **SYS-01** 用户管理模块（`app/users/`）
- [x] **SYS-02** 权限/角色管理模块（`app/permissions/`）
- [x] **SYS-03** 系统设置页（`app/settings/`）
### 文件上传（UPL）
- [x] **UPL-01** 后端代理上传接口封装（`lib/api/upload.ts`，image / avatar / audio / animation）
- [x] **UPL-02** 上传进度回调（Axios `onUploadProgress`）
### 通用 UI 基础设施（UI）
- [x] **UI-01** shadcn 风格原子组件库（`components/ui/`，30+ 组件）
- [x] **UI-02** 表单层（React Hook Form + Zod + `@hookform/resolvers`）
- [x] **UI-03** Toast 通知（Sonner + Radix Toast，`hooks/use-toast.ts`）
- [x] **UI-04** 暗黑/明亮主题切换（`next-themes` + Tailwind CSS 变量）
- [x] **UI-05** 移动端断点检测 hook（`hooks/use-mobile.tsx`）
- [x] **UI-06** 二次确认对话框（删除 / 发布）
### 部署（DEP）
- [x] **DEP-01** Docker 多阶段构建（builder + runner）
- [x] **DEP-02** Next.js standalone 输出
- [x] **DEP-03** Yarn + 淘宝镜像源（仅 Dockerfile）
- [x] **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）
- [x] **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` 导出
- [x] **CRED-FE-02** RBAC 模块声明：`lib/permissions.ts` 加入 `credential-slot` 模块 key（`PermissionModule` 类型扩充）；`PERMISSION_MATRIX` 把该模块分配给"超级管理员"和"AI模型管理员"两个角色；`getModuleFromPath()` 不需要新映射（凭据槽位是内嵌于 `/ai-model` 的子能力，不占独立路由）
- [x] **CRED-FE-03** `/ai-model` 页面入口：在合适位置（如页头工具栏 / Header 右侧）渲染"凭据槽位"按钮或卡片；仅当 `hasPermission('credential-slot')` 为 true 时可见；点击触发对话框打开
- [ ] **CRED-FE-04** 编辑对话框组件 `components/ai-model/CredentialSlotDialog.tsx`：基于 `components/ui/dialog.tsx`；表单 React Hook Form + Zod 校验；预填态显示后端返回的 `app_id` 明文 + `access_token` 末 4 位掩码 + 不可改的 `updated_at`；表单语义为"留空保留旧值，重新输入才覆写"（避免把脱敏掩码当真值回写）；提交触发 `updateCredentialSlot()`，仅提交用户实际输入的字段
- [ ] **CRED-FE-05** 提交反馈：成功调用 `useToast()` 弹 Sonner 成功 toast 并自动关闭对话框、重新触发 GET 刷新预填；失败走 `lib/api/error-handler.ts` 统一映射后端错误并 toast 提示
### 候选优先级（已转移自 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
<!-- 由 /gsd-roadmap 在生成 ROADMAP 时回填；后续 /gsd-plan-phase 可继续细化到 plan 粒度 -->
### 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 编辑对话框 `CredentialSlotDialog.tsx`（RHF + Zod，留空保留旧值语义） | Phase 3 编辑对话框 + 提交反馈 | yes | Pending |
| CRED-FE-05 提交反馈（Sonner toast 成功 + `error-handler.ts` 失败映射） | Phase 3 编辑对话框 + 提交反馈 | yes | Pending |
**覆盖率**：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*
Reference in New Issue View Git Blame Copy Permalink