Giao diện
Phạm vi & độ tin cậy
Trang sinh tự động
Mọi số liệu dưới đây do bộ sinh đo trên schema sau khi chạy 820 migration, tại commit ad83b0aea. Trang này không viết tay con số nào — nếu có thì chính nó sẽ là chỗ sai đầu tiên.
Đọc trang này trước khi dùng tài liệu để ra quyết định. Nó khai rõ phần nào đáng tin đến mức nào, và phần nào còn thiếu.
Ba mức độ tin cậy
| Mức | Nội dung | Vì sao tin được, hoặc không |
|---|---|---|
| Sinh từ source | Bảng, cột, khoá ngoại, hàm SQL, RLS policy, API, quyền, mã lỗi, route, job, migration | Bộ sinh đọc thẳng từ code hoặc từ PostgreSQL. Gate docgen-check trong CI fail khi lệch, nên tài liệu không thể sai quá một pull request. |
| Rút từ mô tả có trong source | Mô tả bảng, cột, hàm | Lấy từ COMMENT ON trong migration. Không viết lại, không suy diễn. Độ phủ chưa đủ — xem ngay dưới. |
| Viết tay | Nghiệp vụ, khái niệm, lý do thiết kế, các trang kiến trúc | Người viết, dựa trên docs/technical/ và docs/sow/. Có thể lạc hậu so với code; mỗi trang ghi nguồn ở chân trang. |
Độ phủ mô tả trong database
| Đối tượng | Có mô tả | Tổng | Tỷ lệ |
|---|---|---|---|
| Bảng ứng dụng | 222 | 226 | 98% |
| Hàm SQL của dự án | 901 | 1.518 | 59% |
| Cột | 224 | 3.202 | 7% |
| Schema | 15 | 38 | 39% |
Cột mới phủ 7% là giới hạn lớn nhất của tài liệu này. 224 cột có mô tả tập trung ở những bảng quan trọng nhất (orders 20 cột, campaigns 17 cột, spin_rule_versions 10 cột, refund_cases 8 cột), còn phần lớn cột chỉ có tên và kiểu. Muốn tài liệu cột đầy đủ thì thêm COMMENT ON COLUMN vào migration — tài liệu tự nhận ở lần docgen sau, không phải sửa gì ở đây.
Chưa có mô tả
4 bảng ứng dụng chưa có COMMENT ON TABLE:
public.permissionspublic.role_assignmentspublic.rolespublic.tier_version_missions
Ngoài ra 4 bảng stub Supabase (auth, storage) cũng không có mô tả — đó là stub cho PostgreSQL thuần, không phải bảng ứng dụng.
RLS
RLS bật trên cả 226 bảng ứng dụng.
3 bảng không bật RLS còn lại đều là stub Supabase: auth.sessions, auth.users, storage.buckets.
Lệch giữa hợp đồng và database
Nhóm domain trong mục Cơ sở dữ liệu lấy từ docs/contracts/schema-registry. Khi đối chiếu registry với database thật:
Có trong database nhưng chưa có trong registry (2):
spin.wheel_change_eventsspin.wheels
Có trong registry nhưng không còn trong database (1):
public.skip_requests
Trạng thái dự án
Những điều này đúng tại thời điểm sinh tài liệu và không bị che:
- app-sale đang tạm dừng phát triển (#294). Quality gate không phân tích và không chạy test cho nó. Tài liệu vẫn mô tả app-sale vì code còn đó, nhưng đó không phải phần đang được phát triển.
- uat đang dừng deploy (#487).
- PiPoint tắt ở uat và production; ví PiPoint chỉ chạy thật ở dev và staging.
- production chưa được tạo. Mọi phát biểu về production là thiết kế dự kiến, không phải hệ thống đang chạy.
Tài liệu nguồn còn chỗ lạc hậu
docs/ của repo có hàng nghìn file Markdown, nhiều file đúng ở thời điểm viết rồi thành sai. Ví dụ docs/db/README.md ghi "migrations/ hiện rỗng; DB local chỉ còn Supabase stubs" — câu đó từ ngày reset 01/10/2026, trong khi thực tế đã có 820 migration và 226 bảng ứng dụng.
Vì vậy tài liệu này không nhúng toàn bộ docs/. Nó chỉ dùng những file đã được đối chiếu, và trang nào dựa trên một file docs/ thì ghi rõ tên file ở chân trang.
Giới hạn của bộ sinh
Những thứ sau chưa tự động hoá được, và tài liệu nói rõ thay vì lấp bằng nội dung viết tay có thể lạc hậu:
| Thiếu gì | Vì sao | Hệ quả |
|---|---|---|
| Mô tả nghiệp vụ của từng bảng và từng cột | Chỉ có COMMENT ON; chỗ nào thiếu thì tài liệu để trống có nhãn | Xem độ phủ ở trên |
| Bằng chứng cho phần lớn mục NFR | Phần lớn NFR là mục tiêu đo (thời gian, thông lượng, RPO/RTO); chứng minh cần một lượt đo trên môi trường yên tĩnh, kết quả nằm ngoài source | Đối chiếu tiêu chuẩn nêu rõ mục nào chưa nối |
| Truy vết là theo nhắc tên, không phải chứng minh cài đúng | Máy đọc được mã yêu cầu trong comment, nhưng không đọc được yêu cầu rồi kết luận code có đúng không | Truy vết yêu cầu nói rõ giới hạn này ngay đầu trang |
| Phần nghiệp vụ của trang module có độ sâu khác nhau | Viết tay; module nào chưa đối chiếu kỹ thì phần mô tả ngắn hơn | 19/19 module đều có mô tả, nhưng không đều nhau |
Mỗi mục trên là một việc có thể làm tiếp, không phải một giới hạn vĩnh viễn.
Tài liệu này không bao gồm
- Hướng dẫn cho người dùng cuối. Đây là tài liệu kỹ thuật.
- Đặc tả nghiệp vụ gốc. Nguồn chính thức là Word/PDF của Product trong
docs/user-story/original-from-product/. Tài liệu này mô tả cái đã làm, không thay thế cái được yêu cầu. - Bí mật vận hành. Không có khoá, mật khẩu, connection string hay giá trị secret nào — chỉ có tên biến môi trường.
- Lịch sử chi tiết từng đợt phát triển. Các đợt có hồ sơ riêng trong
docs/implementation-plans/; ở đây chỉ có index và tóm tắt, vì nội dung đó là lịch sử và dễ bị đọc nhầm thành trạng thái hiện tại.
Cách tài liệu tự chống sai
| Cơ chế | Chặn gì |
|---|---|
| Mọi số liệu do bộ sinh ghi, trang Markdown không chứa số gõ tay | Trang A nói một số, trang B nói số khác |
Gate docgen-check trong CI | Tài liệu nói khác code |
| Mỗi trang sinh tự động ghi commit đã sinh | Không biết nội dung cũ đến đâu |
ignoreDeadLinks: false khi build | Link chết |
| Sidebar sinh từ các trang có thật trên đĩa | Mục lục trỏ tới trang không tồn tại |
| Trang này | Giấu giới hạn |
Nếu bạn thấy tài liệu nói khác code, đó là lỗi của bộ sinh hoặc của một trang viết tay — báo lại, đừng tự suy ra ý đúng.