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/tenants/:tenantID：租户详情
• /superadmin/users：用户管理
• /superadmin/users/:userID：用户详情
• /superadmin/orders：订单管理
• /superadmin/orders/:orderID：订单详情
• /superadmin/contents：内容管理（跨租户汇总）
• /superadmin/creators：创作者/成员审核（待补超管接口）
• /superadmin/coupons：优惠券（待补超管接口）
• /superadmin/finance：财务与提现（待补超管接口）
• /superadmin/reports：报表与导出（待补超管接口）
• /superadmin/assets：资产与上传（待补超管接口）
• /superadmin/notifications：通知与消息（待补超管接口）

1.1 迭代路线（按接口可用性）

• P0（已有接口可落地）：登录、概览、租户管理/详情、用户管理/详情、订单列表/详情/退款、内容治理。
• P1（需补超管接口）：创作者审核、优惠券、财务/提现、报表导出。
• P2（扩展增强）：资产/上传治理、通知中心、审计日志。

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

• 创建租户并关联租户管理员（新增）
  • 表单字段：code、name、admin_user_id、duration(7/30/90/180/365 天)
  • API：POST /super/v1/tenants（dto.TenantCreateForm）
  • 行为：创建 tenants 记录，并创建 tenant_users 关系，角色为 tenant_admin
• 租户列表（筛选/分页/排序）
  • 过滤：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/tenants/:tenantID

• 基本信息、管理员/成员列表、内容与订单列表。
• API：
  • GET /super/v1/tenants/{tenantID}
  • GET /super/v1/tenants/{tenantID}/users
  • GET /super/v1/tenants/{tenantID}/contents
  • GET /super/v1/orders（按 tenant_id 过滤）

2.5 用户管理 /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 打开弹窗

2.6 用户详情 /superadmin/users/:userID

• 资料展示、状态/角色变更、拥有/加入的租户列表。
• API：
  • GET /super/v1/users/{userID}
  • PATCH /super/v1/users/{userID}/status
  • PATCH /super/v1/users/{userID}/roles
  • GET /super/v1/tenants（按 user_id 过滤）
  • GET /super/v1/users/{userID}/tenants

2.7 订单管理 /superadmin/orders

• 订单列表（跨租户筛选/分页/排序）、平台退款、跳转详情页。
• API：
  • GET /super/v1/orders
  • POST /super/v1/orders/{orderID}/refund

2.8 订单详情 /superadmin/orders/:orderID

• 订单详情、支付信息、退款入口。
• API：GET /super/v1/orders/{orderID}

2.9 内容治理 /superadmin/contents

• 内容列表（跨租户筛选/排序）、审核、状态变更。
• API：
  • GET /super/v1/contents
  • POST /super/v1/contents/{contentID}/review
  • PATCH /super/v1/tenants/{tenantID}/contents/{contentID}/status

2.10 创作者与成员审核 /superadmin/creators

• 现状：页面已提供占位提示，等待超管侧跨租户接口。
• 建议接口：
  • GET /super/v1/creators
  • GET /super/v1/creator-applications
  • POST /super/v1/creator-applications/{id}/review
  • GET /super/v1/creator-members
  • POST /super/v1/creator-members/{id}/review

2.11 优惠券 /superadmin/coupons

• 现状：页面已提供占位提示，等待超管侧跨租户接口。
• 建议接口：
  • GET /super/v1/coupons
  • PATCH /super/v1/coupons/{id}/status
  • GET /super/v1/coupon-grants

2.12 财务与提现 /superadmin/finance

• 现状：页面已提供占位提示，等待超管侧跨租户接口。
• 建议接口：
  • GET /super/v1/withdrawals
  • POST /super/v1/withdrawals/{id}/approve
  • POST /super/v1/withdrawals/{id}/reject
  • GET /super/v1/wallet-ledgers

2.13 报表与导出 /superadmin/reports

• 现状：页面已提供占位提示，等待超管侧跨租户接口。
• 建议接口：
  • GET /super/v1/reports/overview
  • GET /super/v1/reports/series
  • POST /super/v1/reports/export

2.14 资产与上传 /superadmin/assets

• 现状：页面已提供占位提示，等待超管侧跨租户接口。
• 建议接口：
  • GET /super/v1/assets
  • DELETE /super/v1/assets/{id}
  • GET /super/v1/assets/usage

2.15 通知与消息 /superadmin/notifications

• 现状：页面已提供占位提示，等待超管侧跨租户接口。
• 建议接口：
  • GET /super/v1/notifications
  • POST /super/v1/notifications/broadcast
  • GET /super/v1/notifications/templates
  • POST /super/v1/notifications/templates

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。
• 跨租户超管接口缺口：创作者审核、优惠券、提现/钱包、报表、资产、通知等仍依赖租户侧接口，需要补齐 /super/v1/* 聚合能力后才能落地。