⚠️ CO HAI TAI LIEU CHO DIEU 14 — SO HIEU LUC TRO SANG CAI KIA

Tai lieu nay tu xung "SSOT v1.2" (14.062 ky tu, chi tiet). Nhung normative_registry ghi Dieu 14 dang hieu luc la v1.0, kb_path tro sang knowledge/dev/laws/law-14-no-duplicate.md (1.817 ky tu, ban tom tat).

Do ngay 2026-07-29. CHUA XAC DINH DUOC ban nao la ban dung:

Tai lieu nay co so phien ban CAO hon (v1.2 > v1.0) va noi dung day du hon;

Nhung so hieu luc lai tro sang ban kia. Mot trong hai dang sai, chua do ra duoc la ben nao.

Dung tu quyet. Can trich dan Dieu 14 thi doc CA HAI va hoi chu he thong. Khong xoa, khong sua ban nao — dot 2026-07-29 chi dan nhan.

HAN DUNG: tu 2027-01-29 nhan nay la GIA THUYET — DO LAI. CHI TIET: docs/BAN-DO-HE-THONG-20260729.md

Luật Chống Trùng Lặp — Hướng dẫn Chi tiết Điều 14 Hiến pháp

SSOT v1.2 | S109 (2026-03-10) | Trực thuộc Hiến pháp Điều 14 v1.1: +Gemini Council (chỉ đường, namespace, auto-suggest, người phán xử) v1.2: +GPT Council (định nghĩa pháp lý, override, canonical selection, migration, SLA, metrics, alias, AI tự điền) Tuyên bố: Luật này không chỉ chống tạo bản sao, mà BUỘC hệ thống quy về MỘT canonical reference DUY NHẤT cho mỗi bản chất nghiệp vụ. Đọc: search_knowledge("luật chống trùng lặp duplicate")

1. TẠI SAO CẦN LUẬT RIÊNG

Trùng lặp là lỗi NGUY HIỂM NHẤT vì im lặng — không crash, không báo lỗi, chỉ SAI. Data ghi entity A, AI đọc entity B (bản sao) → sai mà không ai hiểu. Khi hệ thống có hàng ngàn entity, trùng BẤT KHẢ KHÁNG nếu không phòng ngừa.

2. ĐỊNH NGHĨA "CÙNG BẢN CHẤT" (v1.2 — GPT Council)

Đây là tiêu chí phán xử quan trọng nhất. Mọi quyết định trùng/không trùng đều dựa trên 3 câu hỏi:

#	Câu hỏi	Ví dụ trùng	Ví dụ KHÔNG trùng
1	Entity này dùng để làm gì? (mục đích)	"Kiểm tra CI" vs "Verify CI" = cùng	"Duyệt HĐ lao động" vs "Duyệt HĐ đối tác" = khác
2	Nó tạo ra hiệu lực gì trong hệ thống?	Cả 2 đều block merge = cùng	1 ký HĐ nhân sự, 1 ký HĐ bán hàng = khác
3	Nó phục vụ phạm vi nào? (namespace)	Cả 2 cùng CI/CD pipeline = cùng	1 phòng HR, 1 phòng Sales = khác

Quy tắc: Nếu 3 câu trả lời trùng đáng kể → CÙNG BẢN CHẤT (dù tên khác). Nếu ≥1 câu khác rõ ràng → KHÔNG trùng (dù tên giống).

3. BA CẤP ĐỘ TRÙNG

Cấp	Định nghĩa	Hành động
Cấp 1	Tên GIỐNG 100% sau chuẩn hoá, CÙNG namespace	CHẶN + CHỈ ĐƯỜNG — trả ID entity cũ + chỉ thị tái sử dụng
Cấp 2	Mô tả tương tự ≥ngưỡng semantic, cùng namespace	CẢNH BÁO + CHỈ ĐƯỜNG — ghi system_issues + trả ID
Cấp 3	2 tổ hợp chứa ≥ngưỡng cùng items (Jaccard)	CẢNH BÁO — review bắt buộc bởi Người phán xử

4. NGUYÊN TẮC "CHỈ ĐƯỜNG THAY VÌ CHỈ CẤM" (v1.1 — Gemini)

