Hoan thien core finance v2 - Calculation Pipeline, Form Templates

AGENTS.md

@@ -174,6 +174,39 @@
 
 ---
 
+### 3.5. Form Templates (Biểu mẫu in ấn)
+**Kiến trúc:** Mail Merge Engine - Word-style template với merge fields.
+
+**Models:** `FormTemplate`, `FormField`, `FormPrintLog`
+
+**FormTemplate:**
+- `name`, `code`, `target_model` (Contract/Product/Customer)
+- `html_template`: Nội dung HTML với placeholder `{{ma_truong}}`
+- `paper_size`: A4/A5/Letter
+
+**FormField (Merge Fields):**
+- `code`: Tên biến trong template (ví dụ: `ten_khach_hang`)
+- `source_type`: `db_column` | `db_relation` | `formula` | `input` | `static`
+- `source_config`: JSON cấu hình (tên cột, công thức, relation path...)
+- `format`: `text` | `number` | `currency` | `date` | `percent`
+- `decimal_places`: Số chữ số thập phân
+
+**Cách hoạt động:**
+1. Admin tạo template HTML, chèn `{{ten_khach_hang}}`
+2. Định nghĩa FormField: `ten_khach_hang` lấy từ `contract.customers.0.full_name`
+3. Khi in: `MailMergeService::render()` evaluate tất cả fields → thay vào template
+4. Snapshot được lưu vào `FormPrintLog`
+
+**Filament Resource:**
+- `FormTemplateResource` → CRUD biểu mẫu với Repeater fields
+
+**Services:**
+- `MailMergeService::evaluateFields()` - Tính toán giá trị tất cả fields
+- `MailMergeService::render()` - Render HTML cuối cùng
+- `MailMergeService::savePrintLog()` - Lưu snapshot + rendered HTML
+
+---
+
 ## 4. CÁC COMMAND IMPORT DỮ LIỆU
 
 ### `import:products-excel {file=sanpham.xlsx}`
@@ -227,6 +260,8 @@
 - [x] **Appendix Resource:** Form + Table đầy đủ
 - [x] **Settlement Resource:** Form + Table đầy đủ
 - [x] **Discount Engine:** Tính toán tự động chiết khấu + hiển thị `final_value` trong ContractForm
+- [x] **Calculation Pipeline:** Kiến trúc tính toán tường minh (Step-by-step) với làm tròn tại mỗi bước
+- [x] **Form Templates:** Mail Merge Engine cho phiếu tính giá, HĐ, phụ lục - Admin tự tạo template
 
 ### 5.2. Đang dở / Cần tiếp tục
 - [x] **Dashboard thống kê:** Đã tạo `ContractStatsOverview` + `UpcomingPaymentsTable`
@@ -290,15 +325,20 @@ DB_HOST=127.0.0.1 php artisan migrate
 
 ### Migrations mới
 - `database/migrations/2026_04_24_083000_add_payment_template_id_to_contracts.php`
+- `database/migrations/2026_04_28_013900_add_calculation_log_to_contracts.php`
+- `database/migrations/2026_04_28_020000_create_form_templates_tables.php`
 
 ### Services mới
 - `app/Services/DiscountEngine.php` - Tính toán chiết khấu
+- `app/Services/Calculation/` - Calculation Pipeline (RoundingRule, CalculationStep, CalculationResult, CalculationPipeline, PriceCalculationService)
+- `app/Services/Forms/MailMergeService.php` - Engine xử lý biểu mẫu in ấn
 - `app/Console/Commands/GenerateContractSchedules.php` - Command tạo lịch hàng loạt
 
 ### Filament Resources mới
 - `app/Filament/Resources/PaymentFines/` (Resource + Form + Table + Pages)
 - `app/Filament/Resources/Appendices/` (Resource + Form + Table + Pages)
 - `app/Filament/Resources/Settlements/` (Resource + Form + Table + Pages)
+- `app/Filament/Resources/FormTemplates/` (Resource + Form + Table + Pages)
 
 ### Widgets mới
 - `app/Filament/Widgets/ContractStatsOverview.php` - Dashboard tổng quan tài chính