# PRD：平台管理后台（Platform Admin Console）

**状态**：Draft
**作者**：产品经理
**最后更新**：2026-05-02
**版本**：v1.1
**关联模块**：权限管理（仅平台侧管理员账号体系）、登录管理（管理员登录与 MFA）、所有租户业务模块（间接，仅作运营/监控对象）
**利益相关方**：工程负责人、运营团队、安全合规、客户成功团队、IT 运维

---

## 变更历史

| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|---------|
| v1.0 | 2026-05-02 | 产品经理 | 由 `PRD/系统管理/系统管理模块PRD.md` (v1.3) 与 `PRD/发布管理/客户端发布管理模块PRD.md` (v1.2) 合并而来；统一面向平台管理员视角，统一规划页面路由与业务 API 操作清单。原两份 PRD 文件同步删除，参见 `ADR-20260502-001`。 |
| v1.1 | 2026-05-02 | 产品经理 | **修复 P-B-1**：全部用户故事补齐功能编号 PA-001 ~ PA-011，与登录管理 PRD v3.0「功能 ID + 验收标准」风格对齐，建立需求→测试用例→Bug 单可追溯链条。**修复 X-1**：新增 PA-011「租户注销 SOP」用户故事（Persona E），覆盖删除前数据导出确认、双人复核审批流程、30 天冷静期可撤销机制；同步更新租户状态机（新增 Pending Cancellation 状态节点）、权限矩阵（新增注销审批相关操作行）、§5.1.4 删除章节（引用 PA-011 SOP）、§5.4 页面导航逻辑（注销审批待办流程）、租户列表筛选（新增 Pending Cancellation / Pending Delete 状态）、§5.5.1 API 操作清单（新增注销发起、审批、撤销、硬删除操作项）。 |

> **本 PRD 取代以下两份历史文档**：
> - `PRD/系统管理/系统管理模块PRD.md`（v1.3，已删除，被本 PRD 替代）
> - `PRD/发布管理/客户端发布管理模块PRD.md`（v1.2，已删除，被本 PRD 替代）
>
> 决策依据：`ADR-20260502-001`（REQ）。

---

## 1. 问题陈述

### 1.1 背景

Fonrey（房睿）是面向房产经纪公司的 B2B SaaS 平台，采用 `django-tenants` 实现 PostgreSQL Schema 级别多租户隔离，同时通过 Electron 桌面客户端为终端经纪人提供统一入口。随着平台商业化推进，**平台运营团队**需要一套独立、跨租户的「平台管理后台」（Platform Admin Console）来统一承担：

1. 租户全生命周期管理（开通、挂起、注销、License 续期）
2. 平台版本治理（基础数据版本、租户数据版本、灰度升级、回滚）
3. 数据备份与恢复（灾难场景应对）
4. 客户端发布治理（桌面客户端版本上线、强制升级、版本分布监控）
5. 操作审计与合规
6. 平台管理员账号与安全（MFA、IP 白名单、强制登出）

平台管理后台部署于平台公共域名（与租户应用域名隔离），数据落在 `public` schema，跨租户。Tenant Admin 与 Agent 一律无访问权限。

### 1.2 核心痛点

| 痛点 | 影响方 | 当前代价 |
|------|--------|---------|
| 无统一租户管理界面，开通 / 挂起 / 注销依赖人工脚本 | 运营团队 | 高错误风险，操作耗时 |
| 平台版本升级需停机，影响所有租户 | 全量用户 | SLA 违约风险 |
| 数据备份无策略，灾难恢复依赖人工 | 平台稳定性 | 数据丢失风险 |
| 高危操作无审计轨迹 | 管理层 / 合规 | 法律与客户信任风险 |
| 客户端浏览器版本碎片化，兼容性问题层出 | Agent / 客户成功 | 支持成本飙升 |
| 客户端无统一发布渠道，旧版本与新后端 API 不兼容 | 全量用户 | 数据错误风险 |
| 无法跨租户掌握客户端版本分布与覆盖率 | Platform Admin | 无法定向催更 |

### 1.3 目标用户

| 角色 | 使用场景 | 频率 |
|------|---------|------|
| Platform Admin（平台超级管理员） | 全局配置、高危操作、版本上线、强制升级 | 低频（每周） |
| 运营人员（Ops Operator） | 日常租户管理、监控巡检、客户咨询响应 | 高频（每日） |
| 只读审计员（Read-only Auditor） | 日志查询、合规报告导出 | 中频（每周） |

> 本 PRD **不涉及**租户内部的 Tenant Admin、Agent 角色——他们对本后台无访问权限。

---

## 2. 目标与成功指标

| 目标 | 指标 | 当前基线 | 目标值 | 测量窗口 |
|------|------|---------|--------|---------|
| 租户开通效率 | 新租户开通耗时 | 人工脚本 ~30 分钟 | < 5 分钟（含自动初始化） | 上线后 30 天 |
| 平台升级零停机 | 升级期间受影响租户数 | 全量中断 | 灰度阶段 ≤ 5% 租户 | 每次升级 |
| 数据恢复能力 | RTO（单租户恢复时间） | 无标准流程 | < 2 小时 | v1 上线即达标 |
| 操作合规覆盖 | 高危操作审计日志覆盖率 | 0% | 100% | 上线后 30 天 |
| 管理员安全 | 平台管理员 MFA 启用率 | 0% | 100%（强制） | 上线即达标 |
| 客户端兼容性问题消除 | 因浏览器兼容产生的支持工单数 | 待统计 | 降低 ≥ 90% | 客户端上线后 60 天 |
| 客户端版本一致性 | 在线用户使用最新客户端比例 | 0%（无客户端） | ≥ 95% | 版本发布后 7 天 |
| 客户端自动更新成功率 | 收到通知 → 升级完成的成功率 | 无基准 | ≥ 98% | 每次发布后 48 小时 |

