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ỏ.

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.