Back to Details

schema-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Schema Migration

Schema Migration

Khi nào trigger

触发时机

project-orchestrator
phát hiện Data Model trong delta spec (
openspec/changes/<change-name>/specs/<domain>/spec.md
) khác với model đã archive (
openspec/specs/<domain>/spec.md
) hoặc khác với model thật trong code (thêm field, đổi tên, đổi kiểu, xóa field). Đây LUÔN LÀ bước bắt buộc trước khi 
flutter-coding
sửa model, không được bỏ qua kể cả khi thay đổi có vẻ nhỏ.
当
project-orchestrator
检测到delta spec（
openspec/changes/<change-name>/specs/<domain>/spec.md
）中的数据模型与已归档的模型（
openspec/specs/<domain>/spec.md
）或代码中的实际模型存在差异（新增字段、重名字段、更改类型、删除字段）时触发。这是
flutter-coding
修改模型前的必做步骤，即使是微小的变更也不能跳过。

Quy trình

流程

  1. Diff model: so sánh field cũ (trong 
    openspec/specs/<domain>/spec.md
    đã archive, đối chiếu code thật qua codebase-memory nếu có) với field mới (delta spec trong 
    changes/<change-name>/specs/
    ). Liệt kê rõ: field nào thêm, field nào xóa, field nào đổi kiểu.
  2. Xác định loại lưu trữ đang dùng: local DB (Hive/SQFLite/Drift) hay chỉ gọi API/Firebase không lưu local.
    • Nếu chỉ dùng API/Firebase không cache local → thường chỉ cần cập nhật model + parse JSON, rủi ro thấp hơn, vẫn nên test qua MCP.
    • Nếu có local DB → bắt buộc viết migration script (không sửa model rồi để app tự crash lần chạy sau).
  3. Sinh migration script tương ứng:
    • SQFLite/Drift: viết 
      ALTER TABLE
      hoặc bump 
      version
      + 
      onUpgrade
      .
    • Hive: tạo 
      TypeAdapter
      version mới, viết logic đọc dữ liệu cũ và map sang field mới (field mới thêm cần giá trị mặc định).
  4. Chạy thử migration qua MCP trên simulator/dev trước khi cho phép 
    flutter-coding
    sửa code chính thức dùng model mới. Nếu app dữ liệu mẫu (seed data) đang có sẵn, test load lại dữ liệu cũ qua migration để chắc không mất/lỗi data.
  5. Nếu migration fail: rollback (dùng git checkpoint gần nhất, xem 
    git-checkpoint/SKILL.md
    ), sửa lại script, không cố sửa đè lên code đã lỗi.
  6. Sau khi migration pass → mới chuyển sang 
    flutter-coding/SKILL.md
    để cập nhật phần code dùng model mới (UI, provider...).
  1. 对比模型差异：将旧字段（来自已归档的
    openspec/specs/<domain>/spec.md
    ，若有codebase-memory则对照实际代码）与新字段（来自
    changes/<change-name>/specs/
    中的delta spec）进行对比，明确列出：新增哪些字段、删除哪些字段、哪些字段更改了类型。
  2. 确定当前使用的存储类型：是本地数据库（Hive/SQFLite/Drift）还是仅调用API/Firebase不进行本地存储。
    • 若仅使用API/Firebase且不进行本地缓存 → 通常只需更新模型+解析JSON，风险较低，但仍需通过MCP测试。
    • 若使用本地数据库 → 必须编写迁移脚本（不能直接修改模型导致应用下次启动崩溃）。
  3. 生成对应的迁移脚本：
    • SQFLite/Drift：编写
      ALTER TABLE
      语句，或升级版本并实现
      onUpgrade
      逻辑。
    • Hive：创建新版本的
      TypeAdapter
      ，编写读取旧数据并映射到新字段的逻辑（新增字段需设置默认值）。
  4. 在模拟器/开发环境通过MCP测试迁移，之后才能允许
    flutter-coding
    正式修改代码使用新模型。若已有测试种子数据，需测试通过迁移加载旧数据，确保数据不会丢失或出错。
  5. 若迁移失败：回滚（使用最近的git checkpoint，参考
    git-checkpoint/SKILL.md
    ），修改脚本，不要强行覆盖已有错误的代码。
  6. 迁移通过后 → 再进入
    flutter-coding/SKILL.md
    更新使用新模型的代码部分（UI、provider等）。

Ví dụ cụ thể

具体示例

Ngày 7, delta spec trong 
changes/add-product-color/specs/product/spec.md
thêm field 
color
(String) vào model 
Product
(vốn chỉ có 
id
, 
name
trong 
openspec/specs/product/spec.md
đã archive).
  • Diff: thêm field 
    color
    , kiểu String, cần giá trị mặc định (ví dụ 
    ""
    hoặc 
    null
    cho phép).
  • Nếu dùng Hive: bump 
    Product
    TypeAdapter, field mới đánh dấu optional/default để đọc được record cũ không có field này.
  • Test: load lại 1 record cũ (không có 
    color
    ) qua adapter mới, xác nhận không crash, 
    color
    trả về giá trị mặc định.
  • Pass → mới cho 
    flutter-coding
    sinh UI hiển thị 
    color
    trong màn hình Product.
7日，
changes/add-product-color/specs/product/spec.md
中的delta spec为
Product
模型新增了
color
字段（String类型），而已归档的
openspec/specs/product/spec.md
中的
Product
模型仅包含
id
、
name
字段。
  • 差异：新增
    color
    字段，类型为String，需设置默认值（例如
    ""
    或允许为
    null
    ）。
  • 若使用Hive：升级
    Product
    的TypeAdapter，将新字段标记为可选/设置默认值，确保能读取无该字段的旧记录。
  • 测试：通过新适配器加载一条无
    color
    字段的旧记录，确认不会崩溃，
    color
    返回默认值。
  • 测试通过后 → 才能让
    flutter-coding
    生成在产品页面显示
    color
    的UI。

Không làm gì nếu đây là project mới hoàn toàn

全新项目无需操作

Nếu chưa có data thật (project mới init, model đầu tiên) thì không cần migration script, chỉ cần định nghĩa model đúng ngay từ đầu và bỏ qua bước này.
若项目刚初始化，还没有实际数据（首次定义模型），则无需编写迁移脚本，只需从一开始就正确定义模型，跳过此步骤。