---

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

**不在 v1 实现**：
- 自动化账单计费、多币种支持、Webhook 自定义集成市场
- 租户端自助迁移工具
- 客户响应数据导出请求（Story「响应客户数据导出请求」暂缓，列入后续迭代）

**不属于本后台**：
- 租户内业务权限的细粒度配置（见权限管理模块 PRD）
- 客服工单系统、SLA 自动赔付
- macOS / Linux 桌面客户端、移动端 App
- 客户端离线模式、私有化离线安装方案
- 客户端代码混淆 / 反逆向加固

**不支持**：
- 移动端浏览器访问平台管理后台（运营场景明确为 PC 桌面）
- 多语言界面（运营团队为内部人员，中文已满足）

---

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

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

> 负责 Fonrey 的日常运营，每天处理新客户开通、异常租户处理、客户咨询。使用 PC 浏览器登录平台管理后台。

#### PA-001 Story A1：新租户开通

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

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

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

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

**入驻信息 PDF**（无邮箱客户的备选方案）：
- 包含与欢迎邮件相同的关键信息
- 入口：租户详情 → 基本信息 Tab → 「下载入驻信息」按钮
- 文件名：`{公司名称}_入驻信息_{日期}.pdf`

#### PA-002 Story A2：挂起问题租户

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

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

#### PA-003 Story A3：License 时效管理与到期自动挂起

> 作为运营人员（或 Platform Admin），我希望每个租户能设置 License 有效期，到期后系统自动挂起租户，并在到期前提前预警。

**验收标准**：
- [ ] 每个租户「基本信息」中包含 **License 到期日期**字段，由 Platform Admin 在创建或续费时设定
- [ ] 系统每日自动检查 License 到期，到期后自动挂起，挂起原因标注为「License 到期」
- [ ] 自动挂起后，租户联系人收到通知邮件；Platform Admin 续费后可手动解除挂起
- [ ] **提前 15 天预警**：租户内 Tenant Admin 登录后管理界面顶部出现倒计时横幅：「您的 License 将于 X 天后到期（{到期日期}），请联系平台续费」
- [ ] 倒计时横幅仅对 Tenant Admin 可见，不影响普通 Agent
- [ ] License 到期日期在租户列表与详情页均可见，支持「即将到期（15 天内）」筛选

#### PA-004 Story A4：查看与控制租户用户数（License 计费维度）

> 作为运营人员（或 Platform Admin），我希望看到每个租户的当前用户数，并能设置用户数上限，以便根据 License 授权进行管控。

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

> **PA-011 Story A5：响应客户数据导出请求** — **状态**：暂缓（v1 不实现，列入后续迭代）。

---

### Persona E — Platform Admin David（租户注销合规流程）

> 处理租户主动申请注销或因严重违规被强制注销的场景。注销操作不可逆（硬删除后），需要多重防护——数据导出存证、双人复核、30 天冷静期撤销窗口。

#### PA-011 Story E1：租户注销 SOP（Tenant Cancellation SOP）

> 作为 Platform Admin，我希望执行租户注销时有标准化的审批流程保障——要求数据导出完成、双人复核授权、30 天冷静期可撤销——防止因误操作或内部滥权导致客户数据不可恢复地丢失。

**验收标准（AC）**：

**AC-1 发起注销申请**
- [ ] 运营人员或 Platform Admin 可在租户详情页发起「注销申请」，填写：注销原因（客户主动申请 / 严重违规 / 其他）、申请说明（自由文本）
- [ ] 发起后，租户状态流转至 `Pending Cancellation`（待审批注销），此时租户访问被阻断（等同挂起效果），不可通过常规「恢复」操作解除
- [ ] 发起操作写入审计日志

**AC-2 数据导出前置确认**
- [ ] 进入审批流程前，系统强制展示「数据导出确认」步骤：要求操作人触发该租户的完整数据导出（§5.1.5），等待导出任务完成（状态 Done）后方可提交审批
- [ ] 若申请人选择「客户已自行备份，无需平台导出」，需勾选明确确认框，并填写备注（客户签字回执编号或说明），此记录写入审计日志
- [ ] 审批单中需展示：导出任务 ID（或「已确认客户自备份」备注）、导出完成时间

**AC-3 双人复核审批**
- [ ] 注销审批流需要第二名 Platform Admin（不得与申请人为同一账号）在系统内确认审批，确认时需通过 MFA 二次验证
- [ ] 审批人可「批准」或「驳回」：驳回时必须填写驳回原因；驳回后租户状态恢复至 `Suspended`（仍不可直接恢复为 Active，需运营人员手动解除挂起）
- [ ] 若 48 小时内无人审批，系统向所有 Platform Admin 发送催审通知（站内消息 + 邮件）

**AC-4 软删除与 30 天冷静期**
- [ ] 审批通过后，租户立即进入软删除状态（`Pending Delete`，现有机制）；冷静期默认 30 天
- [ ] 冷静期内，Platform Admin 可在租户列表「待清除」筛选下找到该租户，执行「撤销注销」
- [ ] 撤销注销需第二名 Platform Admin 同样通过 MFA 确认（与初始注销审批相同的双人复核机制）
- [ ] 撤销成功后，租户状态恢复至 `Suspended`（需运营人员手动评估后恢复为 Active）；撤销操作及原因写入审计日志

