Component Catalog Model

Phụ lục 02C2 Điều 38

Trạng thái: PASS — GPT review 3 vòng + 16 chỉnh, User duyệt Mục đích: Chốt mô hình quản trị linh kiện/component TRƯỚC khi nói schema. Không làm: Chưa đặt tên bảng, chưa pseudo-SQL, chưa đếm DOT, chưa migration. Câu hỏi cốt lõi: "Catalog linh kiện chuẩn của Incomex sẽ quản cái gì, và nó giúp chống 'xe độc bản' bằng cách nào?"

3 ranh giới cứng của 02C2

#	Ranh giới	Giải thích
R1	Component ≠ text unit	Text unit = nội dung trình bày, thuộc 1 document (02C1). Component = cơ chế/giải pháp chuẩn hóa, độc lập, nhiều documents dùng chung. Không bao giờ trộn 2 loại.
R2	Component catalog ≠ khai lại PG catalog	PG catalog (pg_proc, pg_trigger, pg_class) đã biết metadata kỹ thuật. Component catalog chỉ khai thêm: semantic meaning, ownership, lifecycle, compatibility, composition — cái PG không tự biết (NT11).
R3	BOM ≠ reference	BOM = danh sách component mà document sử dụng (gắn ở cấp document). Reference = text unit trỏ đến component (edge ngang ở cấp unit). 2 cơ chế bổ sung, không thay thế.

1. Component là gì?

Một component là một đơn vị giải pháp chuẩn hóa, đã được đóng gói, có spec rõ ràng, dùng lại được trong nhiều văn bản/hệ thống khác nhau mà không cần viết lại từ đầu.

Ví dụ nôm na: Nhà máy sản xuất gạch tiêu chuẩn. Mỗi loại gạch có: kích thước chuẩn, chịu lực bao nhiêu, dùng cho tường nào, không dùng cho tường nào, ai sản xuất, phiên bản nào. Thợ xây nhà chỉ cần chọn gạch đúng loại từ catalog, không cần tự nung gạch mới mỗi lần xây.

Ví dụ cụ thể Incomex:

Component	Spec tóm tắt	Đang dùng ở đâu
Birth gate pattern	BEFORE INSERT trigger validate metadata bắt buộc trước khi cho entity vào PG	21+ tables, 42 triggers (Fix 27-28)
Paired DOT pattern	Writer DOT thực hiện + Checker DOT phát hiện lệch, paired bắt buộc	252+ DOTs (Đ35)
Self-healing loop	fn_log_issue → auto-fix dispatcher → single-shot re-check → fallback escalate	system_health_checks (Fix 26)
Config-driven rule	Hành vi hệ thống đọc từ config table runtime, không hardcode	nrm_doc_type_config, nrm_approval_rules, dot_config
Binding pattern	Text value liên kết với PG data source, drift tự phát hiện	binding_registry, Đ43 context pack
GENERATED column	PG tự tính giá trị từ data khác, không cần trigger/agent	body_hash, valid_period trên normative_registry

Nhận xét: Những component trên đang tồn tại nhưng chưa được đăng ký vào catalog nào. Chúng sống trong đầu người thiết kế, trong lịch sử phiên, trong code. Không ai biết chính xác: tổng cộng bao nhiêu component? Version nào? Ai sở hữu? Dùng ở đâu? Tương thích với gì? → Đây chính là vấn đề V7, V9, V11 (Phụ lục 01).

Ngưỡng để vào catalog: Không phải mọi function/helper/rule nhỏ đều tự động trở thành component. Chỉ những thứ đủ 3 điều kiện sau mới được đăng ký vào catalog:

Có reuse value — được dùng lại hoặc có căn cứ rõ ràng sẽ được dùng lại ở nhiều hơn một ngữ cảnh
Có ownership/lifecycle rõ — ai sở hữu, trạng thái gì, version nào
Có compatibility/composition xác định — dùng với gì, không dùng với gì

Nếu chỉ là helper function nội bộ dùng 1 lần → không cần vào catalog. Catalog phình to = mất giá trị.

2. Component khác text unit ở đâu?

