4.9 KiB
管理页面规划文档
1. 背景与现状
现有 /panel 区域沿用统一的 PanelLayout（内含侧边栏、顶部 Header 以及 MFA 未完成时的强制指引），目前所有登录用户都会看到相同的入口，没有进一步的角色分流。
侧边栏的导航项是静态定义的数组，大多数功能仍处于 disabled 状态，也没有按照用户身份做差异化展示。
Header 会将任意登录用户标记为 “Admin”，缺少真实的角色区分，导致权限语义与视觉提示不一致。
2. 目标与范围
新增 “管理页面”（位于 dashboard/app/panel/management 或类似命名），仅管理员和运营者可访问；普通注册/订阅用户沿用原有个人中心。
管理页面需提供注册用户与订阅用户数量、趋势分析等基础运营指标。
统一角色体系：管理组（Admin）、运营组（Operator）、用户组（User），默认注册用户归属用户组。
在管理页面内提供权限矩阵表格，可配置注册开关、邀请策略、功能模块以及用户组管理能力。
3. 用户角色体系
UserProvider/useUser() 当前只暴露基础身份信息，文档已明确后续可以扩展角色字段，适合在 User 类型中增加 role、groups 等属性。
/api/auth/session 代理层需要从账号服务返回体中解析角色信息，并随用户对象一同下发，避免前端猜测身份。
后端 model.User 目前含有 Level 字段，可将其与新角色进行映射（例如 0=用户、10=运营、20=管理员），并补充 Role/Groups 字段方便前端直接消费。
注册接口默认没有携带角色信息，需要在账号服务或代理层中注入默认用户组，保证新注册用户落在 User 组。
4. 信息架构与页面模块
数据总览卡片：展示注册用户总数、订阅用户总数、活跃用户数、近 24 小时新增等；可复用现有 Card 组件风格，保持与 User Center 一致。
趋势分析区域：支持按日/周/自定义时间窗口查看用户增长曲线；后端返回时间序列数据，前端选择折线/柱状图呈现。
权限矩阵配置：矩阵行定义功能项（注册开关、公共邀请、具体功能模块），列对应角色组，以复选/开关组件管理授权。
用户组管理：列出现有用户，并支持调整角色、批量邀请或导入；可在管理页中嵌套抽屉式表单或跳转到单独的设置子页。
5. 数据与后端改造
依托已有 ListUsers 服务端能力（GET /api/users），新增聚合接口 GET /api/admin/users/metrics 计算总量、订阅量、活跃量与时间序列；直接使用 CreatedAt 字段即可统计趋势。
新增 GET/POST /api/admin/settings 维护权限矩阵配置，可持久化到数据库或配置服务；前端管理页通过该接口读取/写入。
/api/auth/session 代理扩展为 user.role、user.groups 字段；必要时提供 permissions 数组，方便前端快速做模块开关。
若订阅信息不在同一库，需要补充统计任务或引入独立服务接口，确保趋势数据真实可靠。
6. 前端改造方案
在 userStore 的 User 类型中新增 role, groups, permissions 等字段，并确保 fetchSessionUser() 正确解析。
在 Sidebar 中根据 user.role 动态拼装导航，将管理页面入口仅对 admin/operator 显示，其它角色保持现状。
新建 dashboard/app/panel/admin/page.tsx（或 management），采用同一 PanelLayout。页面内部划分“总览”“趋势”“权限矩阵”“用户组”四个 section，对应上文信息架构。
Header 根据角色显示真实徽章（Admin / Operator / User / Guest），并在缺少权限时展示提示或跳转入口。
对普通用户访问管理页时，使用服务端路由守卫或客户端重定向回 /panel 并提示无权访问；Guest 则跳至登录。
7. 权限控制策略
Next.js 前端：在管理页（或全局中间件）读取 user.role 做最小权限校验；同时对按钮/链接做二次校验，避免 UI 操作泄露。
后端 API：在新建的 /api/admin/* 路由组中校验角色，确保即便绕过前端仍无法操作。必要时记录操作日志便于追责。
8. 里程碑建议
基础数据链路：扩展会话/注册接口、完成角色字段落地；同步更新 Sidebar、Header 的角色化体验。
管理页 MVP：实现总览卡片 + 用户趋势（静态图表或基础折线图），确认数据准确性。
权限矩阵 & 用户组管理：上线矩阵配置、用户组列表与角色调整能力。
完善化：加入操作审计、邀请策略、功能开关等高级配置，并补充单元/端到端测试。
9. 风险与待确认事项
角色/权限数据的来源与持久化方案是否统一在账号服务还是需要自建表。
订阅用户的界定标准与数据可用性（是否有现成接口、是否需要同步任务）。
权限矩阵变更的实时性及对现有系统的兼容性（例如旧用户是否需要迁移）。