Luồng chính của circle
complexity 5 happy path statefulLuồng này bắt đầu khi client gọi endpoint của /api/v1/circle và kết thúc khi API trả JSON response hoặc lỗi chuẩn hóa.
Mỗi mũi tên là một lần gọi thật trong kiến trúc route → controller → service → repository/worker.
| # | Từ | Đến | Message/Method | Dữ liệu truyền đi | Dữ liệu trả về | Ghi chú |
|---|---|---|---|---|---|---|
| 1 | Client | Router | /api/v1/circle | HTTP request + token/body | Route match | Endpoint thật trong route file. |
| 2 | Router | Middleware | authorization/validate | headers/body/query/params | req.user hoặc parsed body | Route protected dừng nếu token sai. |
| 3 | Controller | Service | service method | DTO + userId | domain result | Controller không tự quyết rule phức tạp. |
| 4 | Service | Repository/Provider | Prisma/Redis/Queue/API | domain payload | record/job/result | Side effect xảy ra ở đây. |
| 5 | Service | Controller | return result | record/result | response data | Lỗi throw qua error handler. |
3
src/modules/circle/service/circle.service.ts
Bước service là trọng tâm: code kiểm tra nghiệp vụ, gọi repository, quyết định enqueue job hoặc gọi provider ngoài.
Luồng lỗi phổ biến
| Điểm fail | Điều kiện | Kết quả |
|---|---|---|
| Unauthorized | Thiếu/sai token ở route protected | 401 Token invalid |
| Validation failed | Zod schema không pass | 400 Validation failed |
| Resource not found | Repository không tìm thấy record | 404 Resource not found |
| Forbidden | User không có quyền hoặc role không đúng | 403 Forbidden |
| External dependency fail | Redis/DB/provider lỗi | 500 Internal server error |