# 租户管理员管理 Portal（frontend/tenant_admin）规划

以“中老年人可用性”为第一准则：**大字、少层级、少打扰、强反馈、可撤销**。本规划基于现有后端租户管理员接口：`/t/:tenantCode/v1/admin/*`。

## 1. 设计准则（必须遵守）

### 1.1 视觉与可读性
- 默认开启“大字模式”：正文 ≥ 16–18px，关键数字/按钮 ≥ 18–20px；行高 ≥ 1.5。
- 高对比配色：文字与背景对比度优先（避免浅灰字+浅灰底）；状态色同时配文字标签（不只靠颜色）。
- 重要信息“一屏可读”：首屏优先展示“今天/本月关键数据 + 待办”。

### 1.2 交互与流程
- **三步以内完成**：常用任务（发布内容、调价、处理退款、通过入驻）不超过 3 步。
- **少记忆**：减少需要用户记住的字段（例如状态/角色用下拉；金额用分步输入+自动格式化）。
- **强反馈**：所有提交必须有 loading、成功提示与失败原因（可复制），避免“静默失败”。
- **可撤销**：高风险操作（下架/封禁/退款/移除成员/禁用邀请）必须二次确认，并提供“操作记录/可追溯”入口。

### 1.3 列表呈现（中老年友好）
- 列表优先“卡片式信息块”，表格仅用于“需要对比多列”的场景。
- 筛选默认收起为“基础筛选”；“高级筛选”折叠面板，避免压迫感。
- 每条记录提供明确的“主要动作按钮”（如：下架/通过/退款），避免图标-only。

## 2. 信息架构（路由与菜单建议）

建议路由基座：`/t/:tenantCode/admin/`（便于天然携带 tenantCode）；API 仍走 `/t/:tenantCode/v1/admin/*`。

### 菜单（一级不超过 6 个）
1) 概览（Dashboard）
2) 内容管理
3) 订单与退款
4) 成员管理
5) 邀请与入驻
6) 财务流水

## 3. 页面与功能（页面 → 关键交互 → 对应接口）

### 3.1 登录与租户上下文
- 登录页：大输入框、显示/隐藏密码、登录失败提示可复制。
- 租户切换：若未来支持同一管理员多租户，提供“切换租户”入口（卡片列表）。
- 接口（若已有）：`/t/:tenantCode/v1/*` 的登录/鉴权体系（按现有项目登录方案对接）。

### 3.2 概览 Dashboard（优先做）
目标：一眼看懂 + 一键处理待办。
- 今日/本月：订单数、收入（来自订单/流水聚合）、退款中数量、待处理入驻申请数量。
- 待办区：入驻申请（通过/拒绝）、退款申请（查看/处理）、内容审核中（如果存在 reviewing）。
- 数据来源：`GET /t/:tenantCode/v1/admin/orders`、`GET /t/:tenantCode/v1/admin/ledgers`、`GET /t/:tenantCode/v1/admin/join-requests`（前端聚合，必要时再增后端统计接口）。

### 3.3 内容管理（发布/下架/定价/素材）
#### 3.3.1 内容列表（卡片 + 关键动作）
- 展示：标题、状态（草稿/已发布/已下架/封禁）、可见性、价格（免费/￥）、发布时间。
- 操作：编辑、调价、绑定素材、下架（已发布才显示）、重新上架（若允许）。
- 接口：`POST /admin/contents`、`PATCH /admin/contents/:contentID`、`PUT /admin/contents/:contentID/price`、`POST /admin/contents/:contentID/assets`。

#### 3.3.2 发布向导（强引导）
三步向导：
1) 基本信息（标题/描述/可见性）
2) 上传素材（主视频/试看/封面）
3) 定价与发布（免费/付费，确认发布）
失败时给出“下一步建议”（例如：素材未 ready）。

#### 3.3.3 素材库（Media Assets）
- 列表：状态（uploaded/processing/ready/failed）、类型、上传时间；提供“重新触发处理/删除”。
- 上传：引导式上传（单文件/多文件），显示上传进度与完成确认。
- 接口：`GET /admin/media_assets`、`GET /admin/media_assets/:assetID`、`POST /admin/media_assets/upload_init`、`POST /admin/media_assets/:assetID/upload_complete`、`DELETE /admin/media_assets/:assetID`。

### 3.4 订单与退款（中老年人常用）
#### 3.4.1 订单列表
- 基础筛选：订单号、买家用户名、状态（已支付/退款中/已退款）。
- 卡片展示：买家、金额、状态、创建/支付时间；提供“查看详情”与“发起退款”。
- 接口：`GET /admin/orders`、`GET /admin/orders/:orderID`、`GET /admin/orders/export`。

#### 3.4.2 退款处理
- 退款弹窗：原因（可选模板）、二次确认、成功后提示“退款处理中”。
- 接口：`POST /admin/orders/:orderID/refund`。

### 3.5 成员管理（更强调“安全、少误触”）
- 成员列表：用户名、角色、加入时间；角色变更入口明显，但默认收起到详情页避免误触。
- 操作：移除成员（二次确认）、设置角色（member/tenant_admin）。
- 接口：`GET /admin/users`、`PATCH /admin/users/:userID/role`、`DELETE /admin/users/:userID`、`POST /admin/users/:userID/join`（平台或客服协助加入）。

### 3.6 邀请与入驻（把“待办”放在首屏）
#### 3.6.1 邀请管理
- 创建邀请：生成邀请码/链接，一键复制；可设置有效期/次数（若后端支持）。
- 列表：状态、创建时间、使用情况；禁用邀请（二次确认）。
- 接口：`POST /admin/invites`、`GET /admin/invites`、`PATCH /admin/invites/:inviteID/disable`。

#### 3.6.2 入驻申请（Join Requests）
- 列表：申请人、申请时间、备注（若有）、状态；一键通过/拒绝。
- 接口：`GET /admin/join-requests`、`POST /admin/join-requests/:requestID/approve`、`POST /admin/join-requests/:requestID/reject`。

### 3.7 财务流水（Ledger）
- 展示：收入/退款/手续费等（按 `TenantLedgerType`），支持时间筛选与导出（若后端支持）。
- 接口：`GET /admin/ledgers`。

## 4. 组件与交互规范（落地建议）
- 全局提供“简洁模式/大字模式”开关（默认大字）；切换后记忆到 `localStorage`。
- 列表默认“卡片视图”，提供“表格视图”切换（给高频专业用户）。
- 表单控件：金额用“元”输入但内部转换为“分”；日期选择器默认提供“今天/近7天/本月”快捷。
- 错误提示：同时展示“可读中文 + request_id（可复制）”，便于客服协助。

## 5. MVP 迭代顺序（建议）
1) 登录/鉴权 + Dashboard（含待办）
2) 内容管理：列表 + 发布向导 + 下架
3) 订单列表 + 退款
4) 成员管理 + 入驻申请
5) 邀请管理 + 财务流水