zyc/lty

pmc cfd8a4923a docs(qy-lty-admin): 初始化 REQUIREMENTS.md（Validated）

把代码库现状拆成带 REQ-ID 的可追溯需求：47 项已交付（AUTH-01~06、PERM-01~05、DASH-01~02、
AI-01、CONT-01~09、SYS-01~03、UPL-01~02、UI-01~06、DEP-01~04），1 项缺口（PERM-06，
后端权限校验闭环未验证）。Active 段留空，附 12 项候选优先级供下一 milestone 参考。

2026-05-07 14:33:02 +08:00

6.1 KiB

Raw Blame History

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

初始化日期: 2026-05-07 类型: Brownfield 文档化（从 .planning/codebase/ 推断）状态: 已落地能力归档完成；Active milestone 待 /gsd-new-milestone 启动

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 目标）

（暂无）

本次 /gsd-new-project 是 brownfield 文档化，没有指定新 milestone。

下一次启动新功能开发时，请用：

/gsd-new-milestone

GSD 会引导你确认 milestone 目标、把新需求加到本段（带 REQ-ID），然后 /gsd-plan-phase 拆 phase。

候选优先级（来自 CONCERNS.md 与项目活动信号，按风险/价值排序，仅供参考）：

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

Out of Scope

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

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

Traceability

（暂无 phase；待 /gsd-new-milestone 后启动）

Last updated: 2026-05-07 after brownfield documentation pass

6.1 KiB Raw Blame History Unescape Escape