202 lines
9.0 KiB
Markdown
202 lines
9.0 KiB
Markdown
# 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/*` 聚合能力后才能落地。
|