Tiêu chí	Text unit (02C1)	Component (02C2)
Bản chất	Miếng nội dung — khoản, mục, định nghĩa, điều kiện...	Miếng giải pháp — pattern, template, guard, config rule, workflow step...
Thuộc về	Thuộc 1 document cụ thể (parent-child trong cây)	Độc lập — không thuộc document nào, nhiều documents dùng chung
Quan hệ với document	Document chứa text units (cấu trúc dọc)	Document sử dụng components (BOM — danh sách linh kiện)
Ai tạo	Agent soạn nội dung VB	Agent/kiến trúc sư đề xuất, human authority phê duyệt theo governance path
Lifecycle	Theo document lifecycle (draft→enacted→retired)	Lifecycle riêng (draft→active→deprecated→retired) — độc lập với document
Reuse	Text unit thuộc 1 document. Dùng lại = tham chiếu (edge), không copy	Component được thiết kế ĐỂ dùng lại. Nhiều documents reference cùng component
Ví dụ tương tự ngành	DITA topic	PLM part/component

Quy tắc phân biệt:

Nếu nó là nội dung trình bày trong văn bản → text unit
Nếu nó là cơ chế/pattern/rule mà văn bản tham chiếu hoặc sử dụng → component
Nếu nó vừa là nội dung vừa là cơ chế → tách: phần nội dung = text unit, phần cơ chế = component, text unit tham chiếu component
Component không bao giờ là child trong cây text unit của document. Component được tham chiếu (edge ngang) hoặc ghi trong BOM — không nhúng vào cây.

3. Những loại component nào nên tồn tại?

Dựa trên thực tế Incomex đã có và chuẩn ngành PLM:

Loại component	Mô tả	Ví dụ Incomex
Pattern	Mẫu thiết kế lặp lại, áp dụng được cho nhiều bài toán tương tự	Birth gate, paired DOT, self-healing loop, config-driven rule
Template	Khuôn mẫu nội dung có cấu trúc cố định, điền giá trị khi dùng	Description templates (10 templates Fix 27-28), section templates cho loại VB
Guard	Cơ chế bảo vệ/chặn hành vi sai trong PG	BEFORE INSERT validate, enacted_immutable trigger, EXCLUDE constraint
Config rule	Quy tắc hành vi hệ thống sống trong config table	nrm_approval_rules, dot_config, nrm_doc_type_config entries
Workflow step	Bước trong quy trình nghiệp vụ chuẩn hóa. Lưu ý: đây là ở mức concept catalog — chỉ đăng ký "bước nào tồn tại, spec gì, input/output gì". Không đồng nghĩa workflow engine/runtime đã được chốt ở bước này; triển khai workflow thuộc Đ34 (chưa active).	Review step, approval step, publish step, retire step
Function	PG function phục vụ nghiệp vụ, dùng lại được	fn_birth_registry_auto, fn_log_issue

Đây là bộ loại khởi đầu / controlled vocabulary. Mở rộng thêm loại mới phải theo governance path (config registration + human approve), không phải agent tự ý sáng tác. Đây là nguyên tắc quản loại, chưa phải chốt taxonomy cuối cùng. Controlled vocabulary ở đây là để quản catalog; không đồng nghĩa taxonomy runtime/implementation đã chốt ở bước này.

4. Thuộc tính quản trị của mỗi component

Mỗi component trong catalog cần có các thuộc tính sau — chia theo nhóm:

4.1 Nhận diện & Mô tả

Thuộc tính	Mô tả	Ví dụ
Mã (code)	Duy nhất toàn hệ thống	'COMP-BIRTH-GATE', 'COMP-PAIRED-DOT'
Tên	Tên đọc được	"Birth Gate Pattern"
Loại component	Phân loại (controlled vocabulary, xem mục 3)	'pattern'
Spec tóm tắt	Giải quyết bài toán gì, bằng cách nào	"Validate metadata bắt buộc trước INSERT, reject nếu thiếu"

4.2 Interface (vào/ra)

Thuộc tính	Mô tả	Ví dụ
Input	Component cần gì để hoạt động	Birth gate cần: species_code, owner, description
Output	Component tạo ra gì	Birth gate tạo: validated row + birth_record + audit_log
Precondition	Điều kiện tiên quyết	Species phải tồn tại trong entity_species

Ở bước này chỉ chốt khái niệm interface ở mức governance/spec; chưa chốt contract kỹ thuật chi tiết (data type, format, error handling).

4.3 Lifecycle & Governance

