# PRD：系统管理模块（Admin & System Management）

**状态**：Draft  
**作者**：产品经理  
**最后更新**：2026-05-01  
**版本**：v1.3  
**利益相关方**：工程负责人、运营团队、安全合规、客户成功团队

## 变更历史

| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|---------|
| v1.0 | 2026-04-24 | 产品经理 | 初稿 |
| v1.1 | 2026-05-01 | 产品经理 | ① Story 1 补充「默认配置」内容定义（权限定义 + 系统默认角色）；② Story 1 补充欢迎通知机制（邮件内容规范、默认密码发放、Tenant Code、页面下载 PDF）；③ Story 2 补充 License 时效管理（到期自动挂起、提前 15 天预警倒计时）；④ Story 3 标注为已废弃（暂不实现）；⑤ 新增 Story 7：平台版本总览（基础数据版本 + 租户数据升级版本）；⑥ §5.1.1 补充默认配置内容说明、通知机制细节、时效日期字段、到期挂起流程；⑦ 管理员角色权限矩阵补充版本总览权限 |
| v1.3 | 2026-05-01 | 产品经理 | Story 1 Tenant Admin 权限机制修正：初始 Tenant Admin 不赋予任何业务角色，由系统在租户创建时直接写入独立的「租户管理员」专属权限集合；该集合不在角色管理界面显示，不可自行修改或分配；新增/变更租户管理员须由平台运营方操作 |


---

## 1. 问题陈述

### 1.1 背景

Fonrey 是一套面向房产经纪公司的 B2B SaaS 平台，采用 `django-tenants` 实现 PostgreSQL Schema 级别的多租户隔离。随着平台商业化推进，运营团队需要一套独立的管理后台（Admin Console）来管理租户生命周期、系统升级、备份恢复及合规审计。

**本模块解决的核心问题**：平台运营团队当前缺乏统一的工具来：
1. 管理数百家经纪公司（租户）的开通、暂停、注销流程
2. 在不中断服务的前提下对平台进行版本升级与灰度发布
3. 应对数据灾难场景（数据误删、升级失败）时快速恢复
4. 满足合规要求，对所有高危操作留存完整审计轨迹

### 1.2 核心痛点

| 痛点 | 影响方 | 当前代价 |
|------|--------|---------|
| 无统一租户管理界面，开通/暂停操作依赖人工脚本 | 运营团队 | 高错误风险，操作耗时 |
| 版本升级需停机维护，影响所有租户 | 所有用户 | SLA 违约风险 |
| 数据备份无策略，灾难恢复依赖人工 | 平台稳定性 | 数据丢失风险 |
| 高危操作无审计日志，合规风险暴露 | 管理层/合规 | 法律与客户信任风险 |

### 1.3 目标用户

| 角色                          | 使用场景        | 频率     |
| --------------------------- | ----------- | ------ |
| Platform Admin（平台超级管理员）（Platform Super Admin） | 全局配置、高危操作授权 | 低频（每周） |
| 运维人员（Ops Operator）          | 日常租户管理、监控巡检 | 高频（每日） |
| 只读审计员（Read-only Auditor）    | 日志查询、合规报告导出 | 中频（每周） |

---

## 2. 目标与成功指标

| 目标       | 指标          | 当前基线        | 目标值             | 测量窗口     |
| -------- | ----------- | ----------- | --------------- | -------- |
| 租户管理效率提升 | 新租户开通耗时     | 人工脚本 ~30 分钟 | < 5 分钟（含自动初始化）  | 上线后 30 天 |
| 平台升级零停机  | 升级期间受影响租户数  | 全量中断        | 灰度阶段受影响 ≤ 5% 租户 | 每次升级     |
| 数据恢复能力建立 | RTO（恢复时间目标） | 无标准流程       | 单租户恢复 < 2 小时    | v1 上线即达标 |
| 操作合规覆盖   | 高危操作审计日志覆盖率 | 0%          | 100%            | 上线后 30 天 |
| 管理员安全    | MFA 启用率     | 0%          | 100%（强制）        | 上线即达标    |

---

## 3. 非目标（Non-Goals）

- **不在 v1 实现**：自动化账单计费、多币种支持、Webhook 自定义集成市场
- **不在本模块**：租户内业务权限的细粒度配置（见权限管理模块 PRD）
- **不在本模块**：客服工单系统、SLA 自动赔付
- **不支持**：移动端浏览器（管理后台仅面向桌面，运营人员使用场景明确）

---

## 4. 用户角色与核心故事

### Persona A：运营人员 Lily（日常租户管理）

