Skip to content

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ứcNội dungVì sao tin được, hoặc không
Sinh từ sourceBảng, cột, khoá ngoại, hàm SQL, RLS policy, API, quyền, mã lỗi, route, job, migrationBộ 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 sourceMô tả bảng, cột, hàmLấ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 tayNghiệp vụ, khái niệm, lý do thiết kế, các trang kiến trúcNgườ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ượngCó mô tảTổngTỷ lệ
Bảng ứng dụng22222698%
Hàm SQL của dự án9011.51859%
Cột2243.2027%
Schema153839%

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.permissions
  • public.role_assignments
  • public.roles
  • public.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_events
  • spin.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ì saoHệ quả
Mô tả nghiệp vụ của từng bảng và từng cộtChỉ có COMMENT ON; chỗ nào thiếu thì tài liệu để trống có nhãnXem độ phủ ở trên
Bằng chứng cho phần lớn mục NFRPhầ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 đúngMá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ôngTruy 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 nhauViết tay; module nào chưa đối chiếu kỹ thì phần mô tả ngắn hơn19/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õ tayTrang A nói một số, trang B nói số khác
Gate docgen-check trong CITài liệu nói khác code
Mỗi trang sinh tự động ghi commit đã sinhKhông biết nội dung cũ đến đâu
ignoreDeadLinks: false khi buildLink chết
Sidebar sinh từ các trang có thật trên đĩaMục lục trỏ tới trang không tồn tại
Trang nàyGiấ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.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17