Đọc site này thế nào
AIMY: phần mềm quản lý trung tâm Before/After School Care (giữ trẻ trước & sau giờ học) — đăng ký học, đặt suất, billing, nhân sự, báo cáo sự việc cho phụ huynh.
Trang này: cách tài liệu được tổ chức → bạn lấy đúng thứ cần, dù là người mới, kỹ sư, hay support.
Nguyên tắc trình bày: đi từ ngoài vào trong
Mỗi domain kể chuyện theo cùng một mạch, từ dễ đến sâu. Dừng ở tầng nào tùy nhu cầu:
| Trang | Trả lời câu hỏi | Hợp với ai |
|---|---|---|
| Tổng quan | Domain này là gì, giải quyết vấn đề gì, ai dùng? | Mọi người |
| Góc nhìn end-user | Người dùng cuối thao tác ra sao, thấy gì trên màn hình? | Mọi người, support |
| Khái niệm cốt lõi | Các thuật ngữ và "vật thể" chính trong domain là gì? | Mọi người |
| Kiến trúc hệ thống | Hệ thống gồm những thành phần nào, dữ liệu chảy thế nào? | Kỹ sư, kiến trúc |
| Luồng xử lý trong code | Code nào, queue/worker nào xử lý? | Kỹ sư |
| Case thường gặp | Tình huống thực tế và cách hệ thống phản ứng? | Kỹ sư, support |
Muốn xem đầy đủ ma trận page/domain và các ngoại lệ có chủ đích, đọc Bản đồ cấu trúc wiki.
Hợp đồng nội dung
Mỗi loại trang có một nhiệm vụ riêng: Overview định vị, End-user mô tả thao tác, Concepts giải thích ngôn ngữ và rule, Architecture/Data links giải thích hệ thống, còn Codebase/References giúp truy ngược về source. Khi một trang cần nhắc lại nội dung của trang khác, chỉ tóm tắt phần cần thiết rồi link về trang sở hữu.
Với trang Case thường gặp, đọc theo thứ tự: triệu chứng/câu hỏi → behavior đúng → cách kiểm tra → source anchor → Ví dụ thực tế. Cách này giúp support bắt đầu từ hiện tượng đang thấy, còn engineer vẫn có đường đi rõ ràng tới code và spec.
Các danh mục page/link như Đọc theo thứ tự, Liên quan và Các trang trong phần này dùng ordered list hoặc table để có thể tham chiếu bằng số; bullet list dành cho facts, notes và checklist không có thứ tự.
Quy ước trong tài liệu
- Ngôn ngữ: tiếng Việt là chính, mixed English ở thuật ngữ phổ biến/chuyên ngành (
NotificationJob,Enrollment,EntityEvent…) — dịch "thuần Việt" làm giảm nghĩa và khó tra cứu. Lần đầu xuất hiện có chú thích nghĩa. - Khối code & sơ đồ: ví dụ minh họa để hiểu, không phải bản sao chính xác của code.
- Sơ đồ: vẽ bằng Mermaid. Đọc theo chiều mũi tên; chú thích cạnh mũi tên cho biết "cái gì truyền sang cái gì".
Wiki tóm lược cho dễ hiểu, không phải đặc tả đầy đủ. Khi nghi ngờ chi tiết → đối chiếu hành vi thật của hệ thống hoặc hỏi team domain.
Ba "ứng dụng" bạn sẽ nghe nhắc tới
Hệ thống AIMY gồm 3 project độc lập (chi tiết ở Nền tảng):
| Tên | Là gì | Vai trò |
|---|---|---|
| Topi | Frontend React/UmiJS (cũ, maintenance) | Một phần giao diện admin |
| Tuke | Frontend Next.js (mới, đang phát triển) | Giao diện web hiện đại |
| Tux | Backend .NET 8 + Workers | API, nghiệp vụ, xử lý nền (queue/worker) |
Hầu hết "luồng xử lý bên trong" nằm ở Tux (backend + workers).
Đọc theo implementation hiện tại
Các trang có mục Implementation hiện tại dùng để khoanh vùng phần đã chạy ở code; ngày page được hiển thị bởi VitePress là mốc lần cập nhật gần nhất của trang. Với rule mới, đọc thêm block Ví dụ thực tế ngay sau rule để thấy cách áp dụng.
Nếu code và OpenSpec khác nhau, wiki ưu tiên behavior đang chạy và ghi phần spec chưa implement ra ngoài nội dung user-facing. Giữ nguyên các tên class, route, enum và anchor để kỹ sư có thể tìm ngược về code.
Ví dụ thực tế: OpenSpec mô tả background refresh nhưng code chưa có worker. → Đọc wiki theo behavior hiện tại: manual refresh/invalidate có, proactive refresh chưa có.