> 负责 Fonrey 平台的日常运营，每天需要处理新客户开通、异常租户处理、客户咨询的数据导出请求，使用 PC 浏览器访问管理后台。

**Story 1**：新租户开通

> 作为运营人员，我希望通过填写表单快速完成租户开通，并由系统自动完成数据库初始化与欢迎邮件，无需手动执行脚本。

**验收标准**：
- [ ] 表单提交后，系统在后台自动创建 PostgreSQL Schema 并注入默认配置（见 §5.1.1 默认配置说明），完成时间 < 60 秒
- [ ] 默认配置注入包含两部分：**（1）权限定义（PermissionDef）**：注入该平台所有权限码的定义数据（`permission_code`、描述、模块归属），作为该租户 RBAC 权限体系的基础；**（2）系统默认角色与权限绑定**：按「角色权限矩阵.md」定义注入 7 个系统内置业务角色——置业顾问、店管、区管、区总、副总、总经、其他职能——并完成各角色对应的权限集合绑定
- [ ] 初始 Tenant Admin 用户（以联系人手机号创建）**不通过业务角色赋权**，而是在租户创建时由系统直接写入「租户管理员」专属权限集合；该权限集合独立于 7 个业务角色之外，不在租户的角色管理界面中显示，不可由 Tenant Admin 自行修改或分配给其他用户；如需新增或变更租户管理员，须由平台运营方在管理后台操作
- [ ] 新租户创建后，平台运营管理员收到系统内通知（站内消息）；租户联系人收到欢迎邮件（见下方「欢迎邮件规范」）
- [ ] 若联系人无邮箱，运营人员可在租户详情页下载「入驻信息 PDF 文档」，通过微信等渠道手动转发
- [ ] 租户访问地址采用 Fonrey 平台统一域名 + Tenant Code 参数的形式（如 `https://app.fonrey.com/?tenant=ABCD`），无需为每个租户单独创建子域名；租户详情页展示该访问链接，可一键复制
- [ ] 创建失败时回滚所有已创建资源，并显示明确的错误原因

**欢迎邮件规范**（联系人有邮箱时自动发送）：

| 字段   | 内容                                                                                                          |
| ---- | ----------------------------------------------------------------------------------------------------------- |
| 主题   | 【房睿平台】您的账号已开通，欢迎登录                                                                                          |
| 收件人  | 租户联系人邮箱                                                                                                     |
| 正文内容 | 公司名称、**Tenant Code**（登录时所需的租户识别码）、登录地址（`https://app.fonrey.com/?tenant={Tenant Code}`）、Tenant Admin 手机号（脱敏展示后三位）、**系统初始密码**（明文，首次登录后强制修改）、平台客服联系方式 |
| 备注   | 初始密码由系统随机生成（12 位，含大小写字母+数字），发送后立即标记为「首次登录强制修改」状态                                                            |

**入驻信息 PDF 文档**（可在租户详情页下载，适用于无邮箱客户）：

- 包含与欢迎邮件相同的所有关键信息
- 页面入口：租户详情 → 基本信息 Tab → 「下载入驻信息」按钮
- 文件名格式：`{公司名称}_入驻信息_{日期}.pdf`

**Story 2**：挂起问题租户

> 作为运营人员，我希望能快速冻结欠费租户的访问，同时保证数据不丢失，并在欠费解决后一键恢复。

**验收标准**：
- [ ] 挂起操作执行后，该租户所有用户登录跳转至"账号已暂停"提示页，管理后台数据访问不受影响
- [ ] 支持设置到期时间，到期后系统自动恢复租户状态，并发送通知邮件
- [ ] 所有挂起/恢复操作记录于操作审计日志，包含操作人、时间、原因

**Story 2b**：License 时效管理与到期自动挂起

> 作为 Platform Admin，我希望每个租户能够设置 License 有效期，在到期后系统自动挂起租户，并在到期前提前预警，减少人工干预。

**验收标准**：
- [ ] 每个租户的「基本信息」中包含 **License 到期日期**字段，由 Platform Admin 在创建租户或套餐续费时设定（如购买 1 年期 License）
- [ ] 系统（Celery Beat 每日检查）在 License 到期时自动将租户状态切换为「已挂起 Suspended」，挂起原因标注为「License 到期」
- [ ] 自动挂起后，租户联系人收到通知邮件；Platform Admin 可手动解除挂起（续费后操作）
- [ ] **提前 15 天预警倒计时**：租户内的 Tenant Admin 在登录后的管理界面顶部看到醒目横幅提示，内容示例：「您的 License 将于 X 天后到期（{到期日期}），请联系平台续费。」；提前 15 天开始出现，每天展示直至到期或续费完成
- [ ] 倒计时横幅仅对租户端 Tenant Admin 可见，不影响普通 Agent 用户体验（可配置）
- [ ] License 到期日期在管理后台租户列表和详情页均可见，支持按「即将到期（15 天内）」筛选

