Checklist chất lượng docs
Trang này dùng để kiểm tài liệu trước khi gửi thầy hoặc trước ngày báo cáo. Mục tiêu là tránh ba lỗi: chữ lỗi font, câu chữ mơ hồ, và claim không có evidence.
Checklist nội dung
| Mục kiểm | Đạt khi |
|---|---|
| Trả lời nhanh | Có dashboard cho câu trả lời 60 giây, 12 luồng nghiệp vụ, file/bảng cần nhắc và câu nên/không nên nói |
| Kiểm toán độ sẵn sàng | Có trang gom yêu cầu gốc thành audit: font, flow, thông tin, UX/UI, câu chữ, file code, DB count, evidence |
| Công nghệ | Có nêu backend, frontend, database, deploy, storage, video, offline |
| Luồng nghiệp vụ | Có auth, course authoring, publication, student learning, assessment, upload, video, payment, Wiii |
| Database | Có số đúng: 78 application tables, 2 materialized views, 107 migration SQL files; có trang đối chiếu DB sống/DBeaver |
| Vị trí file code | Có trang riêng chỉ cách mở file khi sửa UI, logic, API, database |
| Sơ đồ thư mục | Có SVG cây thư mục, SVG luồng mở file và Mermaid flow để giải thích cấu trúc code |
| UX/UI và design system | Có trang riêng giải thích vì sao UI hợp lý cho LMS, token màu, sửa layout/màu, Toast/ConfirmDialog và smoke desktop/mobile |
| Wiii safety | Có ranh giới data-wiii-id, data-wiii-click-safe, preview/diff, danh sách action nguy hiểm |
| Video/offline | Có Shaka, ABR, R2, video worker, PWA, IndexedDB/Dexie |
| Payment | Có VNPay/SePay, payment_transactions, refund/payout và cảnh báo vùng nguy hiểm |
| Scale/load | Không đoán số concurrent; nêu load test, metric và hướng scale |
| Vấn đáp | Có câu trả lời ngắn, bộ câu hỏi luyện và kịch bản demo |
| Search | Search ra class, endpoint, table, thuật ngữ, câu hỏi bảo vệ |
| Cloudflare docs deploy | Có runbook Cloudflare Pages/Workers, _headers, wrangler.toml, custom domain checklist và caveat không tự deploy production |
Checklist font và tiếng Việt
| Mục kiểm | Cách kiểm |
|---|---|
| Browser hiển thị tiếng Việt đúng | Mở http://127.0.0.1:4010/, kiểm tiêu đề và bảng |
| Không có mojibake trong source docs | Chạy script kiểm các chuỗi lỗi encoding như U+00C3 + byte Latin-1, U+00E1 U+00BA, U+00E1 U+00BB, U+00E2 U+20AC; không coi chữ tiếng Việt hợp lệ là lỗi |
| Font stack ổn | Body dùng system-ui, Segoe UI, Noto Sans, Arial, sans-serif |
| Mermaid không lỗi font | Sơ đồ render được và dùng font stack hệ thống |
| Terminal PowerShell bị méo chữ | Không coi đây là lỗi file nếu browser/Node đọc UTF-8 đúng |
Checklist UX/UI docs
| Mục kiểm | Đạt khi |
|---|---|
| Sidebar có thứ tự học | Chạy local -> kiến trúc -> coverage -> diagram -> backend/frontend/DB -> flow -> Q&A |
| Search dễ dùng | Placeholder tiếng Việt rõ, Ctrl+K hoạt động, query phổ biến ra kết quả |
| Có trang kiểm cuối | Search Kiểm toán độ sẵn sàng, claim hygiene, font evidence, readiness audit ra trang kiểm toán |
| Có ảnh sơ đồ thư mục | Search Sơ đồ thư mục, directory map, luồng file ra trang sơ đồ; SVG render không vỡ |
| UX/UI app có nơi tra riêng | Search UX/UI, design token, đổi màu, course editor UX ra trang UX/UI và design system |
| Có runbook deploy docs | Search Cloudflare Pages, docs.holilihu.online, wrangler pages deploy ra trang deploy |
| Bảng dài không phá layout | Desktop/mobile không overflow toàn trang; table tự scroll ngang |
| Trang dài có heading rõ | Mỗi trang có H2 theo cụm ý, không dồn thành đoạn dài |
| Mobile đọc được | Không có text tràn ngang ngoài table/code block |
| Print/demo ổn | Sidebar/header ẩn khi print theo CSS hiện tại |
Checklist evidence
| Claim | Evidence cần có |
|---|---|
| “Docs build được” | bundle exec jekyll build pass |
| “Không gãy link nội bộ” | Link-check _site broken 0 |
| “Search hoạt động” | Browser smoke gõ query và có kết quả |
| “Mobile không vỡ layout” | Browser smoke viewport mobile, bodyOverflow = 0 |
| “Schema count đúng” | Generator từ Flyway: 78 tables, 2 materialized views, 107 migrations |
| “UX/UI đã có căn cứ” | Trang UX/UI nêu file source: teacher dashboard, course editor, learning player, shared sidebar, Toast/ConfirmDialog |
| “Font không lỗi” | Source encoding check không có mojibake marker, browser render đúng |
Lệnh kiểm nhanh
Build docs:
docker exec lms-docs-site bash -lc "cd /workspace/docs-site && bundle exec jekyll build"
Kiểm container docs:
docker ps --filter name=lms-docs-site
docker logs lms-docs-site --tail 50
Sinh lại schema catalog:
cd E:\Sach\Sua\LMS_hohulili
node scripts\generate-schema-catalog.mjs
Kiểm số bảng trong catalog:
cd E:\Sach\Sua\LMS_hohulili
node -e "const fs=require('fs'); const s=fs.readFileSync('docs-site/study/sql-schema-catalog.md','utf8'); console.log({tables:(s.match(/<details id=/g)||[]).length,migrations:(s.match(/\\| \\d+ \\| `V/g)||[]).length})"
Quy tắc câu chữ khi gửi thầy
- Nói “theo Flyway hiện tại” khi nêu số bảng/schema.
- Nói “cần load test” khi bị hỏi số người dùng chịu tải.
- Nói “backend kiểm quyền cuối cùng” khi bị hỏi bảo mật route.
- Nói “learner đọc publication snapshot” khi bị hỏi vì sao sửa bài mà student chưa thấy.
- Nói “Wiii phải qua preview/diff” khi bị hỏi AI có tự sửa dữ liệu không.
- Tránh claim “done” nếu không kèm build/test/smoke/link/screenshot hoặc evidence cụ thể.
Nếu tài liệu hoặc UI nhìn lỗi font trong terminal, hãy kiểm lại bằng browser và Node UTF-8 trước. PowerShell có thể hiển thị sai ký tự Việt dù file nguồn vẫn đúng UTF-8.