Thuộc tính	Mô tả	Giá trị
Lifecycle status	Trạng thái vòng đời	draft → active → deprecated → retired → superseded
Governance status	Trạng thái phê duyệt sử dụng	approved_for_reuse / experimental / restricted / deprecated_but_allowed / forbidden_for_new
Version	Phiên bản hiện tại	'1.0', '2.1'
Owner	Ai chốt spec, ai chịu trách nhiệm	Kiến trúc sư, team lead
Authority	Ai được phép sửa spec, ai review khi version bump	Council hoặc owner + reviewer

4.4 Tương thích & Composition

Thuộc tính	Mô tả	Ví dụ
Compatible scope	Dùng được với loại thực thể/VB nào — có thể tương thích theo species, doc family, tier, hoặc governance context. Chi tiết taxonomy tương thích chốt ở bước sau.	Birth gate: mọi species có birth_record
Incompatible with	Không tương thích với component nào	—
Composition	Lắp với component nào để tạo giải pháp hoàn chỉnh	Birth gate + paired DOT + self-healing = governance stack đầy đủ

Compatibility là khái niệm tổng, gồm compatible scope, incompatible pairs và các ràng buộc composition. Chi tiết taxonomy tương thích chốt ở bước sau.

4.5 Truy vết PG (NT11 — khai tối thiểu)

Thuộc tính	Mô tả	Nguyên tắc
PG object refs	Trỏ đến pg_proc/pg_trigger/pg_class nếu component có implementation trong PG	Nghiêm ngặt chỉ trỏ, không khai lại. PG catalog đã biết: function name, parameter types, trigger timing, table columns. Component catalog chỉ khai thêm: semantic meaning (component này giải bài toán gì), ownership (ai chịu trách nhiệm), lifecycle (đang active hay deprecated), compatibility (dùng với gì), composition (lắp với gì). Nếu PG catalog đã biết → KHÔNG khai lại → vi phạm NT11.

4.6 Negative Knowledge (Đ39 C13)

Thuộc tính	Mô tả	Ví dụ
Anti-patterns	Tổ hợp cấm, pattern thất bại, kinh nghiệm tiêu cực	"Birth gate + hardcoded threshold = phải sửa code mỗi lần đổi ngưỡng → vi phạm NT4"

5. Variant — quản biến thể ra sao?

Bài toán: Cùng 1 component gốc (base), có thể có nhiều biến thể (variant) cho các ngữ cảnh khác nhau. VD: Birth gate strict (reject ngay) vs Birth gate warning (cho qua + log).

Nguyên tắc quản lý:

Quy tắc	Giải thích
Variant phải trỏ về base component	Mỗi variant biết mình là biến thể của component gốc nào. Không đứt gốc.
Base component giữ spec chuẩn	Variant chỉ khác ở config/tham số, không khác ở kiến trúc. Nếu khác kiến trúc → đó là component mới, không phải variant.
Variant có version riêng	Version variant độc lập với version base. Nhưng khi base version bump lớn → variant phải review tương thích.
Variant có governance status riêng	Variant A có thể approved, variant B experimental — dù cùng base.

Ví dụ:

COMP-BIRTH-GATE (base, v2.0, approved)
├── COMP-BIRTH-GATE-STRICT (variant, v1.0, approved) — reject nếu thiếu metadata
└── COMP-BIRTH-GATE-WARNING (variant, v1.0, experimental) — cho qua + log warning

6. Golden path — quản mẫu lắp ráp chuẩn ra sao?

Định nghĩa: Golden path = tổ hợp component đã phê duyệt, giải đúng 1 loại bài toán cụ thể. Thợ xây không cần tự nghĩ công thức mới — tra catalog, lấy golden path, dùng.

Ví dụ Incomex:

Golden path	Bài toán	Tổ hợp component
"Full governance stack"	Quản trị 1 collection mới từ A-Z	Birth gate + Description template + Paired DOT + Health check + Self-healing loop
"Config-driven behavior"	Hành vi hệ thống cần thay đổi được mà không sửa code	Config table + Runtime reader function + DOT validate config
"Binding + drift detect"	Text value liên kết với PG data, tự phát hiện lệch	Binding registry entry + DOT-BIND-DRIFT + system_issues alert

Quản lý golden path:

Thuộc tính	Mô tả
Tên	"Full governance stack"
Bài toán giải	"Quản trị collection mới"
Danh sách component (có thứ tự)	[COMP-BIRTH-GATE, COMP-DESC-TEMPLATE, COMP-PAIRED-DOT, ...]
Status	active / deprecated / retired
Approved by	Human (Council/kiến trúc sư) — golden path là TBox (Đ39 nguyên tắc vàng: AI đề xuất, không tự ban hành)

