feat: add guide

docs/CONVENTIONS.md

@@ -0,0 +1,91 @@
+# APLP Backend — Conventions
+
+| | |
+| --- | --- |
+| **Status** | Draft |
+
+## 1. Naming & Package
+
+- Base package: `com.aplp.backend`
+- Mỗi module: `com.aplp.backend.<module>.<layer>` với layer = `api | application | domain | persistence` (xem `ARCHITECTURE.md`).
+- Tên class theo responsibility:
+  - Controller: `XxxController`
+  - Use case: `XxxUseCase` hoặc `XxxService`
+  - Request/Response DTO: `XxxRequest`, `XxxResponse`
+  - Aggregate/Root: tên domain concept (vd `Learner`, `Course`)
+  - Repository interface: `XxxRepository` (định nghĩa ở domain)
+
+## 2. Layer Rules
+
+| Layer | Được phép | Cấm |
+| --- | --- | --- |
+| `api` | AuthN/authorization (framework), input validation, DTO mapping | Business rules |
+| `application` | Orchestrate use case, transaction, call domain/persistence | Nhúng business rules riêng |
+| `domain` | Business logic, invariants, domain services, repository interface | Spring/JPA/HTTP dependencies |
+| `persistence` | Repository impl, JPA entities, mappers | Business logic |
+
+- **Domain không import Spring/JPA/HTTP.**
+- Persistence entities tách biệt (hoặc mappers) khỏi domain model nếu cần.
+
+## 3. Transaction
+
+- Transaction mở ở **Application** layer (`@Transactional` trên use case/service).
+- Không ném transaction qua domain khi chỉ để đọc.
+- Repository phương thức read nên read-only transaction khi cần.
+
+## 4. Validation
+
+- **Input/API validation** ở `api` layer (bean validation trên DTO).
+- **Business invariant** trong `domain` (domain exception).
+- Response lỗi dùng format đồng nhất (vd `ApiError` với code + message).
+
+## 5. Errors & Exceptions
+
+- `DomainException` cho lỗi business; mapping sang HTTP status ở `api` layer.
+- Error response nhất quán: `code`, `message`, `details` (tuỳ thỏa thuận).
+- Kèm `traceId`/requestId để dễ debug (Phase 0).
+- Error code dùng **global enum `ErrorCode`** ở `common/api` (kèm HTTP status); mở rộng bằng cách thêm hằng số khi có module mới.
+
+## 6. DTO Mapping
+
+- Không để JPA entity lọt ra ngoài `persistence`/`api` response.
+- **Mapping thủ công** (static method) trong repository impl / DTO factory — quyết định ở Phase 0 (không dùng MapStruct cho giai đoạn này; thêm khi có justification).
+
+## 7. Repository
+
+- Interface repository của module ở `domain`; implementation ở `persistence`.
+- Chỉ expose các method cần thiết cho use case, không leek Query/spec toàn module.
+- Query đặc thù (search, aggregation) nằm trong repository implementation.
+
+## 8. Domain Events (khi cần)
+
+- Dùng để tách rời side-effect giữa module (vd assessment hoàn thành → cập nhật adaptive state).
+- Không lạm dụng: nếu đồng bộ đơn giản và cùng transaction, gọi trực tiếp qua interface.
+- Nếu dùng Spring events: publish ở application layer, không trong domain.
+
+## 9. Config & Secrets
+
+- Cấu hình theo environment (`application.yml`, profile dev/prod).
+- **Không commit secret/key vào repo.** Dùng env vars hoặc bí quyết quản lý (vault) khi có.
+- Không log secret/token/password.
+
+## 10. Testing
+
+- Unit test cho `domain` + `application`.
+- Test repository/persistence khi cần.
+- Integration test cho API layer.
+- Quyết định framework/test DB ở Phase 0.
+
+## 11. Code Style
+
+- Java theo tiêu chuẩn project (indent 4 spaces — xác nhận khi setup).
+- Code của backend **không comment thừa**; tên rõ nghĩa.
+- `@author`/metadata không bắt buộc.
+
+## 12. Open Questions
+
+| ID | Question | Status |
+| --- | --- | --- |
+| CON-001 | Dùng MapStruct hay mapping thủ công? | **Resolved**: thủ công (Phase 0) |
+| CON-002 | Error code convention (enum per module vs global)? | **Resolved**: global `ErrorCode` trong `common/api` |
+| CON-003 | JPA entities tách hay dùng chung domain model? | **Resolved**: tách riêng (`*JpaEntity` trong `persistence`, domain model trong `domain`) |