**Story 3**：响应客户数据导出请求

> **状态**：暂缓（当前 P0 计划阶段不实现，后续迭代规划）。本 Story 保留需求描述，待进入相应排期后正式细化。

---

### Persona B：Platform Admin（平台超级管理员） David（系统升级与回滚）

> 负责平台技术运维，周期性执行版本升级，关注升级稳定性与租户影响面，有权执行所有高危操作。

**Story 4**：灰度系统升级

> 作为Platform Admin（平台超级管理员），我希望先对内测租户升级新版本，验证稳定后再全量推送，避免一次性影响所有客户。

**验收标准**：
- [ ] 升级前自动执行健康检查，存在异常服务时阻断升级并提示
- [ ] 支持指定目标租户进行灰度升级，灰度租户名单可编辑
- [ ] 升级过程实时展示进度（每个租户的升级状态），支持查看升级日志
- [ ] 升级失败时系统自动告警，并提供一键回滚入口

**Story 5**：升级失败回滚

> 作为Platform Admin（平台超级管理员），我希望在升级出现问题时能立即回滚至上一稳定版本，并生成事件报告。

**验收标准**：
- [ ] 回滚操作触发前自动保存当前状态快照
- [ ] 支持全量回滚或单租户回滚
- [ ] 回滚完成后生成事件报告：失败原因、回滚耗时、影响范围
- [ ] 回滚操作需二次身份验证确认

---

### Persona C：只读审计员 Carol（合规审计）

> 负责平台合规审查，定期导出操作日志供法务或客户审查，无任何写权限。

**Story 6**：审计日志查询与导出

> 作为审计员，我希望能按操作人、时间范围、操作类型筛选操作日志，并导出为报告格式。

**验收标准**：
- [ ] 日志列表支持多维度筛选：操作人、时间范围、操作对象、操作类型（创建/修改/删除/高危操作）
- [ ] 日志条目包含：操作人、操作时间、操作对象（租户/用户ID）、操作内容摘要、操作结果（成功/失败）、操作来源 IP
- [ ] 支持导出筛选结果为 CSV 格式

---

### Persona D：Platform Admin（平台超级管理员）David（平台版本总览）

**Story 7**：查看平台与租户版本总览

> 作为 Platform Admin，我希望能在管理界面一眼看到整个平台的版本情况，包括基础数据版本和每个租户各自的数据升级版本，以便掌握升级进度和版本差异。

**验收标准**：
- [ ] 管理控制台「系统版本管理」页面提供「版本总览」视图，分为两个部分：

  **Part 1：平台基础数据版本**
  - 展示当前平台基础数据（公共 Schema 中的 PermissionDef、系统配置等 seed 数据）的版本号
  - 该版本对所有租户一致，每次平台升级为一次性全量升级
  - 展示字段：版本号、最后升级时间、升级描述、升级执行人

  **Part 2：租户数据升级版本**
  - 以列表形式展示每个租户当前的数据版本号（即该租户 Schema 已完成的 migration 版本）
  - 由于采用灰度升级，各租户版本号可能不一致
  - 列表字段：租户名称、当前数据版本号、上次升级时间、升级状态（最新 / 待升级 / 升级中 / 升级失败）
  - 支持按「待升级」「升级失败」筛选，快速定位异常租户
  - 点击租户行可跳转至该租户详情的「备份记录」Tab 查看详情

- [ ] 页面支持手动刷新版本状态
- [ ] 「版本总览」数据展示无需实时，允许最多 5 分钟缓存延迟

---

**Story 8**：查看与控制租户用户数

> 作为 Platform Admin，我希望能在管理界面看到每个租户当前的用户数量，并能设置用户数上限，以便根据 License 授权进行管控（用户数是 License 计费的重要依据）。

**验收标准**：
- [ ] 租户列表新增「当前用户数」列，显示该租户当前已创建的有效用户总数（含 Tenant Admin + 所有 Agent，不含已删除/离职用户）
- [ ] 租户详情页「基本信息」Tab 显示：当前用户数 / License 授权用户数上限（如：12 / 50）
- [ ] Platform Admin 可在租户详情页设置「License 授权用户数上限」字段；当租户实际用户数达到上限时，Tenant Admin 在该租户内将无法继续创建新用户，并收到提示：「当前用户数已达 License 上限，请联系平台扩容」
- [ ] Platform Admin 可随时调整用户数上限（续费扩容 or 缩容），变更记录写入操作审计日志
- [ ] 租户列表支持按「用户数已满（≥ 上限）」筛选，便于平台运营主动识别需要续费的租户

