AI — OpenRouter scoring và report evaluation

Mục đích

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ề mặt kỹ thuật, module này bám pattern route -> controller -> service -> repository. Những việc chậm hoặc phụ thuộc service ngoài được đẩy sang Redis/BullMQ khi code có producer tương ứng.

Phạm vi

Trong phạm vi ✓	Ngoài phạm vi ✗
Các endpoint dưới /api/v1/ai	UI frontend và copy hiển thị trong app
Validation, business rules, side effects từ code	Ý định product không thể thấy trong source
DB/cache/queue/service ngoài module gọi trực tiếp	SLA chính thức nếu không có trong config/code

Công nghệ & thư viện sử dụng

Thành phần	Công nghệ	Phiên bản	Lý do chọn	Ghi chú
HTTP	Express	5.1.0	Router/middleware rõ ràng	package.json
Validation	Zod	3.25.76	Validate request trước controller	Route nào có validate() mới enforce
DB	Prisma + MySQL/MariaDB	Prisma 7	Repository truy cập database	schema.prisma
Async	BullMQ + Redis	BullMQ 5	Tách tác vụ nền	Không phải module nào cũng enqueue

Cấu trúc file

Sơ đồ này cho thấy module được chia theo vai trò: route nhận URL, controller đọc request, service quyết định nghiệp vụ, repository chạm database.

Đây là cấu trúc lặp lại trong hầu hết module, không dùng thư viện vẽ ngoài.

src/modules/ai/ai.routes.ts

File này là một phần của luồng ai. Đọc nó để trace request từ entrypoint tới nghiệp vụ.

snippet định vị

// đọc file này để trace module ai
import ... from "src/modules/ai/ai.routes.ts"

src/modules/ai/service/ai.service.ts

File này là một phần của luồng ai. Đọc nó để trace request từ entrypoint tới nghiệp vụ.

snippet định vị

// đọc file này để trace module ai
import ... from "src/modules/ai/service/ai.service.ts"

src/modules/ai/promt/system.promt.ts

File này là một phần của luồng ai. Đọc nó để trace request từ entrypoint tới nghiệp vụ.

snippet định vị

// đọc file này để trace module ai
import ... from "src/modules/ai/promt/system.promt.ts"

workers/evaluate.worker.ts

File này là một phần của luồng ai. Đọc nó để trace request từ entrypoint tới nghiệp vụ.

snippet định vị

// đọc file này để trace module ai
import ... from "workers/evaluate.worker.ts"

Dependency map

Module này dùng các dependency ở bên trái và có thể được module bên phải gọi hoặc phụ thuộc gián tiếp.

Mũi tên đi vào là dependency module dùng; mũi tên đi ra là nơi kết quả được tiêu thụ.

Tóm tắt luồng chính

Worker gọi aiService, prompt yêu cầu JSON, service parse kết quả rồi worker cập nhật DB.