> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked.
# Fonrey — Public Schema 数据模型

> **作者**: Backend Architect  
> **版本**: v1.2  
> **日期**: 2026-04-26  
> **权威源**: 本文件是 `public` schema 所有表的唯一权威定义  
> **设计依据**: 系统管理模块 PRD（`PRD/系统管理/系统管理模块PRD.md`）；客户端发布管理模块 PRD（`PRD/发布管理/客户端发布管理模块PRD.md`）  
> **索引文档**: [`DATA_MODEL.md §三`](./DATA_MODEL.md)（仅保留摘要索引，开发以本文件为准）

---

## 一、概览

`public` schema 存储**平台运营层**数据，与各租户的业务 schema 完全隔离。

### 架构定位

```
PostgreSQL Instance
│
├── public schema（平台运营层）← 本文件覆盖
│   ├── tenants               租户注册与生命周期（含 feature_flags JSONB）
│   ├── domains               域名路由
│   ├── tenant_status_logs    状态变更审计
│   ├── platform_admins       管理员账号
│   ├── admin_mfa_devices     TOTP 设备
│   ├── admin_sessions        登录会话
│   ├── ip_whitelist          访问控制
│   ├── platform_audit_logs   操作审计
│   ├── backup_schedules      备份计划
│   ├── backup_records        备份记录
│   ├── export_tasks          数据导出
│   ├── system_versions       版本历史
│   ├── upgrade_events        升级事件（A/B/C 分级 + B 类分批编排）
│   ├── client_releases       客户端版本发布
│   ├── feature_flag_definitions  Feature Flag 定义（C 类灰度控制平面）
│   └── feature_flag_change_log   Feature Flag 变更历史（append-only）
│
├── tenant_abc schema（租户业务层，见各子文档）
└── tenant_xyz schema
```

### 表清单

| 表名 | 说明 | 节 |
|------|------|----|
| `public.tenants` | 租户主表（每家房产公司一条记录） | §2.1 |
| `public.domains` | 域名↔租户映射（多域名支持） | §2.1 |
| `public.tenant_status_logs` | 租户状态变更不可变审计日志 | §2.1 |
| `public.platform_admins` | 平台管理员账号（3 种角色） | §2.2 |
| `public.admin_mfa_devices` | 管理员 TOTP MFA 设备（强制启用） | §2.2 |
| `public.admin_sessions` | 管理员登录会话（30 min 超时，支持强制登出） | §2.2 |
| `public.ip_whitelist` | 管理控制台 CIDR 白名单 | §2.2 |
| `public.platform_audit_logs` | 所有写操作+高危操作审计（append-only，建议月度分区） | §2.3 |
| `public.backup_schedules` | 全局/租户级定时备份计划 | §2.4 |
| `public.backup_records` | 备份任务执行记录（自动/手动/升级前/恢复前） | §2.4 |
| `public.export_tasks` | 数据导出异步任务（CSV/JSON/SQL Dump） | §2.4 |
| `public.system_versions` | 平台版本历史，唯一 current 约束 | §2.5 |
| `public.upgrade_events` | 升级/回滚事件，A/B/C 升级类型分级，B 类按租户分批编排 + 健康门控 | §2.5 |
| `public.client_releases` | Windows 客户端发布版本，含安装包 URL、SHA256、强制更新标记 | §2.6 |
| `public.feature_flag_definitions` | Feature Flag 全局定义（C 类运行时灰度控制平面） | §2.7 |
| `public.tenants.feature_flags` | 租户级 Flag 显式覆盖（`tenants` 表新增 JSONB 列） | §2.7 |
| `public.feature_flag_change_log` | Feature Flag 变更历史（append-only） | §2.7 |

---

## 二、DDL 定义

### 2.1 租户管理

