# 平台管理后台 UI 设计文档

> **模块**：平台管理后台（Platform Admin Console）  
> **输出文件**：`UI_DESIGN/平台管理后台/平台管理后台_UI.md`  
> **设计基线**：`UI_SYSTEM/UI_SYSTEM.md`、`UI_SYSTEM/组件规范设计.md`  
> **需求依据**：`PRD/平台管理后台/平台管理后台PRD.md`  
> **数据模型依据**：`DATA_MODEL/DATA_MODEL_PUBLIC.md`  
> **定位声明**：本界面面向**平台管理员/运营/审计员**，非终端经纪人界面

---

## 1. 设计目标与范围

### 1.1 目标

围绕平台侧管理链路，提供一套高密度、强审计、低误操作风险的后台 UI，覆盖：

1. 租户全生命周期管理（开通/挂起/恢复/删除/License）
2. 平台版本治理（灰度升级、回滚、版本总览）
3. 数据备份恢复与导出
4. 客户端发布治理与版本分布监控
5. 平台监控与告警
6. 审计日志与管理员安全设置（MFA/IP 白名单/会话）

### 1.2 非目标（UI 层）

- 不设计租户内业务页面（房源、客源等终端业务流）
- 不设计移动端适配（桌面优先，`>=1280px`）
- 不设计主题切换入口（保持后台浅色高对比工作流）

---

## 2. 管理员后台设计原则（Admin-first）

1. **可控优先**：所有高危操作（删除、恢复、回滚、强制更新）采用统一二次确认 + MFA。
2. **信息密度优先**：列表和状态总览优先，卡片用于关键 KPI 快速判断。
3. **风险分级可视化**：高危动作使用 `danger` 语义色，关键状态统一 Badge 体系。
4. **可追溯**：写操作入口旁可快速进入审计记录，避免“做了但查不到”。
5. **可扩展 Dashboard**：仪表盘采用模块化组件插槽，便于后续新增运营看板。

---

## 3. 全局信息架构（IA）

## 3.1 页面路由与导航分组

### 一级导航（Sidebar）

- 概览看板
- 租户管理
- 系统版本
- 备份与恢复
- 客户端发布
- 监控与告警
- 审计日志
- 管理员设置

> Topbar 仅承载品牌、全局告警与管理员信息，不承担页面切换。

### 页面清单（与 PRD 对齐）

1. `/admin/login` 登录页
2. `/admin` 仪表盘
3. `/admin/tenants` 租户列表
4. `/admin/tenants/new` 新建租户
5. `/admin/tenants/{id}` 租户详情-基本信息
6. `/admin/tenants/{id}/users` 租户详情-用户管理
7. `/admin/tenants/{id}/plan` 租户详情-套餐信息
8. `/admin/tenants/{id}/monitoring` 租户详情-监控
9. `/admin/tenants/{id}/backups` 租户详情-备份记录
10. `/admin/tenants/{id}/history` 租户详情-操作历史
11. `/admin/system/versions` 系统版本管理（含版本总览）
12. `/admin/system/backups` 备份管理
13. `/admin/monitoring` 监控与告警
14. `/admin/client-releases` 客户端版本管理
15. `/admin/audit-logs` 审计日志
16. `/admin/settings/admins` 管理员设置

## 3.2 页面壳层规范（复用 UI_SYSTEM）

- Topbar：`h-14`，`bg-primary-800`，固定顶部
- Sidebar：展开 `w-60`，折叠 `w-16`
- Main：展开态 `ml-60`，折叠态 `ml-16`
- 主内容区：`bg-neutral-50`，`px-6 py-4`
- 列表工具栏：`sticky top-14 z-30`

> 仅替换导航文案与菜单结构，壳层尺寸、栅格、颜色 token 不做新发明。

---

## 4. 关键页面 UI 设计

## 4.1 登录页（平台管理员）

### 页面结构

- 左侧品牌区（平台管理后台标识）
- 右侧登录卡片（账号 + 密码）
- 登录成功后若未配置 MFA，强制进入 MFA 设置向导

### 交互要点

- 登录失败提示明确（账号/密码错误、IP 不在白名单）
- 首次登录强制绑定 TOTP
- 会话超时 30 分钟后自动跳回登录页

---

## 4.2 仪表盘（可扩展）

### v1 固定模块

1. **全局概览 Stat Card**
   - 总租户数
   - 活跃租户数
   - 本月新增
2. **系统健康面板**（服务状态）
   - Django / PostgreSQL / Redis / Celery / R2
3. **近期告警列表（24h）**
4. **资源概览趋势**（存储/API 调用）
5. **客户端覆盖**（活跃安装数、最新版本占比）
6. **最近高危操作（10条）**

### Dashboard 扩展位（预留）

- `widget-slot-a`（左侧 2/3 宽）
- `widget-slot-b`（右侧 1/3 宽）
- `widget-slot-footer`（全宽）