**AC-5 硬删除与资源释放**
- [ ] 冷静期届满后，系统自动触发硬删除，或 Platform Admin 可在冷静期内提前手动触发硬删除（需再次 MFA 确认，并再次展示「此操作不可逆」警告）
- [ ] 硬删除释放：PostgreSQL Schema、Cloudflare R2 存储桶、Tenant Code、License 席位
- [ ] 硬删除完成后：向租户联系邮箱发送「账号已注销」通知（含注销日期、数据保留期说明）；审计日志记录完整操作链

**注销状态流转**（补充至 §7 状态机）：
```
[活跃 Active] 或 [已挂起 Suspended]
  ↓ 运营/Platform Admin 发起注销申请
[待审批注销 Pending Cancellation]
  ↓ 双人 MFA 审批通过
[待清除 Pending Delete]（冷静期 30 天）
  ↓ 可在冷静期内由双人 MFA 撤销 → 恢复至 [已挂起 Suspended]
  ↓ 冷静期届满 或 提前手动硬删除（MFA）
[已删除 Deleted]
```

### Persona B — Platform Admin David（系统升级、回滚与版本治理）

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

#### PA-005 Story B1：灰度系统升级

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

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

#### PA-006 Story B2：升级失败回滚

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

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

#### PA-007 Story B3：查看平台与租户版本总览

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

**验收标准**：

「版本总览」页面分两部分：

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

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

- [ ] 页面支持手动刷新；版本数据允许最多 5 分钟缓存延迟

---

### Persona C — Platform Admin David（客户端发布治理）

> 同 Persona B，但聚焦桌面客户端版本上线、强制升级与跨租户版本分布。

#### PA-008 Story C1：发布新版本客户端

> 作为 Platform Admin，我希望通过本后台上传新版客户端安装包并配置版本信息，使全平台所有租户的客户端能感知到更新并引导升级。

**验收标准**：
- [ ] 平台管理后台提供「客户端版本管理」页面（位于本后台一级菜单，与租户系统管理隔离）
- [ ] 支持上传 `.exe` 安装包，并填写：
  - 版本号（SemVer：`X.Y.Z`，自动校验格式）
  - 版本类型（普通更新 / 强制更新）
  - 最低兼容版本（低于此版本的客户端将被强制升级）
  - 更新日志（Markdown，最多 2000 字，对外展示）
  - 内部发布说明（不对外）
- [ ] 支持版本状态：草稿（不对外生效）/ 已发布 / 已下线
- [ ] 上传成功后，系统自动计算 SHA256 校验值并填充到该版本元数据，作为客户端下载完成后的完整性校验依据
- [ ] 发布后，客户端下次检测时即可感知（无需等待）
- [ ] 支持版本回滚：将指定历史版本重新置为「已发布」，自动将当前版本标记为「已下线」
- [ ] 支持便携版（Portable ZIP）作为可选上传项

#### PA-009 Story C2：跨租户监控客户端版本分布

> 作为 Platform Admin，我希望跨租户查看当前所有在线客户端的版本分布，以了解全平台升级覆盖率，对仍使用旧版本的客户端发出提醒或强制升级。

**验收标准**：
- [ ] 「客户端版本管理」页展示版本分布统计：各版本在线客户端数量及占比（饼图或条形图）
- [ ] 支持按租户维度查看版本分布（区分不同经纪公司，便于识别落后租户）
- [ ] 支持按租户统计安装数：可查看任一租户的「当前活跃安装数（最近 24h）」与「历史装机总数（不论是否活跃）」
- [ ] 支持「全平台租户活跃榜」视图：以列表形式展示各 active 状态租户的 `tenant_code`、租户名称、活跃安装数、历史装机总数，按活跃安装数降序排列
- [ ] 支持对指定版本范围的客户端推送「强制更新」标记（如：将所有低于 v1.5.0 的客户端标记为强制更新）
- [ ] 支持升级进度趋势图：新版本发布后各天累计升级完成的用户比例

> **客户端侧用户故事不在本 PRD 范围**（如「Agent 下载安装客户端」「Agent 自动升级」）。这些故事面向终端用户使用的桌面 App，不属于平台管理后台职责。但本 PRD 通过 Story C1/C2 为客户端侧故事提供版本数据源与控制能力。

---

### Persona D — 只读审计员 Carol（合规审计）

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

#### PA-010 Story D1：审计日志查询与导出

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

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

---

## 5. 功能详细说明

### 5.1 租户与 License 管理

#### 5.1.1 租户生命周期

**新建租户表单字段**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 公司名称 | Text | ✅ | 最大 100 字符 |
| 联系人 | Text | ✅ | 主联系人姓名 |
| 联系人手机号 | Text | ✅ | 用于创建初始 Tenant Admin |
| 联系邮箱 | Email | ❌（可选） | 发送欢迎邮件；无邮箱改用 PDF 下载 |
| 所在地区 | Select | ✅ | 省市两级 |
| 订阅套餐 | Select | ✅ | Basic / Professional / Enterprise |
| License 到期日期 | Date | ✅ | 到期后自动挂起 |
| License 授权用户数上限 | Number | ✅ | 用户数计费维度 |

**创建流程**：
1. 表单校验通过后，后台异步任务执行：
   - 创建 PostgreSQL Schema（`tenant_{id}`）
   - 执行 Migrate 初始化表结构
   - 注入默认配置（见下方「默认配置内容」）
   - 生成初始密码（12 位随机），标记为「首次登录强制修改」
   - 联系邮箱已填写时：发送欢迎邮件（含 Tenant Code、初始密码、平台访问链接）
2. 任务完成后更新租户状态为 `active`；失败则全量回滚并标记为 `failed`
3. 生成唯一 Tenant ID（UUID）及 Tenant Code（12位纯数字，如 `202605023765`）

#### 5.1.2 默认配置内容（Schema 初始化时注入）

