POFA · TECHNICAL DESIGN

多租户数据库隔离与 AI 辅助迁移架构

版本 v0.1 · 设计草案 · 适用于球员身份、普通社团、私密社团与赛事数据

模块化单体优先可演进至独立数据库AI 辅助、确定性执行

核心原则：先建立明确的租户边界、数据所有权、统一访问接口和可验证的迁移流程；初期不为每个社团部署单独数据库。

1. 目标与边界

POFA 的全局身份域保存球员登录账号、外部身份标识（例如 DUPR ID 的关联）、组织目录和租户数据路由。普通社团可使用共享数据库；对隐私或部署有更高要求的社团，未来可迁入独立数据库或受支持的客户托管环境。

私密社团的会员名单、联系方式、比赛记录及文件应按其授权边界存储和访问。文件通常存放在受隔离的对象存储，而非直接放入关系数据库。

2. 建议的逻辑结构

POFA Web / API
    │
    ├── Identity & Authorization（全局身份与授权）
    ├── Tenant Router（club_id → 数据位置）
    │     ├── Shared PostgreSQL（共享 schema + RLS）
    │     └── Dedicated PostgreSQL（按需独立库）
    ├── Object Storage（租户作用域的文件访问）
    ├── Migration Runner（版本迁移、校验、回滚）
    └── Audit & Event Outbox（审计与可靠同步）

3. 数据归属

数据类别	权威位置	设计说明
账号、登录身份	全局身份域	一个人可加入多个社团；不要复制独立密码库
DUPR ID 关联	全局身份域	外部标识须验证归属；不等同内部主键
社团目录、租户路由	总库	路由记录位置、状态、版本，不明文存放数据库凭据
会员名单、联系方式	社团所属数据域	通过 club_id 和访问控制隔离
比赛、比分、签表	赛事所属数据域	定义权威记录及跨域共享规则
上传文件	对象存储	按租户授权、加密与保留期管理

4. 第一版必须建立的约束

全局稳定 ID：业务实体优先使用 UUID；UUID 降低碰撞风险，但不能自动解决重复身份、业务冲突和版本分歧。
租户边界：所有社团作用域表包含 club_id；全局用户和全局路由表不必强行添加。复合唯一约束与外键需匹配租户边界。
共享库安全：PostgreSQL RLS 与应用层授权同时使用，测试跨租户越权、后台任务及管理员绕过路径。
统一业务契约：共享库与独立库保持对应业务模块的兼容 schema / API 版本，而非要求所有库包含完全相同的表。
迁移版本：按库记录迁移版本和结果；支持批量执行、失败重试与逐租户暂停，不假设所有库总能同步升级成功。
独立密钥：独立部署采用租户级密钥管理；密钥轮换、备份与销毁需可审计。

5. 数据库迁出、并入与删除

迁出至独立库

冻结或控制租户写入 → 生成一致性快照 → 导入目标库 → 校验记录数、关联关系、权限和业务不变量 → 处理增量变更 → 原子切换路由 → 观察与回滚窗口 → 按保留策略清理旧副本。

并入共享库

预检 UUID、租户 ID、重复账号与业务冲突 → 临时区导入 → 按已审核映射转换 → 验证外键与比分等业务规则 → 切换路由 → 监测 → 清理旧库及副本。仅复制数据并修改路由不足以保证迁移成功。

删除

先验证申请人和处理权限，识别适用的法定保留义务，再执行访问撤销、主库删除、密钥销毁（若适用）及备份到期清除。缓存、对象存储、日志和授权共享的副本需要独立处理。加密擦除是否有效取决于密钥隔离和所有副本的管理方式。

合规边界：GDPR、CCPA/CPRA 等删除权并非无条件覆盖全部记录；客户自托管环境的物理删除无法仅凭 POFA 云端指令保证，必须明确控制者、处理者及合同责任。

6. 跨库身份与赛事同步

一个球员可以属于多个社团。全局身份只提供稳定引用；私密社团数据不得因拥有相同球员 ID 而自动参与公开排名。跨库排行和成绩汇总必须建立明确的授权、数据最小化与撤回机制。

比分等权威数据保留在赛事所属库。对外同步使用 Outbox 事件、幂等消费者和可重放的处理记录，避免假设多个数据库能天然原子提交。

7. AI 字段校准与迁移审计

AI 可以读取脱敏 schema、字段注释和经过许可的样本，提出字段映射、类型转换、重复身份候选及异常检查。它不能仅凭字段名确认 club_id 与 organization_id 等价，也不能将置信度当作迁移验收。

Schema/脱敏样本 → AI 提议映射
    → 人工审核歧义与敏感映射
    → 版本化映射规则
    → 确定性迁移程序（先 dry-run）
    → 记录数 / 外键 / 哈希 / 比分规则 / 权限校验
    → 批准切换 + 审计日志

涉及个人信息的样本数据应遵守最小化原则，明确模型服务的数据处理范围；高风险字段默认使用合成样本或脱敏样本。

8. 迭代路线

阶段	实施内容	验收重点
V1	模块化单体、共享 PostgreSQL、RLS、UUID、club_id、统一 API	跨租户访问被拒绝，核心赛事闭环通过
V1.5	租户路由抽象、导出/导入、dry-run、迁移审计	可重复迁移，校验失败不切流
V2	按需独立库、独立密钥、备份恢复、Outbox 同步	可恢复、可回滚、可验证隔离
Enterprise	受控客户自托管、明确责任边界、部署与升级协议	可维护、可审计、符合客户合同要求

9. 尚待决策

私密社团是否允许公开赛事结果，以及哪些字段可以公开。
赛事与社团是否始终一对一归属；跨社团联合赛事如何确定数据权威源。
DUPR 外部标识的绑定、解绑、同步与授权策略。
独立库和客户自托管的付费门槛及服务级别。
各地区的数据保留期、删除例外与支付数据责任划分。