Điều 26: LUẬT PIVOT — v4.0
ĐIỀU 26: LUẬT PIVOT — v4.0
v4.0 | S146 (2026-03-29) | ĐỔI TÊN: "Luật Registries & Đếm" → "LUẬT PIVOT" Lý do đổi tên: Mọi thứ đếm bằng pivot. pivot_count() là PHƯƠNG THỨC ĐẾM DUY NHẤT. Tên cũ không còn chính xác. v4.0 bổ sung: Tab Pivot 9 dòng. 5 Layers chi tiết. Ma trận đa chiều. Phân nhóm DOT + Collections. Thực nghiệm S146 (M3→M4c). AP-13 rút ra. Giữ nguyên: §I MT1-MT8, §II BT1-BT3, §III Quy trình, §IV-XII từ v3.5. Hội đồng: v3.4 (L1) + v3.5 (L2) đã thông qua. v4.0 = bổ sung thực nghiệm, KHÔNG thay đổi kiến trúc core.
§I. HỆ THỐNG 8 MỤC TIÊU (giữ nguyên v3.5)
MT1: HÀNG VẠN CÂU HỎI BẤT ĐỊNH → TRẢ LỜI TỰ ĐỘNG
MT2: ĐẾM LUÔN ĐÚNG BY DEFINITION (COUNT trực tiếp, không cache)
MT3: SCALE BẰNG DOT, KHÔNG BẰNG CODE
MT4: NHIỀU NHÓM REGISTRIES CHO NHIỀU ĐỐI TƯỢNG
MT5: HỆ THỐNG TỰ QUẢN LÝ CHÍNH NÓ
MT6: SẴN SÀNG MỌI THAY ĐỔI (metadata, không code)
MT7: QUY MÔ TRĂM TRIỆU, THIẾT KẾ TỪ NGÀY 1
MT8: MỌI THỰC THỂ KHAI SINH → M2M ĐẦY ĐỦ TỰ ĐỘNG
§II. MÔ HÌNH: 3 BÀI TOÁN (giữ nguyên v3.5)
BÀI TOÁN 1: M2M ĐẦY ĐỦ — "NGUYÊN LIỆU" (giữ nguyên v3.5)
BÀI TOÁN 2: PIVOT TABLE + MA TRẬN — "TRÍCH XUẤT" (giữ nguyên v3.5)
BÀI TOÁN 3: DÂY ĐIỆN + MÀN HÌNH + ẮC QUY — "HIỂN THỊ" (giữ nguyên v3.5)
(Chi tiết 3 bài toán: xem v3.5 §II — pivot_definitions schema, filter_spec, whitelist, canonical signature, performance 3 tầng — TẤT CẢ GIỮ NGUYÊN.)
§II-BIS. TAB PIVOT — TỔNG QUAN HỆ THỐNG (v4.0 — S146 Huyên quyết định)
Tab Pivot = MÀN HÌNH CHÍNH để nhìn toàn bộ hệ thống qua con số. Đặt trên navigation giữa Registries và Laws.
1. Cấu trúc: 9 DÒNG
| STT | Dòng | Source | Đếm gì | Thứ tự |
|---|---|---|---|---|
| 1 | 🟢 Nguyên tử (Atom) | meta_catalog virtual CAT-ALL | SUM managed active atoms | 1 |
| 2 | 🔵 Phân tử (Molecule) | meta_catalog virtual CAT-MOL | SUM managed active molecules | 2 |
| 3 | 🟣 Hợp chất (Compound) | meta_catalog virtual CAT-CMP | SUM managed active compounds | 3 |
| 4 | 🟠 Vật liệu (Material) | meta_catalog virtual CAT-MAT | SUM managed active materials | 4 |
| 5 | 🔶 Sản phẩm (Product) | meta_catalog virtual CAT-PRD | SUM managed active products | 5 |
| 6 | 🔷 Công trình (Building) | meta_catalog virtual CAT-BLD | SUM managed active buildings | 6 |
| 7 | 🧬 Loài (Species) | meta_catalog virtual CAT-SPE | COUNT entity_species | 7 |
| 8 | 🔧 DOT Tools | meta_catalog virtual (cần tạo) | COUNT dot_tools published | 8 |
| 9 | 📦 Collections | meta_catalog virtual (cần tạo) | COUNT collection_registry | 9 |
Thứ tự BẮT BUỘC: Lớp 1→6 (Điều 0-B) → Species (Điều 29) → DOT → Collections. KHÔNG sort alphabet.
Dòng 1-6: 6 lớp cấu tạo theo Điều 0-B. Filter: identity_class='managed' AND status='active' AND composition_level=[level]. Auto-refresh bởi fn_refresh_virtual_summaries + fn_refresh_cat_all (triggers ENABLED, đã fix S146-M4b).
Dòng 7: Species = meta-layer ĐỨNG NGOÀI 6 lớp (Điều 29). composition_level = NULL hoặc 'meta'.
Dòng 8: DOT Tools. Phân nhóm theo §II-TER (bên dưới).
Dòng 9: Collections. Phân nhóm: managed/observed/excluded (governance_role trong collection_registry).
2. Các cột L1
| Cột | Source | Mô tả |
|---|---|---|
| Lớp | meta_catalog.name | Tên hiển thị |
| Phân loại | meta_catalog.composition_level | Loại cấu tạo |
| Tổng cá thể | meta_catalog.record_count | SUM entities thuộc lớp |
| Số loài | pivot (GROUP BY composition_level ON entity_species) | COUNT species thuộc lớp |
| Mồ côi | meta_catalog.orphan_count hoặc pivot | SUM orphan entities thuộc lớp |
Cột "Số loài" + "Mồ côi": data từ PG pivot → meta_catalog fields → Directus serve → Nuxt readItems. KHÔNG tính ở Nuxt.
3. Nguyên tắc Tab Pivot
- §0-BA: Nuxt = màn hình. readItems → render. KHÔNG business logic.
- §0-AU: KHÔNG hardcode. Thêm dòng = INSERT meta_catalog virtual row. KHÔNG sửa code.
- Điều 13: Tạo record = tự hiện. Tab Pivot đọc meta_catalog virtual rows.
- Điều 7: PG trước. Counting bằng pivot_count(). Nuxt cuối cùng.
- MT6: Thay đổi = metadata. Thêm dòng 10, 11, 12... = INSERT data. KHÔNG code.
- AP-13: ĐỌC LUẬT NÀY trước khi làm. Vi phạm luật đã viết = tạo rắc rối mất cả tuần dọn.
§II-TER. PHÂN NHÓM DOT + COLLECTIONS (v4.0 — Huyên quyết định)
1. DOT Tools — Phân cấp 3 lớp (theo Điều 24 Faceted Classification)
| Lớp | Tên | Ví dụ | Field |
|---|---|---|---|
| Lớp mẹ | Chức năng tổng quát | Hành động, Giám sát | dot_tools.category (hiện có) |
| Lớp con | Chuyên môn lĩnh vực | Pivot, Schema, Directus, Registry | Cần thêm field hoặc dùng taxonomy M2M |
| Lớp cháu | Chi tiết (tuỳ chọn) | Tương ứng layers/labels | Gán label sau (Điều 24) |
2 nhóm chức năng chính (Lớp mẹ):
| Nhóm | Chức năng | Ví dụ DOT | Hiến pháp |
|---|---|---|---|
| Hành động | Tạo, khai báo, migrate, deploy | dot-pivot-declare, dot-entity-create, dot-metadata-fill | Điều 4 (Sinh sản), Điều 12 (Vòng đời) |
| Giám sát | Scan, health, audit, verify | dot-pivot-health, dot-orphan-scan, dot-registry-diff | Điều 19 (Side B), Điều 22 (Tự sửa), Điều 31 (Toàn vẹn) |
DOT Giám sát — 2 quy trình (Điều 22):
Quy trình 1 — Tự phát hiện:
DOT scan → NHẬN DIỆN vấn đề → LIỆT KÊ vào system_issues → tự động
Quy trình 2 — Đề xuất + Phê duyệt:
DOT phát hiện → ĐỀ XUẤT fix → User PHÊ DUYỆT → DOT ÁP DỤNG → VERIFY
Mô tả chức năng DOT — BẮT BUỘC (Điều 3 Metadata):
Mỗi DOT tool PHẢI có field description mô tả ngắn gọn chức năng. Áp dụng cho MỌI thực thể có ID (Điều 3 Khoản 2). DOT thiếu description = metadata thiếu = vi phạm Điều 3.
2. Collections — Phân nhóm theo governance_role
| Nhóm | governance_role | Ý nghĩa | Màu |
|---|---|---|---|
| Quan tâm | managed, observed | Collections hệ thống theo dõi, đếm, giám sát | 🟢 Xanh |
| Không quan tâm | excluded | System tables, Directus internal, không giám sát | 🔴 Đỏ |
L2 drill-down: click nhóm → danh sách collections. L3: chi tiết collection + mô tả chức năng.
§II-QUATER. 5 LAYERS CHI TIẾT (v4.0 — bổ sung v3.3 "L1/L2/L5 cứng, L3/L4 mềm")
Quy tắc chung: L1/L2/L5 = CỨNG (bắt buộc có). L3/L4 = MỀM (tuỳ context).
Layer 1: TỔNG HỢP (Summary) — CỨNG
Nội dung: Bảng 9 dòng (§II-BIS). Mỗi dòng = 1 nhóm lớn, hiện con số tổng. Cột: Lớp, Phân loại, Tổng cá thể, Số loài, Mồ côi. Data: meta_catalog virtual rows. Cuối L1: Ma trận đa chiều tổng quan (xem §II-QUINQUIES).
Layer 2: DANH SÁCH NHÓM (Group List) — CỨNG
Nội dung: Click 1 dòng L1 → hiện danh sách NHÓM CON.
| Dòng L1 | L2 hiện gì | Chiều chính L2 | Source |
|---|---|---|---|
| Atom | Danh sách loài atom (17 species) | species_code | entity_species WHERE composition_level='atom' |
| Molecule | Danh sách loài molecule (11 species) | species_code | entity_species WHERE composition_level='molecule' |
| Compound | Danh sách loài compound (6 species) | species_code | entity_species WHERE composition_level='compound' |
| Material~Building | Tương tự (hiện 0 nếu chưa có) | species_code | entity_species |
| Species | Danh sách species theo lớp cấu tạo | composition_level | entity_species GROUP BY composition_level |
| DOT | Danh sách nhóm DOT (Hành động/Giám sát → chuyên môn) | category | dot_tools GROUP BY category |
| Collections | Danh sách nhóm (managed/observed/excluded) | governance_role | collection_registry GROUP BY governance_role |
Mỗi nhóm L2 hiện: Tên nhóm, số cá thể, link drill-down L3. Dùng dynamic page HIỆN CÓ — KHÔNG tạo page mới (AP-11). Cuối L2: Ma trận đa chiều cho nhóm đó (xem §II-QUINQUIES).
Layer 3: DANH SÁCH CÁ THỂ (Entity List) — MỀM
Nội dung: Click 1 nhóm L2 → hiện danh sách CÁ THỂ thuộc nhóm đó. Ví dụ: Click loài "SPE-DOT" → danh sách DOT tools. Click "managed" → danh sách managed collections. Data: readItems collection tương ứng, filter theo nhóm. Dynamic page [entityType] đã có.
Layer 4: CHI TIẾT CÁ THỂ (Entity Detail) — MỀM
Nội dung: Click 1 entity → trang chi tiết (Lớp 3 — "DB về chính nó", Điều 21). 6 heading chuẩn: Identity, Relations, Dependencies, History, Labels, Metrics. Dynamic page [entityType]/[id] đã có. Mô tả chức năng: Mỗi entity PHẢI có description (Điều 3). DOT, Collection, Entity — tất cả đều cần mô tả ngắn.
Layer 5: MA TRẬN ĐA CHIỀU (Matrix) — CỨNG
Nội dung: Ma trận GROUP BY nhiều chiều, hiện cuối MỖI layer (không chỉ L5). Chi tiết: Xem §II-QUINQUIES bên dưới.
§II-QUINQUIES. MA TRẬN ĐA CHIỀU (v4.0 — Huyên ý tưởng + thiết kế)
1. Nguyên tắc — GHI VÀO LUẬT
1A: Vị trí: Ma trận hiện ở CUỐI mỗi Layer (L1→L5). Mỗi layer có thể có 1+ ma trận.
1B: Cấu trúc: 1 CHIỀU CHÍNH (main axis) + tối đa 6 chiều phụ = MAX 7 CHIỀU.
- Chiều chính = cái người xem MUỐN SO SÁNH. Luôn hiện dạng HÀNG trong bảng.
- Chiều 2 = CỘT trong bảng (2D display).
- Chiều 3-7 = filter/dropdown/tab — chọn 1 giá trị → bảng thay đổi.
- Con người khó nhận thức > 7 chiều. Nếu cần > 7 → tách thành 2 ma trận.
1C: Data = PG → Directus → Nuxt. Ma trận = pivot GROUP BY nhiều chiều. Tạo ma trận = INSERT pivot_definitions với nhiều groups trong group_spec. KHÔNG code hiển thị — dùng DirectusMatrix (TPL-002 Điều 28) hoặc UTable.
1D: Quản lý = pivot_definitions. Mỗi ma trận = 1+ pivot_definitions records với registry_group phân nhóm. Giai đoạn đầu dùng pivot_definitions + registry_group. Khi 100+ pivot → tính tách matrix_definitions collection riêng.
1E: Thực hiện bằng DOT. Tạo ma trận = DOT khai báo pivot_definitions. KHÔNG INSERT tay.
1F: Cập nhật tự động. Data ma trận = pivot_results refresh mỗi 10 phút (cron). Dual-trigger: cron + PG trigger khi pivot_definitions change.
2. Ví dụ — Ma trận L2 cho Atom
Chiều chính (hàng): Loài atom (17 species: SPE-DOT, SPE-TPL, SPE-COL...) Chiều 2 (cột): Metrics (Tổng cá thể, Mồ côi, Active, Draft) Chiều 3 (filter): Status (active/published/draft)
| Loài atom | Tổng | Active | Mồ côi |
|-----------------|------|--------|--------|
| SPE-DOT (DOT) | 152 | 150 | 0 |
| SPE-TPL (Template)| 50 | 48 | 2 |
| SPE-COL (Collection)| 145| 145 | 0 |
| ... | ... | ... | ... |
Click 1 hàng → L3 (danh sách cá thể thuộc loài đó).
3. Ví dụ — Ma trận L1 tổng quan
Chiều chính (hàng): 6 lớp cấu tạo Chiều 2 (cột): Tổng cá thể, Số loài, Mồ côi Chiều 3 (filter): identity_class (managed/log/virtual)
§III–XII. GIỮ NGUYÊN TỪ v3.5
(Quy trình vận hành, tận dụng 34 Điều, DOT tools 7, Môi trường PG, Triển khai missions, #DISABLE, Khả thi, Thước đo, Sửa luật khác, Tham chiếu — TẤT CẢ giữ nguyên.)
Bổ sung §VII — MISSIONS ĐÃ HOÀN THÀNH (v4.0):
| Mission | Status | PR | Kết quả |
|---|---|---|---|
| 0.5 Fix Blockers | ✅ | — | 3 blockers PG fixed |
| 1 Pivot CHẠY | ✅ | #640 | pivot_definitions + pivot_count() LIVE, 30 triggers DISABLED |
| 2 DOT khai báo | ✅ | #641 | DOT-113 dot-pivot-declare + DOT-114 dot-pivot-health |
| 3 VIEW cross-table | ✅ | — | PIV-101~106 cross-table pivots |
| S146-M4b Fix Virtual Summaries | ✅ | #645,#646,#647 | fn_refresh_virtual_summaries per-level + status='active'. 6/6 KHỚP. H7 so COUNT thật. Cron path fix. |
| S146-M4c Tab Pivot | ✅ | #648 | Tab Pivot LIVE 7 dòng. Species CAT-SPE. E2E GREEN. |
LỊCH SỬ VERSION
| Ver | Bước tiến |
|---|---|
| v1.0 | Pivot. Thiếu quy mô. |
| v2.0 | Quy mô. Registry Master. |
| v3.0 | 8 mục tiêu. 4 yếu tố. Tận dụng hệ thống. |
| v3.1 | M2M tổng quát. Quy trình nhập kho. |
| v3.2 | 3 bài toán. Điều 31 = dây điện. |
| v3.3 | Quy trình vận hành. SPE-PIV. 3 missions. |
| v3.4 | HỘI ĐỒNG L1: filter→JSON. M2M edge. Performance. AI guardrails. |
| v3.5 | HỘI ĐỒNG L2: whitelist phổ quát. Canonical signature. Promote/demote. Dependency audit. |
| v4.0 | ĐỔI TÊN → LUẬT PIVOT. Tab Pivot 9 dòng. 5 Layers chi tiết. Ma trận đa chiều (1 chính + max 7 chiều). Phân nhóm DOT (Hành động/Giám sát → chuyên môn 3 lớp). Phân nhóm Collections (managed/observed/excluded). S146 thực nghiệm: M4b fix virtual summaries, M4c Tab Pivot LIVE. AP-13 rút ra. |
BÀI HỌC S146 (v4.0)
AP-13: Viết luật nhưng không đọc lại. Agent viết Điều 7 (PG trước), Điều 13 (danh mục sống), Điều 26 (pivot đếm) nhưng khi làm Registries → sáng tạo 717 dòng Nuxt code vi phạm chính 3 Điều đã viết. Tạo rắc rối 10 phút, dọn cả tuần (4 missions: M3→M4c). MỌI agent PHẢI đọc luật liên quan TRƯỚC MỌI hành động.
v4.0 | Luật Pivot. S146. Tab Pivot 9 dòng. 5 Layers. Ma trận. DOT + Collections phân nhóm.