quyun-v2/docs/superadmin_plan.md

超级管理员后台功能规划（按页面拆解）

目标：基于现有 /super/v1/* 能力，补齐平台级“管理 + 统计”闭环。以下按页面拆分，分别给出管理动作、统计指标与接口对照。

0) 全局约定

• 鉴权：Authorization: Bearer <token>；登录后本地持久化 token。
• 路由基座：/super/（前端），API 基座 /super/v1。
• 分页：统一 page/limit，响应为 requests.Pager。
• 枚举：优先取 /super/v1/tenants/statuses、/super/v1/users/statuses。

1) 登录 /auth/login

• 管理功能：账号登录、token 写入、自动续期。
• 统计功能：可选记录登录失败次数、IP、设备指纹（审计）。
• 现有接口：
  • POST /super/v1/auth/login（需补齐实现）
  • GET /super/v1/auth/token（token 校验/续期）

2) 概览 Dashboard /

• 管理功能：快捷入口（租户/用户/订单/内容）。
• 统计指标（建议）：
  • 租户总数/活跃数/过期数
  • 用户总数/活跃数（按状态拆分）
  • 订单数/成交额/退款额（按日、按状态）
  • 内容总数/新增内容/被封禁内容
• 现有接口：
  • GET /super/v1/users/statistics（需补齐实现）
  • GET /super/v1/orders/statistics（需补齐实现）
  • GET /super/v1/tenants?limit=1&page=1（可取 total）
  • GET /super/v1/contents?limit=1&page=1（可取 total）

3) 租户管理 /superadmin/tenants

• 管理功能：
  • 新建租户（绑定管理员）
  • 更新租户状态（正常/禁用）
  • 续期/变更过期时间
• 统计指标：
  • 状态分布（待审核/正常/禁用）
  • 即将过期租户数（7/30 天）
  • 租户 GMV Top N（需补接口）
• 现有接口：
  • POST /super/v1/tenants
  • GET /super/v1/tenants
  • PATCH /super/v1/tenants/{tenantID}/status
  • PATCH /super/v1/tenants/{tenantID}（续期）
  • GET /super/v1/tenants/statuses

4) 租户详情 /superadmin/tenants/:tenantID

• 管理功能（建议）：
  • 基本信息/状态/过期时间编辑
  • 管理员与成员列表（角色管理）
  • 内容列表、订单列表、资金汇总
• 统计指标（建议）：
  • 租户用户数、内容数、订单数、GMV
• 现有接口：
  • GET /super/v1/tenants/{tenantID}（已有）
• 建议补充接口：
  • GET /super/v1/tenants/{tenantID}/users
  • GET /super/v1/tenants/{tenantID}/contents
  • GET /super/v1/tenants/{tenantID}/orders
  • GET /super/v1/tenants/{tenantID}/statistics

5) 用户管理 /superadmin/users

• 管理功能：
  • 用户列表筛选（用户名/状态/角色/所属租户）
  • 状态变更、角色授予
• 统计指标：
  • 用户状态统计（已提供）
• 现有接口：
  • GET /super/v1/users
  • PATCH /super/v1/users/{userID}/status
  • PATCH /super/v1/users/{userID}/roles
  • GET /super/v1/users/statistics
  • GET /super/v1/users/statuses

6) 用户详情 /superadmin/users/:userID

• 管理功能（建议）：
  • 用户资料、角色、状态
  • 用户所属/拥有租户列表
  • 用户订单与内容购买记录
• 统计指标（建议）：
  • 用户消费总额、退款次数
• 现有接口：
  • GET /super/v1/users/{userID}（已有）
• 建议补充接口：
  • GET /super/v1/users/{userID}/tenants
  • GET /super/v1/users/{userID}/orders
  • GET /super/v1/users/{userID}/contents

7) 订单管理 /superadmin/orders

• 管理功能：
  • 订单列表（按租户/用户/状态/时间过滤）
  • 退款操作（平台侧）
• 统计指标：
  • 订单状态分布、GMV、退款额
• 现有接口：
  • GET /super/v1/orders
  • POST /super/v1/orders/{orderID}/refund（需补齐实现）
  • GET /super/v1/orders/statistics（需补齐实现）

8) 订单详情 /superadmin/orders/:orderID

• 管理功能：
  • 查看订单快照、支付信息、退款信息
  • 退款/强制关闭
• 现有接口：
  • GET /super/v1/orders/{orderID}（需补齐实现）

9) 内容管理 /superadmin/contents

• 管理功能：
  • 跨租户内容列表
  • 内容状态更新（封禁/下架）
• 统计指标：
  • 内容状态分布、热门内容 Top N
• 现有接口：
  • GET /super/v1/contents
  • PATCH /super/v1/tenants/{tenantID}/contents/{contentID}/status

10) 财务/提现（可选）

• 管理功能：
  • 提现订单审核（通过/驳回）
  • 记录操作原因
• 统计指标：
  • 提现订单数、金额、失败率
• 现有接口：无（服务层有 ListWithdrawals/Approve/Reject，需补 controller + route）

11) 审计日志 / 操作记录（建议）

• 管理功能：
  • 展示后台操作日志（操作人、对象、动作、时间）
  • 支持导出
• 现有接口：无（可基于 services.Audit 扩展）

12) 系统配置 / 平台策略（建议）

• 管理功能：
  • 平台佣金比例、内容审核策略、默认到期策略
• 现有接口：无（需新增配置表与接口）