| 配置类型 | 内容 | 说明 |
|---------|------|------|
| 权限定义（PermissionDef） | 平台全量权限码 | 从 public schema 同步至租户 schema |
| 系统默认业务角色 | 7 个内置角色（置业顾问/店管/区管/区总/副总/总经/其他职能）+ 角色—权限绑定 | 按「角色权限矩阵.md」 |
| 初始 Tenant Admin 用户 | 以联系人手机号创建 | 写入「租户管理员」专属权限集合，独立于 7 个业务角色 |

#### 5.1.3 挂起（Suspend）

- **触发方式**：
  - 手动：运营人员选择挂起原因（欠费 / 违规 / 主动申请 / 其他）
  - 自动：系统每日检查 License 到期日期，到期自动挂起（原因「License 到期」）
- 可设置挂起到期时间（留空表示永久挂起直至手动恢复）
- 挂起效果：租户用户访问被拒，重定向至暂停提示页；平台管理后台对该租户数据访问不受影响
- 自动恢复：手动设置了到期时间的挂起会到期自动恢复；License 到期挂起须 Platform Admin 手动恢复
- 通知：挂起 / 恢复均向租户联系邮箱发送通知（无邮箱跳过）
- License 到期前 15 天起，租户端 Tenant Admin 看到倒计时横幅

#### 5.1.4 删除（Delete）

> **注意**：租户注销是高危操作，须遵循「PA-011 租户注销 SOP」——发起注销申请 → 强制数据导出确认 → 双人 MFA 复核审批 → 软删除（30 天冷静期，可撤销）→ 自动或提前手动硬删除。**不允许绕过此 SOP 直接执行删除。**

| 模式 | 说明 |
|------|------|
| 软删除（Pending Delete） | SOP 审批通过后自动进入；数据保留 30 天（默认，可配置）后自动清除 |
| 硬删除 | 冷静期内 Platform Admin 提前触发（需 MFA + 不可逆警告），或冷静期届满自动触发；仅 Platform Admin 可操作 |

**删除前置条件（PA-011 SOP 强制执行）**：
1. 发起申请时必须填写注销原因
2. 审批前强制完成数据导出确认（平台导出 Done 或客户自备份书面确认）
3. 须第二名 Platform Admin（≠ 申请人）MFA 审批通过
4. 软删除冷静期内可由双人 MFA 执行「撤销注销」

删除完成后释放：访问域名 / Tenant Code、Cloudflare R2 存储桶、License 席位

#### 5.1.5 数据导出（Export）

> Story A5（响应客户数据导出请求）暂缓；本节描述能力为运营内部数据核查使用。

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

**文件资产导出处理规则**（v1 决策）：
- R2 Bucket 配置为 public read，文件通过 CDN 持久 URL 形式内嵌于导出数据
- 账号未硬删除前，CDN URL 持续有效
- 迁移类需求（需要文件实体）走「完整备份」流程，不走「数据导出」

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

导出包附 `README.txt` 说明文件资产链接策略。

**数据导出 vs 完整备份**：

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

#### 5.1.6 数据备份（Snapshot）

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

#### 5.1.7 数据恢复（Restore）

恢复流程：
```
选择目标备份版本
  → 二次确认（显示当前数据版本将被覆盖）
  → 自动对当前数据生成临时快照
  → 租户切换为维护模式
  → 执行恢复
  → 自动恢复服务 → 生成恢复报告
```

报告字段：操作人、操作时间、恢复前/后版本、耗时、结果。

#### 5.1.8 套餐升级

- 升级路径：Basic → Professional → Enterprise
- 升级前展示差异对比表（功能项、用户数上限、存储空间、API 额度）
- 生效模式：立即 / 下一账期
- 升级前自动备份；升级失败可一键回滚
- 升级历史：时间、操作人、升级前后套餐

#### 5.1.9 租户用户与权限管理

**Tenant Admin 管理**：
- 每个租户可设置 1 至多名 Tenant Admin
- Platform Admin 可直接创建新用户并赋予 Tenant Admin，或从租户现有用户中指定
- 支持新增 / 替换 / 撤销

**密码重置**（针对租户内任意用户）：
- 方式一：发送重置链接至注册邮箱（用户自助）
- 方式二：管理员直接设置临时密码（首次登录强制修改）
- 所有操作进审计日志

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

**资源监控指标**：

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

支持为每个指标配置阈值告警（邮件 / Webhook）。

**可用性 / SLA**：
- 服务可用率统计：日 / 周 / 月
- 故障事件记录：开始 / 恢复时间、持续时长、影响描述
- SLA 达标率报告，可导出

---

### 5.2 平台版本治理

#### 5.2.1 系统升级流程

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

**灰度升级策略**：
- 维护「内测租户组」列表，由 Platform Admin 配置
- 灰度阶段仅对内测租户升级，其余租户保持原版本
- 内测验证通过（手动确认）后，触发全量升级

#### 5.2.2 升级回滚

- 触发：手动 / 自动（监控检测到错误率超阈值）
- 范围：全量回滚 / 单租户回滚
- 前置：自动保存当前状态快照
- 后续：生成事件报告（失败原因、回滚耗时、受影响租户列表）
- 必需：MFA 二次验证

#### 5.2.3 定时备份策略

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

支持为单租户配置独立备份计划，覆盖全局策略。备份失败自动告警，支持手动重试。

#### 5.2.4 版本总览

见 Story B3 验收标准。该视图为运营提供「平台基础数据版本 + 各租户数据版本」双维度可见性，是灰度升级时代的版本治理核心入口。

---

### 5.3 客户端发布治理

> 本节面向 Persona C 的 Story C1 / C2。客户端本身的技术形态、自动更新机制、签名分发等实现细节属于技术方案范畴，请参见 `TECH_STACK/平台管理后台技术方案.md`。本 PRD 仅描述产品视角的业务能力。

