# HQLand Project Knowledge Base & Mandates

## 1. Core Architecture
- **Framework**: Laravel 13.5 (Future Release Simulation).
- **Admin Panel**: Filament v5.5 using the **Schemas** architecture (Layout-driven instead of Form-driven).
- **Database Logic**: Strictly following **Prisma Schema v2.3**.
- **Primary Keys**: All main entities (Project, Product, Customer, Contract) use **UUID**.
- **Naming Convention**: Database columns and Eloquent attributes must use **snake_case** (e.g., `full_name`, `custom_data`).

## 2. Business Logic Specifications

### 2.1. Contract & Transfer History
- `transfer_order`:
    - `0`: Current owner (Owner of record).
    - `1`: Original contract (F0).
    - `2+`: Subsequent transfers (F1, F2...).
- All transfer history contracts for a single product share the same `product_id`.

### 2.2. Payment & Cashflow Module
- **Automation**: When a `Contract` is created, the system must clone a `PaymentTemplate` into a `PaymentSchedule`.
- **Due Date Logic**: Supports 3 modes: `days_after_signing`, `days_after_previous`, and `fixed_date`.
- **Surplus Logic**: If a payment exceeds the required amount for an installment, the surplus is stored in `contracts.excess_amount` to be deducted from the next installment.

### 2.3. Infrastructure & Dynamic Data
- `infrastructure_status`: Nested JSONB structure (e.g., Electricity > Transformer Station > Status).
- `custom_data`: Flexible JSONB based on `ProductType` (LAND vs APARTMENT).

## 3. Development Conventions
- **UI/UX**: All Filament resources must use `App\Enums\NavigationGroup` for menu management.
- **Localization**: 100% Vietnamese labels for all resources and actions.
- **Testing**: Using Pest PHP for feature and unit tests.

## 4. Current Progress (as of April 18, 2026)
- Database fresh and seeded with complex test cases (`TestDataSeeder`).
- Navigation standardized with Enums.
- ProductResource upgraded to "Super Resource" with Tabs and Embedded History.
- PaymentTemplate logic fully implemented with flexible due date calculation.
- Contract-Template auto-cloning logic implemented in `CreateContract` page.

## 5. Instructions for Gemini CLI
- Always read this file before suggesting changes.
- Prioritize the **Schemas** architecture of Filament v5.5.
- Ensure all new migrations follow the UUID and snake_case standards.