# QuyUn Tenant Admin（frontend/admin）页面与功能规划

基于 `backend/docs/swagger.json` 中 `/t/{tenantCode}/v1/admin/*` 管理端接口（租户维度），规划 `frontend/admin/` 的信息架构、页面路由与核心交互。

> 当前 `frontend/admin/src/tenant.ts` 的路由基座为 `/t/:tenantCode/admin/`，API 基座为 `/t/:tenantCode/v1`；本文中 API 路径均以该 baseURL 为前缀（即请求 `/admin/...`）。

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

- **租户上下文**：从 URL 解析 `tenantCode`（已存在 `getTenantCodeFromPath`），所有接口都带上路径参数 `{tenantCode}`。
- **分页/排序**：多数列表接口使用 `page/limit`，部分支持 `asc/desc`；统一封装 `Pager` 查询参数与列表组件。
- **过滤条件同步 URL**：列表页筛选项写入 query（便于分享/刷新不丢失）。
- **危险操作二次确认 + 审计信息**：退款、禁用邀请码、审批加入申请、移除成员、删除媒体资源等，弹窗确认并强制填写 `reason`（后端字段标注为可选，但管理端建议必填以便追溯）。
- **枚举展示**：基于 swagger 的 `consts.*` 枚举做 label 映射（见文末“枚举”）。

## 1. 路由与菜单（建议）

路由均相对 `getAdminRouterBase()`（`/t/:tenantCode/admin/`）：

- `/dashboard`：概览
- `/members`：成员管理
- `/invites`：邀请码管理
- `/join-requests`：加入申请
- `/orders`：订单管理
- `/orders/:orderID`：订单详情
- `/ledgers`：余额流水（审计）
- `/media`：媒体资源库
- `/media/upload`：上传媒体资源
- `/media/:assetID`：媒体资源详情
- `/contents`：内容管理（接口缺口见“待补接口/风险”）
- `/contents/new`：创建内容（草稿）
- `/contents/:contentID`：内容编辑（基础信息/价格/绑定资源）

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

### 2.1 概览 `/dashboard`

目标：提供“运营入口 + 关键待办”。

- 待办卡片：`加入申请待处理数量`、`最近退款/退款中订单`、`最近上传失败媒体资源`
- 快捷入口：跳转到成员/订单/媒体/内容
- 数据来源（可先不做聚合，使用列表接口取前 N 条）：
  - 加入申请列表：`GET /admin/join-requests?status=pending&limit=10&page=1`
  - 订单列表：`GET /admin/orders?status=refunding,refunded,paid&limit=10&page=1`（按 `paid_at`/`created_at` 排序）
  - 媒体资源列表：`GET /admin/media_assets?status=failed,processing&limit=10&page=1`

### 2.2 成员管理 `/members`

核心对象：租户成员关系 + 用户基础信息（`dto.AdminTenantUserItem` 组合 `models.TenantUser` + `models.User`）。

- 成员列表（带筛选/分页）
  - 过滤：`username`、`user_id`、`role`、`status`
  - API：`GET /admin/users`
- 添加成员（通过 `userID` 加入）
  - 交互：输入 `userID`（或未来可通过用户名搜索，当前 swagger 未提供）
  - API：`POST /admin/users/{userID}/join`
- 设置角色
  - 交互：角色下拉（`member` / `tenant_admin`）
  - API：`PATCH /admin/users/{userID}/role`（`dto.AdminTenantUserRoleUpdateForm`）
- 移除成员
  - API：`DELETE /admin/users/{userID}`

### 2.3 邀请码管理 `/invites`

- 邀请码列表（筛选/分页）
  - 过滤：`code`、`status`
  - API：`GET /admin/invites`
- 创建邀请码
  - 表单字段：`code?`、`expires_at?`、`max_uses?`、`remark?`（`dto.AdminTenantInviteCreateForm`）
  - API：`POST /admin/invites`
- 禁用邀请码
  - 表单字段：`reason?`（建议必填；`dto.AdminTenantInviteDisableForm`）
  - API：`PATCH /admin/invites/{inviteID}/disable`

### 2.4 加入申请 `/join-requests`

- 加入申请列表（筛选/分页）
  - 过滤：`status`、`user_id`
  - API：`GET /admin/join-requests`
- 审核通过 / 拒绝
  - 表单字段：`reason?`（建议必填；`dto.AdminTenantJoinRequestDecideForm`）
  - API：
    - `POST /admin/join-requests/{requestID}/approve`
    - `POST /admin/join-requests/{requestID}/reject`

### 2.5 订单管理 `/orders`

- 订单列表（筛选/分页/导出）
  - 过滤：
    - 金额：`amount_paid_min` / `amount_paid_max`（单位分）
    - 订单：`status`、`type`
    - 用户：`user_id`、`username`
    - 内容：`content_id`、`content_title`
    - 时间：`created_at_from/to`、`paid_at_from/to`
  - 排序：`asc` / `desc`
  - API：
    - 列表：`GET /admin/orders`
    - 导出：`GET /admin/orders/export`（应与当前筛选条件一致）
- 订单详情入口：点击行跳 `/orders/:orderID`

### 2.6 订单详情 `/orders/:orderID`

- 详情展示
  - API：`GET /admin/orders/{orderID}`（返回 `dto.AdminOrderDetail`，内含 `models.Order`，其中 `items` 为订单项）