Khi chặn/cảnh báo → thông báo BẮT BUỘC kèm:

Cấp 1:

LỖI: Trùng lặp với [CP-045] "Kiểm tra CI xanh".
CHỈ THỊ: Dừng tạo mới. Tái sử dụng [CP-045].
LINK: /knowledge/registries/checkpoint_type/CP-045

Cấp 2:

CẢNH BÁO: Tương tự 78% với [CP-045] "Kiểm tra CI xanh".
GỢI Ý: Xem xét tái sử dụng [CP-045].
NẾU KHÁC THẬT: Điền form kháng nghị (Mục 5).

→ AI nhận ID → dùng ngay, không lách bằng đổi tên.

5. QUYỀN KHÁNG NGHỊ CÓ KIỂM SOÁT (v1.2 — GPT Council)

Khi AI/người muốn tạo mới DÙ bị nghi trùng → PHẢI điền 3 trường bắt buộc:

#	Trường	Ví dụ
1	Khác entity cũ ở điểm nào?	"CP-045 kiểm tra CI trên GitHub. Entity mới kiểm tra CI trên GitLab, pipeline khác hoàn toàn."
2	Tại sao không thể tái sử dụng entity cũ?	"CP-045 gắn cứng với GitHub Actions. GitLab dùng cơ chế khác."
3	Rủi ro nếu gộp nhầm là gì?	"Nếu gộp → pipeline GitLab sẽ bị skip kiểm tra → code lỗi deploy production."

Lưu thành decision record trong system_issues type="kháng_nghị_trùng". Nếu sau phát hiện override sai → có log audit.

6. KHÔNG GIAN CÁCH LY — NAMESPACE/SCOPE (v1.1 Gemini + v1.2 GPT)

Cùng tên + KHÁC namespace = KHÔNG trùng.

Loại entity	Namespace từ đâu
Checkpoint Types	`category` (compliance, quality...)
DOT Tools	`category` (kiểm_tra_lỗi, vận_hành...)
Fields	`collection` (field thuộc bảng nào)
Workflows	`workflow_categories` / domain / phòng ban
Nodes	`workflow_id`
Tổ hợp Sets	`applicable_to` hoặc domain

Khi chưa có namespace → Cấp 2 CẢNH BÁO (không CHẶN). Khi Tầng 4 có phòng ban/domain → namespace tự nhiên có.

7. MÔ TẢ THEO TIÊU CHUẨN — AI TỰ ĐIỀN (v1.2 — Huyen + GPT)

7.1 Mỗi entity PHẢI có Thẻ mô tả (Entity Card)

Duplicate Engine phụ thuộc CHẤT LƯỢNG mô tả. Entity thiếu mô tả = Engine mù.

Thẻ mô tả tối thiểu (bắt buộc cho MỌI entity có nguy cơ trùng):

Trường	Nội dung	Ví dụ
Mục đích	Dùng để làm gì? (≥1 câu)	"Kiểm tra CI pipeline phải xanh trước khi merge code"
Hiệu lực	Tạo ra kết quả gì?	"Chặn merge nếu CI đỏ"
Phạm vi	Áp dụng ở đâu?	"Tất cả PR trên repo web-test"
Phân biệt	Khác entity tương tự ở điểm nào?	"Khác CP-029 (verify API) — CP này chỉ check CI status"

Lưu trong field description (tiếng Việt có dấu, ≥20 từ). Trường description = NGUYÊN LIỆU cho Engine.

7.2 AI tự động điền và cập nhật

Không dựa vào người nhớ điền mô tả — AI tự điền:

LUỒNG TỰ ĐỘNG:

1. Entity mới được tạo (bởi AI hoặc người):
   → Directus Flow trigger → check description trống/ngắn?
   → CÓ → ghi system_issues type="thiếu_mô_tả" → AI Agent đọc + tự điền

2. AI Agent (Gemini/Claude) nhận task "điền mô tả":
   → Đọc entity name + fields + code liên quan + tài liệu kiến trúc
   → Sinh mô tả theo 4 trường Thẻ mô tả (tiếng Việt có dấu)
   → Cập nhật field description qua Directus API