---



### 5.1 租户管理（Tenant Management）

#### 5.1.1 租户生命周期

**新建租户**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 公司名称 | Text | ✅ | 最大 100 字符 |
| 联系人 | Text | ✅ | 租户主联系人姓名 |
| 联系邮箱 | Email | ❌（可选） | 用于发送欢迎邮件及系统通知；无邮箱时改用 PDF 下载方式 |
| 所在地区 | Select | ✅ | 省市两级 |
| 订阅套餐 | Select | ✅ | Basic / Professional / Enterprise |
| 子域名 | Text | ❌（无需） | 租户访问统一使用 Fonrey 平台域名 + Tenant Code 参数，无子域名 |
| License 到期日期 | Date | ✅ | 由 Platform Admin 设定，决定租户有效期；到期后系统自动挂起 |

创建流程：
1. 表单校验通过后，后台 Celery 任务执行：
   - 创建 PostgreSQL Schema（`tenant_{id}`）
   - 执行 Migrate 初始化表结构
   - 注入默认配置（见下方「默认配置内容」说明）
   - 生成初始密码（12 位随机，含大小写字母+数字），标记为「首次登录强制修改」
   - 若联系邮箱已填写：发送欢迎邮件（含 Tenant Code、初始密码、平台访问链接 `https://app.fonrey.com/?tenant={TenantCode}`）
2. 任务完成后更新租户状态为 `active`，失败则全量回滚并标记为 `failed`
3. 生成唯一 Tenant ID（UUID）及 Tenant Code（可读短码，如 `FR-2024-0001`），记录创建时间、创建人

**默认配置内容（Schema 初始化时注入）**：

| 配置类型 | 内容 | 说明 |
|---------|------|------|
| 权限定义（PermissionDef） | 平台全量权限码（`permission_code`、描述、模块归属） | 从 public schema 同步至租户 schema，作为 RBAC 权限体系基础 |
| 系统默认角色 | Tenant Admin（租户管理员）、Agent（经纪人） | 按权限管理模块 PRD 定义的权限集合完成角色-权限绑定 |
| 初始 Tenant Admin 用户 | 以联系人手机号创建，角色为 Tenant Admin | 首次登录后强制修改密码 |

**挂起（Suspend）**

- 操作触发条件：
  - **手动触发**：运营人员手动触发，选择挂起原因（欠费 / 违规 / 主动申请 / 其他）
  - **自动触发**：Celery Beat 每日检查 License 到期日期，到期后自动挂起（原因标注为「License 到期」）
- 可设置挂起到期时间（留空表示永久挂起直至手动恢复）
- 挂起效果：该租户所有用户请求返回 `HTTP 403`，重定向至暂停提示页；管理后台数据仍可访问
- 到期自动恢复：`Celery Beat` 定时检查到期挂起记录，自动切换状态为 `active`（仅适用于手动设置了到期时间的挂起；License 到期自动挂起需 Platform Admin 手动恢复）
- 通知：挂起与恢复均向租户联系邮箱发送通知邮件（无邮箱则跳过）
- **License 到期预警**：License 到期前 15 天起，租户端 Tenant Admin 管理界面顶部显示倒计时横幅，直至到期或续费后由 Platform Admin 更新 License 到期日期

**删除（Delete）**

| 模式 | 说明 |
|------|------|
| 软删除（Soft Delete） | 标记删除状态，数据保留 30 天（默认，可配置）后由 Celery 定时任务清除 |
| 硬删除（Hard Delete） | 立即清除所有数据、Schema、存储资源及子域名授权；仅Platform Admin（平台超级管理员）可操作 |

删除前置条件：
1. 操作人必须确认数据导出已完成（勾选确认框）
2. 硬删除需二次身份验证（MFA 确认）
3. 软删除冷静期内（默认 30 天），可在租户列表中对已删除租户执行"撤销删除"

删除完成后：释放子域名、Cloudflare R2 存储桶、License 席位

#### 5.1.2 数据管理

**数据导出**

- 触发方式：管理员手动触发，选择目标租户 + 导出模块 + 格式
- 异步执行：Celery 任务，任务状态实时刷新（Pending → In Progress → Done / Failed）
- 导出包内容：结构化数据（CSV / JSON / SQL Dump）+ 文件资产 URL 清单，**不打包文件实体**
- 导出模块选项：客户数据 / 房源数据 / 交易记录 / 系统配置 / 全量
- 导出包存储：压缩后存于 Cloudflare R2 临时目录，生成带签名下载链接，有效期 24 小时

