Đặc tả nguyên mẫu kiểm tra trước xuất bản

Tài liệu sửa đổi 1.1 · Hợp đồng kỹ thuật 1 · 26/09/2026 · Chỉ kiểm gói tổng hợp, không cấp quyền.

1. Phạm vi

Công cụ tools/KIEM_TRA_TRUOC_XUAT_BAN.py chỉ đọc đầu vào được chỉ định.
Không nhập bộ sinh trang, quét toàn kho, tạo thư mục, ghi báo cáo hoặc truy cập mạng.
Không sửa HTML, sổ quyền, schema hoặc kho tri thức.
Q08 chưa được giải quyết. Nguyên mẫu không đóng T15.

Hàm validate_manifest(manifest, root) nhận đối tượng JSON đã giải mã và thư mục gốc.
CLI nhận --manifest FILE --root DIR; --json là cờ tùy chọn, mặc định luôn in JSON ra stdout.
Không có tham số đường dẫn báo cáo hoặc lệnh gọi bộ sinh trang.

2. Hợp đồng bản kê

Chỉ chấp nhận đúng năm trường cấp gốc. Trường dư làm dừng.

sha256 gồm đúng 64 ký tự hex thường, khớp toàn bộ byte nguồn.
Tham chiếu bằng chứng chỉ chứng minh file tồn tại trong gói, không chứng minh nội dung hay thẩm quyền.
Không tạo hồ sơ bằng chứng thật từ ví dụ này.

Ví dụ dưới đây hoàn toàn giả. Mã băm toàn số không cố ý không hợp lệ với file thông thường.

{
  "version": "cxk-publication-preflight/1",
  "release_id": "fictional-demo-001",
  "audience": "synthetic-internal",
  "entries": [
    {
      "path": "demo.md",
      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
      "output": "demo.html"
    },
    {
      "path": "fictional-evidence.txt",
      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
      "output": "fictional-evidence.txt"
    }
  ],
  "evidence_refs": ["fictional-evidence.txt"]
}

3. Đường dẫn và loại file

Đường dẫn tương đối dùng /, dài tối đa 240 ký tự.
Mỗi thành phần bắt đầu chữ/số ASCII; phần còn lại chỉ chữ/số, _, -, ..
Cấm thành phần rỗng, dấu chấm cuối, chuỗi .., tên thiết bị Windows và mọi dấu %.
Do đó cấm đường tuyệt đối, UNC, ổ đĩa, wildcard, mã hóa URL, truy vấn và luồng NTFS.
Không chấp nhận symlink, reparse point hoặc hardlink nhiều tên.
Kiểm cả các thư mục cha của nguồn và thư mục gốc.

Nguồn hỗ trợ .md, .txt, .png, .jpg, .jpeg, .gif, .webp; đuôi phải viết thường.
Markdown dự kiến thành .html; loại khác giữ đuôi. Đây chỉ là khai báo, không tạo đầu ra.
Cấm nguồn trùng và đích trùng khi bỏ phân biệt hoa/thường.
Cấm xung đột file/thư mục giữa các đường nguồn hoặc giữa các đường đích.
Đầu ra là tên logic; không kiểm trạng thái thư mục đầu ra thật.

Mọi file phải tồn tại, là file thường, đọc được và không rỗng.
Văn bản phải là UTF-8 không BOM, không chỉ có khoảng trắng.
Ảnh chỉ được kiểm byte và mã băm; chưa xác minh định dạng hay nội dung ảnh.

4. Tập con cú pháp được hỗ trợ

Đây không phải bộ phân tích Markdown đầy đủ. Cú pháp không rõ phải làm dừng.
Áp dụng cùng bộ quét cho .md và .txt để tránh né bằng đổi đuôi.

• Liên kết đơn: <code>📄 nhãn</code>; ảnh đơn: !<code>🖼️ nhãn (Sơ đồ phác đồ BYT)</code>.
• Nhãn không rỗng, không chứa dấu ngoặc vuông hoặc xuống dòng.
• Chấp nhận xuống dòng LF hoặc CRLF; sau chuẩn hóa CRLF, ký tự CR đơn còn lại làm dừng.
• Đích không có khoảng trắng, ngoặc tròn hoặc tiêu đề phụ.
• Tham chiếu: [nhãn][id], ![nhãn][id], [id][].
• Định nghĩa phải đứng riêng: [id]: file.txt, đúng một dấu cách sau dấu hai chấm.
• ID định nghĩa chỉ gồm chữ/số ASCII, _, -; đối chiếu không phân biệt hoa/thường.
• Định nghĩa trùng hoặc tham chiếu không có định nghĩa làm dừng.
• Mọi định nghĩa đều được kiểm, kể cả chưa sử dụng.
• Đích tương đối tính từ thư mục của nguồn; phải có tên chính xác trong entries.
• Chấp nhận file.md#anchor hoặc #anchor; anchor chỉ gồm chữ/số ASCII, _, -.
• Không kiểm anchor thực sự tồn tại. Không hỗ trợ giải mã URL hoặc chuẩn hóa anchor.

