PHỤ LỤC ĐIỀU 38 — COMPONENT & BOM GOVERNANCE

Phụ lục 04 Điều 38 (Component/BOM)

Trạng thái: DỰ THẢO — chờ Council review + User duyệt Loại: Phụ lục mới gắn vào Đ38 Concept gốc: 02C2 (Component Catalog Model) Đóng blocker: 02D0 blocker "Đ38 chưa có component/BOM governance" Che phủ hở: 02DX QĐ4 — "Chưa có phụ lục component/BOM governance" GPT review: PASS có điều kiện, 10 chỉnh + 3 khuyến nghị đã áp dụng

§1. Mục đích

Luật hóa component là đơn vị giải pháp chuẩn hóa, dùng lại được — và BOM là cơ chế biết văn bản lắp từ component nào.

Chuyển Incomex từ "xe độc bản" (mỗi văn bản viết riêng từ đầu) sang "công nghiệp hóa" (lắp ráp từ linh kiện chuẩn).

Component không thay thế luật; authority pháp lý vẫn nằm ở văn bản/unit/change-set được duyệt. Component là đơn vị giải pháp kỹ thuật/quản trị phục vụ lắp ráp và reuse.

§2. Phạm vi

Áp dụng cho mọi pattern, template, guard, config rule, workflow step, function đủ điều kiện đăng ký vào catalog (xem §3.3). Phục vụ toàn chuỗi Text → Code → Workflow → Knowledge.

§3. Định nghĩa

§3.1 Component

Đơn vị giải pháp chuẩn hóa, đã đóng gói, có spec rõ ràng, dùng lại được trong nhiều văn bản/hệ thống. Tương tự PLM part.

§3.2 Component version

Mỗi component có version riêng, quản lý độc lập với document version. Version bump phải qua review bởi authority.

§3.3 Ba ranh giới cứng

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

§3.4 Ngưỡng vào catalog

Chỉ đăng ký vào catalog khi đủ 3 điều kiện:

Có reuse value — được dùng lại hoặc có căn cứ rõ ràng sẽ dùng lại
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ì

Helper nội bộ dùng 1 lần → không vào catalog.

§3.5 Loại component (controlled vocabulary)

Bộ loại khởi đầu: pattern, template, guard, config rule, workflow step, function. Đây là bộ khởi đầu, không phải danh sách vĩnh viễn. Mở rộng thêm loại mới phải qua catalog governance/approval (config registration + human approve), không phải agent tự sáng tác.

Đây là controlled vocabulary ở mức catalog governance; taxonomy runtime/implementation xác định ở design phase.

§3.6 Thuộc tính quản trị tối thiểu

Mỗi component phải có tối thiểu:

Nhận diện: mã unique, tên, loại, spec tóm tắt
Interface: input/output ở mức governance (contract kỹ thuật chi tiết thuộc design)
Lifecycle: draft → active → deprecated → retired → superseded (tuân thủ Đ4)
Governance status: approved_for_reuse / experimental / restricted / deprecated_but_allowed / forbidden_for_new. Tên trạng thái kỹ thuật/enum cụ thể thuộc design phase.
Ownership & authority: ai chốt spec, ai review khi version bump
PG object refs: trỏ đến pg_proc/pg_trigger/pg_class nếu có implementation — nghiêm ngặt chỉ trỏ, không khai lại (NT11)

Tên cột/kiểu dữ liệu cụ thể thuộc L3 + design phase.

§3.7 Variant

Variant phải trỏ về base component, không đứt gốc.
Variant khác base ở config/tham số, không ở kiến trúc. Khác kiến trúc = component mới hoặc major version/new base component theo governance decision.
Variant có version + governance status riêng.

§3.8 Golden path

Tổ hợp component đã phê duyệt, giải đúng 1 loại bài toán. Golden path là approved reference assembly/reference pattern trong Catalog/Registry. KG/Đ39 có thể projection thành TBox hoặc node tri thức với provenance.

Phải là data queryable trong PG, không phải markdown hướng dẫn.

§3.9 Anti-pattern / Negative knowledge

Tổ hợp cấm, pattern thất bại, kinh nghiệm tiêu cực — ghi nhận và quản lý theo Đ39 C13. Nguồn: lịch sử Incomex, self-learning loop, council review.

Anti-pattern/negative knowledge chỉ trở thành tổ hợp cấm hoặc rule enforcement khi được authority phê duyệt và ghi vào compatibility/assembly rule.

§3.10 BOM (Bill of Materials)

Danh sách component mà 1 document sử dụng, kèm version + config.

§3.10.1 BOM entry

Mỗi entry trong BOM ghi: component nào, version nào tại thời điểm add, usage type (required/optional/reference/alternative), config override nếu khác default.

§3.10.2 Quy tắc BOM

