Mục lục
Vì sao có dự án này · Tính năng · Kiến trúc · Chấm điểm · Ảnh chụp · Cài đặt · Cấu hình · Kết nối GitLab · Harness repo · API · Phát triển · Release · Bảo mật
Vì sao có dự án này
Khi nhiều dev dùng AI "vibecoding" trên nhiều repo, mỗi repo có harness riêng (README, AGENTS.md, CLAUDE.md, subagent, skill, tài liệu tính năng), người review không thể đọc hết từng MR. ASDLC Review tự clone repo, nạp framework chung và harness của repo đó, review theo bộ tiêu chí chi tiết (convention, kiến trúc, đặt tên, “vì sao làm vậy?”), chấm điểm, comment lại cho tác giả để họ cải thiện, và gom số liệu cho leaderboard và báo cáo cuối kỳ.
Tính năng
- Nhiều cách trigger: webhook GitLab, comment
/review hoặc @mr-reviewer review, dán link trên giao diện, API chat, poller định kỳ.
- Hiểu harness của repo: đọc README, AGENTS.md, CLAUDE.md, skill, subagent và tài liệu tính năng trong giới hạn ngân sách ngữ cảnh.
- Phân tích tĩnh + AI: secret, debug code, test bị skip, suppress lint, TODO… chạy tất định; AI tìm vấn đề còn lại, kèm bằng chứng và câu hỏi “tại sao”.
- Điểm tất định: LLM không tự cho điểm; công thức + cổng chặn tính điểm 0–100.
- AI đa nhà cung cấp:
claude CLI, codex CLI hoặc API tương thích OpenAI.
- Dashboard: tổng quan, danh sách review, chi tiết finding (có phản hồi đồng ý/không), leaderboard Bayesian, thành viên, repo, báo cáo
.md/.csv.
- Desktop: vỏ Electron tuỳ chọn; server cũng chạy headless được.
Kiến trúc
Backend là micro-module: 14 module độc lập, không import lẫn nhau, mỗi module sở hữu logic và dữ liệu riêng, chỉ lộ index.ts. Chỉ app/ (composition root) nối chúng qua public API và Port/Adapter. Luật được kiểm bằng máy (pnpm arch).
Luồng review
Cấu trúc thư mục
apps/
server/ Fastify API + webhook + worker
src/kernel/ config, logger, errors, event-bus, exec, db, clock, http
src/modules/<m>/ 14 module: domain/ application/ infra/ + index.ts + MODULE.md
src/app/ composition root: http/, workflows/, adapters/
prisma/schema/ mỗi module một file .prisma (không quan hệ chéo)
web/ React 19 + Vite + Tailwind v4 + shadcn/ui, design token, dark mode (features/<x>/ độc lập)
desktop/ vỏ Electron mỏng
packages/contracts/ DTO + zod dùng chung
frameworks/asdlc/ framework chung: ~50 tiêu chí, mức độ, cổng chặn
docs/ tools/arch/ tài liệu, bộ kiểm luật kiến trúc
Chấm điểm tất định
deduction = severity × confidence × sizeFactor; hạng mục lấy trung bình có trọng số; cổng chặn: lộ secret ≤ 30, lỗi bảo mật critical ≤ 49, có blocker ≤ 59. Chi tiết và công thức leaderboard: docs/SCORING.md.
Ảnh chụp
| Danh sách review | Chi tiết finding |
|---|
| |
| Leaderboard thi đua (podium top 3, animation, confetti) | Báo cáo cuối kỳ |
| |
Giao diện dùng shadcn/ui + Tailwind với token màu (sáng/tối); ảnh chụp tĩnh, trên app thật podium có animation.
Ảnh chụp dùng dữ liệu demo giả (apps/server/scripts/seed-demo.ts).
Cài đặt
Yêu cầu
| |
|---|
| Node.js | 22+ |
| pnpm | 10+ |
| git | có trong PATH |
| AI | claude hoặc codex CLI đã đăng nhập, hoặc OPENAI_API_KEY |
| Redis | không bắt buộc: mặc định hàng đợi chạy trong process và lưu vào SQLite (REDIS_URL=sqlite); chỉ đặt redis://… khi chạy nhiều server |
Chạy từ mã nguồn
git clone https://github.com/nguyendinhphongdx/asdlc-review.git
cd asdlc-review
cp .env.example .env # tuỳ chọn: token GitLab nhập được trên UI
pnpm install
pnpm redis # tuỳ chọn: docker compose up -d redis
pnpm db:push # tạo SQLite (cũng tự chạy lần đầu)
pnpm build # build web
pnpm dev # server :4319 + web :5173
Production: pnpm build rồi pnpm --filter @mrd/server start (server phục vụ luôn web). Hoặc tải gói ở Releases, giải nén và chạy các bước trên.
Chạy desktop
pnpm desktop
Cấu hình (.env)
| Biến | Ý nghĩa |
|---|
GITLAB_URL, GITLAB_TOKEN, GITLAB_WEBHOOK_SECRET | Dự phòng; thường nhập trên UI (ưu tiên giá trị lưu trong DB). Webhook không có secret thì bị từ chối |
MRD_SECRET_KEY | Khoá mã hoá token trong DB (≥ 16 ký tự). Bỏ trống: tự tạo data/secret.key |
GITHUB_TOKEN, GITHUB_WEBHOOK_SECRET | Cho GitHub (đang phát triển) |
BOT_MENTION | Từ khoá trong comment để trigger review |
REVIEW_PROVIDER | claude-cli | codex-cli | gemini-api | openai-compatible |
CLAUDE_MODEL, CLAUDE_MAX_BUDGET_USD | Model và trần chi phí mỗi review |
OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL | Provider tương thích OpenAI |
REDIS_URL | sqlite (mặc định), memory hoặc redis://… |
DATA_DIR, DATABASE_URL | Nơi lưu repo cache và SQLite |
INLINE_MIN_SEVERITY, MAX_INLINE_COMMENTS | Điều khiển comment inline |
POLL_INTERVAL_MIN | >0 bật poller (khi không nhận được webhook) |
Kết nối GitLab
Làm theo docs/SETUP.md: nhập URL + token ở Cài đặt → Kết nối (token được mã hoá trong DB), bấm Kiểm tra kết nối, thêm repo ở Repository (có nút tạo webhook tự động), rồi dán link MR hoặc comment /review.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