**文件资产（图片/附件）的导出处理规则**

> **设计决策**：v1 不打包文件实体，文件以 CDN 持久 URL 形式内嵌于导出数据中。
> 依据：R2 Bucket 配置为 public read，文件通过 Cloudflare CDN 对外提供持久访问；
> 在租户账号未被硬删除的情况下，CDN URL 始终有效，满足合规/审计场景需求。
> 迁移场景（需要文件实体）走"完整备份"流程，不走"数据导出"流程。

各导出格式的文件字段表达方式：

| 导出格式 | 图片字段示例 | 附件字段示例 |
|---------|------------|------------|
| CSV | `photos` 列：多个 CDN URL 以英文分号分隔 | `attachments` 列：`文件名\|CDN URL` 以分号分隔 |
| JSON | `"photos": [{"url": "https://cdn.../xxx.jpg", "filename": "封面.jpg", "created_at": "..."}]` | `"attachments": [{"url": "...", "filename": "合同.pdf"}]` |
| SQL Dump | 文件元数据表原样导出，`file_url` 字段为 CDN URL | 同左 |

导出包内附说明文件（`README.txt`），注明：
> "图片与附件以 Cloudflare CDN 链接形式提供，链接在账号有效期内持续可访问。账号注销后链接将在 30 天冷静期结束时失效。如需迁移文件本体，请联系平台支持发起完整数据备份（Backup）。"

**数据导出 vs 完整备份的边界**

| 维度 | 数据导出（Export） | 完整备份（Backup） |
|------|------------------|-----------------|
| 用途 | 合规审计、数据核查、业务分析 | 灾难恢复、租户迁移 |
| 文件资产 | CDN URL 清单，不含文件实体 | 含 R2 文件实体（完整同步） |
| 完成时间 | 分钟级 | 小时级（取决于文件总量） |
| 触发方式 | 运营人员手动触发 | 手动触发 / 系统自动触发（升级前） |
| 存储成本 | 极低（仅压缩包） | 较高（完整文件副本） |

**数据备份（Snapshot）**

- 自动触发：升级前系统自动触发该租户全量备份
- 手动触发：管理员可在租户详情页手动发起备份
- 备份内容：数据库 Schema（pg_dump）+ Cloudflare R2 文件存储（附件、图片）
- 备份记录展示字段：备份时间、触发方式（自动/手动）、备份大小、状态（进行中/成功/失败）
- 保留策略：默认保留最近 10 个版本，可在系统全局配置中调整
- 存储：加密存储，支持目标存储配置（本地 / S3 / Cloudflare R2 / GCS）

**数据恢复（Restore）**

恢复流程：

```
选择目标备份版本
  → 二次确认弹窗（显示将覆盖的当前数据版本信息）
  → 自动对当前数据生成临时快照（防止恢复失误）
  → 租户切换为维护模式（用户访问显示"维护中"提示）
  → 执行数据恢复（Celery 任务）
  → 恢复完成 → 自动恢复服务 → 生成恢复操作报告
```

恢复操作报告包含：操作人、操作时间、恢复前数据版本、恢复后数据版本、耗时、结果

#### 5.1.3 套餐与升级管理

**Plan 升级**

- 支持升级路径：Basic → Professional → Enterprise
- 升级前展示差异对比表（功能项、用户数上限、存储空间、API 调用额度）
- 生效模式：立即生效 / 按账期生效（下一个账期开始时生效）
- 升级前自动触发数据备份
- 升级失败：提供一键回滚至备份版本
- 升级历史记录：时间、操作人、升级前套餐、升级后套餐

#### 5.1.4 用户与权限管理

**Tenant Admin 管理**

- 每个租户可设置 1 至多名 Tenant Admin（超级用户）
- Platform Admin（平台超级管理员）可直接在后台创建新用户并赋予 Tenant Admin 角色，或从租户现有用户中指定
- 支持查看当前 Tenant Admin 列表，执行：新增 / 替换 / 撤销权限

**Tenant Admin 权限配置（RBAC）**

可配置权限项：

| 权限项 | 说明 |
|--------|------|
| 创建/删除子用户 | 是否允许 Tenant Admin 管理租户内部用户 |
| 修改系统配置 | 是否允许修改租户级系统设置（字段标签、规则等） |
| 查看账单与套餐 | 是否允许查看订阅信息和费用详情 |
| 数据导出 | 是否允许在租户端触发数据导出 |

权限基于 RBAC 模型，支持自定义角色（角色名称 + 权限集合），可在多 Tenant Admin 间复用。

**密码重置**