7. Anti-pattern — quản kinh nghiệm tiêu cực ra sao?

Bài toán: Bên cạnh "nên dùng gì" (golden path), cần biết "KHÔNG nên dùng gì" (anti-pattern). Đây là negative knowledge — Đ39 C13.

Nguồn anti-pattern:

Lịch sử Incomex: Fix 6 (DOT 94% NULL), Fix 27 (description quên fill), S142 (hardcoded JWT bom hẹn giờ), S173 (SSH fail2ban override)
Kết quả self-learning loop (Đ39 C9): quyết định sai → rút bài học → ghi anti-pattern
Council review: phát hiện tổ hợp nguy hiểm

Cấu trúc 1 anti-pattern:

Thuộc tính	Mô tả	Ví dụ
Tổ hợp cấm	Component nào + component nào = nguy hiểm	"Directus filter flow + hardcoded JWT token"
Tại sao cấm	Hậu quả gì	"Token expired → 403 → 500 cho end user"
Thay thế bằng gì	Golden path nào thay thế	"Dùng PG trigger thay Directus filter flow"
Nguồn	Phát hiện từ đâu	"S142 — bài học thực tế"

Anti-pattern ở mức component đơn lẻ gắn vào thuộc tính anti_patterns (mục 4.6). Anti-pattern ở mức tổ hợp (2+ component kết hợp sai) ghi ở cấp catalog chung.

8. BOM — nối document với component bằng cách nào?

Định nghĩa BOM: Bill of Materials = danh sách component mà 1 document sử dụng, kèm version + config override.

Cấu trúc logic BOM:

Thành phần	Mô tả	Ví dụ
Document	Văn bản nào	Đ43 (Luật Bản đồ Hệ thống)
Component	Dùng component nào	COMP-BIRTH-GATE
Version	Version component lúc add vào BOM	v2.0
Usage type	required / optional / reference / alternative	required
Config override	Cấu hình riêng cho document này (nếu khác default)	threshold: 'strict', species_scope: 'all'

Quy tắc BOM:

Quy tắc	Giải thích
1 component chỉ xuất hiện 1 lần trong BOM 1 document	Tránh trùng lặp. Nếu một document cần cùng base component trong hai vai trò/cấu hình khác nhau, phải thể hiện bằng variant hoặc by-design distinct component entry, không lặp mơ hồ cùng một component.
BOM ghi version tại thời điểm add	Khi component bump version → BOM không tự đổi. DOT phát hiện mismatch → cảnh báo.
BOM machine-readable	Máy đọc, máy enforce, máy kiểm tra được. Không phải markdown mô tả.
Component trong BOM phải lifecycle active	Không được add component retired vào BOM mới. Deprecated_but_allowed = cảnh báo.

BOM vs Reference — phân biệt rõ:

BOM gắn ở cấp document (normative_registry): trả lời "document này lắp từ component gì?" — nhìn tổng.
Reference từ text unit: edge ngang unit → component: trả lời "đoạn văn này nói về component nào?" — nhìn chi tiết.
2 cơ chế bổ sung, không thay thế (R3 ranh giới cứng).
Về sau có thể có derived view tổng hợp unit → component usage (nhìn từ dưới lên). Nhưng đó là view phái sinh, không làm BOM chính tụt xuống cấp unit. BOM chính luôn ở cấp document.

9. Reuse decision — ghi lại quyết định dùng lại/tạo mới ra sao?

Thứ tự bắt buộc (02B QĐ4):

① Reuse nguyên trạng    → dùng đúng component đã có
② Reuse + cấu hình      → dùng component đã có + config khác
③ Extend bằng variant   → tạo biến thể, giữ trace với base
④ Tạo mới (justified)   → chỉ khi 1-3 bất khả thi, phải giải thích lý do

Mỗi quyết định cần ghi lại:

Thuộc tính	Mô tả
Loại quyết định	reuse_exact / reuse_config / extend_variant / create_new
Component mục tiêu	Component tạo hoặc reuse
Base component	Nếu reuse/extend → base là gì
Justification	Nếu create_new → tại sao không reuse?
Kết quả tìm kiếm	Đã tìm component tương tự chưa? Kết quả gì? (evidence)
Ai quyết	Agent/kiến trúc sư
Ai phê duyệt	Human approve nếu create_new