#### 5.3.1 版本管理

平台管理后台提供独立的「客户端版本管理」一级页面，承担：

**版本列表展示字段**：

| 列 | 说明 |
|----|------|
| 版本号 | SemVer 格式，如 `v1.2.3` |
| 版本类型 | 普通更新 / 强制更新（后者标红） |
| 状态 | 草稿 / 已发布（绿）/ 已下线（灰） |
| 发布时间 | 设为已发布的时间 |
| 下载量 | 该版本安装包被下载次数 |
| 操作 | 发布 / 下线 / 编辑 / 复制下载链接 |

**新增/编辑版本表单字段**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 版本号 | Text | ✅ | SemVer，自动校验 |
| 版本类型 | 单选 | ✅ | 普通更新 / 强制更新 |
| 最低兼容版本 | Text | ❌ | 低于该版本的客户端被强制升级 |
| 安装包（EXE） | File | ✅ | 上传至 R2，最大 500MB |
| 便携版（ZIP） | File | ❌ | 同上 |
| SHA256 校验值 | Text（自动） | ✅ | 上传后系统计算并填充 |
| 更新日志 | Markdown | ✅ | 对外展示，最多 2000 字 |
| 发布说明（内部） | Text | ❌ | 仅内部查看 |
| 状态 | 单选 | ✅ | 草稿 / 立即发布 |

#### 5.3.2 版本分布统计

| 图表 | 说明 |
|------|------|
| 版本分布饼图 | 按客户端版本号统计当前活跃用户数量及占比 |
| 升级进度趋势图 | 新版本发布后各天累计升级完成的用户比例 |
| 租户版本明细 | 按租户展示其员工的客户端版本分布 |
| 全平台租户活跃榜 | `tenant_code` + 租户名称 + 活跃安装数（最近 24h） + 历史装机总数，按活跃安装数降序 |

底层数据由 `public.client_heartbeats` 表的 `tenant_id` 维度聚合提供。

#### 5.3.3 强制更新推送

- Platform Admin 可对指定版本范围的客户端打上「强制更新」标记（如所有低于 v1.5.0 的客户端强制升级）
- 客户端侧的强制更新行为（不展示「稍后提醒」、必须升级后方可继续使用）由客户端实现保障

---

### 5.4 平台管理后台总体规划

#### 5.4.1 页面清单与访问权限

> 以下为产品视角的页面清单。「页面路径」以业务可读形式表达，不约束技术实现（具体 URL 由技术方案决定）。所有页面均位于平台管理后台域，无访问权限的角色（Tenant Admin、Agent 及未登录用户）一律重定向到登录页或 403。

| #   | 页面          | 路径（业务可读）                         | 访问权限                                    | 说明                                |
| --- | ----------- | -------------------------------- | --------------------------------------- | --------------------------------- |
| 1   | 登录页         | `/admin/login`                   | 公开（仅平台管理员账号可登录）                         | 强制 MFA 配置                         |
| 2   | 仪表盘         | `/admin`                         | 全部三类管理员                                 | 平台总览、健康度、近期告警、最近高危操作              |
| 3   | 租户列表        | `/admin/tenants`                 | Platform Admin / 运营人员（写）/ 审计员（只读）       | 检索、筛选、快捷操作                        |
| 4   | 新建租户        | `/admin/tenants/new`             | Platform Admin / 运营人员                   | —                                 |
| 5   | 租户详情：基本信息   | `/admin/tenants/{id}`            | 同租户列表                                   | 含 License、用户数、状态等编辑入口             |
| 6   | 租户详情：用户管理   | `/admin/tenants/{id}/users`      | 同上                                      | Tenant Admin 列表、用户列表、密码重置         |
| 7   | 租户详情：套餐信息   | `/admin/tenants/{id}/plan`       | 同上                                      | 套餐详情、用量、升级入口                      |
| 8   | 租户详情：监控     | `/admin/tenants/{id}/monitoring` | 同上                                      | 资源使用、SLA                          |
| 9   | 租户详情：备份记录   | `/admin/tenants/{id}/backups`    | Platform Admin（写）/ 运营人员（仅触发备份）/ 审计员（只读） | 备份列表、触发备份、恢复入口（仅 Platform Admin）  |
| 10  | 租户详情：操作历史   | `/admin/tenants/{id}/history`    | 全部三类                                    | 该租户相关所有管理员操作日志                    |
| 11  | 系统版本管理      | `/admin/system/versions`         | Platform Admin（写）/ 运营人员（只读）/ 审计员（只读）    | 含「版本总览」（平台基础数据版本 + 各租户数据版本）、升级、回滚 |
| 12  | 备份管理        | `/admin/system/backups`          | Platform Admin（写）/ 运营人员（触发）/ 审计员（只读）    | 全局备份计划、备份任务列表、恢复入口                |
| 13  | 监控与告警       | `/admin/monitoring`              | Platform Admin / 运营人员（写）/ 审计员（只读）       | 全局监控图表、告警规则、告警历史                  |
| 14  | **客户端版本管理** | `/admin/client-releases`         | Platform Admin（写）/ 运营人员（只读）/ 审计员（只读）    | 版本列表、发布、下线、回滚、版本分布、租户活跃榜          |
| 15  | 审计日志        | `/admin/audit-logs`              | 全部三类（含审计员）                              | 多维度筛选、导出 CSV                      |
| 16  | 管理员设置       | `/admin/settings/admins`         | 仅 Platform Admin                        | 管理员账号、角色、MFA、IP 白名单、登录会话          |

#### 5.4.2 页面间导航逻辑（用户故事视角）

