danyang-match/docs/database/MIGRATION_GUIDE.md

# 数据库迁移清单 — MIGRATION_GUIDE.md

> **最后更新：2026-09-18** —— 原文仅列 **V001~V011**，实测 **46** 个迁移（最新 **V046**），本轮按实测重写。
>
> ⚠️ **权威来源**：`backend/src/main/resources/db/migration/`。本文件为**索引**，不一致时以迁移文件为准。
> 生产由 Flyway 驱动；**已发布的迁移只向前修复，不修改**（Phase 22 Gate 明确要求）。
> 相邻文档：`TABLE_INVENTORY.md`（表清单）、`docs/善缘丹阳 V1.1 数据库与API增量设计.md`（V1.1 增量设计）。

## 迁移命名规范

```
V{三位版本号}__{描述}.sql
```

## 迁移清单（V001~V046，共 46 个）

| 版本 | 文件 | 建表 | 说明 |
|---|---|---|---|
| V001 | `V001__init_base_tables.sql` | 11 | 基础表：users / organizations / operators / roles / permissions / role_permissions / operator_roles / audit_logs / sensitive_access_logs / system_configs / interest_dictionary + 初始化数据 |
| V002 | `V002__add_user_and_verification_tables.sql` | 7 | 用户资料 / 偏好 / 兴趣 / 照片 / 隐私设置 / 实名认证 / 同意记录 |
| V003 | `V003__add_review_and_relation_tables.sql` | 6 | 审核任务 / 明细 / 原因字典 + 用户关系 / 匹配 / 成功牵手请求 |
| V004 | `V004__add_messaging_and_recommendation_tables.sql` | 5 | 会话 / 会话成员 / 消息 / 通知 / 推荐记录 |
| V005 | `V005__add_review_tables.sql` | — | 审核表补强（无建表） |
| V006 | `V006__add_match_tables.sql` | 1 | `match_rule_configs` + 初始化规则 |
| V007 | `V007__add_relationship_tables.sql` | — | 关系表补强（无建表） |
| V008 | `V008__add_messaging_tables.sql` | 3 | 消息类表补强（以 `IF NOT EXISTS` 形式，与 V004 同名表） |
| V009 | `V009__add_matchmaker_tables.sql` | 3 | 红娘服务 / 推荐 / 跟进 |
| V010 | `V010__add_activity_tables.sql` | 2 | 活动 / 活动报名 |
| V011 | `V011__add_activity_interests.sql` | 1 | 活动互选意向 |
| V012 | `V012__add_risk_and_report_tables.sql` | 3 | 举报 / 风险事件 / 风控处置 |
| V013 | `V013__add_appeals_table.sql` | 1 | 申诉 |
| V014 | `V014__add_consent_and_privacy_tables.sql` | — | 同意与隐私字段扩展 |
| V015 | `V015__add_v11_roles_and_permissions.sql` | — | **V1.1 角色与权限**（13 条 INSERT） |
| V016 | `V016__add_liveness_verification_fields.sql` | — | 活体核验字段 |
| V017 | `V017__add_local_eligibility_tables.sql` | 2 | 本地资格 / 佐证 |
| V018 | `V018__extend_review_for_local_eligibility.sql` | — | 审核扩展至本地资格 |
| V019 | `V019__add_home_banners_and_service_locations.sql` | 2 | 首页 Banner / 善缘服务站 |
| V020 | `V020__extend_notification_types.sql` | — | 通知类型扩展（对齐 `chk_notification_type` 短名白名单） |
| V021 | `V021__add_service_appointments_and_referral_fields.sql` | 1 | 服务预约 + 红娘转介字段 |
| V022 | `V022__add_counseling_services.sql` | 2 | 婚恋咨询 / 婚前辅导 + 随访 |
| V023 | `V023__extend_activities_v11.sql` | 2 | 活动 V1.1 扩展（名额分组 / 主办单位） |
| V024 | `V024__add_activity_mutual_connection_consents.sql` | 1 | **互选二阶段同意** |
| V025 | `V025__extend_risk_sources.sql` | — | 风险来源扩展 |
| V026 | `V026__add_content_and_program_tables.sql` | 5 | 内容分类 / 文章、服务项目 / 成员、组织关系 |
| V027 | `V027__seed_production_data.sql` | — | **生产基础数据种子**（3 条 INSERT） |
| V028 | `V028__add_service_location_operator_scope.sql` | 1 | 服务站人员数据范围 |
| V029 | `V029__complete_service_station_permissions.sql` | — | 服务站权限补全 |
| V030 | `V030__add_operator_soft_delete.sql` | — | 运营账号软删 |
| V031 | `V031__align_audit_log_base_fields.sql` | — | 审计日志基础字段对齐 |
| V032 | `V032__align_admin_soft_delete_columns.sql` | — | 管理端软删列对齐 |
| V033 | `V033__align_messaging_entity_base_fields.sql` | — | 消息实体基础字段对齐 |
| V034 | `V034__extend_sensitive_access_audit.sql` | — | 敏感访问审计扩展 |
| V035 | `V035__align_sensitive_access_base_fields.sql` | — | 敏感访问基础字段对齐 |
| V036 | `V036__add_notification_idempotency_index.sql` | — | 通知幂等 partial unique index |
| V037 | `V037__align_entity_columns_with_migrations.sql` | — | **实体↔迁移列对齐（23 处 ALTER）** |
| V038 | `V038__align_matchmaker_status_constraints.sql` | — | 红娘状态 CHECK 白名单扩展 |
| V039 | `V039__add_counseling_idempotency_and_status_guards.sql` | — | 咨询幂等键 + 三个 CHECK 白名单显式固化 |
| V040 | `V040__add_activity_staff_assignments.sql` | 1 | 活动工作人员分配 |
| V041 | `V041__extend_mutual_consent_expiry.sql` | — | 互选同意 `expires_at` + `match_id` |
| V042 | `V042__add_service_location_announcements.sql` | 1 | 服务站公告 |
| V043 | `V043__grant_analytics_view_to_data_roles.sql` | — | 授予 `data_viewer` / `platform_admin` 的 `analytics.view` |
| V044 | `V044__grant_all_permissions_to_super_admin.sql` | — | super_admin 全权限授予 |
| V045 | `V045__add_idempotency_records.sql` | 1 | **通用幂等表** + 唯一索引 `uk_idempotency_scope` |
| V046 | `V046__fix_idempotency_actor_id_type.sql` | — | 修正幂等表 `actor_id` 类型（VARCHAR → uuid） |

---

## 注意事项

1. 所有迁移文件必须幂等（`CREATE TABLE IF NOT EXISTS` / `ADD COLUMN IF NOT EXISTS` 等）。
2. 敏感字段存储加密值。
3. 命名规范：索引 `idx_{table}_{columns}`；唯一约束 `uk_{table}_{columns}`；外键 `fk_{table}_{column}`。
4. **已发布的迁移不得修改** —— 修正一律追加新版本（如 V046 修正 V045 的列类型）。Phase 22 Gate 明确「Flyway 只向前修复，不破坏 V001~V027」。
5. **文档与实际不一致时以迁移文件为准**：本文件曾长期停留在 V001~V011（实际 46 个）；`TABLE_INVENTORY.md` 曾列 40 表（实际 59 张）。两处已于 2026-09-18 按实测重写。

---

*最后更新: 2026-09-18 — 由 V001~V011 重写为实测 V001~V046（46 个）*