---
name: schema-compatibility
when: '数据库变更, 字段修改, 表结构变更, 数据迁移, Schema变更, 加字段, 改字段, 删字段, DDL'
scope:
  - backend
products:
  - '*'
id: ka-pattern-schema-compatibility
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 数据库变更
  - 字段修改
  - 表结构变更
  - 数据迁移
  - Schema变更
  - 加字段
  - 改字段
  - 删字段
  - DDL
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 新增字段必须指定：默认值、可空性、存量数据回填策略
- 修改字段类型、长度、语义或枚举范围必须指定：存量数据读取行为和迁移策略
- 删除字段必须指定：兼容窗口、废弃标记、回滚计划，不得假设所有调用方已同步升级
- 字段兼容策略必须同时覆盖四层：数据库、接口契约、前端展示、导出逻辑
- 禁止在实现阶段临时决定兼容策略、删除语义或字段默认值
- 数据库 Schema 变更必须向前兼容（先加新字段 → 迁移 → 再删旧字段）
- 新增字段必须设默认值或允许 NULL，保证旧代码不受影响
- 列类型变更必须分步进行（先加新列 → 双写 → 迁移 → 删旧列）
- Schema 迁移脚本必须纳入版本控制，禁止手动执行 SQL
- 索引变更必须在低峰期执行，大表加索引必须使用 ONLINE DDL 或 pt-osc

## 验收项
- [AC-01] 新增字段有默认值和回填策略
- [AC-02] 字段变更覆盖数据库/接口/前端/导出四层
- [AC-03] 删除字段有兼容窗口和回滚计划
- [AC-04] 无临时决定的兼容策略
- [AC-05] Schema 变更向前兼容
- [AC-06] 新字段有默认值
- [AC-07] 迁移脚本纳入版本控制
