Điều 28: Luật Khuôn Mẫu Chuẩn — Standard Template Law v1.0
Đ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."