3. Sau mỗi workflow/deploy lớn:
   → Lên lịch batch: Gemini CLI rà soát entities thiếu/cũ mô tả
   → Tự cập nhật description dựa trên code/tài liệu mới nhất

4. Kiểm tra chất lượng:
   → dot-description-quality quét: description < 20 từ? thiếu mục đích/hiệu lực?
   → Ghi system_issues → AI tự sửa trong batch tiếp

Kết quả: Mô tả luôn đầy đủ + cập nhật → Engine luôn có nguyên liệu → phát hiện trùng chính xác.

8. TIÊU CHÍ TRÙNG THEO LOẠI ENTITY

8.1 Checkpoint Types (CP) — NGUY HIỂM CAO

Cấp 1: [namespace] + chuẩn hoá tên → exact match
Cấp 2: Vector mô tả ≥ngưỡng

8.2 DOT Tools (DOT) — NGUY HIỂM TRUNG BÌNH

Cấp 1: [category] + bỏ "dot-" → sort tokens → exact match
Cấp 2: Vector mô tả ≥ngưỡng

8.3 Fields — NGUY HIỂM CAO (số lượng lớn nhất)

Cấp 1: [collection] + chuẩn hoá tên
Cross-collection: canonical dictionary (Mục 9)

8.4 Workflows + Nodes

Cấp 1: [domain] + chuẩn hoá tên
Cấp 3: ≥ngưỡng cùng nodes cùng thứ tự

8.5 Tổ hợp Sets/Templates — NGUY HIỂM CAO

Cấp 3: Jaccard index ≥ngưỡng

8.6 Collections + Bảng UI

Bỏ prefix → singular/plural → so sánh
≥ngưỡng cùng field names → Cấp 3

9. TỪ ĐIỂN CHUẨN HOÁ — CANONICAL DICTIONARY (v1.2 — GPT)

9.1 Vấn đề: Cùng nghĩa khác tên

"CI xanh", "CI green", "verify CI passes", "kiểm tra CI pass" = cùng concept nhưng normalization lexical bỏ sót.

9.2 Giải pháp: Map alias về canonical token

# Từ điển canonical (file config, cập nhật dần)
owner, assigned_to, responsible_person → assignee_concept
CI xanh, CI green, CI passes, CI pass → ci_pass_concept
duyệt, approve, review, xét duyệt → approval_concept
tạo, create, sinh, thêm mới → create_concept

9.3 AI tự mở rộng từ điển

Khi Engine phát hiện 2 entity cùng concept (qua semantic) nhưng tên khác → tự đề xuất thêm alias vào dictionary → review → áp dụng. Dictionary tự lớn theo thời gian.

10. CƠ CHẾ CHẠY TỰ ĐỘNG (Huyen — "không ai gọi, chạy tự động")

10.1 Realtime — sau mỗi thay đổi

Entity mới tạo/sửa → Directus Flow trigger tự động:
  → Tầng 1: exact match [namespace + name] → CHẶN hoặc cho qua
  → (Async) Tầng 2: embed description → Qdrant top 5 → CẢNH BÁO nếu ≥ngưỡng
  → Nếu description trống → ghi system_issues "thiếu_mô_tả"
NGƯỜI DÙNG KHÔNG GỌI GÌ. Tự động 100%.

10.2 Hàng đêm — quét chi tiết toàn bộ (khi tải thấp)

Scheduled job (Directus Flow schedule hoặc cron 02:00 hàng đêm):
  → dot-duplicate-engine chạy TẤT CẢ kiểm tra:
    1. Exact match toàn bộ per namespace (Cấp 1)
    2. Semantic similarity toàn bộ per type (Cấp 2)
    3. Jaccard tổ hợp (Cấp 3)
    4. dot-description-quality (mô tả đủ chưa)
  → Ghi kết quả → system_issues
  → Sáng hôm sau: AI/Agent/Con người vào → THẤY báo cáo đêm qua

10.3 Sau deploy — kiểm tra nhanh

deploy-vps.yml thêm step:
  → dot-duplicate-engine --quick (chỉ check entities mới trong 24h)