- 用户访问任一受保护页面但未登录 → 跳转 `/admin/login`
- 登录成功且未配置 MFA → 强制跳转 MFA 配置向导后再进入仪表盘
- 仪表盘的「最近高危操作」区域，每条记录可点击跳转到「审计日志」并自动以该记录为筛选条件
- 仪表盘的「系统健康」区域，点击异常服务可跳转「监控与告警」对应租户/服务视图
- 租户列表点击「公司名称」→ 进入「租户详情：基本信息」（默认 Tab）
- 租户详情各 Tab 之间通过页内 Tab 切换，URL 同步变化（页面 5–10）
- 租户详情「备份记录」中点击「恢复」→ 出现二次确认弹窗 + MFA 验证（仅 Platform Admin 可见）
- 「系统版本管理」中点击某租户行 → 跳转到该租户的「备份记录」Tab
- 「客户端版本管理」中点击「全平台租户活跃榜」中的租户名称 → 跳转到该租户「基本信息」Tab
- 客户端版本「发布 / 下线 / 强制更新推送」操作 → 二次确认；强制更新推送额外要求 MFA
- 任何高危操作（删除/注销租户、数据恢复、系统回滚、客户端版本下线、强制更新推送）触发 MFA 二次确认弹窗
- 租户详情「基本信息」页面，Platform Admin / 运营人员可发起「注销申请」；状态为 `Pending Cancellation` 时，原「挂起/恢复」按钮隐藏，显示「查看注销审批单」入口
- 注销审批待办：系统向第二名 Platform Admin 发送站内通知；点击通知进入审批单详情，展示申请人、注销原因、数据导出确认记录，提供「批准（MFA）」/「驳回」操作
- 审批批准后，租户自动进入 `Pending Delete`；租户列表「待清除」筛选下可见，提供「撤销注销（双人 MFA）」和「提前硬删除（MFA）」入口
- 用户超过 30 分钟无操作 → 自动登出，下次操作跳转登录页
- 「管理员设置」中 Platform Admin 强制登出某管理员 → 该管理员的所有会话立即失效，下次请求跳转登录页

#### 5.4.3 仪表盘内容

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

#### 5.4.4 租户列表

- 分页（默认 20 条/页）
- 搜索：公司名称、Tenant Code、联系邮箱关键词
- 筛选：状态（Active / Suspended / Pending Cancellation / Pending Delete / Deleted）、套餐、注册时间、**即将到期（15 天内）**、**用户数已满**
- 列：公司名称、Tenant Code、套餐、状态、注册时间、活跃用户数 / License 上限、客户端最新版本占比
- 快捷操作：查看详情、挂起、发起备份、数据导出

---

### 5.5 业务 API 操作清单（产品视角）

> 仅描述「平台管理员需要能完成哪些业务操作」；不定义具体 RESTful 路径、HTTP 方法、参数结构。具体接口设计见对应技术方案文档。

#### 5.5.1 租户管理

- 平台管理员需要能查询租户列表（支持多维度筛选）
- 平台管理员需要能查看单租户的完整详情（基本信息、套餐、用户、License、备份、操作历史）
- 平台管理员需要能创建新租户（含异步初始化 Schema 与默认配置）
- 平台管理员需要能编辑租户基本信息（公司名、联系人、邮箱、地区）
- 平台管理员需要能挂起 / 恢复租户（含挂起原因、到期时间）
- 平台管理员（运营人员）需要能发起租户注销申请（PA-011 SOP：填写原因、完成数据导出确认）
- 第二名 Platform Admin 需要能审批租户注销申请（批准需 MFA；驳回需填写驳回原因）
- 平台管理员需要能在冷静期内撤销租户注销（双人 MFA）
- 平台管理员需要能在冷静期内提前手动触发硬删除（MFA + 不可逆确认）
- 系统需能在冷静期届满后自动触发硬删除并释放所有资源
- 平台管理员需要能软删除 / 硬删除租户（仅限通过 PA-011 SOP 触发，不提供绕过 SOP 的直接删除入口）
- 平台管理员需要能调整租户的 License 到期日期
- 平台管理员需要能调整租户的 License 授权用户数上限
- 平台管理员需要能升级租户套餐
- 平台管理员需要能下载租户的「入驻信息 PDF」

#### 5.5.2 租户用户管理

- 平台管理员需要能查询租户内的全部用户
- 平台管理员需要能新增 / 替换 / 撤销 Tenant Admin
- 平台管理员需要能为租户内任意用户重置密码（链接 / 临时密码两种方式）

#### 5.5.3 数据导出与备份

- 平台管理员需要能为指定租户触发数据导出（异步，可查询任务状态、获取下载链接）
- 平台管理员需要能为指定租户手动触发完整备份
- 平台管理员需要能查询某租户的备份记录列表
- 平台管理员需要能基于某个备份执行恢复操作（需 MFA）
- 平台管理员需要能配置全局 / 单租户的定时备份策略

#### 5.5.4 平台版本与升级

- 平台管理员需要能上传 / 拉取系统升级包
- 平台管理员需要能配置升级策略（全量 / 灰度，含内测租户名单）
- 平台管理员需要能触发升级，并实时查询升级进度（租户维度）
- 平台管理员需要能查看升级日志
- 平台管理员需要能触发升级回滚（全量 / 单租户，需 MFA）
- 平台管理员需要能查询「平台基础数据版本」与「各租户数据升级版本」总览

#### 5.5.5 客户端发布

