LIMS Native AI

Hệ thống Quản lý Phòng Thí Nghiệm (LIMS) thế hệ mới tích hợp trí tuệ nhân tạo, được xây dựng theo kiến trúc Monorepo gồm Backend NestJS và Frontend React + Vite.

---

Tổng Quan Kiến Trúc

APP 5/
├── backend/          # NestJS + TypeScript + PostgreSQL
├── frontend/         # React 18 + Vite + TypeScript
├── projectDocument/  # Tài liệu kỹ thuật & kế hoạch dự án
│   ├── masterPlans/  # Checklist & kế hoạch từng giai đoạn
│   ├── rules/        # Quy tắc phát triển (ruleV1.md)
│   ├── architecture/ # Sơ đồ cấu trúc DB, module
│   └── trackingPlans/# Theo dõi tiến độ kế hoạch con
└── base_doc/         # Tài liệu tham chiếu gốc

---

Tech Stack

Backend

Thành phần	Công nghệ
Framework	NestJS 10
Ngôn ngữ	TypeScript 5
Database	PostgreSQL (pg)
Auth	JWT + Passport + HttpOnly Cookie
Real-time	WebSocket (ws) — Dev Gateway
AI Engine	LLM Client (Giai đoạn 3)
Dev runner	ts-node-dev

Frontend

Thành phần	Công nghệ
Framework	React 18
Build tool	Vite 5
Ngôn ngữ	TypeScript 5
Editor	TinyMCE (React wrapper)
Icons	lucide-react
i18n	i18next + react-i18next

---

Cài Đặt & Khởi Chạy

Yêu Cầu Hệ Thống

• Node.js >= 18.x
• PostgreSQL >= 14
• npm >= 9.x

1. Clone repository

git clone <repository-url>
cd "APP 5"

2. Cài đặt Backend

cd backend
npm install
cp .env.example .env
# Mở file .env và điền đầy đủ thông tin kết nối

Xem chi tiết biến môi trường tại backend/.env.example và backend/README.md.

3. Cài đặt Frontend

cd ../frontend
npm install

File env frontend đã có sẵn .env.development với giá trị mặc định trỏ tới backend localhost:4000.

4. Chạy Development (2 terminal riêng biệt)

# Terminal 1 — Backend (cổng 4000)
cd backend
npm run dev

# Terminal 2 — Frontend (cổng 3000)
cd frontend
npm run dev

Dịch vụ	URL
Frontend	http://localhost:3000
Backend API	http://localhost:4000
WebSocket Dev	ws://localhost:4000/dev-socket

Lưu ý: Frontend đã cấu hình proxy — mọi request tới /api/* sẽ được tự động chuyển tiếp tới backend localhost:4000.

---

Luồng Xác Thực

Client (FE)  →  POST /auth/login  →  Backend
                                        ↓
                              Set-Cookie: authToken (HttpOnly JWT)
                                        ↓
             ←  Response user info  ←  Backend

Các request tiếp theo tự động gửi kèm cookie authToken

• Token được lưu trong HttpOnly Cookie (authToken) — bảo mật khỏi XSS.
• Frontend cũng lưu vào localStorage để API client tự động đính kèm vào header Authorization: Bearer.

---

Tính Năng Hiện Tại (Giai đoạn 1 → 2)

Dashboard Tiếp Nhận Mẫu

• Danh sách phiếu tiếp nhận với thống kê chỉ tiêu màu sắc: đã có biên bản / đã có kết quả / đã phân công / tổng số
• Modal chi tiết phiếu nhận mẫu, mẫu thử nghiệm và phiếu kết quả phân tích
• Phiếu kết quả tích hợp TinyMCE editor hỗ trợ cấu hình VILAS riêng từng mẫu

Chụp Ảnh Mẫu (Di Động)

• Truy cập qua QR Code hoặc link: /receipt/upload-img?sessionId=<token>&receiptId=<id>
• Tự động xác thực phiên qua sessionId trên URL
• Giao diện mobile-first, chọn mẫu thử và chụp ảnh đính kèm

---

Lộ Trình Phát Triển

✅ Giai đoạn 1 — Base cấu trúc (Hoàn thành)
   Khởi tạo NestJS, PostgreSQL schema, React + Vite, Auth, cấu trúc module

⏳ Giai đoạn 2 — Luồng nghiệp vụ cơ bản (Đang thực hiện)
   API CRUD Receipt/Sample/Analysis, Dashboard, trang chụp ảnh mẫu

🔜 Giai đoạn 3 — Tích hợp AI (Kế hoạch)
   AI Engine (LLM), prompt động, Function Calling, workspace chia đôi màn hình

Chi tiết từng giai đoạn:

• Phase 1 — Base
• Phase 2 — Core Business
• Phase 3 — AI Integration

---

Hệ Thống Log

Mọi hoạt động quan trọng được ghi vào backend/logs/app.log dưới định dạng JSONL:

{"time":"2026-07-02T01:00:00.000Z","level":"INFO","statusCode":"200","filePath":"src/modules/lab/receipt.service.ts","funcName":"getFullById","message":"..."}

Level: INFO | WARN | ERROR | AI | AUTH

---

Tài Liệu Kỹ Thuật

Tài liệu	Mô tả
backend/README.md	Hướng dẫn chi tiết backend, API endpoints, policy
projectDocument/rules/ruleV1.md	Quy tắc phát triển bắt buộc (naming, log, auth)
projectDocument/masterPlans/checklist.md	Checklist tổng quan 3 giai đoạn

---

Quy Tắc Đặt Tên

Toàn bộ codebase tuân thủ camelCase:

• Biến, hàm, file: receiptId, getFullById, authMiddleware.ts
• Cột database: receiptId, sampleName, technicianId
• Tuyệt đối không dùng snake_case hay kebab-case trong code

---

Đóng Góp

1. Đọc projectDocument/rules/ruleV1.md trước khi viết code.
2. Cập nhật checklist tiến độ tương ứng sau mỗi thay đổi quan trọng.
3. Mọi secret (password, API key, JWT secret) không được commit — chỉ lưu trong .env local.