Incomex AI Portal
KB-9897 rev 3

Balo thực thể — handoff vận hành canonical sau LỆNH 2C

7 min read Revision 3
pg-read-pgbalohandoffcanonicalreconciledot-balo-reconcile2026-07-16

Balo thực thể — biên bản chốt thiết kế (handoff)

Mục đích: chốt thiết kế "đeo balo" để phiên mới bắt đầu chuẩn hoá ngay, không phải đọc lại phiên dài cũ. Vẫn trong khuôn khổ PG read PG.

Cập nhật canonical — vận hành sau LỆNH 2C (2026-07-16)

Phần này có quyền ưu tiên nếu các ghi chú thiết kế lịch sử phía dưới còn cách diễn đạt khác.

  • balo-core-first-run.sql chỉ dùng đúc lần đầu; không chạy lại first-run để bổ sung object.
  • Cơ chế duy trì canonical: /opt/incomex/dot/bin/dot-balo-reconcile.
  • Ba lệnh chính xác:
dot-balo-reconcile --dry-run
dot-balo-reconcile --apply
dot-balo-reconcile --verify
  • Scope hiện hành: table | view | function | trigger; chưa gồm column và 7 loại Census còn lại.
  • KEEP giữ nguyên STT, không UPDATE và không đổi date_updated.
  • ADD mới do sequence cấp STT; reconcile không insert STT, loai_census, da_mat hay audit fields.
  • Object mất chỉ da_mat=true, không DELETE; object trở lại cùng khóa giữ nguyên STT.
  • Rename/chuyển schema: khóa mới ADD, khóa cũ MARK_MISSING; không tự ghép hai khóa.
  • Các trường phải-gật không được reconcile tự động.
  • UI Làm mới chỉ đọc; vẫn không có cron hoặc máy chạy ngầm.
  • Từ 2026-07-17: thêm nút "Đồng bộ Balo từ PG" — Administrator-only WRITE, on-demand, một lần bấm chạy --sync (dry-run → apply atomic nếu có chênh lệch an toàn → verify) qua fixed-purpose Unix-socket bridge. Không cron. Không phải "Làm mới". Đường ghi vẫn là dot-pg-atomic-apply; Directus/Nuxt không WRITE PG trực tiếp. Quy định đầy đủ: §16 của balo-thuc-the-quy-dinh.md (§16 thay thế một phần §15 v1.9 vốn cấm nút UI đồng bộ).
  • Vận hành/deploy cho nút (thiếu một là hỏng): compose service nuxt cần volumes: /run/incomex:/run/incomex:ro + group_add: ["987"] (GID live của incomex-balo-sync — preflight getent group bắt buộc) + cả hai biến NUXT_BALO_OPERATOR_ROLE_IDS và NUXT_PUBLIC_BALO_OPERATOR_ROLE_IDS; Nginx cần location = /api/balo/reconcile → nuxt_backend. Deploy chỉ docker compose up -d nuxt — cấm docker compose up -d trần (recreate agent-data, mất 10 env, hạ mem 2560→1536 MiB).
  • Commit triển khai: 65a2d732dd31459ce9d9312fce5b36c9ac9627a3; commit bảo tồn manifest: bddfdcc5a504ff6f4c1bc4fdf075dc8dde209402.

Quy tắc kết thúc mission

Sau mission đã tạo, xóa, đổi tên hoặc chuyển schema một object thuộc bốn loại trên, chạy dot-balo-reconcile --dry-run.

Chỉ apply trong cùng mission nếu mission đã được phép WRITE PG, delta chỉ gồm ADD đúng object vừa tạo, CONFLICT=0, sequence_safe=true, không REVIVE/MARK_MISSING và không có METADATA_UPDATE ngoài phạm vi. Sau apply chạy --verify rồi --dry-run; delta phải bằng 0.

HOLD chờ Owner nếu có ADD ngoài mission, MARK_MISSING, REVIVE, METADATA_UPDATE không giải thích, CONFLICT, sequence không an toàn hoặc schema contract lệch. Không tự sửa nhãn, không setval, không dùng đường WRITE khác.

Mission chỉ sửa dữ liệu nghiệp vụ, UI, tài liệu, kiểm tra read-only hoặc object ngoài bốn loại hiện hành không bắt buộc reconcile.

