Nghiệp vụ — Circle

Bối cảnh nghiệp vụ

Module này cho phép người dùng tạo cộng đồng nhỏ gọi là circle, mời thành viên, xử lý yêu cầu tham gia, đăng bài trong nhóm và dùng cơ chế HP/EXP để phản ánh chất lượng đóng góp.

Ví dụ thực tế: client gọi endpoint của circle, server kiểm tra token nếu route yêu cầu, validate dữ liệu, gọi service đúng domain, rồi ghi DB/cache hoặc enqueue job theo đúng nhánh trong code.

Luồng chính — Happy Path

src/modules/circle/circle.routes.ts

Request vào route. Bước này chuyển dữ liệu sang lớp tiếp theo theo pattern hiện có.

src/modules/circle/controller/circle.controller.ts

Middleware auth/validate chạy. Bước này chuyển dữ liệu sang lớp tiếp theo theo pattern hiện có.

src/modules/circle/service/circle.service.ts

Controller gọi service. Bước này chuyển dữ liệu sang lớp tiếp theo theo pattern hiện có.

src/modules/circle/service/circle-enery.service.ts

Service áp dụng rule nghiệp vụ. Đây là bước quan trọng nhất vì service quyết định request có được ghi dữ liệu, enqueue job hoặc bị trả lỗi.

src/modules/circle/repository/circle-post-quality-log.repository.ts

Repository/worker/provider thực thi. Bước này chuyển dữ liệu sang lớp tiếp theo theo pattern hiện có.

src/modules/circle/repository/circle-post-quality-log.repository.ts

Response trả về client. Bước này chuyển dữ liệu sang lớp tiếp theo theo pattern hiện có.

Business Rules — Quy tắc nghiệp vụ

Rule ID	Tên rule	Điều kiện kích hoạt	Hành động	Ví dụ minh họa	File kiểm tra
BR-CIRCLE-001	Chỉ member mới được đăng bài circle	Tạo post/reply	Không có CircleMember thì Forbidden	User ngoài circle bị chặn	circle.service.ts
BR-CIRCLE-002	Giới hạn 5 bài/giờ/user/circle	Tạo bài circle	Redis counter quá 5 thì throw RATE_LIMIT_EXCEEDED	Spam bài bị từ chối	circle.service.ts
BR-CIRCLE-003	Quản trị circle dựa trên role permission	Manage members/logs/join requests	Kiểm tra CIRCLE_ROLE_PERMISSIONS	Member thường không xem manage	circle.service.ts
BR-CIRCLE-004	Admin chỉ invite role MEMBER	Admin gửi email invitation	Admin invite role khác MEMBER thì Forbidden	Owner có quyền rộng hơn admin	circle.service.ts
BR-CIRCLE-005	Invitation có resend limit	Mời lại người cũ	User flow limit 5, admin email flow limit 3	Không spam email mời	circle.service.ts
BR-CIRCLE-006	Bài circle đi qua AI quality pipeline	Sau create post circle	Tạo CirclePostQualityLog pending rồi enqueue evaluation_queue	HP/EXP cập nhật sau	circle.service.ts + evaluate.worker.ts
BR-CIRCLE-007	Sacrifice cần karma đủ và không restriction	POST /sacrifice	Kiểm tra karma/restriction rồi update energy	Thiếu karma bị lỗi	circle.service.ts

Các rule trên được rút từ route/service/DTO/worker đã đọc. Nếu một rule ghi [CẦN XÁC NHẬN], phần code hiện tại là stub, TODO hoặc trả dữ liệu mock.

Validations — Kiểm tra dữ liệu đầu vào

Input Validation

Field	Kiểu	Required	Rule	Lỗi nếu vi phạm	Ví dụ hợp lệ	Ví dụ không hợp lệ
Authorization	header	Có với route protected	Bearer access token nếu cần	401	Bearer eyJ...	missing
params	string	Tùy endpoint	Không rỗng theo DTO route	400	publicId/code
query.take	number	Không	int dương, thường max 100 nếu DTO có	400	20	1000
body	object	Tùy endpoint	Theo DTO tương ứng	400	{"content":"Hello"}	{} thiếu field

Business Validation

Điều kiện kiểm tra	Khi nào chạy	Lỗi trả về	Lý do rule này tồn tại
Chỉ member mới được đăng bài circle	Tạo post/reply	Không có CircleMember thì Forbidden	Ngăn dữ liệu sai đi sâu vào DB hoặc worker.
Giới hạn 5 bài/giờ/user/circle	Tạo bài circle	Redis counter quá 5 thì throw RATE_LIMIT_EXCEEDED	Ngăn dữ liệu sai đi sâu vào DB hoặc worker.
Quản trị circle dựa trên role permission	Manage members/logs/join requests	Kiểm tra CIRCLE_ROLE_PERMISSIONS	Ngăn dữ liệu sai đi sâu vào DB hoặc worker.
Admin chỉ invite role MEMBER	Admin gửi email invitation	Admin invite role khác MEMBER thì Forbidden	Ngăn dữ liệu sai đi sâu vào DB hoặc worker.
Invitation có resend limit	Mời lại người cũ	User flow limit 5, admin email flow limit 3	Ngăn dữ liệu sai đi sâu vào DB hoặc worker.