docs: update superadmin pages

2026-01-14 17:42:59 +08:00
parent 788ba4c53a
commit 1cd610a25a
1 changed files with 108 additions and 23 deletions
--- a/frontend/superadmin/SUPERADMIN_PAGES.md
+++ b/frontend/superadmin/SUPERADMIN_PAGES.md
@@ -13,37 +13,31 @@
 - **分页/排序**：列表接口使用 `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. 路由与菜单（建议）
+## 1. 路由与菜单（与现有路由保持一致）

-（与现有路由保持一致，业务页面放在 `/superadmin/*`）
+业务页面统一放在 `/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 迭代路线（按优先级依次实现）
+## 1.1 迭代路线（按接口可用性）

-1) **安全与鉴权**
-   - `/super/v1/*`（除 `/auth/login`）强制 JWT 校验与 `super_admin` 角色校验
-   - `/super/v1/auth/token` 改为基于当前 token 的续期/校验（不再返回固定用户 token）
-2) **订单管理**
-   - 订单列表（跨租户筛选/分页/排序）
-   - 订单详情（含 items / snapshot 展示）
-   - 平台侧退款（支持强制退款，记录操作人）
-3) **租户管理增强**
-   - 租户详情页（基本信息、过期续期、状态变更、管理员/成员/内容管理）
-4) **内容管理**
-   - 内容列表（跨租户查询/筛选/分页/排序、下架/封禁）
-   - 可选：内容详情页（资源/定价/审计）
-5) **用户管理增强**
-   - 用户详情页（角色、状态、余额/冻结、加入/拥有的租户、操作记录）
-   - 角色授予/回收（`super_admin`）
-5) **审计与运维**
-   - 操作审计日志、关键行为告警
-   - 任务队列/退款处理监控、健康检查面板
+- **P0（已有接口可落地）**：登录、概览、租户管理/详情、用户管理/详情、订单列表/详情/退款、内容治理。
+- **P1（需补超管接口）**：创作者审核、优惠券、财务/提现、报表导出。
+- **P2（扩展增强）**：资产/上传治理、通知中心、审计日志。

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

@@ -88,7 +82,16 @@
  - 方案：提供固定档位（7/30/90/180/365 天）或日期选择器（二选一；swagger 当前为 duration 档位）
  - API：`PATCH /super/v1/tenants/{tenantID}`（`dto.TenantExpireUpdateForm.duration`）

-### 2.4 用户管理 `/superadmin/users`
+### 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`

@@ -103,6 +106,88 @@
  - 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
@@ -113,4 +198,4 @@

 - **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/*` 聚合能力后才能落地。