# Tài Liệu API: Phân Hệ Quản Lý Dự Án (Projects)

> [!NOTE]
> Mọi Endpoint đều phải tuân thủ API Gateway Prefix là `/v1/erp` (theo Core Law #6).
> Định dạng dữ liệu Trả về (Response) và Gửi đi (Request) tuân thủ nghiêm ngặt Pydantic Schemas.

## 1. Tạo Mới Dự Án (Create Project)
**Endpoint:** `POST /v1/erp/projects`
**Module:** Projects
**Luồng xử lý:** `CreateProjectCommand` -> `CommandHandler` -> Event `ProjectCreatedIntegrationEvent`.

### Request Body (JSON)
```json
{
  "name": "Dự án Khu dân cư A",
  "project_code": "KDC-A-2026",
  "start_date": "2026-09-01",
  "description": "Xây dựng hạ tầng cơ sở cho khu dân cư A"
}
```

### Response
- **201 Created**: Tạo thành công.
```json
{
  "project_id": "uuid-1234-...",
  "status": "success"
}
```
- **400 Bad Request**: Lỗi nghiệp vụ (Domain Validation Failed).
- **401/403**: Lỗi phân quyền (User Access).

## 2. Lấy Chi Tiết Dự Án (Get Project Details)
**Endpoint:** `GET /v1/erp/projects/{project_id}`
**Module:** Projects
**Luồng xử lý:** `GetProjectDetailsQuery` -> `QueryHandler` (Raw SQL on Views).

### Response
- **200 OK**:
```json
{
  "id": "uuid-1234-...",
  "code": "KDC-A-2026",
  "name": "Dự án Khu dân cư A",
  "created_at": "2026-08-31T12:00:00Z"
}
```
- **404 Not Found**: Không tìm thấy dự án.

## 3. Cập Nhật Trạng Thái Dự Án (Update Project Status)
**Endpoint:** `PATCH /v1/erp/projects/{project_id}/status`
**Module:** Projects

### Request Body (JSON)
```json
{
  "status": "IN_PROGRESS",
  "reason": "Đã nhận được giấy phép xây dựng"
}
```

## Lưu ý về tích hợp
Các API trên chỉ thao tác dữ liệu nội bộ của schema `projects`. Các thông tin về "Ngân sách", "Dự toán (Takeoff)", "Nhân sự" của dự án này sẽ không được gộp vào API `/v1/erp/projects`. Để lấy dữ liệu tổng hợp, Frontend (Client) cần gọi thêm các API đọc (Queries) của các module tương ứng (như `Accounting` hoặc `HR`), hoặc hệ thống sẽ cung cấp một **BFF (Backend For Frontend)** API để tổng hợp dữ liệu.