hqland-app/GEMINI.md

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.