ishenwei/nexus

Fork 0

Files

Shen Wei 464c5fce51 系统管理模块更新

2026-05-02 05:10:16 +08:00

35 KiB

Raw Blame History

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 核心痛点

痛点	影响方	当前代价
无统一租户管理界面，开通/暂停操作依赖人工脚本	运营团队	高错误风险，操作耗时
版本升级需停机维护，影响所有租户	所有用户	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 设定，决定租户有效期；到期后系统自动挂起

创建流程：

表单校验通过后，后台 Celery 任务执行：
- 创建 PostgreSQL Schema（tenant_{id}）
- 执行 Migrate 初始化表结构
- 注入默认配置（见下方「默认配置内容」说明）
- 生成初始密码（12 位随机，含大小写字母+数字），标记为「首次登录强制修改」
- 若联系邮箱已填写：发送欢迎邮件（含 Tenant Code、初始密码、平台访问链接 https://app.fonrey.com/?tenant={TenantCode}）
任务完成后更新租户状态为 active，失败则全量回滚并标记为 failed
生成唯一 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（平台超级管理员）可操作

删除前置条件：

操作人必须确认数据导出已完成（勾选确认框）
硬删除需二次身份验证（MFA 确认）
软删除冷静期内（默认 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）及高危操作必须记录审计日志，字段规范如下：

{
    "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/          # 管理员设置

35 KiB Raw Blame History Unescape Escape

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

变更历史

1. 问题陈述

1.1 背景

1.2 核心痛点

1.3 目标用户

2. 目标与成功指标

3. 非目标（Non-Goals）

4. 用户角色与核心故事

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

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

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

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

5.1 租户管理（Tenant Management）

5.1.1 租户生命周期

5.1.2 数据管理

5.1.3 套餐与升级管理

5.1.4 用户与权限管理

5.1.5 租户监控与统计

5.2 系统管理（System Management）

5.2.1 版本升级与回滚

5.2.2 定时备份策略

5.3 管理控制台（Admin Console）

5.3.1 核心页面规格

5.3.2 访问控制与安全

5.3.3 操作审计日志规范

6. 技术考量

6.1 系统架构定位

6.2 关键依赖

6.3 已知风险

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

7. 发布计划

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

9. 附录

9.1 租户状态机

9.2 管理员角色权限矩阵

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

35 KiB

Raw Blame History