- Platform Admin（平台超级管理员）可为任意租户的任意用户发起密码重置
- 方式一：发送重置链接至注册邮箱（用户自助重置）
- 方式二：管理员直接设置临时密码（用户首次登录后强制修改）
- 所有重置操作记录于操作审计日志

#### 5.1.5 租户监控与统计

**资源监控**

实时展示指标（基于 Grafana + 自定义数据采集）：

| 指标 | 展示维度 |
|------|---------|
| CPU / 内存占用 | 实时折线图 |
| 存储用量 | 当前值 vs 套餐上限 |
| API 调用次数 | 当日 / 本月累计 |
| 活跃用户数 | 当日活跃数 |
| 当日登录次数 | 累计折线图 |
| 异常请求数 | 4xx / 5xx 分类 |
| 慢查询数量 | > 500ms 查询次数 |

告警配置：支持为每个关键指标设置阈值，超限时触发邮件 / Webhook 通知。

**可用性统计（Availability / SLA）**

- 服务可用率（Uptime）统计：支持日 / 周 / 月维度
- 故障事件记录：开始时间、恢复时间、持续时长、影响描述
- SLA 达标率报告：可导出供客户成功团队使用

---

### 5.2 系统管理（System Management）

#### 5.2.1 版本升级与回滚

**系统升级流程**

```
上传/拉取升级包（制品库 Artifact Registry）
  → 系统自动健康检查（所有服务状态正常才允许继续）
  → 配置升级策略：全量 / 灰度（指定内测租户列表）
  → 升级前自动备份（对所有参与本次升级的租户）
  → 执行升级
  → 实时展示升级进度（租户维度状态列表）
  → 升级完成通知（成功/失败详情）
```

**灰度升级策略**：

- 维护"内测租户组"列表，由Platform Admin（平台超级管理员）配置
- 灰度阶段仅对内测租户执行升级，其余租户保持原版本
- 内测租户验证通过（手动确认）后，触发全量升级

**升级回滚**

- 触发条件：手动触发（管理员判断）或自动触发（监控检测到错误率超阈值）
- 回滚范围：全量回滚（所有租户）/ 单租户回滚
- 回滚前：自动保存当前状态快照
- 回滚后：生成事件报告（失败原因、回滚耗时、受影响租户列表）
- 执行回滚需二次身份验证

#### 5.2.2 定时备份策略

**全局备份计划**

| 配置项 | 选项 |
|--------|------|
| 备份频率 | 每小时 / 每日 / 每周 |
| 执行时间 | 可配置时间窗口（默认每日 02:00） |
| 保留数量 | 最近 N 个版本（默认 10） |
| 存储目标 | 本地 / AWS S3 / Cloudflare R2 / GCS |

- 支持为单个租户配置独立备份计划，覆盖全局策略
- 备份任务执行记录：开始时间、完成时间、备份大小、状态
- 备份失败：自动告警 + 支持手动重试

---

### 5.3 管理控制台（Admin Console）

#### 5.3.1 核心页面规格

**仪表盘（Dashboard）**

| 模块 | 展示内容 |
|------|---------|
| 全局概览 | 总租户数、活跃租户数、本月新增租户数 |
| 系统健康 | 各核心服务状态（Django / PostgreSQL / Redis / Celery / R2） |
| 近期告警 | 最近 24 小时告警列表，按严重程度分类 |
| 资源概览 | 平台整体存储用量、API 调用量趋势图 |
| 最近操作 | 最近 10 条高危操作审计记录 |

**租户列表**

- 分页展示（默认 20 条/页）
- 搜索：按公司名称、子域名、联系邮箱关键词搜索
- 筛选：按状态（Active / Suspended / Deleted）、套餐（Basic/Pro/Enterprise）、注册时间范围、**即将到期（15 天内）**
- 列表字段：公司名称、子域名、套餐、状态、注册时间、活跃用户数
- 快捷操作：查看详情、挂起、发起备份、数据导出

**租户详情**

标签页结构：

| 标签 | 内容 |
|------|------|
| 基本信息 | 公司信息、联系人、子域名、套餐、状态，支持编辑部分字段 |
| 用户管理 | Tenant Admin 列表、普通用户列表、密码重置入口 |
| 套餐信息 | 当前套餐详情、用量统计、升级入口 |
| 监控数据 | 该租户资源使用图表、SLA 统计 |
| 备份记录 | 该租户备份列表、手动触发备份、恢复操作入口 |
| 操作历史 | 该租户相关的所有管理员操作日志 |

**系统版本管理**

- 当前运行版本信息
- 历史版本列表（版本号、发布时间、状态：Current / Previous / Archived）
- 升级入口（上传/拉取升级包）
- 回滚入口（选择目标版本）