```sql
-- ============================================================
-- 文件: shared_schema.sql
-- 用途: django-tenants 公共 Schema，存放平台运营层数据
-- 设计依据: 系统管理模块 PRD v1.0
-- ============================================================

-- ────────────────────────────────────────────────────────────
-- 1. 租户管理
-- ────────────────────────────────────────────────────────────

-- 租户状态枚举（生命周期状态机，见 PRD §9.1）
-- creating → active ←→ suspended → pending_delete → deleted
--                                    ↑ 硬删除直接到 deleted

-- 租户主表（每家房产经纪公司一条记录）
CREATE TABLE public.tenants (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    schema_name     VARCHAR(63) UNIQUE NOT NULL,   -- PG schema 名，最长 63 字符，创建后不可修改
    name            VARCHAR(255) NOT NULL,          -- 公司名称
    short_name      VARCHAR(100),                   -- 简称/品牌名
    contact_name    VARCHAR(100) NOT NULL,          -- 主联系人姓名
    contact_email   VARCHAR(254) NOT NULL,          -- 联系邮箱（接收通知/欢迎邮件）
    region          VARCHAR(100),                   -- 所在地区（省市，如「上海市」）
    plan            VARCHAR(20) NOT NULL DEFAULT 'basic'
                    CHECK (plan IN ('basic','professional','enterprise')),

    -- 状态机
    status          VARCHAR(20) NOT NULL DEFAULT 'creating'
                    CHECK (status IN ('creating','active','suspended','pending_delete','deleted','failed')),
    suspended_until TIMESTAMPTZ,                   -- NULL = 永久挂起，非 NULL = Celery Beat 定时恢复
    suspended_reason VARCHAR(50)
                    CHECK (suspended_reason IN ('overdue','violation','requested','other')),
    deleted_at      TIMESTAMPTZ,                   -- 软删除时间戳；硬删除直接物理删除行

    -- 订阅
    paid_until      DATE,                          -- 订阅到期日
    on_trial        BOOLEAN NOT NULL DEFAULT TRUE,

    -- 灰度升级
    is_canary       BOOLEAN NOT NULL DEFAULT FALSE, -- TRUE = 内测租户，参与灰度升级

    -- Feature Flag 租户级覆盖（详见 §2.7）
    -- 格式: {"flag_key": true|false, ...}
    -- 业务代码只读；写入由 apps.admin_console 经 feature_flag_change_log 审计
    feature_flags   JSONB NOT NULL DEFAULT '{}'::jsonb,

    -- 元数据
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by      UUID,                          -- 创建该租户的管理员 ID（可 NULL，初始化时）
    extra           JSONB NOT NULL DEFAULT '{}'    -- 预留扩展字段
);

CREATE INDEX idx_tenants_status ON public.tenants(status);
CREATE INDEX idx_tenants_suspended_until ON public.tenants(suspended_until)
    WHERE status = 'suspended' AND suspended_until IS NOT NULL;
CREATE INDEX idx_tenants_canary ON public.tenants(is_canary) WHERE is_canary = TRUE;
CREATE INDEX idx_tenants_pending_delete ON public.tenants(deleted_at)
    WHERE status = 'pending_delete';
-- Feature Flag 租户级覆盖的 GIN 索引（详见 §2.7）
-- 同时在 §2.7 中以 ALTER TABLE ADD COLUMN IF NOT EXISTS 兜底，便于按模块独立部署
CREATE INDEX idx_tenants_feature_flags_gin ON public.tenants USING gin (feature_flags);

-- 域名映射表（支持多域名绑定一个租户，子域名创建后不可修改）
CREATE TABLE public.domains (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    domain      VARCHAR(253) UNIQUE NOT NULL,      -- 含子域名的完整域名（如 abc.platform.com）
    tenant_id   UUID NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
    is_primary  BOOLEAN NOT NULL DEFAULT FALSE,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_domains_tenant ON public.domains(tenant_id);
CREATE UNIQUE INDEX idx_domains_primary ON public.domains(tenant_id) WHERE is_primary = TRUE;

-- 租户状态变更日志（append-only，不可删除）
-- 记录所有 status 变更：creating→active / active→suspended / suspended→active / →pending_delete / →deleted
CREATE TABLE public.tenant_status_logs (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id       UUID NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
    from_status     VARCHAR(20),                   -- NULL 表示初始创建
    to_status       VARCHAR(20) NOT NULL,
    reason          TEXT,
    operator_id     UUID,                          -- 操作管理员 ID；NULL = 系统自动（Celery）
    operator_name   VARCHAR(100),                  -- 快照，防止管理员被删后失去可追溯性
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
    -- 无 deleted_at，无 UPDATE，append-only
);

CREATE INDEX idx_tenant_status_logs_tenant ON public.tenant_status_logs(tenant_id, created_at DESC);
```

### 2.2 平台管理员

```sql
-- ────────────────────────────────────────────────────────────
-- 2. 平台管理员
-- ────────────────────────────────────────────────────────────

-- 管理员账号（与租户 staff 完全独立，存于 public schema）
CREATE TABLE public.platform_admins (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    username        VARCHAR(150) UNIQUE NOT NULL,
    email           VARCHAR(254) UNIQUE NOT NULL,
    display_name    VARCHAR(100) NOT NULL,
    password_hash   VARCHAR(255) NOT NULL,          -- Django PBKDF2 / Argon2 哈希
    role            VARCHAR(20) NOT NULL
                    CHECK (role IN ('super_admin','ops_operator','read_only_auditor')),
    is_active       BOOLEAN NOT NULL DEFAULT TRUE,
    mfa_enabled     BOOLEAN NOT NULL DEFAULT FALSE, -- 首次登录前为 FALSE，配置 TOTP 后变 TRUE
    last_login_at   TIMESTAMPTZ,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by      UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL
);

CREATE INDEX idx_platform_admins_role ON public.platform_admins(role) WHERE is_active = TRUE;

-- MFA 设备（TOTP，每管理员可注册多个设备，但通常一个）
CREATE TABLE public.admin_mfa_devices (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    admin_id        UUID NOT NULL REFERENCES public.platform_admins(id) ON DELETE CASCADE,
    device_name     VARCHAR(100) NOT NULL DEFAULT 'Authenticator App',
    totp_secret     VARCHAR(255) NOT NULL,          -- Base32 加密存储
    is_confirmed    BOOLEAN NOT NULL DEFAULT FALSE, -- 首次验证通过后置 TRUE
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    last_used_at    TIMESTAMPTZ
);

CREATE INDEX idx_admin_mfa_devices_admin ON public.admin_mfa_devices(admin_id)
    WHERE is_confirmed = TRUE;

-- 管理员登录会话（支持强制登出）
CREATE TABLE public.admin_sessions (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    admin_id        UUID NOT NULL REFERENCES public.platform_admins(id) ON DELETE CASCADE,
    session_token   VARCHAR(255) UNIQUE NOT NULL,   -- 随机安全令牌
    ip_address      INET NOT NULL,
    user_agent      TEXT,
    is_active       BOOLEAN NOT NULL DEFAULT TRUE,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    expires_at      TIMESTAMPTZ NOT NULL,            -- 默认 NOW() + 30 分钟，活动时滚动续期
    revoked_at      TIMESTAMPTZ,                    -- 强制登出时记录
    revoked_by      UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL
);

CREATE INDEX idx_admin_sessions_admin ON public.admin_sessions(admin_id) WHERE is_active = TRUE;
CREATE INDEX idx_admin_sessions_expires ON public.admin_sessions(expires_at) WHERE is_active = TRUE;

-- IP 白名单（管理控制台访问限制）
CREATE TABLE public.ip_whitelist (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    cidr        CIDR NOT NULL,                     -- 如 203.0.113.0/24 或 203.0.113.5/32
    label       VARCHAR(100),                      -- 备注，如「上海办公室」
    is_active   BOOLEAN NOT NULL DEFAULT TRUE,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by  UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL
);

CREATE INDEX idx_ip_whitelist_active ON public.ip_whitelist(cidr) WHERE is_active = TRUE;
```

