Quy trình khai schema v0 — QT-S1 tạo mới / QT-S2 sửa nâng cấp (NHÁP TẠM)
QUY TRÌNH KHAI SCHEMA — v0 (TẠM, chờ Owner rà)
Ghi ngày 2026-07-30. Trạng thái: NHÁP TẠM — chưa ban hành, chưa thành luật. Bản gốc song song:
/opt/incomex/docs/mcp-writes/quy-trinh-khai-schema-v0.md(có git auto-snapshot 5 phút). Mục đích: chốt CÁCH LÀM cho việc khai báo bảng/cột/quan hệ trong PG. Hai quy trình: QT-S1 tạo mới, QT-S2 sửa/nâng cấp.
0. Ranh giới — quản gì, KHÔNG quản gì
| Quản | KHÔNG quản |
|---|---|
CÁI HỘP: bảng, cột, kiểu, khoá ngoại, ràng buộc, chỉ mục, COMMENT |
CÁI TRONG HỘP: dữ liệu, bản ghi, danh mục (300 nhân viên, cây 7 tầng…) |
pgschema dựng được bảng người, nhưng không đổ được người vào đó. Đổ dữ liệu = đường khác (Directus / DOT ghi dữ liệu).
1. Ai giữ sự thật nào (1 SSOT)
SSOT của Ý ĐỊNH = file SQL trong git ở xưởng vẽ
SSOT của HIỆN TRẠNG = chính PG (pg_catalog) — không ai chép lại, không cần chép
LỆCH giữa hai cái = MỘT VIỆC PHẢI XỬ, không phải trạng thái để sống chung
CSV + ma trận trên xưởng vẽ = nơi Owner RÀ, chỉ đọc. Owner khai bằng cách nói; agent ghi vào file SQL; ma trận chiếu lại để Owner soi.
2. Phân vai
| Ai | Làm | KHÔNG được làm |
|---|---|---|
| Owner | Chốt 5 điều cho từng bảng (§3) · duyệt 2 lần (§4) | Không phải đọc DDL, không phải hiểu PG |
| Agent | Viết file SQL theo khuôn + phiếu · git commit | KHÔNG giữ mật khẩu DB. Không chạy apply |
| pgschema | Tính chênh lệch · chạy thử · áp an toàn | Không tự quyết. Không viết sổ |
| PG | Canh khoá ngoại, CHECK, UNIQUE, GENERATED, DOMAIN | — |
| DOT | Cổng duy nhất có mật khẩu ghi | Không có DOT xoá |
3. NĂM ĐIỀU OWNER PHẢI CHỐT CHO MỖI BẢNG
| # | Câu hỏi | Vì sao gốc rễ |
|---|---|---|
| 1 | Đây là DANH TỪ MỚI, hay GIÁ TRỊ của danh từ đã có? | Nếu là giá trị → thêm một DÒNG, không thêm bảng |
| 2 | Bảng này là con của ai? (quan hệ phụ thuộc) | Sai chỗ này thì mọi truy vấn sau sai, không lệnh nào báo lỗi |
| 3 | MỘT DÒNG là một cái gì? | Lẫn "một lần trả tiền" với "một đợt phải thu" → tổng tiền sai âm thầm |
| 4 | HAI DÒNG thế nào thì coi là TRÙNG? | PG dùng để chặn cứng (UNIQUE). Bỏ → dữ liệu nhân đôi, sai âm thầm |
| 5 | Ngoài bộ khuôn, còn cột riêng nào? (số + tên) | Phần còn lại khuôn lo |
Câu 3 và 4 bắt buộc ghi thành COMMENT ON TABLE. Thiếu → dot-schema-plan chặn. Máy kiểm được.
BỘ KHUÔN — chốt MỘT LẦN (điều kiện trước QT-S1)
a) ~8 cột chuẩn mọi bảng đều có → CREATE TABLE (LIKE ... INCLUDING ALL)
b) Quy ước tên khoá ngoại → cột <thuc_the>_id ⇒ tự là khoá ngoại
c) Ba loại cột: người-nghĩ / chọn-từ-danh-sách (DOMAIN) / SUY-RA-CẤM-GÕ (GENERATED ALWAYS)
Luật: khuôn chạy thử trên 3 bảng thật rồi Owner mới đóng dấu cho bảng thứ tư. Khuôn sai thì 300 bảng cùng sai một kiểu.
4. DUYỆT — hai lần, cùng một tờ giấy
Owner không duyệt danh sách DDL (đó là việc máy tự rà). Owner duyệt cái gốc, hai lần, trên cùng một bảng năm dòng:
ANH CHỐT AGENT ĐÃ VIẾT
1 Danh từ mới? ✓ (hiện ở lần 2)
2 Con của ai don_hang don_hang_id → don_hang
3 Một dòng là gì một lần trả tiền "một lần trả tiền"
4 Trùng khi nào hoá đơn + ngày UNIQUE(ma_hoa_don, ngay)
5 Cột riêng 4 cột: a,b,c,d 4 cột: a,b,c,d ✓ KHỚP
- DUYỆT 1 — trước khi agent viết cột. Bắt lỗi Owner chốt sai. Rẻ nhất vì chưa ai làm gì.
- DUYỆT 2 — sau khi agent viết, hai cột cạnh nhau. Bắt lỗi agent làm khác cái đã chốt.
Phiếu sống TRONG file SQL dưới dạng COMMENT ON. Không tạo file phiếu riêng — hai file là hai nguồn sự thật và sẽ lệch.
5. BA DOT (không DOT thứ tư, không DOT xoá)
| DOT | Quyền | Làm gì |
|---|---|---|
dot-schema-plan |
chỉ đọc | (a) đối chiếu COMMENT ↔ DDL trong file · (b) so file ↔ PG, in danh sách việc · (c) DỪNG nếu thấy DROP/RENAME · (d) chặn nếu thiếu COMMENT câu 3/4 |
dot-schema-apply |
ghi (mật khẩu chỉ ở đây) | Kiểm phiếu duyệt Điều 32 → pgschema apply → ghi khai sinh Đ0-G + nhật ký + phát sự kiện |
dot-schema-mirror |
chỉ đọc | pgschema dump ra file RIÊNG (hien-trang.sql) rồi so với sổ → bắt người sửa tay. KHÔNG ghi vào sổ |
Hai lệnh pgschema dễ lẫn:
dump= chụp ảnh ngôi nhà. Dùng đúng một lần lúc gieo sổ; sau đó chỉ soi gương.plan= thợ báo trước sẽ làm gì. Dùng mỗi lần sửa sổ.
Ảnh chụp không bao giờ được ghi lên bản vẽ. Nếu mirror ghi vào sổ thì PG lại thành SSOT → cả hệ chết (đúng vòng lặp đã giết Excel 55 khái niệm / PG 14).
QT-S1 — TẠO MỚI LẦN ĐẦU
Bắt đầu: có nhóm nghiệp vụ cần bảng mà chưa bảng nào phụ trách.
| # | Bước | Ai |
|---|---|---|
| 0 | Chốt bộ khuôn + thử 3 bảng + Owner đóng dấu | Owner + agent |
| 1 | Liệt kê DANH TỪ + vẽ QUAN HỆ | Owner |
| 2 | Trả lời câu 3·4·5 cho từng bảng | Owner |
| 3 | Agent viết lượt 1: tên bảng + quan hệ + COMMENT (chưa cột riêng) | Agent |
| 4 | DUYỆT 1 — GỐC (ma trận 5 dòng) | Owner |
| 5 | Agent viết lượt 2: điền cột riêng theo khuôn | Agent |
| 6 | dot-schema-plan — đối chiếu + in việc + chặn |
máy |
| 7 | DUYỆT 2 — ĐỐI CHIẾU (hai cột) → phiếu Điều 32 | Owner |
| 8 | dot-schema-apply |
DOT |
| 9 | dot-schema-mirror — phải 0 lệch |
máy |
Kết thúc: PG khớp sổ · phiếu và DDL cùng file cùng commit · mirror 0 lệch · bảng có khai sinh.
Còn thiếu: chưa chốt bộ khuôn · chưa cài pgschema · chưa có trang ma trận trên xưởng vẽ · chưa có lịch chạy mirror.
QT-S2 — SỬA / NÂNG CẤP
Bắt đầu: (a) đề xuất từ vận hành · (b) mirror báo lệch (có người sửa tay) · (c) Owner nhìn lại thấy mình chốt sai.
| # | Bước | Ai |
|---|---|---|
| 1 | Ghi đề xuất: bảng nào · vì sao · muốn đạt gì | ai nêu |
| 2 | Phân mức nguy hiểm: THÊM / ĐỔI / XOÁ-ĐỔI TÊN | agent |
| 3 | Sửa PHIẾU trước, KHÔNG sửa DDL trước | Owner |
| 4 | DUYỆT 1 — GỐC: phiếu cũ ↔ phiếu mới, chỉ phần đổi | Owner |
| 5 | Agent sửa DDL cho khớp phiếu | Agent |
| 6 | dot-schema-plan |
máy |
| 7 | DUYỆT 2 — ĐỐI CHIẾU → phiếu Điều 32 | Owner |
| 8 | dot-schema-apply theo mức nguy hiểm |
DOT |
| 9 | dot-schema-mirror — phải 0 lệch |
máy |
Vì sao sửa PHIẾU trước: sửa DDL trước rồi mới cập nhật phiếu → phiếu thành tài liệu chạy sau → sớm muộn không ai cập nhật. Đó chính xác là cách Excel 55 khái niệm chết mà không ai biết.
Ba mức nguy hiểm ở bước 8
| Mức | Việc | Cơ chế |
|---|---|---|
| THÊM | thêm bảng · cột nullable · chỉ mục | tự động sau DUYỆT 2 |
| ĐỔI | đổi kiểu · mặc định · thêm ràng buộc · NOT NULL | chạy thử trước, báo "bao nhiêu dòng sẽ vỡ", Owner xem số đó rồi duyệt |
| XOÁ / ĐỔI TÊN | xoá bảng · xoá cột · đổi tên | KHÔNG có DOT nào làm được. Người chạy tay, có mặt, có lý do. Không ngoại lệ |
Xoá là mất dữ liệu; đổi tên là làm vỡ mã đang chạy. Cố ý không có cửa tự động — cưỡng chế luật bằng cấu trúc, không bằng lời nhắc.
6. Hai chỗ máy KHÔNG canh được — phải là thủ tục
- "Một dòng là một cái gì" — agent sẽ đoán, và đoán rất trôi chảy.
- "Cái gì không được trùng" — bỏ trống thì không lệnh nào báo lỗi.
Cả hai sai theo kiểu âm thầm. Nên bắt buộc ghi thành COMMENT, dot-schema-plan chặn nếu thiếu. Máy không trả lời hộ, nhưng máy kiểm được là đã trả lời hay chưa.
7. Rủi ro sống còn
Có người sửa tay PG. Công cụ nào cũng chết vì cái đó. dot-schema-mirror chạy định kỳ là điều kiện sống, không phải phần thưởng.
8. Còn phải chốt (chưa quyết trong v0)
- Bộ khuôn cụ thể: 8 cột chuẩn là gì · danh sách DOMAIN · quy ước tên khoá ngoại đầy đủ.
- Ai được duyệt ngoài Owner (uỷ quyền lúc Owner vắng).
- Lịch chạy mirror: mỗi giờ / mỗi ngày.
- Phạm vi sổ: cột HIỆN CÓ lấy hết bảng thật; cột MONG MUỐN chỉ nhóm đang thiết kế.
- Kiểm chứng pgschema trên bản sao trước khi tin (công cụ mới, 2025).