Source document: docs/knowledge/KNOWLEDGE-PUBLISHING-SPEC.md
Source version: 1.0.0
Generated time: 2026-07-06T14:59:18.019Z
Owner: Engineering (Enablement)
Audience: Internal
Status: Approved

Knowledge Publishing Specification — Canonical Docs → Academy

Đặc tả xuất bản (spec). Định nghĩa cách mọi tài liệu Markdown canonical được chuyển thành nội dung học (Academy lessons).
Đây là đặc tả, không phải website, không sinh lesson, không triển khai.
Repository luôn là Source of Truth. Academy là view suy dẫn (derived) — không bao giờ tự sửa nội dung.
Phiên bản: 1.0.0 · Ngày: 2026-07-06.

Nguyên tắc nền (bất biến)

Repository là Source of Truth. Academy chỉ trình bày lại, không sở hữu tri thức.
Academy không chỉnh sửa nội dung. Mọi sửa đổi tri thức xảy ra ở Repository, rồi Academy tái sinh.
Mỗi lesson truy về đúng một tài liệu canonical. Không lesson nào không có nguồn.
Không trùng lặp tri thức. Một sự thật, một nơi (kế thừa knowledge-index/06-KNOWLEDGE-LIFECYCLE).
Không copy-paste thủ công. Nội dung được suy dẫn có truy vết, không chép tay.

1. Purpose — Mục đích

Chuẩn hoá cách chuyển tài liệu canonical (docs/) thành nội dung học có cấu trúc, giữ Repository là nguồn duy nhất. Đặc tả này để đội Knowledge/Enablement vận hành Academy như một lớp trình bày tái sinh được từ Repository, không phải một kho tri thức thứ hai.

2. Canonical Source Rule — Quy tắc nguồn canonical

