quyun-v2/frontend/superadmin/SUPERADMIN_PAGES.md

QuyUn 平台超级管理员（frontend/superadmin）页面与功能规划

基于 backend/docs/swagger.json 中平台侧接口 /super/v1/*，规划 frontend/superadmin/ 的信息架构、页面路由与核心交互。

frontend/superadmin/src/router/index.js 的路由基座为 /super/；API base 由 VITE_API_BASE_URL 控制（见 frontend/superadmin/src/service/apiClient.js），本文中的 API 路径均为绝对路径（例如 /super/v1/users）。

0. 全局约定（前端通用能力）

• 鉴权：登录成功后保存 token（建议保存到 localStorage.super_token），所有请求带 Authorization: Bearer <token>（项目已在 frontend/superadmin/src/service/apiClient.js 实现）。
• 路由守卫：
  • 未登录访问受保护页面 → 跳转 /auth/login。
  • 可选：启动时调用 GET /super/v1/auth/token 校验 token 是否有效（401 则清理 token 并回到登录页）。
• 分页/排序：列表接口使用 page/limit，并支持 asc/desc（字段名逗号分隔）。统一封装分页表格组件与 URL query 同步。
• 枚举来源：优先使用 GET /super/v1/tenants/statuses、GET /super/v1/users/statuses 返回的 requests.KV[] 作为下拉选项（swagger 中 dto.*StatusUpdateForm 的 enum 与 consts.*Status 存在不一致，见“风险点”）。

1. 路由与菜单（建议）

（与现有路由保持一致，业务页面放在 /superadmin/*）

• /auth/login：登录
• /：概览 Dashboard
• /superadmin/tenants：租户管理
• /superadmin/users：用户管理

2. 页面规格（页面 → 功能 → API）

2.1 登录 /auth/login

目标：完成超级管理员登录并写入 token。

• 登录表单：username、password（对应 dto.LoginForm）
• API：
  • 登录：POST /super/v1/auth/login → dto.LoginResponse.token
  • 校验/续期：GET /super/v1/auth/token（返回同结构 dto.LoginResponse）
• 交互：
  • 失败提示：展示后端错误信息
  • 成功：保存 token → 跳转到 /superadmin/tenants 或上次访问页面

2.2 概览 /（Dashboard）

目标：提供“关键指标 + 快捷入口”。

• 指标：
  • 用户状态统计：GET /super/v1/users/statistics（dto.UserStatistics[]）
  • 可选：租户总数（利用租户列表响应中的 total）：GET /super/v1/tenants?limit=10&page=1
• 快捷入口：租户管理、用户管理

2.3 租户管理 /superadmin/tenants

核心对象：dto.TenantItem

• 租户列表（筛选/分页/排序）
  • 过滤：name、status
  • 排序：asc/desc
  • API：GET /super/v1/tenants
• 状态更新
  • 选项：GET /super/v1/tenants/statuses（requests.KV[]）
  • API：PATCH /super/v1/tenants/{tenantID}/status（dto.TenantStatusUpdateForm）
  • 交互：点击状态 tag 打开弹窗选择新状态并提交
• 续期/更新过期时间
  • 方案：提供固定档位（7/30/90/180/365 天）或日期选择器（二选一；swagger 当前为 duration 档位）
  • API：PATCH /super/v1/tenants/{tenantID}（dto.TenantExpireUpdateForm.duration）

2.4 用户管理 /superadmin/users

核心对象：dto.UserItem

• 用户列表（筛选/分页/排序）
  • 过滤：username、tenantID、status
  • 排序：asc/desc
  • API：GET /super/v1/users
• 用户状态统计（页头统计条）
  • API：GET /super/v1/users/statistics
• 更新用户状态
  • 选项：GET /super/v1/users/statuses（requests.KV[]）
  • API：PATCH /super/v1/users/{userID}/status（dto.UserStatusUpdateForm）
  • 交互：点击状态 tag 打开弹窗

3. 枚举与数据结构（UI 需要）

• 租户状态：consts.TenantStatus（pending_verify / verified / banned），推荐用 GET /super/v1/tenants/statuses 驱动展示 label
• 用户状态：consts.UserStatus（pending_verify / verified / banned），推荐用 GET /super/v1/users/statuses 驱动展示 label
• KV 结构：requests.KV（key 为机器值，value 为展示文案）

4. 风险点 / 待补能力（从 swagger 反推）

• swagger 不一致：dto.TenantStatusUpdateForm.status / dto.UserStatusUpdateForm.status 在 swagger 里额外出现 normal/disabled enum，但 consts.*Status 与列表筛选 enum 为 pending_verify/verified/banned；前端应以 /statuses 接口返回为准，并推动后端修正 swagger。
• 分页 items 结构疑似不完整：列表接口 swagger 中 items 被标成单个 object（$ref dto.TenantItem/dto.UserItem），实际应为数组；当前前端服务层已做兼容（normalizeItems），但建议后端修正 swagger。
• 租户/用户详情与更多运维能力缺失：目前没有用户详情、租户详情、角色管理、密码重置等超管常见能力；如需要可扩展接口与页面。