### 2.3 审计日志（append-only）

```sql
-- ────────────────────────────────────────────────────────────
-- 3. 审计日志（append-only）
-- ────────────────────────────────────────────────────────────

-- 平台操作审计日志（所有写操作 + 高危操作，无 deleted_at，无 UPDATE）
CREATE TABLE public.platform_audit_logs (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    operator_id     UUID,                          -- 管理员 ID；NULL 表示系统自动操作
    operator_name   VARCHAR(100),                  -- 快照（防止账号删除后失去溯源）
    action_type     VARCHAR(50) NOT NULL,
        -- CREATE_TENANT | SUSPEND_TENANT | RESUME_TENANT | DELETE_TENANT | HARD_DELETE_TENANT
        -- RESTORE_DATA | TRIGGER_BACKUP | SYSTEM_UPGRADE | ROLLBACK
        -- RESET_PASSWORD | CREATE_ADMIN | DEACTIVATE_ADMIN | FORCE_LOGOUT
        -- UPDATE_IP_WHITELIST | UPDATE_BACKUP_SCHEDULE | EXPORT_DATA | ...
    target_type     VARCHAR(30) NOT NULL,          -- Tenant | User | System | Backup | Admin
    target_id       VARCHAR(255),                  -- 操作对象 ID（UUID 或其他）
    target_name     VARCHAR(255),                  -- 操作对象可读名称（快照）
    payload_summary TEXT,                          -- 操作内容摘要（非敏感字段）
    result          VARCHAR(10) NOT NULL DEFAULT 'SUCCESS'
                    CHECK (result IN ('SUCCESS','FAILED')),
    error_message   TEXT,
    ip_address      INET,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
    -- 无 deleted_at，无 UPDATE；建议按月 RANGE 分区
);

CREATE INDEX idx_audit_logs_operator ON public.platform_audit_logs(operator_id, created_at DESC);
CREATE INDEX idx_audit_logs_action ON public.platform_audit_logs(action_type, created_at DESC);
CREATE INDEX idx_audit_logs_target ON public.platform_audit_logs(target_type, target_id, created_at DESC);
CREATE INDEX idx_audit_logs_created ON public.platform_audit_logs(created_at DESC);
```

### 2.4 备份与导出

```sql
-- ────────────────────────────────────────────────────────────
-- 4. 备份与导出
-- ────────────────────────────────────────────────────────────

-- 定时备份计划（全局策略 + 租户覆盖策略）
CREATE TABLE public.backup_schedules (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id       UUID REFERENCES public.tenants(id) ON DELETE CASCADE,
        -- NULL = 全局默认计划；非 NULL = 该租户的独立计划（覆盖全局）
    frequency       VARCHAR(10) NOT NULL DEFAULT 'daily'
                    CHECK (frequency IN ('hourly','daily','weekly')),
    scheduled_time  TIME NOT NULL DEFAULT '02:00',  -- 执行时间窗口（UTC）
    retention_count INTEGER NOT NULL DEFAULT 10,    -- 最多保留 N 个备份版本
    storage_target  VARCHAR(20) NOT NULL DEFAULT 'r2'
                    CHECK (storage_target IN ('local','s3','r2','gcs')),
    is_active       BOOLEAN NOT NULL DEFAULT TRUE,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by      UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL,
    UNIQUE (tenant_id)  -- 每个租户最多一条独立计划；NULL tenant_id 用应用层保证全局唯一
);

-- 备份任务执行记录
CREATE TABLE public.backup_records (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id       UUID NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
    trigger_type    VARCHAR(10) NOT NULL
                    CHECK (trigger_type IN ('auto','manual','pre_upgrade','pre_restore')),
    status          VARCHAR(15) NOT NULL DEFAULT 'pending'
                    CHECK (status IN ('pending','in_progress','success','failed')),
    storage_target  VARCHAR(20) NOT NULL,
    storage_path    TEXT,                           -- R2/S3 存储路径
    size_bytes      BIGINT,                         -- 备份包大小
    started_at      TIMESTAMPTZ,
    completed_at    TIMESTAMPTZ,
    error_message   TEXT,
    triggered_by    UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL,
    upgrade_event_id UUID,                         -- 关联升级事件（pre_upgrade 类型）
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_backup_records_tenant ON public.backup_records(tenant_id, created_at DESC);
CREATE INDEX idx_backup_records_status ON public.backup_records(status)
    WHERE status IN ('pending','in_progress');

-- 数据导出任务（异步 Celery 执行）
CREATE TABLE public.export_tasks (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id       UUID NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
    requested_by    UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL,
    modules         TEXT[] NOT NULL,
        -- 'clients' | 'properties' | 'transactions' | 'system_config' | 'all'
    format          VARCHAR(10) NOT NULL
                    CHECK (format IN ('csv','json','sql_dump')),
    status          VARCHAR(15) NOT NULL DEFAULT 'pending'
                    CHECK (status IN ('pending','in_progress','done','failed')),
    storage_path    TEXT,                           -- R2 临时目录路径
    download_url    TEXT,                           -- 带签名下载链接
    expires_at      TIMESTAMPTZ,                    -- 下载链接有效期（默认 24 小时）
    size_bytes      BIGINT,
    started_at      TIMESTAMPTZ,
    completed_at    TIMESTAMPTZ,
    error_message   TEXT,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_export_tasks_tenant ON public.export_tasks(tenant_id, created_at DESC);
CREATE INDEX idx_export_tasks_status ON public.export_tasks(status)
    WHERE status IN ('pending','in_progress');
```