新增 dashboard 时仅允许以「卡片组件 + 图表组件 + 列表组件」组合，不新增壳层。

---

## 4.3 租户列表

### 筛选区

- 关键词：公司名称 / Tenant Code / 联系邮箱
- 状态：Active / Suspended / Pending Delete / Failed
- 套餐：Basic / Professional / Enterprise
- 到期筛选：即将到期（15天内）
- 用户数筛选：用户数已满（`current >= license_user_limit`）

### 表格列

- 公司名称
- Tenant Code
- 套餐
- 状态
- License 到期日
- 活跃用户数 / License 上限
- 客户端最新版本占比
- 操作（详情 / 挂起 / 备份 / 导出）

### 批量与行操作规则

- 挂起：需要原因（欠费/违规/主动申请/其他）
- 恢复：可直接恢复或按策略恢复
- 删除：软删除默认；硬删除仅 Platform Admin 且需 MFA

---

## 4.4 租户详情（单页分区，无二级 Tab）

租户详情在同一详情页内按信息分区纵向展示：基本信息 / 用户管理 / 套餐信息 / 监控 / 备份记录 / 操作历史。
页面切换统一通过 Sidebar 完成，不在详情抽屉中再设置二级 Tab。

### A. 基本信息

- 公司与联系人信息
- License 到期日期
- License 授权用户上限
- 当前用户数（含 Tenant Admin + Agent）
- 租户访问链接（`https://app.fonrey.com/?tenant={TenantCode}`）
- 入驻信息 PDF 下载

### B. 用户管理

- Tenant Admin 列表
- 用户列表
- 新增/替换/撤销 Tenant Admin
- 重置密码（链接 / 临时密码）

### C. 套餐信息

- 当前套餐
- 升级路径与差异对比
- 生效方式（立即 / 下一账期）

### D. 监控

- CPU/内存、存储、API 调用、慢查询、异常请求

### E. 备份记录

- 备份时间、触发方式、大小、状态
- 手动备份
- 恢复入口（仅 Platform Admin，MFA）

### F. 操作历史

- 该租户相关操作审计流

---

## 4.5 系统版本管理（含版本总览）

### Part 1 平台基础数据版本

- 版本号
- 最后升级时间
- 升级描述
- 执行人

### Part 2 租户数据升级版本

- 租户名称
- 当前数据版本
- 上次升级时间
- 升级状态（最新/待升级/升级中/升级失败）
- 支持筛选：待升级、升级失败

### 升级操作区

- 升级包管理
- 升级策略（全量/灰度）
- 灰度租户名单
- 实时进度（批次 + 租户维度）
- 一键回滚（MFA）

---

## 4.6 备份管理（全局）

### 配置区

- 频率：每小时 / 每日 / 每周
- 执行时间窗口
- 保留数量
- 存储目标（local/s3/r2/gcs）

### 列表区

- 备份任务状态（pending/in_progress/success/failed）
- 支持重试失败任务
- 支持按租户下钻

---

## 4.7 客户端版本管理

### 版本列表

- 版本号（SemVer）
- 版本类型（普通/强制）
- 状态（草稿/已发布/已下线）
- 发布时间
- 下载量
- 操作（发布/下线/编辑/回滚）

### 新增/编辑版本表单

- 版本号
- 最低兼容版本
- 安装包（EXE）
- 便携版（ZIP，可选）
- SHA256（自动生成）
- 更新日志（Markdown）
- 内部发布说明

### 分布统计区（Dashboard 风格）

- 版本分布（饼图/条形）
- 升级进度趋势
- 租户版本分布明细
- 全平台租户活跃榜（tenant_code、活跃安装、历史装机）

### 强制更新

- 支持按版本范围打标
- 强制更新推送需 MFA

---

## 4.8 监控与告警

### 监控维度

- 全局与租户维度切换
- 资源、错误率、SLA、慢查询

### 告警规则

- 指标 + 阈值 + 通知渠道（邮件/Webhook）
- 告警历史可检索

---

## 4.9 审计日志

### 筛选项

- 操作人
- 时间范围
- 操作对象
- 操作类型（创建/修改/删除/高危）
- 结果（成功/失败）

### 列表字段

- 操作人
- 操作时间
- 对象类型/对象ID
- 内容摘要
- 结果
- 来源 IP

### 导出

- 按当前筛选导出 CSV

---

## 4.10 管理员设置

### 功能区

1. 管理员账号管理（创建/编辑/停用）
2. 角色分配（super_admin / ops_operator / read_only_auditor）
3. MFA 设备管理
4. IP 白名单管理（CIDR）
5. 活跃会话与强制登出

---

## 5. 高危操作统一交互模式（全局组件契约）

## 5.1 两段式确认

1. 首次确认弹窗（动作影响说明）
2. MFA 验证弹窗（TOTP 输入）

## 5.2 高危动作清单

- 硬删除租户
- 数据恢复
- 系统回滚
- 客户端版本下线
- 强制更新推送

