# DSCons Enterprise API Reference (Production 2026)

Tài liệu chi tiết toàn bộ các điểm cuối REST API & Server-Sent Events (SSE) của hệ sinh thái DSCons.

---

## 1. Bóc Tách Bản Vẽ & Dự Toán BoQ (`/v1/takeoff`)

| Method | Endpoint | Mô Tả |
| :--- | :--- | :--- |
| `POST` | `/v1/takeoff/upload` | Upload bản vẽ kỹ thuật (PDF/DWG/DXF/PNG), tự động bóc tách khối lượng BoQ |
| `POST` | `/v1/takeoff/batch-upload` | Upload hàng loạt nhiều file bản vẽ |
| `POST` | `/v1/takeoff/smart-batch-upload` | Upload song song cặp đôi Bản vẽ + HSMT, tự động phân loại & ghép cặp |
| `GET` | `/v1/takeoff` | Danh sách các hồ sơ bóc tách bản vẽ kèm bộ lọc |
| `GET` | `/v1/takeoff/{takeoff_id}` | Chi tiết hồ sơ bóc tách, chỉ số tổng hợp (bê tông, ván khuôn, thép, đất) |
| `GET` | `/v1/takeoff/{takeoff_id}/items` | Danh sách 66+ đầu việc BoQ chi tiết |
| `PUT` | `/v1/takeoff/{takeoff_id}/items/{item_id}` | Chỉnh sửa trực tiếp khối lượng/đơn giá một dòng BoQ |
| `POST` | `/v1/takeoff/{takeoff_id}/chat-train` | Huấn luyện trực tiếp với AI Quỳnh QS, nhận giải trình và gợi ý sửa sai |
| `POST` | `/v1/takeoff/{takeoff_id}/chat-train-stream` | **SSE Streaming Endpoint**: Nhận luồng phản hồi thời gian thực từ AI Quỳnh |
| `GET` | `/v1/takeoff/{takeoff_id}/chat-history` | Lấy toàn bộ lịch sử hội thoại của Studio |
| `DELETE`| `/v1/takeoff/{takeoff_id}/chat-history` | Làm mới/Xóa sạch lịch sử hội thoại Studio |
| `GET` | `/v1/takeoff/learned-rules` | Danh sách các quy tắc rút kinh nghiệm vĩnh viễn |
| `POST` | `/v1/takeoff/learned-rules` | Thêm mới quy tắc kinh nghiệm thủ công |
| `DELETE`| `/v1/takeoff/learned-rules/{rule_id}` | Xóa quy tắc kinh nghiệm |
| `GET` | `/v1/takeoff/{takeoff_id}/export-excel` | **Xuất Excel Phụ Lục 03a** & Bảng Giá Thị Trường 2026 (.xlsx) |
| `POST` | `/v1/takeoff/{takeoff_id}/sync-wbs` | Đồng bộ 1-Click toàn bộ BoQ sang tiến độ WBS dự án |
| `DELETE`| `/v1/takeoff/{takeoff_id}` | Xóa hồ sơ bóc tách và các file liên quan |
| `DELETE`| `/v1/takeoff/superadmin/clear-all` | Xóa sạch toàn bộ hồ sơ bóc tách (Super Admin only) |

---

## 2. Hóa Đơn Điện Tử & Đối Soát Thuế (`/v1/invoices`)

| Method | Endpoint | Mô Tả |
| :--- | :--- | :--- |
| `POST` | `/v1/invoices/upload` | Upload XML hóa đơn điện tử GDT NĐ 123 |
| `GET` | `/v1/invoices` | Danh sách hóa đơn mua vào/bán ra |
| `GET` | `/v1/invoices/{invoice_id}` | Chi tiết hóa đơn và các dòng hàng hóa/dịch vụ |
| `GET` | `/v1/invoices/kpis` | Tổng hợp chi phí, VAT đầu vào, công nợ |
| `POST` | `/v1/invoices/sync/auto` | Kích hoạt quét tự động hóa đơn từ email/máy chủ |

---

## 3. 4 Trụ Cột Kinh Doanh Định Sơn (`/v1/four-pillars`)

| Method | Endpoint | Mô Tả |
| :--- | :--- | :--- |
| `GET` | `/v1/four-pillars/summary` | Tổng quan doanh thu và phân bổ chi phí theo 4 Trụ Cột |
| `GET` | `/v1/four-pillars/pillar/{pillar_id}/details` | Chi tiết hợp đồng và hóa đơn theo từng Trụ Cột |
| `POST` | `/v1/four-pillars/classify-invoice` | Phân loại tự động hóa đơn vào đúng Trụ Cột |

---

## 4. Quản Lý Dự Án & WBS (`/v1/projects`)

| Method | Endpoint | Mô Tả |
| :--- | :--- | :--- |
| `GET` | `/v1/projects/management` | Danh sách dự án thi công và tiến độ |
| `POST` | `/v1/projects/crud` | Tạo mới hoặc cập nhật thông tin dự án |
| `POST` | `/v1/projects/{project_id}/wbs/generate` | Sinh cây công việc WBS tự động bằng AI |
| `GET` | `/v1/projects/{project_id}/wbs` | Cây WBS và danh sách mốc nghiệm thu |

---

## 5. Giá Vật Tư & Đối Soát Nhà Nước (`/v1/material-prices`)

| Method | Endpoint | Mô Tả |
| :--- | :--- | :--- |
| `GET` | `/v1/material-prices/published` | Tra cứu giá công bố Sở Xây dựng Hải Phòng theo kỳ |
| `GET` | `/v1/material-prices/compare` | So sánh chênh lệch giá mua Định Sơn với giá Nhà nước |
| `POST` | `/v1/material-prices/sync-state` | Đồng bộ dữ liệu giá công bố mới nhất |

---

## 6. Xác Thực & Người Dùng (`/v1/auth`)

| Method | Endpoint | Mô Tả |
| :--- | :--- | :--- |
| `POST` | `/v1/auth/register` | Đăng ký tài khoản người dùng mới |
| `POST` | `/v1/auth/login` | Đăng nhập hệ thống, cấp JWT Token |
| `GET` | `/v1/auth/me` | Lấy thông tin tài khoản đang đăng nhập |
| `GET` | `/v1/auth/users` | Danh sách người dùng nội bộ |
| `PATCH`| `/v1/auth/users/{user_id}/status` | Kích hoạt hoặc khóa tài khoản |
| `PATCH`| `/v1/auth/users/{user_id}/role` | Phân quyền vai trò mới |

---

## 7. Điều Hành & Tự Động Hóa AI (`/v1/company`, `/v1/autonomous`)

| Method | Endpoint | Mô Tả |
| :--- | :--- | :--- |
| `GET` | `/v1/company/operational-state` | Snapshot trạng thái vận hành toàn diện |
| `GET` | `/v1/company/operational-state/stream` | **SSE Stream**: Cập nhật trạng thái vận hành thời gian thực |
| `GET` | `/v1/autonomous/sessions` | Danh sách các phiên chạy tự động của Agent |
| `POST` | `/v1/autonomous/trigger-session` | Kích hoạt phiên chạy AI tự động theo lịch |