**备份管理**

- 全局备份计划配置
- 备份任务列表（支持按租户、状态、时间筛选）
- 手动触发备份（选择租户）
- 恢复操作入口

**监控与告警**

- 租户级 / 系统级监控图表（基于 Grafana iframe 嵌入或自定义实现）
- 告警规则配置（指标 + 阈值 + 通知渠道）
- 告警历史列表

**审计日志**

- 全平台操作日志，支持多维度筛选与导出
- 每条日志包含：操作人、时间、操作对象、内容摘要、结果、来源 IP

**管理员设置**

- 管理员账号管理（创建、编辑、停用）
- 角色配置（Platform Admin（平台超级管理员） / 运营人员 / 只读审计员）
- MFA 设置（强制启用，支持 TOTP）
- IP 白名单配置
- 登录会话管理（查看活跃会话、强制登出）

#### 5.3.2 访问控制与安全

**强制要求（不可降级）**：

| 安全要求 | 实现方式 |
|---------|---------|
| MFA 强制启用 | 所有管理员账号首次登录强制配置 TOTP；无法跳过 |
| IP 白名单 | 仅允许指定 IP 范围访问管理控制台 URL（Nginx 层或应用层限制） |
| 高危操作二次验证 | 删除租户、数据恢复、系统回滚操作触发 MFA 二次确认弹窗 |
| 会话超时 | 无操作 30 分钟后自动登出，Token 失效 |
| 强制登出 | Platform Admin（平台超级管理员）可在"管理员设置"中强制终止指定管理员的所有会话 |

**与租户应用隔离**：

- 管理控制台部署在独立子域名（如 `admin.platform.com`），与租户应用域名体系分离
- 管理控制台不共享租户应用的 Session / Cookie 机制

#### 5.3.3 操作审计日志规范

所有写操作（Create / Update / Delete）及高危操作必须记录审计日志，字段规范如下：

```python
{
    "id": "UUID",
    "operator_id": "管理员用户 ID",
    "operator_name": "管理员显示名",
    "action_type": "CREATE_TENANT | SUSPEND_TENANT | DELETE_TENANT | RESTORE_DATA | SYSTEM_UPGRADE | ROLLBACK | RESET_PASSWORD | ...",
    "target_type": "Tenant | User | System | Backup",
    "target_id": "操作对象 ID",
    "target_name": "操作对象可读名称",
    "payload_summary": "操作内容摘要（非敏感字段）",
    "result": "SUCCESS | FAILED",
    "error_message": "失败原因（如有）",
    "ip_address": "操作来源 IP",
    "created_at": "ISO 8601 时间戳"
}
```

---

## 6. 技术考量

### 6.1 系统架构定位

基于 Fonrey 技术栈（Django + django-tenants + PostgreSQL + Celery + Cloudflare R2），管理控制台在同一 Django 项目中通过独立 App (`apps/admin_console/`) 实现，利用 Django 的 `public` Schema 作为管理控制台的数据层。

### 6.2 关键依赖

| 依赖 | 用途 | 风险等级 |
|------|------|---------|
| `django-tenants` | Schema 创建/销毁、租户切换 | 高 — 核心依赖，需确认 Schema 创建并发安全性 |
| Celery + Celery Beat | 异步备份、导出、状态同步任务 | 中 — 需监控任务队列积压 |
| PostgreSQL `pg_dump` | 数据备份与恢复 | 高 — 需测试大 Schema 备份耗时与锁表影响 |
| Cloudflare R2 | 备份文件与导出文件存储 | 中 — 需评估大文件上传/下载带宽成本 |
| Grafana | 监控图表展示 | 低 — 已在技术栈中规划 |
| TOTP（如 `django-otp`） | MFA 实现 | 低 — 成熟库，接入成本低 |

### 6.3 已知风险

| 风险 | 可能性 | 影响 | 缓解措施 |
|------|--------|------|---------|
| 大租户 Schema 备份耗时超长（>1 小时） | 中 | 高 | 异步执行 + 进度追踪；评估流式备份方案 |
| 系统升级过程中新请求涌入导致数据不一致 | 低 | 高 | 升级期间租户切换维护模式；使用数据库事务 |
| 软删除数据保留期间存储成本积累 | 中 | 低 | 合理设置默认保留期，提供平台级存储用量监控 |
| 管理控制台 IP 白名单配置错误导致运营团队被锁定 | 低 | 高 | 提供紧急访问恢复流程（通过服务器直接访问），文档化 |

### 6.4 待解决问题（开发启动前必须确认）