### 2.5 版本升级管理

```sql
-- ────────────────────────────────────────────────────────────
-- 5. 版本升级管理
-- ────────────────────────────────────────────────────────────

-- 平台版本历史
CREATE TABLE public.system_versions (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    version_number  VARCHAR(50) UNIQUE NOT NULL,   -- 如 v2.3.1
    release_notes   TEXT,
    artifact_url    TEXT,                           -- 制品库地址
    status          VARCHAR(15) NOT NULL DEFAULT 'previous'
                    CHECK (status IN ('current','previous','archived')),
    released_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by      UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL
);

CREATE UNIQUE INDEX idx_system_versions_current ON public.system_versions(status)
    WHERE status = 'current';  -- 全局只允许一个 current 版本

-- 升级事件（每次执行升级或回滚对应一条记录）
-- 设计依据: 系统管理技术文档 §8.5–§8.6（A/B/C 升级类型分级 + B 类分批编排）
CREATE TABLE public.upgrade_events (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    from_version_id UUID REFERENCES public.system_versions(id) ON DELETE SET NULL,
    to_version_id   UUID NOT NULL REFERENCES public.system_versions(id) ON DELETE RESTRICT,
    event_type      VARCHAR(10) NOT NULL
                    CHECK (event_type IN ('upgrade','rollback')),

    -- 升级类型（决定本表大部分字段是否生效；详见技术文档 §8.5）
    -- A_app    = 应用代码升级（蓝绿全量切换，灰度名单/批次字段无效）
    -- B_schema = 租户 Schema 迁移（按租户分批，批次字段全部生效）
    -- C_feature = Feature Flag 灰度（不在本表编排，详见 §2.7；本字段保留以便统一记录）
    upgrade_type    VARCHAR(16) NOT NULL DEFAULT 'B_schema'
                    CHECK (upgrade_type IN ('A_app','B_schema','C_feature')),

    strategy        VARCHAR(10) NOT NULL DEFAULT 'full'
                    CHECK (strategy IN ('full','canary')),  -- full = 全量，canary = 灰度

    -- 升级编排状态机（与技术文档 §8.6.1 一致）
    -- draft → pre_check → pre_backup → batch_running ⇄ batch_done → succeeded
    --                                                  ↓ 任一批失败/门控不通过
    --                                               halted → rollback_running → rolled_back
    --                                                  ↓ 整体失败
    --                                               failed
    status          VARCHAR(20) NOT NULL DEFAULT 'draft'
                    CHECK (status IN (
                        'draft','pre_check','pre_backup','batch_running','batch_done',
                        'halted','succeeded','failed','rollback_running','rolled_back'
                    )),
    halted_reason   TEXT,                            -- halted 状态时记录失败指标快照（健康门控不通过原因）

    -- 灰度名单（B_schema 类型生效；A_app 类型必须为空数组）
    -- [tenant_id, ...]
    gray_tenant_ids JSONB NOT NULL DEFAULT '[]',

    -- 批次编排参数（B_schema 类型生效）
    batch_size              INTEGER NOT NULL DEFAULT 5
                            CHECK (batch_size BETWEEN 1 AND 100),       -- 每批包含的租户数
    batch_concurrency       INTEGER NOT NULL DEFAULT 2
                            CHECK (batch_concurrency BETWEEN 1 AND 20), -- 批内并发执行的租户数
    batch_interval_seconds  INTEGER NOT NULL DEFAULT 300
                            CHECK (batch_interval_seconds BETWEEN 0 AND 86400), -- 批间观察窗口（秒）
    failure_policy          VARCHAR(16) NOT NULL DEFAULT 'halt_batch'
                            CHECK (failure_policy IN ('halt_batch','continue')),
        -- halt_batch = 任一租户失败立即中断当前批，进入 halted 等待人工
        -- continue   = 其他租户继续，仅标记失败（适用低风险变更）
    current_batch_no        INTEGER NOT NULL DEFAULT 0,                  -- 已完成批次序号
    total_batch_count       INTEGER,                                     -- 总批次数 = ceil(len(gray_tenant_ids)/batch_size)

    -- 健康门控阈值（覆盖默认值；默认值见技术文档 §8.6.5）
    -- {"error_rate_5xx_5m": 0.005, "p95_latency_5m": 2000,
    --  "celery_queue_pending": 1000, "sentry_new_issues_5m": 5}
    health_gate_config      JSONB NOT NULL DEFAULT '{}',

    -- 升级前全局备份引用（B_schema 必须；恢复兜底用）
    pre_backup_record_id    UUID REFERENCES public.backup_records(id) ON DELETE SET NULL,

    -- 单租户进度快照
    -- 数组格式（保留向后兼容）：
    -- [{tenant_id, tenant_name, status, started_at, completed_at,
    --   snapshot_id, batch_no, error}]
    -- status 取值：pending | running | success | failed | rolled_back
    tenant_progress JSONB NOT NULL DEFAULT '[]',

    -- 回滚相关
    rollback_reason TEXT,
    incident_report TEXT,                            -- 回滚后生成的事件报告（halted 转 rolled_back 时写）

    started_at      TIMESTAMPTZ,
    completed_at    TIMESTAMPTZ,
    initiated_by    UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    -- 数据完整性约束：A_app 类型不允许带灰度名单（蓝绿全量切换）
    CONSTRAINT chk_app_upgrade_no_gray
        CHECK (upgrade_type <> 'A_app' OR gray_tenant_ids = '[]'::jsonb)
);

CREATE INDEX idx_upgrade_events_status ON public.upgrade_events(status, created_at DESC);
CREATE INDEX idx_upgrade_events_type   ON public.upgrade_events(upgrade_type, created_at DESC);
-- 用于「halted 状态需要超管处理」的实时告警查询
CREATE INDEX idx_upgrade_events_halted ON public.upgrade_events(created_at DESC)
    WHERE status = 'halted';
```