Cơ chế enforce — đây là cơ chế máy (NT2), không phải guideline hành vi:

Muốn tạo component mới → phải có reuse decision log ghi nhận đã tìm kiếm.
Nếu tạo mới (④) → phải có justification + human approval.
Birth gate component kiểm: có reuse decision record chưa? Nếu chưa → reject.

10. Tóm tắt — chống "xe độc bản" bằng cách nào?

Vấn đề "xe độc bản"	Component catalog giải thế nào
Pattern lặp mà ai cũng viết lại từ đầu	Đóng gói thành component có spec, version, owner. Dùng lại, không viết lại.
Không biết đã có giải pháp tương tự chưa	Reuse decision bắt buộc tìm kiếm trước khi tạo mới. Máy enforce.
Không biết sửa component ảnh hưởng ai	BOM biết document nào dùng component nào. Version bump → DOT phát hiện mismatch → cảnh báo.
Tổ hợp sai mà không ai biết	Anti-pattern ghi negative knowledge. Compatibility ghi tổ hợp cho phép/cấm.
Không có mẫu lắp ráp chuẩn	Golden path = tổ hợp đã phê duyệt. Tra catalog, dùng.
Không rõ ai sở hữu, ai quyết	Owner + authority rõ ràng trên mỗi component. Version bump → review bởi authority.

Ranh giới 02C2: File này chỉ chốt mô hình catalog component và các khái niệm quản trị. Cụ thể:

Chi tiết metadata governance (core schema, profile, field responsibility, validation) → 02C3

Chi tiết schema, trigger, DOT list, implementation → bước thiết kế sau khi legal coverage xong

File này không đủ căn cứ để triển khai kỹ thuật; schema/implementation chỉ được làm sau khi phụ lục component governance (02C0 BLOCKER) hoàn tất.

Bảng tổng kết hiệu chỉnh

#	Đã sửa gì	Vì sao sửa
1	Thêm box "3 ranh giới cứng" đầu file	Khóa ranh giới rõ trước khi đọc chi tiết
2	Thêm ngưỡng "3 điều kiện vào catalog"	Chống catalog phình to, mất giá trị
3	Ghi rõ loại component = controlled vocabulary	Agent không tự sáng tác loại mới
4	Workflow step thêm câu "mức concept, chưa chốt engine"	Tránh vượt scope Đ34
5	NT11 PG refs siết mạnh hơn	Liệt kê rõ PG biết gì, catalog khai gì
6	BOM thêm phân biệt derived view	Giữ BOM chính ở cấp document
7	Component không bao giờ là child trong cây unit	Chống nhúng, bám 02C1 quy tắc cây
8	Ranh giới cuối file 3 dòng chặt	Khóa legal, khóa scope, trỏ 02C3
9	"Ai tạo" → Agent/kiến trúc sư đề xuất, human phê duyệt	Phù hợp mô hình agent-assisted
10	Controlled vocabulary thêm "ở mức catalog, không phải runtime"	Tránh hiểu nhầm taxonomy
11	Compatible species → compatible scope (species, doc family, tier, context)	Component tương thích theo nhiều chiều
12	BOM 1 lần → thêm câu variant/distinct entry nếu 2 vai trò	Chặn tranh cãi trùng lặp
13	"Treo cho 02C3" → metadata governance toàn bộ model	02C3 phục vụ unit + component + relation + envelope
14	Reuse value → "có căn cứ rõ ràng sẽ được dùng lại"	Bớt cơ học, bao gồm component chiến lược mới
15	Interface thêm "chỉ chốt khái niệm, chưa contract kỹ thuật"	Tránh hiểu nhầm đã chốt runtime interface
16	Compatibility thêm câu tổng hợp ở 4.4	Đọc mượt hơn, khái niệm rõ hơn

Treo cho 02C3	Nội dung
Metadata governance cho toàn bộ model	02C3 phục vụ text unit, component, relation, document envelope — không chỉ component
Core schema + profile strategy thống nhất	Áp cho mọi loại object, không chỉ 1 loại
Field responsibility matrix	Ai fill, khi nào, auto/derive/manual — xuyên suốt
Completeness / correctness / validation	Rule kiểm tra chất lượng metadata cho toàn bộ

PASS | 02C2 Component Catalog Model | 10 mục + 3 ranh giới + 16 chỉnh | GPT review 3 vòng | User duyệt