Bản đồ nền tảng
Trang này là nguồn sự thật duy nhất về cấu trúc hệ thống Conan School. Cả người vận hành lẫn AI trợ lý đều đọc từ đây trước khi sửa bất cứ thứ gì.
Đọc trang này trước
Nếu bạn (hoặc AI) sắp sửa code, hãy đọc Mô hình dữ liệu và Quy tắc triển khai trước. Phần lớn lỗi trong lịch sử dự án đến từ ba cạm bẫy được ghi ở đó.
Các site trong nền tảng
| Domain | Thư mục repo | Vai trò | Cloudflare |
|---|---|---|---|
api.conan.school | api.conan.school/ | API trung tâm (Hono + OpenAPI) | Workers |
tokyo.conan.school | com.conan.school/ | Cổng thành viên (Builder Community) | Pages conan-com |
www.conan.school | www.conan.school/ | Web marketing công khai | Pages |
admin.conan.school | admin.conan.school/ | Trang quản trị | Pages admin-conan-school |
docs.conan.school | docs.conan.school/ | Tài liệu (trang này) | Pages docs-conan-school |
mentors.conan.school | mentors.conan.school/ | Cổng mentor | Pages |
play.conan.school | play.conan.school/ | Trải nghiệm tương tác | Pages |
video.conan.school | video.conan.school/ | Nền tảng video | Pages |
Hạ tầng dùng chung
Toàn bộ nền tảng chạy chỉ trên Cloudflare, không có máy chủ nào khác.
- D1, cơ sở dữ liệu chính,
conan-platform-production - Workers AI + AI Gateway (
conan-gateway), mọi lời gọi mô hình đều đi qua gateway để có log và cache - Workflows, tác vụ nhiều bước, có thử lại (Member Intelligence, sinh sách)
- R2, lưu ảnh và media
- KV, cache
- Vectorize, tìm kiếm ngữ nghĩa
Luồng xác thực
Cổng thành viên Tokyo không gọi thẳng API bằng tên miền chéo. Nó dùng proxy cùng nguồn:
Trình duyệt → tokyo.conan.school/api/* (Pages Function)
→ api.conan.school/api/* (kèm cookie thành viên)Vì vậy /api/session trả 404 khi gọi thẳng api.conan.school là đúng, route đó do Pages Function của Tokyo phục vụ, không phải API trung tâm.
Ba tầng middleware xác thực trong API:
| Middleware | Hành vi | Dùng cho |
|---|---|---|
authMiddleware | Bắt buộc đăng nhập, 401 nếu không | Hầu hết /api/user/* |
optionalAuthMiddleware | Cho phép khách vãng lai, userId có thể undefined | Nội dung công khai |
tenantMiddleware | Bắt buộc header x-school-id | Toàn bộ API đa trường |
Cạm bẫy đã từng gây lỗi 500
Với optionalAuthMiddleware, c.get('userId') có thể là undefined. Viết c.get('userId')! chỉ là lời hứa suông với TypeScript, không kiểm tra lúc chạy, truyền undefined vào D1 sẽ ném D1_TYPE_ERROR và trả 500. Luôn kiểm tra thật trước khi dùng.
Đa trường học (multi-tenant)
Mọi truy vấn dữ liệu phải lọc theo school_id. Trường mặc định của Tokyo:
5c000000-0001-4000-8000-000000000001Client bắt buộc gửi header x-school-id; thiếu header sẽ nhận 400 Missing x-school-id.
Đọc tiếp
- Mô hình dữ liệu, hai họ bảng và tiền tố
legacy_ - Quy tắc triển khai, CI/CD và điều tuyệt đối không được làm
- Conan Tool Plane, lớp năng lực và quản trị cho các agent cloud
- Mô hình chương trình học, Course → Unit → Concept → Hành trình khám phá → Quiz