### 2.6 客户端发布管理

```sql
-- ────────────────────────────────────────────────────────────
-- 6. 客户端发布管理
-- ────────────────────────────────────────────────────────────
-- 设计依据: 客户端发布管理模块 PRD §5.3
-- 说明: 本表属于 shared_apps（public schema），所有租户共享同一套客户端版本，
--       不做多租户隔离。

-- 客户端版本发布表
CREATE TABLE public.client_releases (
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    -- 版本标识
    version             VARCHAR(20) UNIQUE NOT NULL,
        -- SemVer 格式，如 '1.2.3'；由应用层校验格式，数据库层仅保证唯一性
    platform            VARCHAR(20) NOT NULL DEFAULT 'win32'
                        CHECK (platform IN ('win32')),
        -- 当前仅支持 Windows；后续支持 darwin / linux 时扩展 CHECK
    arch                VARCHAR(10) NOT NULL DEFAULT 'x64'
                        CHECK (arch IN ('x64', 'arm64')),

    -- 版本类型与状态
    release_type        VARCHAR(10) NOT NULL DEFAULT 'normal'
                        CHECK (release_type IN ('normal', 'force')),
        -- normal = 普通更新，提示但可延后；force = 强制升级，不可跳过
    status              VARCHAR(10) NOT NULL DEFAULT 'draft'
                        CHECK (status IN ('draft', 'published', 'archived')),
        -- draft = 草稿，不对外生效；published = 已发布，客户端可感知；archived = 已下线

    -- 兼容性约束
    min_required_version VARCHAR(20),
        -- 低于该版本的客户端将被强制要求升级，NULL = 无最低版本限制
        -- 由应用层在查询时比较 SemVer，数据库层不做运算

    -- 安装包（EXE）
    download_url        TEXT NOT NULL,
        -- Cloudflare R2 公开 URL，格式：
        -- https://download.fonrey.com/releases/v{version}/fonrey-setup-{version}-win.exe
    checksum_sha256     VARCHAR(64) NOT NULL,
        -- 安装包 SHA256 十六进制字符串（64 位），客户端下载完成后校验
    file_size_bytes     BIGINT,
        -- 安装包字节大小，用于前端展示下载大小

    -- 便携版（ZIP，可选）
    portable_url        TEXT,
        -- 无需安装的 ZIP 版本，供无管理员权限的企业环境使用
    portable_checksum_sha256 VARCHAR(64),

    -- 更新内容
    release_notes       TEXT NOT NULL,
        -- 对外展示的更新日志，Markdown 格式，最多 2000 字
    internal_notes      TEXT,
        -- 内部技术说明，不对外展示

    -- 统计
    download_count      INTEGER NOT NULL DEFAULT 0,
        -- 该版本安装包被下载次数，由应用层在每次下载时原子递增

    -- 时间与操作人
    published_at        TIMESTAMPTZ,
        -- 首次设为 published 时记录，后续状态变更不更新此字段
    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by          UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL,
    published_by        UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL
);

-- 只允许一条 published 记录（同平台+架构下的当前生效版本）
CREATE UNIQUE INDEX idx_client_releases_published
    ON public.client_releases(platform, arch)
    WHERE status = 'published';

-- 快速查找草稿/已发布版本（管理后台列表查询）
CREATE INDEX idx_client_releases_status ON public.client_releases(status, created_at DESC);

-- 按版本号快速定位（客户端更新检测时传入 current_version 查询）
CREATE INDEX idx_client_releases_version ON public.client_releases(version);
```

### 2.7 Feature Flag 灰度体系

