Luật Chống Trùng Lặp v1.2 — Điều 14 (Gemini + GPT Council Review)
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 |