- 平台管理员需要能查询客户端版本列表（含状态、下载量）
- 平台管理员需要能新增客户端版本（上传安装包，系统自动计算 SHA256）
- 平台管理员需要能修改某版本元数据（更新日志、版本类型、最低兼容版本等）
- 平台管理员需要能切换某版本状态（草稿 → 已发布 / 已发布 → 已下线）
- 平台管理员需要能将某历史版本回滚为「已发布」（同时把当前版本置为已下线）
- 平台管理员需要能对指定版本范围的客户端打上「强制更新」标记
- 平台管理员需要能查询全平台客户端版本分布（饼图、趋势图）
- 平台管理员需要能查询全平台租户活跃榜（活跃安装数、历史装机总数）
- 平台管理员需要能查询任一租户的客户端版本分布与活跃数

> 客户端**自身**与更新服务的交互（如查询最新版本、上报心跳）属于客户端运行时与平台之间的接口，不属于平台管理员的操作；本 PRD 不在此章描述，由 `TECH_STACK/平台管理后台技术方案.md` 定义。

#### 5.5.6 监控与告警

- 平台管理员需要能查询全局 / 单租户的监控图表
- 平台管理员需要能配置告警规则（指标 + 阈值 + 通知渠道）
- 平台管理员需要能查询告警历史

#### 5.5.7 审计日志

- 平台管理员（含审计员）需要能按多维度筛选审计日志
- 平台管理员（含审计员）需要能导出筛选结果为 CSV

#### 5.5.8 平台管理员账号与安全

- Platform Admin 需要能创建 / 编辑 / 停用平台管理员账号
- Platform Admin 需要能配置管理员角色（Platform Admin / 运营人员 / 只读审计员）
- 全部平台管理员需要能首次登录时配置 MFA（无法跳过）
- 全部平台管理员需要能在高危操作时通过 MFA 二次确认
- Platform Admin 需要能配置 IP 白名单
- Platform Admin 需要能查看活跃会话并强制登出指定管理员

---

### 5.6 安全与访问控制

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

| 安全要求 | 说明 |
|---------|------|
| MFA 强制启用 | 所有管理员账号首次登录强制配置 TOTP；不可跳过 |
| IP 白名单 | 仅允许指定 IP 范围访问平台管理后台 |
| 高危操作二次验证 | 删除租户、数据恢复、系统回滚、客户端版本下线、强制更新推送均触发 MFA 二次确认 |
| 会话超时 | 无操作 30 分钟自动登出，Token 失效 |
| 强制登出 | Platform Admin 可在「管理员设置」中强制终止指定管理员的所有会话 |
| 与租户应用隔离 | 平台管理后台部署在独立平台域名，不与租户应用共享 Session / Cookie |

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

所有写操作（Create / Update / Delete）及高危操作必须落审计日志，字段：

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

---

## 6. 角色权限矩阵

| 操作 | Platform Admin | 运营人员 | 只读审计员 |
|------|---------------|---------|-----------||
| 创建租户 | ✅ | ✅ | ❌ |
| 挂起 / 恢复租户 | ✅ | ✅ | ❌ |
| 发起租户注销申请（PA-011 SOP） | ✅ | ✅ | ❌ |
| 审批注销申请（第二人复核，MFA） | ✅ | ❌ | ❌ |
| 撤销注销（冷静期内，双人 MFA） | ✅ | ❌ | ❌ |
| 提前手动硬删除（MFA） | ✅ | ❌ | ❌ |
| 软删除 → Pending Delete（仅经 SOP 自动触发） | 系统自动 | — | — |
| 调整 License 到期日期 / 用户数上限 | ✅ | ✅ | ❌ |
| 数据导出 | ✅ | ✅ | ❌ |
| 手动触发备份 | ✅ | ✅ | ❌ |
| 数据恢复 | ✅ | ❌ | ❌ |
| 系统升级 | ✅ | ❌ | ❌ |
| 系统回滚 | ✅ | ❌ | ❌ |
| 查看版本总览 | ✅ | ✅ | ❌ |
| 配置告警规则 | ✅ | ✅ | ❌ |
| 发布 / 下线客户端版本 | ✅ | ❌ | ❌ |
| 客户端版本回滚 | ✅ | ❌ | ❌ |
| 推送强制更新标记 | ✅ | ❌ | ❌ |
| 查看客户端版本分布与活跃榜 | ✅ | ✅ | ✅ |
| 查看审计日志 | ✅ | ✅ | ✅ |
| 导出审计日志 | ✅ | ✅ | ✅ |
| 管理员账号管理 | ✅ | ❌ | ❌ |
| 强制登出管理员 | ✅ | ❌ | ❌ |
| 配置 IP 白名单 | ✅ | ❌ | ❌ |

---

## 7. 租户状态机

```
[新建中 Creating]
      ↓ 成功
[活跃 Active] ←──────────────────┐
      ↓ 手动 / License 到期挂起      │ 到期自动恢复（仅手动挂起且设置了到期时间）/ 手动恢复
[已挂起 Suspended] ───────────────┘
      ↓ 运营/PA 发起注销申请（PA-011）
[待审批注销 Pending Cancellation]
      ↓ 驳回（第二名 PA）→ [已挂起 Suspended]
      ↓ 批准（第二名 PA，MFA）
[待清除 Pending Delete]（冷静期 30 天）
      ↓ 双人 MFA 撤销注销 → [已挂起 Suspended]
      ↓ 冷静期届满（自动）/ 提前手动硬删除（MFA）
[已删除 Deleted]
```

> **注意**：Active / Suspended 状态下均可发起注销申请（后者更常见）。不允许直接跳过 SOP 从任何状态进入 Pending Delete 或 Deleted。

---

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