```sql
-- ────────────────────────────────────────────────────────────
-- 7. Feature Flag 灰度体系
-- ────────────────────────────────────────────────────────────
-- 设计依据: 系统管理技术文档 §8.7（C 类升级 / 运行时功能灰度）
-- 说明: 与 §2.5 upgrade_events 的 B 类（schema 迁移）配合使用，
--       负责「行为切换」的运行时灰度。详见技术文档 §8.7.6 四步发布流程。

-- 全局 Flag 注册表（控制平面）
CREATE TABLE public.feature_flag_definitions (
    key                 VARCHAR(64) PRIMARY KEY,
        -- 命名规范：snake_case，业务前缀 + 功能名 + 版本号
        -- 例：'property_ai_description_v2' / 'search_ranking_algo_2026q2'
    description         TEXT NOT NULL,                  -- 业务说明（必填，便于审计回溯）
    default_value       BOOLEAN NOT NULL DEFAULT FALSE,
        -- 未在 tenants.feature_flags 显式覆盖、且不命中 rollout_strategy 时返回此值

    -- 灰度策略
    rollout_strategy    VARCHAR(16) NOT NULL DEFAULT 'tenant'
                        CHECK (rollout_strategy IN ('tenant','percentage','user')),
        -- tenant     = 仅按 tenants.feature_flags 显式开关，不做百分比
        -- percentage = 按租户 ID 稳定哈希进百分比桶（rollout_config.percentage）
        -- user       = 按用户 ID 稳定哈希（rollout_config.percentage），需调用方传 user
    rollout_config      JSONB NOT NULL DEFAULT '{}',
        -- percentage / user 策略下：{"percentage": 30}
        -- tenant 策略下：通常为空 {}

    owner_admin_id      UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL,
        -- 责任人（用于到期清理提醒、问题归因）

    -- 生命周期
    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    archived_at         TIMESTAMPTZ,
        -- 归档后所有查询永久返回 FALSE；不删除以保留审计链路
    archived_reason     TEXT
);

CREATE INDEX idx_ff_def_active ON public.feature_flag_definitions(rollout_strategy)
    WHERE archived_at IS NULL;
CREATE INDEX idx_ff_def_owner  ON public.feature_flag_definitions(owner_admin_id)
    WHERE archived_at IS NULL;

-- 租户级 Flag 覆盖（存于 tenants 表的 JSONB 列）
-- 设计上不单建表，避免每次 is_enabled() 多查一次 JOIN；
-- public.tenants.feature_flags 列与 idx_tenants_feature_flags_gin 索引已在 §2.1 声明，
-- 此处用 IF NOT EXISTS 兜底，便于本节单独执行（如分阶段迁移）：
ALTER TABLE public.tenants
    ADD COLUMN IF NOT EXISTS feature_flags JSONB NOT NULL DEFAULT '{}'::jsonb;
    -- 格式：{"flag_key": true|false, ...}
    -- 仅 platform_admin 通过本模块写入；业务代码只读

CREATE INDEX IF NOT EXISTS idx_tenants_feature_flags_gin
    ON public.tenants USING gin (feature_flags);

-- Flag 变更历史（append-only，与 platform_audit_logs 同等约束）
CREATE TABLE public.feature_flag_change_log (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    flag_key        VARCHAR(64) NOT NULL,
        -- 不加外键引用 feature_flag_definitions(key)：归档/重命名时不应连带删除审计
    tenant_id       UUID REFERENCES public.tenants(id) ON DELETE SET NULL,
        -- NULL 表示全局变更（如调整 rollout_strategy / percentage / archive）
        -- 非 NULL 表示该租户的覆盖值变更
    change_scope    VARCHAR(20) NOT NULL
                    CHECK (change_scope IN (
                        'definition_create','definition_update','definition_archive',
                        'tenant_override_set','tenant_override_clear'
                    )),
    old_value       JSONB,                          -- 变更前的完整值（NULL 表示首次创建）
    new_value       JSONB NOT NULL,                 -- 变更后的完整值
    operator_id     UUID NOT NULL REFERENCES public.platform_admins(id) ON DELETE RESTRICT,
        -- 强制保留操作人；账号停用不可级联删除审计
    operator_name   VARCHAR(100) NOT NULL,          -- 快照
    reason          TEXT NOT NULL,                  -- 强制填写变更原因（业务流程要求）
    ip_address      INET,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
    -- 无 deleted_at，无 UPDATE，append-only
);

CREATE INDEX idx_ff_log_flag    ON public.feature_flag_change_log(flag_key, created_at DESC);
CREATE INDEX idx_ff_log_tenant  ON public.feature_flag_change_log(tenant_id, created_at DESC)
    WHERE tenant_id IS NOT NULL;
CREATE INDEX idx_ff_log_operator ON public.feature_flag_change_log(operator_id, created_at DESC);
```

---

## 三、关键约束与禁止操作

| 规则 | 说明 |
|------|------|
| `tenant_status_logs` append-only | 禁止 UPDATE / DELETE；状态机变更只追加新行 |
| `platform_audit_logs` append-only | 禁止 UPDATE / DELETE；建议按月 RANGE 分区 |
| `public.tenants.schema_name` 不可修改 | 创建后禁止 UPDATE，PG schema 绑定 |
| `public.domains.domain` 不可修改 | 子域名创建后禁止 UPDATE |
| `system_versions` 唯一 current | `idx_system_versions_current` 部分唯一索引保证全局只有一个 `status='current'` |
| `backup_schedules.tenant_id` UNIQUE | 每个租户最多一条独立计划；`NULL` 全局计划由应用层保证唯一 |
| `platform_admins` 与 `staff` 完全独立 | 不共享表、不共享 auth 系统 |
| MFA 强制 | `platform_admins.mfa_enabled` 在首次 TOTP 确认后才变 TRUE；登录流必须检查 |
| `admin_sessions` 30 分钟滚动超时 | 应用层每次活跃请求更新 `expires_at = NOW() + 30min` |
| `client_releases` 唯一 published | `idx_client_releases_published` 部分唯一索引保证同平台+架构下只有一条 `status='published'` |
| `client_releases` 不可跨租户隔离 | 本表属于 public schema，所有租户共享；禁止在租户 schema 中创建副本 |
| `client_releases.download_count` 原子递增 | 必须使用 `UPDATE ... SET download_count = download_count + 1`，禁止先读后写 |
| `upgrade_events.gray_tenant_ids` 与 `upgrade_type` 一致性 | A_app 类型必须为空数组（CHECK 约束 `chk_app_upgrade_no_gray` 强制）；只有 B_schema 类型才使用灰度名单与批次字段 |
| `upgrade_events` 状态流转单向 | 状态机详见 §4.2；`succeeded` / `rolled_back` / `failed` 为终态，禁止再写回中间态 |
| `feature_flag_change_log` append-only | 禁止 UPDATE / DELETE；任何 Flag 变更都必须经此表追溯，含 `reason` 强制非空 |
| `feature_flag_definitions.key` 不可修改 | 创建后禁止 UPDATE 主键；废弃 Flag 走 `archived_at` 软归档 |
| `tenants.feature_flags` 写入路径强约束 | 仅允许 `apps.admin_console.services.feature_flags` 写入；业务代码只读，且必须经 `is_enabled()` 服务接口（不得直读 JSONB） |