- 退款操作
  - 表单字段：`reason`（建议必填）、`idempotency_key`（前端生成 UUID）、`force`（受控开关，默认 false）
  - API：`POST /admin/orders/{orderID}/refund`（`dto.AdminOrderRefundForm`）
  - 交互：退款前展示校验信息（当前接口描述存在“paid_at + 24h”窗口逻辑），并将强制退款标注为高危操作

### 2.7 余额流水（审计）`/ledgers`

- 流水列表（筛选/分页）
  - 过滤：`user_id`、`order_id`、`operator_user_id`、`biz_ref_type`、`biz_ref_id`、`type`、`created_at_from/to`
  - API：`GET /admin/ledgers`
- 展示重点：
  - `dto.AdminLedgerItem.type_description` 直接用于 UI 展示
  - 金额字段以“分”为单位的，统一格式化为元（保留两位）

### 2.8 媒体资源库 `/media`

- 资源列表（筛选/分页/排序）
  - 过滤：`type`、`status`、`created_at_from/to`
  - 排序：`asc/desc`
  - API：`GET /admin/media_assets`
- 删除资源（软删）
  - API：`DELETE /admin/media_assets/{assetID}`
- 进入详情：跳 `/media/:assetID`

### 2.9 上传媒体资源 `/media/upload`

建议采用“上传任务”模型（可多文件队列）：

1) 初始化上传（创建资源记录 + 获取上传参数）
- API：`POST /admin/media_assets/upload_init`（`dto.AdminMediaAssetUploadInitForm` → `dto.AdminMediaAssetUploadInitResponse`）
- 表单字段：`type`（必填）、`variant`、`source_asset_id?`、`sha256?`、`file_size?`、`content_type?`
2) 直传到对象存储
- 使用返回的 `upload_url` + `form_fields`/`headers` 完成上传
3) 确认上传完成，触发后端处理
- API：`POST /admin/media_assets/{assetID}/upload_complete`（`dto.AdminMediaAssetUploadCompleteForm`）

### 2.10 媒体资源详情 `/media/:assetID`

- API：`GET /admin/media_assets/{assetID}`
- 展示：`type/variant/status/provider/bucket/object_key/meta/created_at` 等；对 `failed` 状态展示失败原因（若后端写在 `meta`）

### 2.11 内容管理 `/contents`（待补接口）

swagger 中目前仅提供：

- 创建草稿：`POST /admin/contents`（`dto.ContentCreateForm`）
- 更新内容：`PATCH /admin/contents/{contentID}`（`dto.ContentUpdateForm`）
- 设置价格：`PUT /admin/contents/{contentID}/price`（`dto.ContentPriceUpsertForm`）
- 绑定媒体资源：`POST /admin/contents/{contentID}/assets`（`dto.ContentAssetAttachForm`）

建议页面拆分：

- 内容列表 `/contents`：需要后端补 `GET /admin/contents`（支持状态/可见性/标题搜索/分页），否则前端无法管理草稿/下架内容。
- 内容创建 `/contents/new`：填写 `title/description/preview_seconds/visibility`
- 内容编辑 `/contents/:contentID`：
  - 基础信息：`PATCH /admin/contents/{contentID}`
  - 价格与折扣：`PUT /admin/contents/{contentID}/price`
  - 资源绑定：从媒体资源库选择 `asset_id`，按 `role(main/cover/preview)` 绑定到内容

## 3. 枚举（UI 需要的固定值）

（直接来自 swagger `definitions/consts.*`）

- 成员角色 `consts.TenantUserRole`：`member`、`tenant_admin`
- 邀请码状态 `consts.TenantInviteStatus`：`active`、`disabled`、`expired`
- 加入申请状态 `consts.TenantJoinRequestStatus`：`pending`、`approved`、`rejected`
- 媒体类型 `consts.MediaAssetType`：`video`、`audio`、`image`
- 媒体状态 `consts.MediaAssetStatus`：`uploaded`、`processing`、`ready`、`failed`、`deleted`
- 订单状态 `consts.OrderStatus`：`created`、`paid`、`refunding`、`refunded`、`canceled`、`failed`
- 订单类型 `consts.OrderType`：`content_purchase`
- 流水类型 `consts.TenantLedgerType`：`debit_purchase`、`credit_refund`、`freeze`、`unfreeze`、`adjustment`
- 内容可见性 `consts.ContentVisibility`：`public`、`tenant_only`、`private`
- 内容状态 `consts.ContentStatus`：`draft`、`reviewing`、`published`、`unpublished`、`blocked`
- 内容资源角色 `consts.ContentAssetRole`：`main`、`cover`、`preview`
- 折扣类型 `consts.DiscountType`：`none`、`percent`、`amount`
- 币种 `consts.Currency`：`CNY`

## 4. 待补接口 / 风险点（从 swagger 反推）

- **内容列表缺失**：没有 `GET /admin/contents`；无法做内容管理主列表、草稿管理、下架列表等。
- **分页返回结构疑似不完整**：多个列表接口在 swagger 中将 `items` 描述为单个 object（`$ref models.*`），但实际应为数组；前端需以实际返回为准，或推动后端修正 swagger（`items: { type: array, items: ... }`）。
- **鉴权机制未在 swagger 体现**：`securityDefinitions` 仅有 `BasicAuth`，且各接口未标注 `security`；前端需确认实际鉴权方式（JWT/Cookie/BasicAuth），并统一处理 401/403。