## 5.3 文案模板

- 标题：`确认执行高危操作？`
- 副文案：`该操作可能影响在线租户与数据可用性，请完成 MFA 验证后继续。`
- 按钮：`取消`（Secondary） / `继续并验证`（Danger）

---

## 6. 组件复用清单（来自 UI_SYSTEM/组件规范）

1. **Data Table**：租户列表、版本列表、审计日志
2. **Pagination**：统一 20/50/100 条
3. **Toolbar**：批量操作与快捷入口
4. **Section Navigation（详情分区）**：租户详情采用单页分区结构（无二级 Tab），版本管理保持分区信息架构
5. **Modal Dialog**：确认与新建操作
6. **Drawer**：复杂编辑（规则、详情）
7. **Date Range Picker**：日志与统计筛选
8. **Stat Card**：仪表盘 KPI

> 禁止引入不在 UI_SYSTEM 定义的新视觉范式。

---

## 7. 数据模型映射（DATA_MODEL_PUBLIC）

| 页面能力 | 主要表 |
|---|---|
| 租户列表/详情/状态变更 | `public.tenants`, `public.tenant_status_logs` |
| 管理员登录/MFA/会话/IP 白名单 | `public.platform_admins`, `public.admin_mfa_devices`, `public.admin_sessions`, `public.ip_whitelist` |
| 审计日志 | `public.platform_audit_logs` |
| 备份与导出 | `public.backup_schedules`, `public.backup_records`, `public.export_tasks` |
| 系统版本与升级事件 | `public.system_versions`, `public.upgrade_events` |
| 客户端发布 | `public.client_releases`, `public.client_heartbeats` |
| Feature Flag（后续扩展） | `public.feature_flag_definitions`, `public.feature_flag_change_log`, `public.tenants.feature_flags` |

---

## 8. 角色权限与页面可见性矩阵

| 页面/操作 | Platform Admin | 运营人员 | 只读审计员 |
|---|---:|---:|---:|
| 仪表盘查看 | ✅ | ✅ | ✅ |
| 租户创建/挂起/恢复 | ✅ | ✅ | ❌ |
| 硬删除租户 | ✅ | ❌ | ❌ |
| 调整 License 到期/用户上限 | ✅ | ✅ | ❌ |
| 备份触发 | ✅ | ✅ | ❌ |
| 数据恢复 | ✅ | ❌ | ❌ |
| 系统升级/回滚 | ✅ | ❌（只读） | ❌ |
| 客户端发布/下线/强制更新 | ✅ | ❌（只读） | ❌ |
| 审计日志查看与导出 | ✅ | ✅ | ✅ |
| 管理员设置 | ✅ | ❌ | ❌ |

---

## 9. 状态矩阵（关键页面）

| 页面 | 默认态 | 加载态 | 成功态 | 失败态 |
|---|---|---|---|---|
| 租户列表 | 最近查询结果 | 表格骨架/Spinner | Toast 成功 + 刷新列表 | 错误 Toast + 保留原列表 |
| 租户详情 | 分区信息默认展开 | 局部 Skeleton | 字段回写 + 操作日志入口 | 字段级错误提示 |
| 系统版本 | 当前版本总览 | 批次进度中 | 升级完成状态标记 | `halted` 告警 + 回滚入口 |
| 客户端发布 | 版本列表 | 上传进度 | SHA256 回填 + 发布成功 | 校验失败/上传失败提示 |
| 审计日志 | 最近记录 | 列表刷新中 | 导出任务创建成功 | 导出失败提示 + 重试 |

---

## 10. 校验与文案规范（管理员语境）

1. 所有错误文案需“可操作”：
   - ✅ `版本号格式错误，应为 X.Y.Z`
   - ❌ `参数非法`
2. 高危操作失败需包含最小原因：
   - `MFA 验证失败，请重新输入 6 位动态码`
3. 操作成功反馈需带动作对象：
   - `租户「上海某某地产」已挂起`
4. 审计可见入口：写操作成功 Toast 提供 `查看审计记录` 链接

---

## 11. 可访问性与实现约束

- 所有 Icon 按钮必须有 `aria-label`
- 表格头使用 `scope="col"`
- 弹窗支持 `Esc` 关闭（高危二次确认按流程控制）
- 焦点可见（`focus-visible:ring-*`）
- 禁止仅用颜色表达状态，必须 `Badge + 文本`

---

## 12. 验收清单

- [x] 页面 IA 与路由覆盖 PRD 16 个页面
- [x] 管理员三角色权限可见性已定义
- [x] 高危操作统一二段式确认（含 MFA）
- [x] Dashboard 已定义固定模块 + 扩展插槽
- [x] 与 `DATA_MODEL_PUBLIC` 主表映射完成
- [x] 复用 `UI_SYSTEM` 与 `组件规范设计` 组件体系
- [x] 明确本后台为管理员使用，不采用终端用户视觉套路