---

## 四、状态机

### 4.1 租户生命周期

```
creating ──(初始化完成)──► active
active   ──(逾期/违规/申请)──► suspended ──(恢复条件满足)──► active
active   ──(申请注销)──► pending_delete ──(30天后/管理员确认)──► deleted
suspended ──(申请注销)──► pending_delete
creating ──(初始化失败)──► failed
```

**字段映射**：
- `status` 枚举：`creating | active | suspended | pending_delete | deleted | failed`
- `suspended_until = NULL`：永久挂起；`suspended_until IS NOT NULL`：Celery Beat 定时自动恢复
- `deleted_at`：软删除时间戳；硬删除时物理删除整行

### 4.2 升级事件状态

```
draft ──提交──► pre_check ──健康检查通过──► pre_backup ──全局备份完成──► batch_running
                                                                            │
                                            ┌───── 当前批全部租户成功 ───────┘
                                            ▼
                                       batch_done
                                            │
                            是否还有下一批 ◄┤
                                ↓ 否       │ 是
                            succeeded   下一批 → batch_running
                                            │
                                            │ 任一批失败 / 健康门控不通过
                                            ▼
                                         halted
                                            │
                              超管选择 ◄────┤
                                ↓ 回滚      │ 继续下一批
                       rollback_running     batch_running
                                ↓
                         rolled_back
```

**字段映射**（详见技术文档 §8.6）：
- `upgrade_type ∈ {A_app, B_schema, C_feature}`：A_app 类型不参与本状态机（蓝绿全量切换由运维侧执行），仅记录元数据
- `current_batch_no` / `total_batch_count`：批次进度，UI §4.6 据此渲染进度表
- `halted_reason`：halted 状态时记录失败指标快照（健康门控不通过原因）
- `tenant_progress[].status ∈ {pending, running, success, failed, rolled_back}`：单租户细粒度状态
- 终态 `succeeded` / `rolled_back` / `failed` 一旦写入禁止再变更（应用层 + 审计日志双重保证）

### 4.3 Feature Flag 变更流程

```
[admin 创建 Flag definition] ──► reason=必填 ──► 写 feature_flag_change_log(scope=definition_create)
       │
       ├─► 调整 rollout_strategy / percentage ──► scope=definition_update
       │
       ├─► 租户级覆盖开/关 ──► scope=tenant_override_set / tenant_override_clear
       │                       同时 UPDATE tenants.feature_flags
       │
       └─► 归档 ──► archived_at = NOW(), scope=definition_archive
                  归档后 is_enabled() 永久返回 FALSE，但记录保留
```

**强制约束**：所有变更必须由 `apps.admin_console` 服务层写入；任何写操作都必须同时落 `feature_flag_change_log`（含 `reason`）+ `platform_audit_logs`（双重审计）。

---

## 五、查询模式

### 5.1 常用查询