11. QUY TẮC CHỌN CANONICAL ENTITY (v1.2 — GPT)

Khi xác nhận 2 entity TRÙNG THẬT → chọn entity CHÍNH (canonical) theo thứ tự:

Ưu tiên	Tiêu chí	Lý do
1	Entity được tham chiếu nhiều hơn (inbound references)	Ít ảnh hưởng khi migrate
2	Entity có metadata đầy đủ hơn (description, tags, relations)	Chất lượng cao hơn
3	Entity có trạng thái active (không draft/deprecated)	Đang hoạt động
4	Nếu vẫn hoà → ID nhỏ hơn (cũ hơn)	Quy tắc mặc định

12. QUY TRÌNH MIGRATION AN TOÀN (v1.2 — GPT)

Khi gộp 2 entity trùng → migrate references từ entity phụ sang canonical:

BƯỚC 1 — PRE-CHECK:
  → Thống kê TOÀN BỘ inbound references tới entity phụ
  → Liệt kê: collection nào, field nào, bao nhiêu records

BƯỚC 2 — MIGRATE:
  → Batch update: đổi tất cả references entity_phụ → entity_canonical
  → Transaction/batch có LOG chi tiết

BƯỚC 3 — POST-CHECK:
  → Đếm inbound references entity phụ = PHẢI = 0
  → Nếu > 0 → rollback + báo lỗi

BƯỚC 4 — DEPRECATE:
  → Entity phụ status = "deprecated"
  → Ghi: "Đã gộp vào [CANONICAL_ID]. Lý do: [...]"
  → KHÔNG XOÁ — retire sau khi confirm 0 references ≥30 ngày

BƯỚC 5 — ROLLBACK PLAN:
  → Nếu migrate lỗi → revert batch update từ log
  → Entity phụ khôi phục status active

13. SLA XỬ LÝ SYSTEM_ISSUES (v1.2 — GPT)

Mức	Loại	Thời hạn xử lý	Ai xử
P1	Cấp 1 giữa entity nguy hiểm cao (checkpoint, field)	24 giờ	Tự động CHẶN + AI review ngay
P2	Cấp 2 checkpoint/field/DOT	3 ngày	Gemini CLI review + đề xuất
P3	Cấp 3 structural/tổ hợp/UI	7 ngày (review tuần)	Người phán xử quyết định

Issue quá hạn SLA → tự động escalate lên mức cao hơn + cảnh báo đỏ.

14. NGƯỜI PHÁN XỬ — PHÂN VAI (v1.1 Gemini + v1.2 GPT)

Vai trò	Ai	Làm gì	Khi nào
Phát hiện	DOT scripts (tự động)	Quét + ghi system_issues	Realtime + hàng đêm
Điền mô tả	Gemini/Claude (tự động)	Đọc code → sinh description → cập nhật	Sau tạo entity + batch đêm
Phân tích	Gemini CLI	Đọc issues → gộp → đề xuất → đăng thảo luận	Hàng tuần hoặc >10 issues
Quyết định	Người quản lý	Đồng ý/Từ chối đề xuất	Review đề xuất
Thực thi	Claude Code CLI	Migrate references + deprecate	Sau quyết định

15. NGƯỠNG SIMILARITY — CẤU HÌNH CÓ KIỂM SOÁT (v1.2 — GPT)

Ngưỡng là cấu hình, KHÔNG PHẢI chân lý cố định.

Loại entity	Ngưỡng Cấp 2 (semantic)	Ngưỡng Cấp 3 (Jaccard)	Ghi chú
Checkpoint Types	0.70	—	Nhạy vì nguy hiểm cao
DOT Tools	0.70	—
Fields	0.65	—	Nhiều alias → hạ ngưỡng
Workflows	0.75	0.80	Ít trùng → nâng ngưỡng
Tổ hợp Sets	—	0.80	Jaccard chính
Collections	0.75	0.70 (field overlap)

Hiệu chuẩn sau 30 ngày vận hành:

Tỷ lệ cảnh báo bị bác bỏ (false positive) > 30% → TĂNG ngưỡng
Phát hiện trùng lọt lưới (false negative) → GIẢM ngưỡng
Issue tồn đọng > 50 → xem xét SLA + ngưỡng
Threshold chỉ sửa KHI CÓ SỐ LIỆU, không sửa theo cảm tính

16. CHUẨN HOÁ TÊN + TỪ ĐIỂN ALIAS

Input: "CI phải GREEN trước khi merge"
→ lowercase → bỏ dấu → bỏ stop words → sort
→ Tra canonical dictionary: "ci green" → "ci_pass_concept"
→ Nối namespace: "[compliance]_ci_pass_concept"

Stop words: phải, cần, không, trước, sau, khi, của, cho, và, hoặc, là, được, để, với, trong, ngoài, về, từ, đến, mỗi, mọi

17. SỐ LIỆU ĐO HIỆU QUẢ (v1.2 — GPT)

Dashboard tối thiểu (hiện trên /knowledge/registries hoặc report đêm):

Metric	Ý nghĩa
Số create bị chặn Cấp 1	Engine hoạt động?
Số cảnh báo Cấp 2	Độ nhạy?
Tỷ lệ cảnh báo xác nhận trùng thật	Chính xác? (>50% = tốt)
Số duplicate merge thành công	Giá trị thực tế?
Số issue tồn đọng theo tuổi	Bottleneck?
Top entity types gây trùng nhiều nhất	Cần siết loại nào?
% entity có description đạt chuẩn	Engine có nguyên liệu?

18. KIẾN TRÚC KỸ THUẬT — DOT SCRIPTS

dot-duplicate-engine              ← ĐIỀU PHỐI (1 lệnh duy nhất)
  ├─ dot-dup-check-names          ← Cấp 1: namespace + chuẩn hoá + exact match
  ├─ dot-dup-check-semantic       ← Cấp 2: Qdrant vector search
  ├─ dot-dup-check-structure      ← Cấp 3: Jaccard tổ hợp
  └─ dot-description-quality      ← Kiểm tra mô tả đủ chất lượng

Hạ tầng đã có: Qdrant ✅, Directus ✅, system_issues ✅, Agent Data embeddings ✅

19. GỢI Ý TỰ ĐỘNG TRÊN GIAO DIỆN — AUTO-SUGGEST UX (v1.1 Gemini)

Khi người dùng gõ tên entity → hệ thống hiện danh sách "Gợi ý có sẵn" ngay dưới ô nhập liệu. Áp dụng Phase sau khi có form nhập liệu Tầng 4. Hiện tại AI nhận ID từ thông báo CHẶN = "auto-suggest cho AI".

20. LỘ TRÌNH TRIỂN KHAI

Phase	Nội dung	Effort
Phase 1	Chuẩn hoá tên + namespace + exact match + CHỈ ĐƯỜNG	Nhỏ
Phase 2	Qdrant semantic Cấp 2 + canonical dictionary khởi tạo	Trung bình
Phase 3	Jaccard Cấp 3 cho tổ hợp	Trung bình
Phase 4	Realtime Directus hook (check trước save)	Trung bình
Phase 5	dot-description-quality + AI tự điền batch	Nhỏ-Trung bình
Phase 6	Auto-suggest UX (Tầng 4 forms)	Trung bình
Phase 7	Gemini CLI auto-review + override form	Trung bình
Phase 8	Metrics dashboard + threshold calibration sau 30 ngày	Nhỏ
Phase 9	Test cases 70 ca (phụ lục)	Trung bình

Phase 1 làm TRƯỚC — effort thấp, giá trị cao.

21. REVIEW COUNCIL

Phiên bản	Reviewer	Đóng góp chính
v1.0	Claude Opus (soạn) + Huyen (yêu cầu)	Khung 3 cấp + 7 loại entity + kiến trúc scale
v1.1	Gemini Council	Chỉ đường, namespace, auto-suggest, người phán xử
v1.2	GPT Council	Định nghĩa pháp lý, override, canonical selection, migration, SLA, metrics, alias, threshold calibration
v1.2	Huyen	AI tự điền mô tả, chạy tự động (realtime + hàng đêm), DOT scripts tách module