# Kế hoạch Đề xuất Tính năng Toàn diện: Phân loại & Khai phá Tri thức Hoá đơn

Mục tiêu: Nâng cấp phân hệ Hoá đơn (Invoices) để hỗ trợ phân loại sâu theo bản chất nghiệp vụ (Thương mại, Dịch vụ) và khai phá tri thức (Knowledge Discovery) từ dữ liệu thực, phục vụ trực tiếp cho hệ sinh thái ERP Định Sơn (DSCons).

## User Review Required

- Việc tự động phân loại hoá đơn phụ thuộc vào nội dung các dòng chi tiết (items) và chiều hoá đơn (input/output). Nếu một hoá đơn bao gồm *cả* hàng hóa thương mại và dịch vụ thi công, chúng ta cần quyết định xem sẽ lấy tỷ trọng cao nhất làm phân loại chính cho hoá đơn, hay tách hoá đơn thành nhiều "phần nghiệp vụ" (business portions).
- Cần xác nhận bộ danh mục con (subcategory) xem đã bao quát toàn bộ nghiệp vụ của 4 Trụ cột Định Sơn chưa.

## Design Decisions
- **Hoá đơn phức hợp (Complex Invoices)**: Được phân loại là **Hỗn hợp (Mixed)** khi một hoá đơn bao gồm cả chi tiết thuộc nhóm Thương mại (vật tư) và Dịch vụ (vận chuyển, thi công).
- **Phân loại chéo (Cross-referencing từ hoá đơn đầu vào)**: Để phân biệt chính xác giữa "Cho thuê lại" (Thương mại) và "Cho thuê máy móc thiết bị" (Dịch vụ) đối với hoá đơn đầu ra, hệ thống sẽ tham chiếu lịch sử hoá đơn đầu vào. Nếu thiết bị đó được thuê vào (có hoá đơn đầu vào thuê ca máy), thì đầu ra sẽ là "Cho thuê lại". Nếu thiết bị thuộc sở hữu của công ty, thì đầu ra sẽ là "Cho thuê máy móc thiết bị".

## Proposed Changes

### 1. Database Schema Updates
Cần bổ sung các cột phân loại vào bảng `erp_invoices` (Sẽ tạo file migration SQL mới `db/migrations/0013_invoice_detailed_classification.sql`).

#### [NEW] `db/migrations/0013_invoice_detailed_classification.sql`
- Thêm cột `business_category` (VARCHAR): `commercial` (Thương mại), `service` (Dịch vụ), `mixed` (Hỗn hợp).
- Thêm cột `business_subcategory` (VARCHAR) để phân loại chi tiết:
  - Commercial: `purchase_in` (mua hàng vào), `sales_out` (bán hàng ra), `machine_rental_in` (thuê ca máy), `machine_sublease_out` (cho thuê lại).
  - Service: `equipment_leasing` (cho thuê thiết bị), `transport_hire` (vận chuyển thuê), `construction_work` (thi công công trình).
- Tạo Index trên các cột này để phục vụ tốc độ truy vấn BI/Analytics cao.

### 2. Application Logic: Invoice Truth Classifier Update

Cập nhật service trích xuất & phân loại hoá đơn để tự động gán nhãn nghiệp vụ (Business tagging) ở cấp độ Hoá đơn (Invoice Level), thay vì chỉ ở cấp độ Dòng chi tiết (Item Level).

#### [MODIFY] `app/modules/invoices/application/invoice_truth/classifier.py`
- Bổ sung hàm `classify_invoice_business_type(invoice, items)`:
  - Phân tích danh sách `items` đã được phân loại (`OWNED_EQUIPMENT`, `RENTAL_EQUIPMENT`, `WAREHOUSE_MATERIAL`, `SUBCONTRACT_SERVICE`).
  - Kết hợp với `direction` (`input` vs `output`) để suy luận logic.
  - Ví dụ: `direction=input` + Đa số item là `WAREHOUSE_MATERIAL` => `commercial / purchase_in`.
  - Ví dụ: `direction=output` + Đa số item là `RENTAL_EQUIPMENT` => Phân tích thêm seller/buyer để quyết định là `commercial / machine_sublease_out` hay `service / equipment_leasing`.

### 3. Analytics & Knowledge Discovery UI (Khai phá Tri thức)

Đề xuất bổ sung các báo cáo & Dashboard BI (Dark Slate UI) chuyên biệt:

1. **Dashboard Tối ưu hoá Máy móc (Machinery ROI Analytics)**
   - Khai phá tương quan giữa tổng chi phí "Thuê ca máy" (input) và doanh thu "Cho thuê lại / Cho thuê thiết bị" (output).
   - Thuật toán Gợi ý: Đề xuất "Nên mua hay nên thuê tiếp?" bằng cách tính toán điểm hoà vốn (Break-even) dựa trên chi phí thuê mướn hằng tháng.
2. **Kiểm soát Dòng tiền Thầu phụ & Vận chuyển (Subcontractor & Transport Cost Radar)**
   - Phân tích các hoá đơn "Vận chuyển thuê" và "Thi công công trình".
   - Đối chiếu với hệ thống **Định mức AEC (aec-pricing-norms)** để phát hiện các hoá đơn vận chuyển/nhân công có đơn giá cao bất thường (Anomaly Detection).
3. **Phân tích Cấu trúc Lợi nhuận (Profit Margin Drift)**
   - Tách bạch biên lợi nhuận giữa "Thương mại thuần túy" (mua đi bán lại vật tư) vs "Dịch vụ giá trị gia tăng" (thi công).

#### [NEW] `app/static/invoices_knowledge_discovery.html`
- Giao diện Dashboard mật độ cao (Bloomberg style), sử dụng Recharts hoặc D3.js.
- Các bộ lọc đa chiều: Theo danh mục Thương mại/Dịch vụ, Dự án, Khoảng thời gian.

#### [MODIFY] `app/modules/invoices/presentation/invoice_routes.py`
- Thêm các API endpoints phục vụ Analytics:
  - `GET /api/invoices/analytics/business-breakdown`
  - `GET /api/invoices/analytics/machinery-roi`
  - `GET /api/invoices/analytics/cost-anomalies`

## Verification Plan

### Automated Tests
- `pytest tests/test_invoice_classifier.py -v`: Chạy bộ test mới để kiểm chứng logic phân loại hoá đơn tự động (đạt 100% Passed).
- `pytest tests/test_invoice_analytics_routes.py -v`: Kiểm tra các API trả về dữ liệu Dashboard chính xác định dạng JSON.

### Manual Verification
- Sử dụng **Playwright** hoặc Test tự động trên Trình duyệt để load trang `invoices_knowledge_discovery.html`, kiểm tra hiển thị biểu đồ Dark Slate theme, lọc theo loại hoá đơn (Thương mại vs Dịch vụ) đảm bảo không lỗi UI, không tràn Toast.