文档更新

Project/fonrey/UI_DESIGN/平台管理后台/平台管理后台_UI.md

@@ -0,0 +1,448 @@
+# 平台管理后台 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] 明确本后台为管理员使用，不采用终端用户视觉套路