```sql
-- 查询所有活跃租户
SELECT id, name, plan, paid_until
FROM public.tenants
WHERE status = 'active'
ORDER BY created_at DESC;

-- 查询即将到期的租户（7 天内）
SELECT id, name, contact_email, paid_until
FROM public.tenants
WHERE status = 'active'
  AND paid_until BETWEEN CURRENT_DATE AND CURRENT_DATE + 7;

-- 查询灰度租户（canary 升级目标）
SELECT id, schema_name, name
FROM public.tenants
WHERE is_canary = TRUE AND status = 'active';

-- 查询某租户所有状态变更历史
SELECT from_status, to_status, reason, operator_name, created_at
FROM public.tenant_status_logs
WHERE tenant_id = $1
ORDER BY created_at DESC;

-- 查询待自动恢复的挂起租户（Celery Beat 使用）
SELECT id, schema_name, name
FROM public.tenants
WHERE status = 'suspended'
  AND suspended_until IS NOT NULL
  AND suspended_until <= NOW();

-- 查询某管理员近 30 天的审计记录
SELECT action_type, target_type, target_name, result, created_at
FROM public.platform_audit_logs
WHERE operator_id = $1
  AND created_at >= NOW() - INTERVAL '30 days'
ORDER BY created_at DESC;

-- 查询进行中的备份任务
SELECT br.id, t.name AS tenant_name, br.trigger_type, br.started_at
FROM public.backup_records br
JOIN public.tenants t ON t.id = br.tenant_id
WHERE br.status IN ('pending', 'in_progress')
ORDER BY br.created_at DESC;

-- 客户端更新检测：查询当前生效版本（platform=win32, arch=x64）
SELECT version, release_type, download_url, portable_url,
       checksum_sha256, file_size_bytes, release_notes, published_at
FROM public.client_releases
WHERE platform = 'win32'
  AND arch = 'x64'
  AND status = 'published'
LIMIT 1;

-- 客户端版本管理列表（管理后台，含各状态版本）
SELECT version, platform, arch, release_type, status,
       download_count, published_at, created_at
FROM public.client_releases
ORDER BY created_at DESC;

-- 统计各版本活跃客户端数（需结合客户端上报心跳表，当前仅记录下载量）
SELECT version, download_count
FROM public.client_releases
WHERE status IN ('published', 'archived')
ORDER BY published_at DESC;

-- ============================================================
-- 升级编排相关查询（B 类 Schema 迁移分批升级）
-- ============================================================

-- 查询当前处于 halted 状态、需要超管处理的升级事件（实时告警查询）
SELECT id, to_version_id, current_batch_no, total_batch_count,
       halted_reason, started_at, initiated_by
FROM public.upgrade_events
WHERE status = 'halted'
ORDER BY created_at DESC;

-- 查询某租户的升级历史（含每次升级的最终状态）
SELECT ue.id, ue.to_version_id, ue.upgrade_type, ue.status,
       progress->>'status' AS tenant_status,
       progress->>'completed_at' AS tenant_completed_at,
       progress->>'error' AS tenant_error
FROM public.upgrade_events ue,
     jsonb_array_elements(ue.tenant_progress) AS progress
WHERE progress->>'tenant_id' = $1::text
ORDER BY ue.created_at DESC;

-- 查询某次升级事件中失败的租户列表（用于人工排查）
SELECT progress->>'tenant_id' AS tenant_id,
       progress->>'tenant_name' AS tenant_name,
       progress->>'error' AS error,
       progress->>'snapshot_id' AS snapshot_id
FROM public.upgrade_events ue,
     jsonb_array_elements(ue.tenant_progress) AS progress
WHERE ue.id = $1
  AND progress->>'status' = 'failed';

-- ============================================================
-- Feature Flag 相关查询（C 类运行时灰度）
-- ============================================================

-- 查询所有未归档的 Flag 定义（管理后台列表）
SELECT key, description, default_value, rollout_strategy, rollout_config,
       owner_admin_id, created_at
FROM public.feature_flag_definitions
WHERE archived_at IS NULL
ORDER BY created_at DESC;

-- 查询某 Flag 当前已显式开启的租户列表（GIN 索引加速）
SELECT id, name, schema_name, feature_flags->$1 AS flag_value
FROM public.tenants
WHERE feature_flags ? $1
  AND status = 'active';

-- 查询某 Flag 近 90 天的所有变更（审计回溯）
SELECT change_scope, tenant_id, old_value, new_value,
       operator_name, reason, created_at
FROM public.feature_flag_change_log
WHERE flag_key = $1
  AND created_at >= NOW() - INTERVAL '90 days'
ORDER BY created_at DESC;

-- 查询某管理员近 30 天的 Flag 变更操作（个人操作审计）
SELECT flag_key, change_scope, tenant_id, reason, created_at
FROM public.feature_flag_change_log
WHERE operator_id = $1
  AND created_at >= NOW() - INTERVAL '30 days'
ORDER BY created_at DESC;
```

### 5.2 禁止查询

| 禁止操作 | 原因 |
|----------|------|
| `UPDATE public.tenant_status_logs` | append-only 审计表 |
| `DELETE FROM public.platform_audit_logs` | append-only 审计表 |
| `UPDATE public.tenants SET schema_name = ...` | schema 名绑定 PG 物理 schema |
| `UPDATE public.domains SET domain = ...` | 域名路由不可变 |
| `UPDATE public.client_releases SET version = ...` | 版本号创建后不可修改，变更须新建记录 |
| 在租户 schema 中创建 `client_releases` 副本 | 本表属于 public schema，多租户共享，禁止下沉到租户层 |
| `UPDATE public.feature_flag_change_log` / `DELETE FROM ...` | append-only 审计表 |
| `UPDATE public.feature_flag_definitions SET key = ...` | Flag key 是主键且为业务标识，禁止修改；废弃用 `archived_at` |
| 在租户 schema 内重复定义 `feature_flag_definitions` | Flag 体系是平台级控制平面，必须存于 public schema |
| 业务代码直接读 `tenants.feature_flags` JSONB | 必须经 `apps.admin_console.services.feature_flags.is_enabled()` 服务接口，绕过策略层会导致灰度策略失效 |
| `UPDATE public.upgrade_events` 修改终态行 | `succeeded` / `rolled_back` / `failed` 状态的事件禁止再次修改，应用层 ORM Manager 强制保护 |

---

## 六、版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v1.0 | 2026-04-24 | 从 `DATA_MODEL.md §三` 独立拆分；内容等价于 v1.2 DATA_MODEL.md §三 |
| v1.1 | 2026-04-24 | 新增 §2.6 `client_releases` 表（客户端发布管理）；同步更新表清单、约束规则、查询模式 |
| v1.2 | 2026-04-26 | 配合系统管理技术文档 v1.2 升级分批专节：§2.5 `upgrade_events` 增加 `upgrade_type`、`gray_tenant_ids`、`batch_size`、`batch_concurrency`、`batch_interval_seconds`、`failure_policy`、`current_batch_no`、`total_batch_count`、`health_gate_config`、`pre_backup_record_id`、`halted_reason` 字段，状态机扩展为 10 态；新增 §2.7 Feature Flag 体系（`feature_flag_definitions` / `tenants.feature_flags` JSONB / `feature_flag_change_log`）；同步更新表清单、§4.2 升级状态机、§4.3 Flag 流程、§5.1 查询模式、§5.2 禁止操作 |