pmc
01634eea9a
通用凭据槽位前端集成 5 项 Active 需求： - CRED-FE-01 API 客户端 lib/api/credential-slot.ts（GET/PUT + adapter + 类型） - CRED-FE-02 RBAC 模块声明（lib/permissions.ts 加 credential-slot key，分配给超级管理员 + AI模型管理员） - CRED-FE-03 /ai-model 页面入口（按钮/卡片，按权限可见） - CRED-FE-04 编辑对话框（RHF + Zod + 留空保留旧值语义，避免回写脱敏假值） - CRED-FE-05 提交反馈（Sonner toast 成功 + error-handler 失败处理） 候选优先级段保留为下一周期参考。
137 lines
7.8 KiB
Markdown
137 lines
7.8 KiB
Markdown
# Requirements — 洛天依应用管理后台（qy-lty-admin）
|
||
|
||
**初始化日期**: 2026-05-07
|
||
**类型**: Brownfield 文档化（从 `.planning/codebase/` 推断）
|
||
**状态**: 已落地能力归档完成；Active milestone 待 `/gsd-new-milestone` 启动
|
||
|
||
---
|
||
|
||
## 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 契约已锁定）
|
||
目标：在 `/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/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-plan-phase 在生成 phase 时回填：每个 phase 解决哪些 REQ-ID -->
|
||
|
||
（暂无 phase；待 `/gsd-new-milestone` 后启动）
|
||
|
||
---
|
||
|
||
*Last updated: 2026-05-07 启动 Milestone v1.0「通用凭据槽位前端集成」*
|