Nghiệp vụ — AI

Bối cảnh nghiệp vụ

Module này có API AI assistance và service nội bộ để chấm điểm post circle, đánh giá report bằng OpenRouter JSON schema.

Ví dụ thực tế: client gọi endpoint của ai, 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/ai/ai.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/ai/service/ai.service.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/ai/promt/system.promt.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ó.

workers/evaluate.worker.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.

workers/evaluate.worker.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ó.

workers/evaluate.worker.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-AI-001	Request đi qua route/controller/service	Client gọi endpoint	Controller đọc request rồi service xử lý nghiệp vụ chính	Trace rõ từ route đến service	src/modules/ai/ai.routes.ts
BR-AI-002	Auth theo route thật	Endpoint có authorization	JWT được kiểm tra trước controller	Thiếu token bị chặn	src/modules/ai/ai.routes.ts
BR-AI-003	Validate bằng Zod nếu route có validate()	Request body/params/query	Sai schema trả 400	Client sửa field sai	src/modules/ai/ai.routes.ts
BR-AI-004	Repository là nơi chạm DB	Service cần dữ liệu	Service gọi repository/Prisma, controller không tự query	Dễ trace lỗi DB	src/modules/ai/promt/system.promt.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
Request đi qua route/controller/service	Client gọi endpoint	Controller đọc request rồi service xử lý nghiệp vụ chính	Ngăn dữ liệu sai đi sâu vào DB hoặc worker.
Auth theo route thật	Endpoint có authorization	JWT được kiểm tra trước controller	Ngăn dữ liệu sai đi sâu vào DB hoặc worker.
Validate bằng Zod nếu route có validate()	Request body/params/query	Sai schema trả 400	Ngăn dữ liệu sai đi sâu vào DB hoặc worker.
Repository là nơi chạm DB	Service cần dữ liệu	Service gọi repository/Prisma, controller không tự query	Ngăn dữ liệu sai đi sâu vào DB hoặc worker.

Edge Cases — Trường hợp ngoại lệ

Edge case 1

Public AI endpoints là stubs.

Nếu không hiểu điểm này, QA có thể viết thiếu case hoặc frontend có thể hiển thị trạng thái sai.

Edge case 2

JSON parse fail làm job fail.

Nếu không hiểu điểm này, QA có thể viết thiếu case hoặc frontend có thể hiển thị trạng thái sai.

Edge case 3

Model đang dùng openrouter/free.

Nếu không hiểu điểm này, QA có thể viết thiếu case hoặc frontend có thể hiển thị trạng thái sai.

Error Handling — Xử lý lỗi

Tình huống lỗi	Nguyên nhân	HTTP Status	Error Code	Message trả về	Cách recover
Unauthorized	Thiếu/sai token ở route protected	401	UNAUTHORIZED	Token invalid	Login lại hoặc refresh token.
Validation failed	Zod schema không pass	400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
Resource not found	Repository không tìm thấy record	404	NOT_FOUND	Resource not found	Refresh dữ liệu.
Forbidden	User không có quyền hoặc role không đúng	403	FORBIDDEN	Forbidden	Ẩn action trong UI.
External dependency fail	Redis/DB/provider lỗi	500	INTERNAL_SERVER_ERROR	Internal server error	On-call kiểm tra provider/log.

Lỗi cần alert ngay: DB/Redis/worker/provider ngoài fail liên tục, vì các flow chính có thể trả 500 hoặc mất side effect như search, email, notification.

Side Effects — Tác dụng phụ

Hành động	Khi nào xảy ra	Đồng bộ hay bất đồng bộ	Nếu thất bại thì sao?
DB read/write	Khi service cần dữ liệu bền vững	Đồng bộ	Request fail nếu DB fail.
Cache/queue/realtime	Nếu module gọi Redis/Pusher/jobs	Tùy flow	Có thể delay hoặc fail riêng.
External API	Nếu module gọi service ngoài	Bất đồng bộ hoặc đồng bộ	Phụ thuộc cấu hình provider.

FAQ — Câu hỏi thường gặp

Câu hỏi	Trả lời
Tôi bắt đầu đọc module ai từ đâu?	Bắt đầu ở src/modules/ai/ai.routes.ts, sau đó đi sang controller và service.
Lỗi validation nằm ở đâu?	Ở DTO Zod và middleware validate(). Route nào không gọi validate() thì không có lớp check này.
Side effect có chạy trong cùng request không?	Tùy flow. Nếu có producer/worker thì side effect chạy bất đồng bộ sau response.
Có chỗ nào chưa hoàn chỉnh không?	Xem phần Gotchas và các dòng [CẦN XÁC NHẬN].
QA nên test gì trước?	Happy path, thiếu token, sai DTO, resource không tồn tại, và side effect fail/defer.