---
name: backend-clean-architecture
description: Chuẩn kiến trúc Clean Architecture/DDD/Hexagonal, độ chính xác tài chính Decimal(18,4), cơ chế ghi sổ kép (Double-entry ledger), vòng đời máy chủ FastAPI (--reload) và dọn dẹp dữ liệu test (Teardown). Kích hoạt khi phát triển backend, thiết kế database PostgreSQL, viết API routes hoặc cấu hình kiểm thử.
---

# BACKEND CLEAN ARCHITECTURE & RELIABILITY STANDARDS

## 1. Kiến Trúc Lục Giác (Hexagonal Architecture / Ports & Adapters) & Ranh Giới DDD
- **Bốn tầng kiến trúc chuẩn mực (4 Strict Layers)**:
  - **Driving / Inbound Adapters (`presentation/`)**:
    - FastAPI Routers, CLI commands, Webhooks.
    - **Nhiệm vụ duy nhất**: Validate request schema (Pydantic), xác thực phiên (JWT/Role), và gọi Application Services/Command Handlers.
    - **CẤM TUYỆT ĐỐI**: Không mở DB connection (`with db.get_connection()`), không viết raw SQL (`cur.execute()`), không chạy DDL (`CREATE TABLE`).
  - **Application Layer (`application/`)**:
    - Use Cases, Orchestration, Command/Query Handlers, Service Facades.
    - **Nguyên tắc phụ thuộc**: Chỉ phụ thuộc vào Domain Core và tương tác với thế giới bên ngoài thông qua **Domain Ports**.
    - **CẤM TUYỆT ĐỐI**: Không import trực tiếp HTTP clients cấp thấp (`httpx`, `requests`, `urllib.request`). Không gọi trực tiếp REST endpoint của LLM bên ngoài (`openrouter.ai`, `generativelanguage.googleapis.com`).
  - **Domain Core (`domain/`)**:
    - Business Entities, Value Objects, Domain Events, Domain Services.
    - **Domain Ports**: Giao diện trừu tượng (`@runtime_checkable Protocol`) định nghĩa hợp đồng trao đổi dữ liệu (ví dụ: `EquipmentRepositoryPort`, `EmailNotificationPort`, `TelegramPort`, `ZaloGatewayPort`).
    - **Độc lập hoàn toàn**: 0% phụ thuộc vào Framework (FastAPI), CSDL (PostgreSQL/SQLAlchemy), ORM, hay thư viện mạng bên ngoài.
  - **Driven / Outbound Adapters (`infrastructure/`)**:
    - Concrete Repositories (`PostgresEquipmentRepository`, `PostgresZaloCrmRepository`): Chứa câu truy vấn SQL an toàn, transaction management.
    - External Service Adapters (`BrevoEmailAdapter`, `TelegramHttpAdapter`, `ZaloHttpAdapter`): Đóng gói toàn bộ các thư viện mạng (`httpx`, `aiohttp`).
    - AI Gateway: Tích hợp mô hình AI duy nhất qua `EnterpriseAiGateway` (Antigravity SDK native + auto-failover OpenRouter). CẤM hardcode endpoint LLM trong business logic.
- **Quy tắc Code Modularity**:
  - Giữ các file mã nguồn dưới 200-300 dòng; tách nhỏ thành các mixin / handler / adapter chuyên biệt.
  - Không tạo circular dependencies; quản lý import sạch sẽ theo một chiều (Presentation -> Application -> Domain <- Infrastructure).
- **Hàng Rào Ranh Giới Kiến Trúc (Architecture Boundary Gate)**:
  - Mọi thay đổi mã nguồn mới bắt buộc phải vượt qua: `pytest tests/test_architecture_boundary_enforcement.py` đạt **100% Passed**.

## 2. Xử Lý Giao Dịch & Độ Chính Xác Số Học Tài Chính
- **Nguyên tắc Sổ Kép (Double-Entry Ledger)**: Bất biến (Immutable Event Log) cho mọi biến động tài chính, dự toán và kho vật tư.
- **Khóa giao dịch**: Áp dụng Optimistic/Pessimistic Locking khi can thiệp hạn mức ngân sách và xuất/nhập kho.
- **Độ chính xác số học**:
  - **Tuyệt đối không dùng FLOAT hoặc DOUBLE** cho tiền tệ VNĐ và khối lượng BoQ.
  - Bắt buộc dùng `NUMERIC(18, 4)` hoặc `BIGINT` trong PostgreSQL và `Decimal` trong Python.

## 3. Vòng Đời Máy Chủ Backend & Auto-Reload
- Luôn khởi động máy chủ FastAPI/Uvicorn với cờ `--reload` (`python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload`).
- Trước khi nghiệm thu tính năng, kiểm tra tiến trình đang chạy để đảm bảo route/model mới nhất đã hot-reload.

## 4. Chính Sách Thu Dọn Dữ Liệu Kiểm Thử (Strict Automated Test Teardown)
- Toàn bộ các test tự động (`pytest tests/`) chèn dữ liệu kiểm thử vào DB (users, takeoffs, chat, rules...) **bắt buộc phải có cơ chế Teardown / Cleanup sạch sẽ 100%** (qua `finally`, `tearDown()`, hoặc `pytest fixture yield`).
- Tuyệt đối không để sót bản ghi mock/test (`TEST-%`, `API_CAD%`, `SAMPLE_CAD%`) trong DB sau khi test kết thúc.

## 5. Routing & API Gateway Constraints
- **API Gateway Prefix**: Mọi API Endpoints và UI Dashboards mới đều BẮT BUỘC phải tuân thủ prefix /v1/erp (Ví dụ: `@router.get("/v1/erp/dashboard/...")`). Tuyệt đối không mount routes ở root level nếu không API Gateway (Nginx/Cloudflare Tunnel) sẽ chặn và trả về 404 (Lỗi 'quên V1 vào end point').