BOM mặc định ở cấp document/assembly. Unit-level use/claim/reference được quản bằng edge/binding riêng.
1 component chỉ xuất hiện 1 lần trong BOM 1 document (cần 2 vai trò → dùng variant hoặc distinct entry).
BOM ghi version tại thời điểm add. Component bump version → BOM không tự đổi → DOT phát hiện mismatch → cảnh báo.
BOM machine-readable, machine-checkable.
Component mới add vào BOM phải active hoặc approved_for_reuse. Component deprecated_but_allowed chỉ được giữ hoặc dùng theo rule/approval.

§3.11 Reuse decision (thứ tự bắt buộc)

① 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

Đây là cơ chế máy (NT2) — không phải guideline hành vi. Tạo component mới phải có reuse decision log ghi nhận đã tìm kiếm + justification + human approval.

Birth path phải kiểm reuse decision. Cơ chế block/warn/escalate xác định ở L4/design.

§3.12 Species

component phải được đăng ký như species/loài quản trị hoặc class tương đương theo Đ29/cơ chế hiện hành. Thao tác cụ thể xử lý ở L4/design.

§4. Nguyên tắc bắt buộc

#	Nguyên tắc	Cơ sở
1	Reuse trước, tạo mới sau. Mọi tạo mới phải chứng minh không thể reuse/extend.	QĐ4, TC10, Phụ lục 01 MT0C
2	Máy enforce reuse decision. Birth path kiểm reuse decision. Cơ chế cụ thể (block/warn/escalate) xác định ở L4/design.	NT2, 02C2 §9
3	Không khai lại PG catalog. Component catalog chỉ khai semantic/ownership/lifecycle/compatibility.	NT11
4	BOM ở cấp document/assembly. Unit-level reference quản bằng edge/binding riêng. 2 cơ chế tách biệt.	02C2 R3
5	Golden path = data PG. Approved reference assembly trong Catalog/Registry. Machine-readable, machine-checkable.	TC6, Phụ lục 01
6	Controlled vocabulary. Agent không tự sáng tác loại component. Bộ loại khởi đầu, mở rộng qua catalog governance/approval.	02C2 §3, 02C3
7	Reuse pattern birth gate. Nguyên lý từ Đ0-G/Fix 27-28, thiết kế mới theo scope component.	02DY
8	Component không thay thế luật. Authority pháp lý nằm ở văn bản/unit/change-set được duyệt.	Đ32, HP

§5. Ranh giới — không làm gì trong phụ lục này

Không làm	Lý do
Không định nghĩa text unit	Thuộc L1
Không chốt metadata schema cụ thể	Thuộc L3 + design phase
Không định nghĩa bảng/cột cụ thể	Schema thuộc design phase
Không chốt trigger/function/DOT list	Thuộc design + implementation
Không chốt workflow engine	Ngoài scope, Đ34 chưa active
Không chốt interface contract kỹ thuật	Thuộc design phase
Không chốt compatibility matrix cụ thể, approved combinations cụ thể, hay danh sách golden path cụ thể	Thuộc design/seed phase

§6. Liên kết với luật hiện hành

Luật	Quan hệ
Đ38 v3.0	Phụ lục này bổ sung Đ38: component/BOM là mô hình reuse chính thức
L1 (Text Unit)	Component ≠ unit. Component được tham chiếu từ unit (edge) hoặc ghi trong BOM (document).
Đ4 (Lifecycle)	Component lifecycle tuân thủ Đ4
Đ0-G (Birth)	Birth gate áp cho component — xem L4
Đ29 (Species)	component đăng ký species/class tương đương — thao tác ở L4/design
Đ32 (Approval)	Component tạo mới (④) cần human approval. Authority pháp lý nằm ở văn bản/unit.
Đ39 (KG)	Anti-pattern → negative knowledge Đ39 C13. Golden path → KG projection với provenance.
HP NT2	Cơ chế máy, không guideline
HP NT8	Assembly First — QĐ4 là hiện thực hóa NT8 cho text domain
HP NT11	Khai tối thiểu — không khai lại PG catalog
Phụ lục 01	MT0B (Component Registry), MT0C (Reuse Decision), MT8-9 (Module/BOM)

§7. Điều kiện PASS

#	Điều kiện
1	3 ranh giới cứng (component≠unit, catalog≠PG catalog, BOM≠reference) rõ ràng
2	Reuse decision 4 bước + máy enforce nhất quán với 02C2 và Phụ lục 01 MT0C
3	BOM ở cấp document/assembly, unit-level reference quản riêng — nhất quán với 02C2 R3
4	Không trượt sang schema/implementation/tên bảng
5	Không mâu thuẫn với L1, Đ38, Đ4, Đ0-G, Đ29, Đ32, Đ39, HP
6	L2 đủ làm tiền đề cho L3 (Metadata Governance) và L4 (Birth Gate mở rộng)
7	Council review + User duyệt

DỰ THẢO | Phụ lục 04 Đ38 — Component & BOM Governance | L2 | GPT review: PASS có điều kiện, 10 chỉnh + 3 khuyến nghị đã áp dụng | Chờ Council + User