Hoan thien core finance v2 - Calculation Pipeline, Form Templates

NEXT_SESSION.md

@@ -7,152 +7,75 @@
 
 ## ⚠️ THÔNG BÁO QUAN TRỌNG
 
-Có **26 file thay đổi CHƯA COMMIT**. Bạn cần commit hoặc stash trước khi chuyển máy, nếu không sẽ mất toàn bộ công việc vừa làm!
+Có **rất nhiều file thay đổi CHƯA COMMIT**. Bạn cần commit trước khi chuyển máy!
 
 ```bash
-# Cách 1: Commit ngay (KHUYẾN NGHỊ)
 git add -A
-git commit -m "Hoan thien core finance v2"
-
-# Cách 2: Hoặc stash để commit sau
-git stash -u
+git commit -m "Hoan thien core finance v2 - Calculation Pipeline, Form Templates"
+git push origin main
 ```
 
 ---
 
-## 1. NHỮNG GÌ VỪA HOÀN THÀNH (Phiên hiện tại)
+## 1. NHỮNG GÌ VỪA HOÀN THÀNH
 
-### ✅ Fix lỗi quan trọng
-- **EditAction not found:** Đã sửa namespace `Filament\Actions\EditAction` (không phải `Filament\Tables\Actions\EditAction`)
-- **User quyền truy cập:** Thêm `FilamentUser` interface vào `User.php`
+### ✅ Kiến trúc mới: Calculation Pipeline
+- Tính toán giá BĐS tường minh, step-by-step với làm tròn tại mỗi bước
+- `RoundingRule`: NONE, UNIT (đồng), THOUSAND, MILLION
+- `CalculationStep`: Định nghĩa từng bước (tên, công thức, làm tròn, ghi đè)
+- `CalculationResult`: Lưu snapshot + price_sheet cho phiếu tính giá
+- `PriceCalculationService`: Pipeline chuyên BĐS (QSDĐ + Móng → Subtotal → CK → Net → VAT → Total)
+- `Contract::calculation_log`: JSONB lưu toàn bộ quá trình tính toán
 
-### ✅ ContractForm + Tự động tạo lịch
-- Migration mới: `payment_template_id` trong bảng `contracts`
-- `payment_template_id` đã lưu vào DB, không còn `dehydrated(false)`
-- Tự động tạo lịch thanh toán khi tạo HĐ mới
+### ✅ Module mới: Form Templates (Biểu mẫu in ấn)
+- **Mail Merge Engine:** Admin tự tạo template HTML, chèn `{{ma_truong}}`
+- **FormField:** Định nghĩa nguồn dữ liệu (db_column, db_relation, formula, input, static)
+- **FormPrintLog:** Lưu snapshot khi in
+- **FormTemplateResource:** CRUD trong Filament với RichEditor WYSIWYG + Repeater fields
+- Layout: 3 section xếp dọc (Thông tin → Trường dữ liệu → Nội dung mẫu in)
 
-### ✅ PaymentForm Validation
-- Số tiền thu không vượt quá công nợ đợt TT / công nợ HĐ
-- Helper text hiển thị công nợ còn lại
-- Fix lỗi khi edit payment (kiểm tra `instanceof Payment`)
-
-### ✅ PaymentsTable
-- Thêm cột: Loại đợt, Trạng thái đối soát (Đủ/Thiếu/Thừa), Còn thiếu
-
-### ✅ ContractsTable
-- Thêm cột: `paid_amount`, `remaining_amount`
-- `ContractResource` giờ delegate về `ContractsTable` Schemas
-
-### ✅ Hiệu năng
-- Fix N+1 query ở `PaymentScheduleItem::getPaidAmountAttribute()` (kiểm tra `relationLoaded`)
-
-### ✅ Command mới
-- `php artisan contracts:generate-schedules {--force}` - Tạo lịch hàng loạt cho 139 HĐ
-
-### ✅ Resources mới
-- `PaymentFineResource` - Quản lý tiền phạt
-- `AppendixResource` - Quản lý phụ lục HĐ
-- `SettlementResource` - Quản lý quyết toán & sổ đỏ
-
-### ✅ Discount Engine
-- `DiscountEngine::calculate()` - Tính chiết khấu tự động
-- Accessor `final_value` trong Contract model
-- Hiển thị giá trị sau chiết khấu cả khi create và edit
-
-### ✅ Dashboard
-- `ContractStatsOverview` - 5 chỉ số tài chính tổng quan
-- `UpcomingPaymentsTable` - Danh sách đợt TT sắp đến hạn (30 ngày)
+### ✅ Các fix trước đó
+- EditAction namespace, User FilamentUser, ContractForm tạo lịch tự động
+- Payment validation, PaymentsTable đối soát, ContractsTable công nợ
+- PaymentFine/Appendix/Settlement Resources, Dashboard widgets
 
 ---
 