Nguồn hợp lệ = tài liệu ở trạng thái Approved trong vòng đời tri thức (knowledge-index/06). Tài liệu Draft/Deprecated/Archived không được xuất bản.
Sổ đăng ký nguồn = knowledge-index/01-DOCUMENT-MAP. Academy chỉ lấy nguồn từ đây; không tự khai nguồn ngoài bản đồ.
Ánh xạ: một lesson ⇒ đúng một tài liệu nguồn. Một tài liệu ⇒ nhiều lesson (mục 3).
Thuật ngữ lấy từ knowledge-index/04-GLOSSARY; Academy không định nghĩa lại thuật ngữ.
Corpus khởi đầu (ví dụ, không giới hạn): bộ Commercial Release v1.0 (docs/commercial/*) theo COMMERCIAL-RELEASE-v1.0.
Tài liệu tác nghiệp/nội bộ nhạy cảm chỉ xuất bản vào Academy nếu bản đồ nguồn cho phép và đúng phân tầng đối tượng (mục 6).

3. Lesson Generation Rules — Quy tắc sinh lesson

Đơn vị sinh: mỗi mục logic của tài liệu nguồn (thường là mỗi section cấp hai) ⇒ một Knowledge Card (mục 4). Vì vậy một tài liệu sinh ra nhiều lesson.
Chỉ biến đổi, không thêm tri thức. Cho phép: chia nhỏ, tóm tắt, đặt lại cấu trúc, thêm mục tiêu học / câu hỏi kiểm tra / điều hướng *suy ra từ* nguồn. Cấm: thêm sự thật, số liệu, cam kết không có trong nguồn.
Truy vết bắt buộc: mỗi phát biểu nghiệp vụ trong lesson phải tồn tại ở nguồn (anchor tới section). Nếu cần một sự thật chưa có ⇒ sửa Repository trước, rồi tái sinh — không thêm vào Academy.
Suy dẫn, không chép tay: lesson được sinh từ nguồn bằng phép biến đổi xác định (deterministic), lặp lại cho cùng kết quả; không có bước copy-paste thủ công.
Không trùng lặp: nếu hai nguồn chồng chủ đề, chỉ nguồn owner (một chủ đề một owner — 06) sinh lesson; nguồn kia liên kết tới, không sinh trùng.

4. Knowledge Card Structure — Cấu trúc thẻ tri thức

Knowledge Card = đơn vị lesson nhỏ nhất, truy về một section nguồn.

Front-matter (bắt buộc):

Trường	Ý nghĩa
`card_id`	Định danh ổn định
`title`	Tiêu đề lesson
`source_path`	Đường dẫn tài liệu canonical (một nguồn)
`source_version`	Phiên bản nguồn tại lúc sinh (từ Change Log của nguồn)
`source_sections`	Anchor(s) section nguồn được dùng
`source_hash`	Băm nội dung nguồn (hoặc các section) — cho đồng bộ phiên bản
`audience`	Đối tượng (Founder / Sales / Customer …)
`learning_objectives`	Mục tiêu học (suy ra từ nguồn)
`prerequisites`	Card tiên quyết (nếu có)
`tags`	Chủ đề/segment
`sync_state`	`current` / `stale` / `orphaned` (mục 7)

Body: khái niệm → vì sao quan trọng → điểm chính (mỗi điểm truy về section nguồn) → kiểm tra hiểu (câu hỏi suy ra từ nguồn).

Provenance footer (bắt buộc): liên kết canonical + source_version ("Nguồn sự thật: <source_path> v<version>"). Không có provenance ⇒ card không hợp lệ, không xuất bản.

5. Learning Path Structure — Cấu trúc lộ trình học

Learning Path = tập có thứ tự các Knowledge Card; Path không chứa tri thức riêng, chỉ thứ tự + khung dẫn dắt.
Path tham chiếu card; card tham chiếu nguồn ⇒ chuỗi truy vết Path → Card → Canonical.
Ví dụ khung (thứ tự phản ánh workflow canonical, không thêm nội dung): Phạm vi (White Label) → Discovery → Định giá → Đề xuất → Pilot.
Path có thể theo vai trò (Founder / Sales) hoặc theo hành trình — nhưng mọi card trong path vẫn suy về nguồn canonical của nó.

Nhất quán đặt tên với Repository: tiêu đề card giữ tên chủ đề canonical; không đặt tên trái nguồn.
Đồ thị liên kết phản chiếu quan hệ tài liệu (knowledge-index/03-RELATIONSHIP-MAP, 07-NAVIGATION); cross-link giữa card = ánh xạ từ mục *Related Documents* của nguồn.
Phân tầng đối tượng: tách rõ card hướng-khách-hàng vs nội bộ; không lộ nội dung nội bộ cho đối tượng ngoài.
Một chủ đề một điểm vào chuẩn: phản chiếu "một chủ đề, một owner doc"; không có hai card cùng dạy một chủ đề từ hai nguồn.
Không ngõ cụt: mỗi card có đường tới nguồn canonical và tới path chứa nó.

7. Version Synchronization — Đồng bộ phiên bản

Cơ chế phát hiện lệch (spec, chưa triển khai):

Mỗi card lưu source_version + source_hash tại thời điểm sinh.
Kiểm đồng bộ so source_hash/source_version đã lưu với trạng thái hiện tại của nguồn:
current — khớp: card còn đúng.
stale — nguồn đổi (băm khác / Change Log bump): card cần tái sinh. Đây là tín hiệu tự động thoả Release Gate ("cập nhật Repository ⇒ nhận diện nội dung Academy cần tái sinh").
orphaned — nguồn bị Deprecated/Archived/xoá: card gỡ xuất bản.
Trigger: cập nhật Change Log của tài liệu canonical (đổi version) hoặc thay đổi nội dung section ⇒ đánh dấu mọi card tham chiếu là stale.
Không drift ngầm: card stale/orphaned không được hiển thị như nội dung hiện hành.

8. Publication Workflow — Quy trình xuất bản

Quy trình suy dẫn, tái chạy được (spec, không triển khai):

Chọn nguồn từ Document Map (chỉ Approved).
Trích section theo quy tắc sinh (mục 3).
Sinh Knowledge Card kèm front-matter + provenance (mục 4).
Lắp Learning Path (mục 5) + điều hướng (mục 6).
Kiểm hợp lệ: provenance đầy đủ · không tri thức mới · đúng phân tầng đối tượng.
Kiểm đồng bộ phiên bản (mục 7); đánh dấu stale/orphaned.
Duyệt (mục 9) → xuất bản / tái sinh.

Mọi lần chạy trên cùng nguồn + cùng phiên bản ⇒ cùng kết quả (không sáng tạo nội dung mới).

9. Review Policy — Chính sách duyệt

Owner duyệt: theo knowledge-index/05-DOCUMENT-OWNERS — owner của nhóm tài liệu nguồn duyệt các card sinh từ nhóm đó (vd nội dung thương mại → Founder/Sales).
Tiêu chí duyệt: (a) trung thành với nguồn — không thêm sự thật; (b) provenance đầy đủ; (c) đúng đối tượng; (d) không trùng card khác.
Sửa ở nguồn, không ở Academy: nếu duyệt phát hiện thiếu/sai, sửa tài liệu canonical rồi tái sinh — cấm vá trực tiếp lesson.
Duyệt trước khi xuất bản; card stale phải được tái sinh + duyệt lại trước khi hiển thị lại.

10. Change Log — Nhật ký thay đổi

Phiên bản	Ngày	Thay đổi
1.0.0	2026-07-06	Tạo đặc tả xuất bản tri thức (canonical → Academy): quy tắc nguồn, quy tắc sinh lesson, cấu trúc Knowledge Card, Learning Path, điều hướng, đồng bộ phiên bản, quy trình xuất bản, chính sách duyệt. Kế thừa knowledge-index (lifecycle/owners/document-map/glossary). Không website, không sinh lesson, không triển khai.

Nguồn sự thật (Source of Truth): docs/knowledge/KNOWLEDGE-PUBLISHING-SPEC.md · v1.0.0 · sinh tự động lúc 2026-07-06T14:59:18.019Z. Trang này là view suy dẫn — không sửa trực tiếp.