- [ ] **数据库备份方案**：`pg_dump` 直接执行还是基于 WAL 的增量备份（如 pgBackRest）？— Owner: 工程负责人 — Deadline: 技术评审前
- [ ] **监控数据来源**：Grafana 直接对接 PostgreSQL 指标还是通过 Prometheus Exporter？— Owner: 运维团队
- [ ] **MFA 库选型**：`django-otp` + TOTP 还是集成第三方认证（如 Okta）？— Owner: 工程负责人
- [ ] **子域名管理机制**：Cloudflare DNS API 自动创建还是手动配置？— Owner: 运维团队
- [ ] **审计日志存储**：写入 `public` Schema 还是独立日志服务（如 Elasticsearch）？— Owner: 工程负责人

---

## 7. 发布计划

| 阶段 | 时间 | 范围 | 通过标准 |
|------|------|------|---------|
| 内部 Alpha | Week 1–4 | 平台内部团队使用 | 核心租户 CRUD 流程无 P0 Bug；MFA 可用 |
| 封闭 Beta | Week 5–6 | 运营团队日常使用 | 备份/恢复流程完整可用；审计日志 100% 覆盖 |
| 正式上线 | Week 7 | 全量运营团队 | 升级/回滚流程验证通过；监控告警规则配置完成 |

**回滚标准**：若正式上线后 72 小时内发现租户数据隔离漏洞或审计日志丢失，立即回滚并进入 P0 修复流程。

---

## 8. 不构建清单（What We're NOT Building）

| 请求/功能 | 原因 | 重新评估条件 |
|----------|------|------------|
| 自动化账单与发票生成 | 超出本模块范围，财务模块独立立项 | 财务模块 PRD 完成后接入 |
| 租户端自助迁移工具 | 当前用户规模不需要，运营团队手动处理即可 | 租户数 > 500 时重新评估 |
| 移动端管理界面 | 运营团队使用场景明确为 PC，移动端收益低 | v2 规划，用户调研支持时推进 |
| Webhook 事件推送市场 | 集成复杂度高，当前无客户需求驱动 | 有 3+ 客户明确需求时评估 |
| 多语言管理界面 | 运营团队为内部人员，中文已满足需求 | 国际化扩张时规划 |

---

## 9. 附录

### 9.1 租户状态机

```
[新建中 Creating]
      ↓ 成功
[活跃 Active] ←──────────────────┐
      ↓ 手动挂起                  │ 到期自动恢复 / 手动恢复
[已挂起 Suspended] ───────────────┘
      ↓ 删除操作（软删除）
[待清除 Pending Delete]（冷静期 30 天）
      ↓ 冷静期到期 / 硬删除
[已删除 Deleted]
```

### 9.2 管理员角色权限矩阵

| 操作 | Platform Admin（平台超级管理员） | 运营人员 | 只读审计员 |
|------|-----------|---------|-----------|
| 创建租户 | ✅ | ✅ | ❌ |
| 挂起 / 恢复租户 | ✅ | ✅ | ❌ |
| 软删除租户 | ✅ | ✅ | ❌ |
| 硬删除租户 | ✅ | ❌ | ❌ |
| 数据导出 | ✅ | ✅ | ❌ |
| 手动触发备份 | ✅ | ✅ | ❌ |
| 数据恢复 | ✅ | ❌ | ❌ |
| 系统升级 | ✅ | ❌ | ❌ |
| 系统回滚 | ✅ | ❌ | ❌ |
| 查看版本总览 | ✅ | ✅ | ❌ |
| 配置告警规则 | ✅ | ✅ | ❌ |
| 查看审计日志 | ✅ | ✅ | ✅ |
| 导出审计日志 | ✅ | ✅ | ✅ |
| 管理员账号管理 | ✅ | ❌ | ❌ |
| 强制登出管理员 | ✅ | ❌ | ❌ |
| 配置 IP 白名单 | ✅ | ❌ | ❌ |

### 9.3 页面路由规划（管理控制台）

```
/admin/                          # 仪表盘
/admin/tenants/                  # 租户列表
/admin/tenants/new/              # 新建租户
/admin/tenants/{id}/             # 租户详情（信息）
/admin/tenants/{id}/users/       # 租户用户管理
/admin/tenants/{id}/plan/        # 套餐信息与升级
/admin/tenants/{id}/monitoring/  # 监控数据
/admin/tenants/{id}/backups/     # 备份记录
/admin/tenants/{id}/history/     # 操作历史
/admin/system/versions/          # 版本管理
/admin/system/backups/           # 备份管理
/admin/monitoring/               # 全局监控与告警
/admin/audit-logs/               # 审计日志
/admin/settings/admins/          # 管理员设置
```