Bối cảnh đã xong (nền)

  • Reports MVP chạy thật trên production: /reports + /reports/report-pg (census 12 loại, số live). Khuôn = DOT-B dot-report-publish + SharedDirectusTable + table_registry. Deploy volume-based, rollback = restore volume.
  • Đã đăng ký cụm Reports vào cơ chế bảo vệ Đ30/31 có sẵn (PARTIAL: phần Nuxt được phủ; DOT-B nằm ở dot repo ngoài tầm — ghi nợ).
  • report-workflow + report-dot: ĐÃ thiết kế prompt, CHƯA chạy (gác lại để làm balo tổng quát trước).

Định nghĩa "thực thể" và "balo"

  • Thực thể = mọi object PG đếm được (census 12 loại: schema/table/view/matview/sequence/function/procedure/trigger/constraint/index/foreign_table/column).
  • Balo = bộ ~12 trường nhãn gắn với mỗi thực thể (hồ sơ cơ bản chuẩn hoá).

5 mấu việc đeo balo (theo thứ tự)

  1. Định danh STT: dùng MOT sequence native PG cap so toan he — bat bien, khong trung (ke ca song song/rollback), sinh-truoc-so-truoc, mu ve loai/cho. Day la Nhom A thuc su. ID nay la "so can cuoc balo".
  2. Dinh nghia balo = ~12 truong nhan. Tu dong cap O TRONG cho moi thuc the (native PG, INSERT...SELECT tu catalog, vai giay). KHONG tu dong DIEN (tu dien = de rac kieu cot classification cu).
  3. Uu tien dan cho thu dung-nhieu/de-nham truoc, KHONG dan het. "Bat buoc" = bat buoc CO O, khong phai dien het ngay. O trong van hop le, loi ra lam thuoc do tien do.
  4. Ghi chú lịch sử: thiết kế đầu từng dự kiến 5 loại gồm column; quyết định triển khai canonical hiện hành chỉ gồm 4 loại table | view | function | trigger. column và các loại khác để phase riêng.

Chieu "loai" — QUYET DINH CHONG PHINH (quan trong)

  • Loai hien it (~6-8: DOT, trigger-fn, checker, reader, helper, system...). CHUA can tang cha "chi"/"ho".
  • KHONG dung 3 bang phan tang (loai/chi/ho) + bang quan he cha-con — do la mega-graph, dung cai registries-pivot may thang khong xong + 41 bang di san hon don.
  • Thay bang: 1 bang tu dien loai, moi loai co 1 cot "nhom cha" (tuy chon, de trong duoc). Gom len chi/ho = GROUP BY cot cha. Phan tang la CACH NHIN (group), khong nhat thiet la CAU TRUC bang. Tach tang chi khi loai dong that.

"Bang con de nhat quan" — lam ro

  • NEN: bang tu dien gia tri hop le cho moi nhan can kiem soat (vd bang "cac loai hop le") — de cot nhan chi nhan gia tri trong danh sach, chong rac tai dien. Nho, don gian.
  • CHUA CAN: mang quan he cha-con phan tang.

Ma dinh danh: dung SEQUENCE, khong dung oid/ten

  • oid doi khi tao lai; ten doi khi rename -> deu rot balo.
  • Sequence = số căn cước Balo, bất biến. Theo contract triển khai hiện hành, rename/chuyển schema tạo khóa mới ADD và khóa cũ MARK_MISSING; mission này không cố suy đoán ghép hai khóa.
  • Xóa/mất object → bắt buộc MARK_MISSING (da_mat=true) thay vì xóa hồ sơ; STT và nhãn cũ được bảo toàn.

Phan biet trong/ngoai "di san hon don" (Nhom A, khach quan)

  • Tieu chi da kiem bang PG: "la collection Directus?" -> chi workflows + dot_tools la collection that; 41 bang/view wf_/v_workflow_/v_universal_* KHONG phai collection = vung nghi may-moc-ngam.
  • Dung tieu chi nay de CHON cai doc cho report (an toan). KHONG dung de ket luan "rac chet" — song/chet phai dieu tra rieng. NO: dieu tra + don di san la du an rieng, sau.

Nguyen tac giu xuyen suot

  • Tu cap o trong OK; tu dien noi dung CAM.
  • Khong dan het moi dung; nhom "(chua dan)" la thuoc do.
  • "Dap da to": nhieu lat cat nho, moi lat mot tinh chat, dan cai chac de trong cai mo ho, agent doc tay la buoc cuoi.
  • Lat "chac" (da trong dot_tools / native-C / trigger-fn) dan thang; lat "doan" (ten giong, hanh vi) chi ra UNG VIEN, nguoi gat.
  • Assemble First, DOT 100% cho moi WRITE, khong mega-registry/graph/pipeline, moi phan boundary ro.