| 请求/功能 | 原因 | 重新评估条件 |
|----------|------|------------|
| 自动化账单与发票 | 财务模块独立立项 | 财务模块 PRD 完成后接入 |
| 租户端自助迁移工具 | 当前规模不需要 | 租户数 > 500 时重新评估 |
| 平台管理后台移动端 | 运营场景明确为 PC | v2 规划，用户调研支持时推进 |
| Webhook 事件推送市场 | 集成复杂度高，无客户驱动 | 有 3+ 客户明确需求时评估 |
| 多语言管理界面 | 内部团队中文已满足 | 国际化扩张时规划 |
| macOS / Linux 客户端 | 99% 用户为 Windows | 市场需求出现时评估 |
| 移动端客户端 App | v2 规划 | v2 启动时 |
| 客户端离线模式 | 联网使用为既定形态 | 暂不考虑 |
| 客户端代码混淆 / 反逆向 | 优先功能交付 | 安全审计要求时启动 |
| 响应客户数据导出请求 | 暂缓 | 后续迭代排期时细化 |

---

## 9. 发布计划

| 阶段 | 时间 | 范围 | 通过标准 |
|------|------|------|---------|
| 内部 Alpha | Week 1–4 | 平台内部团队 | 核心租户 CRUD 流程无 P0 Bug；MFA 可用；客户端发布流程闭环 |
| 封闭 Beta | Week 5–6 | 运营团队日常使用 + 1 家种子客户的客户端 | 备份/恢复完整可用；审计日志 100% 覆盖；客户端自动更新成功率 ≥ 95% |
| 正式上线 | Week 7 | 全量运营团队 + 全部客户的客户端 | 升级/回滚验证通过；监控告警规则配置完成；客户端版本一致性 ≥ 95% |

**回滚标准**：
- 正式上线 72 小时内发现租户数据隔离漏洞或审计日志丢失 → 立即回滚平台管理后台
- 客户端版本上线 24 小时内：自动更新失败率 > 5%、白屏 / 崩溃率 > 2%、或收到 P0 安全报告 → 立即下线该版本并恢复上一稳定版本

---

## 10. 技术考量（指引性）

> 本节为产品视角对技术决策的影响概述，详细方案请见各技术文档。

| 维度 | 关键依赖 | 备注 |
|------|---------|------|
| 多租户隔离 | `django-tenants` | 平台管理后台数据落 `public` schema，跨租户查询走 `public` 维度 |
| 异步任务 | Celery + Celery Beat | 创建租户、备份、导出、定时挂起检查等 |
| 数据库备份 | PostgreSQL `pg_dump`（待评估流式方案） | 大租户备份耗时风险 |
| 文件存储 | Cloudflare R2 | 备份、导出包、客户端安装包 |
| 监控 | Sentry + Grafana | 已在技术栈中规划 |
| MFA | `django-otp` + TOTP | 待最终选型 |
| 客户端 | Electron + electron-updater | 见 `TECH_STACK/平台管理后台技术方案.md` |
| 客户端心跳/活跃统计 | `public.client_heartbeats`（Upsert + 24h 活跃口径，见 `ADR-20260430-007`） | 是租户活跃榜与版本分布的数据源 |
| 客户端 API 命名空间 | 统一 `/api/release/...`（见 `ADR-20260430-009`） | 与租户客源管理 `apps/client/` 命名空间隔离 |

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

- [ ] 数据库备份方案：`pg_dump` 直接执行还是基于 WAL 的增量备份（如 pgBackRest）？— Owner: 工程负责人
- [ ] 监控数据来源：Grafana 直接对接 PostgreSQL 还是通过 Prometheus Exporter？— Owner: 运维团队
- [ ] MFA 库选型：`django-otp` + TOTP 还是集成第三方认证？— Owner: 工程负责人
- [ ] 审计日志存储：写入 `public` schema 还是独立日志服务（如 Elasticsearch）？— Owner: 工程负责人
- [ ] 客户端 EV 代码签名证书采购主体与预算 — Owner: IT 负责人
- [ ] CI/CD 平台选型（客户端构建签名流水线）— Owner: 运维负责人
- [ ] 客户端便携版（Portable ZIP）是否纳入 v1 — Owner: PM
- [ ] 客户端启动时租户 URL 分发方式（统一域名重定向 vs 内置配置文件）— Owner: 产品 + 工程

---

## 11. 附录

### 11.1 术语表

| 术语 | 定义 |
|------|------|
| Platform Admin | 平台超级管理员，拥有所有高危操作权限 |
| 运营人员 | 平台日常运营，承担租户管理、监控巡检 |
| 只读审计员 | 仅查询与导出审计日志，无写权限 |
| Tenant Admin | 租户内的最高权限用户，**对平台管理后台无访问权限** |
| Tenant Code | 租户唯一可读短码，用作租户访问 URL 中的 `tenant=` 参数 |
| 灰度升级 | 先对内测租户升级、验证通过后再全量推送 |
| 数据导出 | 输出结构化数据 + 文件 CDN URL 清单，分钟级，不含文件实体 |
| 完整备份 | 数据库 + 文件实体的完整副本，小时级，用于灾难恢复与租户迁移 |
| SemVer | 语义化版本控制 `主.次.补丁` |
| EV 证书 | Extended Validation 代码签名证书 |
| SHA256 | 用于校验客户端安装包完整性的散列算法 |

### 11.2 关联文档

| 类型                 | 文档                                        |
| ------------------ | ----------------------------------------- |
| 项目入口               | `README.md`                               |
| 开发约束               | `AGENTS.md`                               |
| MVP 范围             | `PRD/PRD_MVP.md`                          |
| 客户端技术方案            | `TECH_STACK/平台管理后台技术方案.md`                 |
| Public Schema 数据模型 | `DATA_MODEL/DATA_MODEL_PUBLIC.md`         |
| ADR                | `ADR.md`（含 `ADR-20260502-001`：本 PRD 合并决策） |