Điều 28: Luật Khuôn Mẫu Chuẩn — Standard Template Law v1.0
⚠️ BAN CU — DIEU 28 DANG HIEU LUC LA v2.0, KHONG PHAI v1.0
Tai lieu nay la Dieu 28 v1.0 (2026-03-21).
normative_registryghi Dieu 28 dang hieu luc la v2.0, tro sangknowledge/dev/architecture/dieu28-display-technology-law-v2-draft.md.Luu y them: ban v2.0 doi han CHU DE ("Display Technology" thay vi "Khuon Mau Chuan") — nen day khong chi la lech phien ban ma co the lech ca pham vi.
⚠️ File v2.0 kia KHONG tim thay trong KB (dot do 2026-07-29). Nghia la theo con tro cua so hieu luc se vao NGO CUT. Hoi chu he thong.
Dung trich dan tai lieu nay lam luat hien hanh. Giu lai de tra cuu lich su.
Do ngay 2026-07-29. HAN DUNG: tu 2027-01-29 nhan nay la GIA THUYET — DO LAI. CHI TIET:
docs/BAN-DO-HE-THONG-20260729.md
ĐIỀU 28: LUẬT KHUÔN MẪU CHUẨN — STANDARD TEMPLATE LAW v1.0
(Bổ sung Hiến pháp Kiến trúc — Thiết kế 1 lần, khai báo để dùng lại)
v1.0 | 2026-03-21 | S157 | Huyên đề xuất + Claude formal hóa Nguyên tắc gốc: "Thiết kế chuẩn 1 lần, dùng lại để khai báo. Nếu thêm 1 label mất 1 tiếng đi code thì còn thua doanh nghiệp dùng Excel." — Huyên Bổ sung: Điều 1 (SSOT), Điều 7 (Assembly First), Điều 0-B (Lớp 4 Vật liệu) Đọc kèm:
search_knowledge("hiến pháp kiến trúc")— Hiến pháp tối caosearch_knowledge("birth registry law")— Điều 0-G: mọi khuôn mẫu sinh ra → có birth recordsearch_knowledge("design feasibility formula")— 4 yếu tố khả thi
I. BỐI CẢNH
Vấn đề:
- Mỗi lần cần bảng mới → code mới. Mỗi lần cần ma trận → code mới. Mỗi lần cần quy trình → code mới.
- 99.5% thực thể chưa sinh ra. Nếu mỗi thực thể mới = code mới → hệ thống KHÔNG BAO GIỜ scale.
- Thêm 1 nút vào bảng chuẩn → 3.000 bảng phải tự cập nhật. Nếu phải sửa 3.000 nơi → thiết kế tồi.
- Nhân viên phải học 100 giao diện khác nhau thay vì 5 khuôn mẫu chuẩn → đào tạo tốn kém, sai nhiều.
Giải pháp:
Khuôn Mẫu Chuẩn (Standard Template) = thiết kế SSOT cho MỘT loại component/module/pattern. Mỗi instance mới = KHAI BÁO CONFIG, không code. Sửa khuôn mẫu = TẤT CẢ instances cập nhật.
II. ĐỊNH NGHĨA
Khuôn Mẫu Chuẩn (Standard Template) = gì?
| Thuộc tính | Giá trị |
|---|---|
| Bản chất | Component/module/pattern được thiết kế 1 LẦN, dùng lại NHIỀU LẦN qua khai báo config |
| Vị trí trong 6 lớp cấu tạo | Lớp 4 — Vật liệu (Material): hợp chất đã chuẩn hóa, tái sử dụng |
| Tương tự vật lý | "Thép chuẩn" — 1 công thức, đúc hàng triệu thanh. Sửa công thức = mọi thanh sau đều khác |
| Tương tự phần mềm | React component: <DataTable config={...} /> — 1 component, vô hạn bảng |
| Quản trị | CÓ — có code (TPL-xxx), có registry, có lifecycle, có birth record |
| Species | SPE-TPL (template) — loài riêng trong entity_species |
2 tầng rõ ràng:
TẦNG 1: KHUÔN MẪU (Template) — Thiết kế chuẩn, code 1 lần
├─ TPL-001: DirectusTable (bảng chuẩn)
├─ TPL-002: DirectusMatrix (ma trận chuẩn)
├─ TPL-003: CommentModule (comment chuẩn)
├─ TPL-004: WorkflowModule (quy trình chuẩn)
├─ TPL-005: TaskModule (task chuẩn)
└─ TPL-xxx: ... (thêm khi cần, KHÔNG GIỚI HẠN)
TẦNG 2: INSTANCE (Bản dùng) — Khai báo config, KHÔNG code
├─ TBL-001..TBL-3000: 3.000 bảng, tất cả dùng TPL-001
├─ MTX-001..MTX-100: 100 ma trận, tất cả dùng TPL-002
└─ ... vô hạn instances
Sửa TPL-001 (thêm nút, đổi style) → 3.000 bảng TỰ ĐỘNG cập nhật. KHÔNG ai sửa gì.
III. 5 NGUYÊN TẮC
Nguyên tắc 1: THIẾT KẾ 1 LẦN, KHAI BÁO ĐỂ DÙNG
Mỗi loại component/pattern trong hệ thống CHỈ ĐƯỢC thiết kế 1 LẦN dưới dạng khuôn mẫu chuẩn. Mọi instance sau đó = khai báo config (metadata), KHÔNG viết code mới.
Test: Nếu tạo instance mới mà phải viết code → vi phạm. Phải khai báo config thôi.
Nguyên tắc 2: KHUÔN MẪU = SSOT
Khuôn mẫu là SSOT cho tất cả instances. Sửa khuôn mẫu = sửa 1 nơi → áp dụng mọi nơi. Không có "bản sao riêng" của khuôn mẫu. Bất kỳ instance nào cần khác biệt → qua config override, KHÔNG fork khuôn mẫu.
Test: Nếu 2 instances cần behavior khác nhau mà phải tạo 2 khuôn mẫu riêng → xem lại: config có thể giải quyết không?
Nguyên tắc 3: KHUÔN MẪU LÀ THỰC THỂ ĐƯỢC QUẢN TRỊ
Mỗi khuôn mẫu chuẩn PHẢI:
- Có ID: TPL-NNN (PREFIX chuẩn)
- Đăng ký trong registry: collection
design_templates(hoặc mở rộng modules) - Có birth record trong birth_registry (tự động qua PG trigger)
- Có species: SPE-TPL (template)
- Có metadata: name, description, version, config_schema, instance_count
- Có lifecycle: draft → active → deprecated → retired
Hệ quả: Hệ thống LUÔN BIẾT có bao nhiêu khuôn mẫu chuẩn — SELECT COUNT(*) FROM birth_registry WHERE species_code = 'template'. Không cần ai đếm thủ công.
Nguyên tắc 4: METADATA-DRIVEN, CODE-FREE
Khuôn mẫu nhận config dưới dạng metadata (JSON, collection records, hoặc Directus fields). Thay đổi behavior = thay đổi config, KHÔNG sửa code.
Config schema mẫu cho DirectusTable (TPL-001):
{
"collection": "dot_tools",
"columns": ["code", "name", "status", "category"],
"sortable": true,
"searchable": true,
"pagination": true,
"row_actions": ["view", "edit"]
}
Config schema mẫu cho DirectusMatrix (TPL-002):
{
"rows": { "source": "entity_species", "key": "species_code", "label": "display_name" },
"columns": [
{ "key": "total", "agg": "count" },
{ "key": "certified", "agg": "count", "filter": { "certified": true } }
],
"data": { "source": "birth_registry", "group_by": "species_code" }
}
Nguyên tắc 5: TỰ PHÁT HIỆN + TỰ ĐẾM
Khi khuôn mẫu mới sinh ra → birth_registry auto capture → entity_species auto resolve SPE-TPL → bộ đếm phổ quát tự bắt. KHÔNG CẦN sửa code để đếm khuôn mẫu mới.
Khi instance mới sinh ra (ví dụ: thêm 1 bảng mới vào table_registry) → birth_registry auto capture với species = SPE-TBL → đếm tự động. Liên kết instance → template qua label hoặc FK.
IV. DANH SÁCH KHUÔN MẪU HIỆN TẠI (snapshot, SẼ TĂNG)
| # | Code | Tên | Mô tả | Instance collection | Instances hiện tại | Status |
|---|---|---|---|---|---|---|
| 1 | TPL-001 | DirectusTable | Bảng UI chuẩn — schema-driven, ~15 dòng config | table_registry | ~20 | ✅ Active |
| 2 | TPL-002 | DirectusMatrix | Ma trận đa chiều chuẩn — config-driven | (chưa tạo) | 0 | 📋 Planned (S157-C) |
| 3 | TPL-003 | CommentModule | Comment chuẩn — gắn vào bất kỳ entity | (modules/M-001) | 1 | ✅ Active |
| 4 | TPL-004 | WorkflowModule | Quy trình chuẩn — DSL + state machine | (modules/M-002) | 1 | ✅ Active |
| 5 | TPL-005 | TaskModule | Task chuẩn — assign + track + verify | tasks | ~6 | ✅ Active |
| 6 | TPL-006 | InspectorDOT | DOT Inspector chuẩn — query unchecked → check → mark | dot_tools (inspect_*) | 1 (pen) | 🔄 Building |
| 7 | TPL-007 | BirthTrigger | PG trigger auto khai sinh — per collection | birth_registry | ~20 triggers | ✅ Active |
Bảng này SẼ TĂNG. Mỗi khi phát hiện pattern lặp lại → chuẩn hóa thành khuôn mẫu → thêm TPL-NNN. Bộ đếm tự bắt từ birth_registry.
V. QUY TRÌNH SINH KHUÔN MẪU MỚI
Cổng Sinh Khuôn Mẫu (chặt hơn sinh thực thể thường):
1. PHÁT HIỆN pattern lặp lại
→ "Tôi đang code giống nhau lần thứ 3" = signal
2. KIỂM TRA: đã có khuôn mẫu cho pattern này chưa?
→ SELECT * FROM design_templates WHERE ...
→ Có → DÙNG LẠI. Không → tiếp bước 3.
3. THIẾT KẾ khuôn mẫu
→ Pass 4 yếu tố khả thi (§0-H)
→ Config schema rõ ràng (input/output)
→ Test: tạo 3 instances KHÁC NHAU chỉ bằng config, KHÔNG sửa code
4. ĐĂNG KÝ
→ TPL-NNN (PG auto-ID)
→ birth_registry (auto trigger)
→ species = SPE-TPL
→ Metadata: name, description, config_schema, version
5. TẠO DOT tool tương ứng (nếu cần)
→ dot-create-[template-name] → đọc config → render instance
6. MIGRATE instances hiện có
→ Instances cũ (code riêng) → chuyển sang dùng khuôn mẫu + config
VI. QUẢN LÝ + ĐẾM TỰ ĐỘNG
Species:
- SPE-TPL (template) — loài cho khuôn mẫu. management_mode = governed.
- Cá thể thuộc lớp: material (Lớp 4 vật liệu — hợp chất đã chuẩn hóa).
Đếm:
-- Có bao nhiêu khuôn mẫu chuẩn?
SELECT COUNT(*) FROM birth_registry WHERE species_code = 'template';
-- Chi tiết per template:
SELECT entity_code, collection_name FROM birth_registry WHERE species_code = 'template';
Thêm khuôn mẫu mới → birth_registry auto capture → COUNT tự tăng. KHÔNG SỬA QUERY.
Registries UI:
- Khuôn mẫu chuẩn = 1 section trong Registries (hoặc 1 species node trong species tree)
- Click vào → danh sách tất cả khuôn mẫu + số instances mỗi cái
- Drilldown: TPL-001 → 3.000 bảng instances
Labels:
- Label
role:templatetrên mỗi khuôn mẫu (Điều 24 taxonomy) - Label
template:TPL-001trên mỗi instance → biết instance dùng khuôn mẫu nào - Label cho phép query: "Tất cả instances của TPL-001" =
WHERE label = 'template:TPL-001'
VII. CÂU HỎI "KHÁI NIỆM MỚI PHÁT SINH"
"99.5% thực thể chưa sinh ra. Làm sao quản lý khái niệm mới mà hạn chế code mới?" — Huyên
Công thức xử lý khái niệm mới:
KHÁI NIỆM MỚI XUẤT HIỆN
│
▼
[1] Đã có khuôn mẫu chuẩn phù hợp?
├─ CÓ → KHAI BÁO CONFIG → XONG (0 code mới)
│ Ví dụ: cần bảng mới → config DirectusTable → bảng có ngay
│
└─ CHƯA → Tiếp bước 2
[2] Khái niệm mới = biến thể của khuôn mẫu có sẵn?
├─ CÓ → MỞ RỘNG CONFIG khuôn mẫu → XONG (sửa config schema, 0 component mới)
│ Ví dụ: cần bảng có tính năng export → thêm option export vào DirectusTable
│
└─ CHƯA → Tiếp bước 3
[3] Khái niệm hoàn toàn mới = TẠO KHUÔN MẪU MỚI
→ Thiết kế 1 lần (Cổng Sinh §V) → TPL-NNN
→ Từ nay: mọi instance = khai báo config
→ Code mới CHỈ XẢY RA 1 LẦN cho mỗi LOẠI khái niệm, KHÔNG cho mỗi cá thể
Bảo đảm scale:
| Khi có | Số khuôn mẫu | Số instances | Code mới cần |
|---|---|---|---|
| 10 loại concept | ~10 TPL | ~100 instances | 0 (chỉ config) |
| 100 loại concept | ~30 TPL | ~10.000 instances | 0 (chỉ config) |
| 1000 loại concept | ~50 TPL | ~1.000.000 instances | 0 (chỉ config) |
Vì sao 1000 concept chỉ cần ~50 TPL? Vì nhiều concept dùng chung khuôn mẫu. 500 loại bảng khác nhau → tất cả dùng DirectusTable. 200 loại ma trận → tất cả dùng DirectusMatrix. Pattern convergence.
VIII. QUAN HỆ VỚI LUẬT HIỆN CÓ
| Luật | Quan hệ |
|---|---|
| Điều 0 (Thực thể) | Khuôn mẫu = thực thể quản trị (có ID, registry, metadata) |
| Điều 0-B (Phân tầng) | Khuôn mẫu = Lớp 4 Vật liệu (hợp chất chuẩn hóa, tái sử dụng) |
| Điều 0-G (Khai sinh) | Mọi khuôn mẫu sinh ra → birth_registry auto → đếm tự động |
| Điều 1 Luật 1 (SSOT) | Khuôn mẫu = SSOT cho tất cả instances |
| Điều 1 Luật 2 (Tự động) | Instance mới = khai báo config, không code → tự động tối đa |
| Điều 7 (Assembly First) | Config-driven, PG VIEW cho data → component render |
| Điều 24 (Nhãn) | Label role:template + template:TPL-NNN cho tracking |
| §0-H (4 yếu tố) | Mỗi khuôn mẫu PHẢI pass 4 yếu tố khả thi |
IX. AGENT CHEAT SHEET
1. Cần component mới? → Kiểm tra: đã có khuôn mẫu chuẩn chưa?
2. Có → KHAI BÁO CONFIG. Xong. 0 code.
3. Chưa → Đang lặp pattern lần thứ 3? → TẠO KHUÔN MẪU MỚI.
4. Khuôn mẫu mới = TPL-NNN, Lớp 4, SPE-TPL.
5. Test khuôn mẫu: 3 instances KHÁC NHAU chỉ bằng config.
6. Sửa khuôn mẫu = TẤT CẢ instances tự cập nhật.
7. Đếm khuôn mẫu = COUNT birth_registry WHERE species='template'. Tự động.
8. Kinh doanh thay đổi = sửa config. KHÔNG SỬA CODE.
9. Thêm khái niệm mới = kiểm tra 3 bước (config? → mở rộng config? → khuôn mẫu mới?)
10. Mục tiêu: ~50 khuôn mẫu quản lý 1 triệu instances.
Điều 28 v1.0 | S157 | Huyên đề xuất + Claude formal hóa "Thiết kế chuẩn 1 lần, khai báo để dùng lại. Sửa code mỗi lần kinh doanh thay đổi = thiết kế tồi."