Mọi tài nguyên được tham chiếu phải nằm trong danh sách và khớp mã băm riêng.
Quét tất cả văn bản trong danh sách, không chỉ trang đầu. Không gọi mạng để kiểm đích từ xa.

5. Cú pháp bị từ chối

Cấm HTML thô, comment HTML, autolink, include, template, shortcode, wiki link và front matter.
Cấm code fence, inline code, dòng thụt bốn dấu cách, dòng bắt đầu tab, directive và escape bằng dấu gạch chéo ngược.
Bộ quét từ chối mọi ký tự <, >, gạch chéo ngược, backtick, ~, {, }, @, $, NUL.
Dòng bắt đầu ---, +++ hoặc .. cũng bị chặn.
Sau khi lấy liên kết hợp lệ, dấu [, ], !, : còn lại làm dừng.
Phần cú pháp đã lấy được thay bằng ranh giới xuống dòng, không nối các phần nguồn hai bên.
Nhờ đó không tạo tham chiếu giả từ những dấu ngoặc vốn không liền nhau.
Vì vậy văn xuôi hợp lệ theo Markdown thông thường vẫn có thể bị từ chối có chủ đích.
Cấm shortcut reference, nhãn lồng, đích có tiêu đề và cú pháp nhiều dòng.
Cấm URL từ xa, giao thức dữ liệu, đường truy vấn, đường cha và đường mã hóa.
Cấm HTML/CSS/JS/SVG/PDF/ZIP làm nguồn; chưa có bộ quét phụ thuộc đáng tin cậy cho các loại này.
Nguyên mẫu không khẳng định hiểu mọi phần mở rộng Markdown của builder tương lai.

6. Báo cáo và mã thoát

structural_status chỉ có technically_consistent hoặc blocked.
counts ghi số mục, file đọc được, phụ thuộc đã xét, phát hiện và lỗi đọc/phân tích.
Khi một file gặp lỗi cú pháp, số phụ thuộc không đại diện tổng phụ thuộc tiềm ẩn.
findings và errors chỉ ghi mã lỗi cùng chỉ số mục khi phù hợp; không ghi đoạn nguồn.

Ba trường luôn là false: build_executed, publication_authorized, human_approval_verified.

Thiếu tham số CLI trả 2 qua bộ phân tích tham số; trường hợp này không có báo cáo JSON.
Hàm nhận dict không thể phát hiện khóa đã bị bộ giải mã khác ghi đè.
CLI dùng bộ giải mã từ chối khóa trùng ở mọi cấp và hằng JSON không chuẩn.

7. Giới hạn và tích hợp còn chờ

Không xác minh chữ ký, danh tính, giấy phép, phê duyệt, y khoa hoặc dữ liệu nhạy cảm.
Không kết luận nội dung trong ảnh an toàn. Không kiểm quyền công bố từ tên file hoặc nhãn đối tượng.
Không chống tuyệt đối thay đổi file đồng thời giữa lúc kiểm và đọc.
Cần gói bất biến cùng cơ chế kiểm lại khi tích hợp; không dùng kết quả cũ cho nguồn đã đổi.
Không kiểm đầu ra cũ, tìm kiếm, sitemap, hub, tải xuống, xác thực hoặc thu hồi.

Chưa tích hợp builder, staging, kiểm đầu ra hay quy trình cấp quyền.
Mã thoát 0 không được dùng tự động để gọi builder hoặc cấp phép xuất bản.
Q08 và quyết định con người vẫn bắt buộc theo quy trình xuất bản.
T15 chưa được tuyên bố hoàn thành; chưa xác nhận tài liệu thật nào được phép công bố.

8. Kiểm thử

testing/scripts/test_publication_preflight.py chỉ tạo dữ liệu tổng hợp trong tmp_path.
Kiểm gói hợp lệ, cú pháp bị chặn, đường dẫn, cấu hình, mã băm, JSON và các mã thoát.
So byte và thời gian sửa file trước/sau lời gọi; chặn socket trong kiểm thử.
Có kiểm hardlink thật nếu hệ thống hỗ trợ và kiểm reparse bằng mô phỏng.
Đợt 3 thêm bốn ca sai về CR đơn và tham chiếu bị ghép; hai ca đúng kiểm CRLF và liên kết liền nhau.
Hàm tạo dữ liệu thử giữ nguyên byte xuống dòng, không để Windows tự đổi CRLF thành CRCRLF.
Không dùng kiểm mô phỏng làm bằng chứng cho mọi kiểu junction trên mọi hệ điều hành.
Nhánh chính phụ trách tích hợp, trạng thái và nhật ký; nguyên mẫu không tự sửa các hồ sơ đó.