schema-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

流程

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

对比模型差异：将旧字段（来自已归档的
```
openspec/specs/<domain>/spec.md
```
，若有codebase-memory则对照实际代码）与新字段（来自
```
changes/<change-name>/specs/
```
中的delta spec）进行对比，明确列出：新增哪些字段、删除哪些字段、哪些字段更改了类型。
确定当前使用的存储类型：是本地数据库（Hive/SQFLite/Drift）还是仅调用API/Firebase不进行本地存储。
- 若仅使用API/Firebase且不进行本地缓存 → 通常只需更新模型+解析JSON，风险较低，但仍需通过MCP测试。
- 若使用本地数据库 → 必须编写迁移脚本（不能直接修改模型导致应用下次启动崩溃）。
生成对应的迁移脚本：
- SQFLite/Drift：编写
```
ALTER TABLE
```
  语句，或升级版本并实现
```
onUpgrade
```
  逻辑。
- Hive：创建新版本的
```
TypeAdapter
```
  ，编写读取旧数据并映射到新字段的逻辑（新增字段需设置默认值）。
在模拟器/开发环境通过MCP测试迁移，之后才能允许
```
flutter-coding
```
正式修改代码使用新模型。若已有测试种子数据，需测试通过迁移加载旧数据，确保数据不会丢失或出错。
若迁移失败：回滚（使用最近的git checkpoint，参考
```
git-checkpoint/SKILL.md
```
），修改脚本，不要强行覆盖已有错误的代码。
迁移通过后 → 再进入
```
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.

若项目刚初始化，还没有实际数据（首次定义模型），则无需编写迁移脚本，只需从一开始就正确定义模型，跳过此步骤。