449 lines
12 KiB
Markdown
449 lines
12 KiB
Markdown
# 平台管理后台 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] 明确本后台为管理员使用，不采用终端用户视觉套路
|