📋 Expert Skill: Tạo & Quản Lý Hợp Đồng

Bảng partners (Đối tác)

-- Filter: type = 'Client'
id, code, name, short_name, tax_code, address, phone, email, type

Bảng addendas (Phụ lục HĐ)

project_id       UUID → projects(id)
name             TEXT
requested_value  NUMERIC
status           TEXT  -- 'Chờ duyệt' | 'Đã duyệt' | 'Từ chối'

2. DUAL RATIO SYSTEM (Quan trọng nhất)

Concept: 2 tỷ lệ phân bổ

┌─────────────────────────────────────────────┐
│ CĐT trả Thăng Long: 100% giá trị HĐ       │
│                                             │
│ Thăng Long chuyển Sateco theo 2 dòng:       │
│                                             │
│ 1. DÒNG GIẤY TỜ (sateco_contract_ratio)    │
│    → Mặc định 98% → Xuất hóa đơn nội bộ    │
│    → Dùng để tính công nợ trên sổ sách      │
│                                             │
│ 2. DÒNG TIỀN MẶT (sateco_actual_ratio)     │
│    → = contract_ratio - internal_deduction  │
│    → Mặc định 98% - 2.5% = 95.5%           │
│    → Tiền thực tế Sateco được giữ           │
│                                             │
│ Chênh lệch (2.5%):                          │
│    → Sateco hoàn trả TL bằng tiền mặt      │
│    → Là "phí quản lý nội bộ"               │
└─────────────────────────────────────────────┘

Auto-calculate (contractHelpers.js)

function calculateAllocations(totalValue, vat, internalVat, contractRatio, internalDeduction) {
    const actualRatio = contractRatio - internalDeduction; // 98 - 2.5 = 95.5
    
    // Thăng Long giữ
    const tl_cutPercent = 100 - contractRatio;  // 2%
    const tl_preVat = totalValue * (1 + vat/100);
    
    // Sateco nhận (dòng giấy tờ - hóa đơn)
    const st_invoice_preVat = totalValue * contractRatio / 100;
    const st_invoice_postVat = st_invoice_preVat * (1 + internalVat/100);
    
    // Sateco nhận (dòng tiền mặt - thực tế)
    const st_actual_preVat = totalValue * actualRatio / 100;
    const st_actual_postVat = st_actual_preVat * (1 + internalVat/100);
    
    return { actualRatio, tl_preVat, st_invoice_preVat, st_actual_preVat, ... };
}

3. FORM TẠO HỢP ĐỒNG (7 sections)

Section 1: Thông tin Pháp lý (ContractLegalInfo)

• Tên HĐ, Mã HĐ (CĐT), Mã nội bộ
• Loại HĐ: Thi công / Cung cấp / Thiết kế / EPC
• Hình thức: Trọn gói / Đơn giá / Đơn giá điều chỉnh
• Đơn vị ký: Thăng Long / Thành Phát
• Trạng thái ký: Chưa ký → Đã ký → Đã ký PL
• Địa chỉ, Mô tả

Section 2: Chủ Đầu tư (ContractPartner)

• Dropdown chọn từ partners (type = 'Client')
• Tạo mới CĐT inline (ContractPartnerModal)
• Thông tin: Tên, MST, Địa chỉ, SĐT, Email

Section 3: Giá trị & Thời gian (ContractValueTime)

• Input giá trị: Nhập trước VAT HOẶC sau VAT → auto-calc ngược
• VAT%: Mặc định 8%, có thể đổi
• Ngày ký / Khởi công / Hoàn thành
• Format: formatInputNumber() — hiện dấu phẩy ngàn khi blur

Section 4: Mốc Thanh toán (ContractMilestones)

• Danh sách milestones: [{name, percentage, amount, condition}]
• Base type: Trước VAT / Sau VAT (chọn 1)
• Tự động tính amount khi thay đổi %
• Mặc định có 1 mốc "Tạm ứng 20%"
• Thêm/xóa milestone tùy ý

Section 5: Phân bổ Sateco (ContractSateco)

• Tỷ lệ HĐ (contract_ratio): mặc định 98%
• Chiết khấu nội bộ: mặc định 2.5%
• VAT nội bộ: mặc định 8%
• Hiện bảng tính: TL giữ / STC HĐ / STC Thực

Section 6: Bảo hành (ContractWarranty)

• Tỷ lệ giữ lại BH: 5%
• Thời hạn BH: 24 tháng
• Bảo lãnh thay thế: có/không
• Ngày bàn giao
• Lịch hoàn trả BH: [{year, percentage, amount}]

Section 7: Thông tin Ngân hàng (ContractBanking)

• 3 bộ TK ngân hàng: TL, TP, STC
• Bank profiles: chọn từ template đã lưu
• Hiện đầy đủ: STK, Tên NH, Chi nhánh, Chủ TK

4. BUSINESS RULES

4.1 Validation

• ❗ BẮT BUỘC: name, code, partner_id, original_value > 0
• ❗ contract_ratio: 0-100%
• ❗ internal_deduction: 0 ≤ deduction ≤ contract_ratio
• ❗ start_date ≤ end_date
• ❗ VAT: 0-30%
• ❗ code + internal_code: UNIQUE (kiểm tra trước khi lưu)

4.2 Auto behaviors

• Khi thay đổi original_value hoặc vat → recalc tất cả allocations
• Khi thay đổi milestone % → recalc amount (và ngược lại)
• Khi save → auto-create Google Drive folder (nếu connected)
• Khi save → ghi audit log + send notification
• Default status: 'Đang thi công'

4.3 Google Drive Integration

• Auto-create folder structure khi tạo HĐ mới
• Folder name: {name} ({internal_code || code})
• Save google_drive_folder_id và document_link

5. FILE MAP

src/components/
├── ContractCreate.jsx              -- Main form orchestrator (602 lines)
├── contract/
│   ├── contractHelpers.js          -- Shared: formatInputNumber, calculateAllocations, navItems
│   ├── ContractLegalInfo.jsx       -- Section 1: Pháp lý
│   ├── ContractPartner.jsx         -- Section 2: CĐT
│   ├── ContractPartnerModal.jsx    -- Modal tạo CĐT mới
│   ├── ContractValueTime.jsx       -- Section 3: Giá trị + Thời gian
│   ├── ContractMilestones.jsx      -- Section 4: Mốc thanh toán
│   ├── ContractSateco.jsx          -- Section 5: Phân bổ Sateco
│   ├── ContractWarranty.jsx        -- Section 6: Bảo hành
│   ├── ContractBanking.jsx         -- Section 7: Ngân hàng
│   ├── ContractExpenseTab.jsx      -- Chi phí (trong Dashboard)
│   ├── ContractAddendaTab.jsx      -- Phụ lục (trong Dashboard)
│   └── ContractDriveTab.jsx        -- Tài liệu Drive (trong Dashboard)

6. COMMON PATTERNS

✅ DO:

• Luôn validate uniqueness cho code + internal_code trước khi save
• Dùng formatInputNumber khi hiển thị, parseFormattedNumber khi đọc
• Lưu cả warranty_ratio + warranty_percentage (backward compat)
• Upsert company_settings khi save (sync bank info)
• Ghi audit log cho CREATE và UPDATE

❌ DON'T:

• Không mix actual_ratio với contract_ratio — chúng khác nhau!
• Không cho phép VAT > 30% hoặc < 0%
• Không lưu HĐ nếu thiếu CĐT (partner_id)
• Không xóa Google Drive folder khi sửa HĐ