-## 2. CẤU HÌNH DATABASE (QUAN TRỌNG)
+## 2. CẤU HÌNH DATABASE
 
-### Database chính (Production)
-- **Connection:** pgsql
-- **Host:** 127.0.0.1 (từ host machine)
-- **Database:** laravel
-- **Username/Password:** sail / password
+### Chạy migrate trên production (NẾU CHƯA CHẠY)
+```bash
+DB_HOST=127.0.0.1 php artisan migrate --force
+```
 
-### Database test
-- **Database:** laravel_testing (đã tạo, migrations đã chạy)
-- **Chạy test:** `DB_HOST=127.0.0.1 ./vendor/bin/pest`
-
-### Lệnh chạy Artisan
-- `DB_HOST=127.0.0.1 php artisan tinker`
-- `DB_HOST=127.0.0.1 php artisan migrate` (KHÔNG dùng `migrate:fresh`!)
+Các migration quan trọng:
+- `2026_04_24_083000_add_payment_template_id_to_contracts`
+- `2026_04_28_013900_add_calculation_log_to_contracts`
+- `2026_04_28_020000_create_form_templates_tables`
 
 ---
 
-## 3. CÁC FILE CHƯA COMMIT
-
-### Modified (17 file)
-```
-AGENTS.md
-app/Console/Commands/ImportContractsComplex.php
-app/Filament/Resources/Contracts/ContractResource.php
-app/Filament/Resources/Contracts/Pages/CreateContract.php
-app/Filament/Resources/Contracts/Schemas/ContractForm.php
-app/Filament/Resources/Contracts/Tables/ContractsTable.php
-app/Filament/Resources/Payments/PaymentResource.php
-app/Filament/Resources/Payments/Schemas/PaymentForm.php
-app/Filament/Resources/Payments/Tables/PaymentsTable.php
-app/Models/Contract.php
-app/Models/PaymentScheduleItem.php
-app/Models/User.php
-app/Providers/Filament/AdminPanelProvider.php
-```
-
-### Untracked mới (9 file/folder)
-```
-app/Console/Commands/GenerateContractSchedules.php
-app/Filament/Resources/Appendices/
-app/Filament/Resources/PaymentFines/
-app/Filament/Resources/Settlements/
-app/Filament/Widgets/
-app/Services/DiscountEngine.php
-database/migrations/2026_04_24_083000_add_payment_template_id_to_contracts.php
-tests/Feature/ContractResourceRenderTest.php
-```
-
----
-
-## 4. VIỆC CẦN LÀM TIẾP THEO (Checklist)
-
-### 🟡 Trung bình ưu tiên
-- [ ] **Notification:** Cảnh báo đợt thanh toán sắp đến hạn (30/7/3 ngày)
-- [ ] **Export Excel:** Xuất báo cáo công nợ khách hàng
-- [ ] **Báo cáo theo Dự án:** Thống kê bán hàng, thanh toán theo dự án
-
-### 🟢 Thấp ưu tiên
-- [ ] **Audit Log:** Lưu lịch sử sửa HĐ, thu tiền
-- [ ] **Queue:** Generate schedules qua queue nếu >1000 HĐ
-- [ ] **Email/SMS:** Tự động nhắc thanh toán
-- [ ] **Advanced Filter:** Tìm HĐ theo khoảng giá trị, ngày ký
-
----
-
-## 5. CÂU LỆNH TEST QUAN TRỌNG
+## 3. TEST
 
 ```bash
-# Test toàn bộ
-DB_HOST=127.0.0.1 ./vendor/bin/pest
-
-# Test cụ thể
-DB_HOST=127.0.0.1 ./vendor/bin/pest --filter="ContractFinanceFlowTest"
-
-# Test render (kiểm tra không bị lỗi class not found)
-DB_HOST=127.0.0.1 ./vendor/bin/pest --filter="ContractResourceRenderTest"
+DB_HOST=127.0.0.1 ./vendor/bin/pest --filter="ContractFinanceFlowTest|ContractResourceRenderTest"
 ```
 
-**Kết quả hiện tại:** 9 tests passed, 0 failed.
-
 ---
 
-## 6. TÀI KHOẢN ĐĂNG NHẬP
+## 4. VIỆC CẦN LÀM TIẾP THEO
+
+- [ ] **Notification:** Cảnh báo đợt thanh toán sắp đến hạn
+- [ ] **Export Excel:** Báo cáo công nợ khách hàng
+- [ ] **In ấn thực tế:** Tích hợp MailMergeService với action "In" trong ContractResource
+
+---
+
+## 5. TÀI KHOẢN
 
 - **Email:** admin@phuongtc.com
 - **Password:** 1Qazxsw2@!321
 
 ---
 
-*Lưu ý: Commit ngay lập tức trước khi tắt máy hoặc chuyển sang máy khác!*
+*Commit ngay lập tức trước khi tắt máy!*