# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

This is an Odoo 18 module that extends the CRM system to process ADF (Auto-Lead Data Format) leads and credit applications from Chrome extension sync. The module features comprehensive credit application processing with advanced income calculations, enhanced UI organization, and seamless Chrome extension integration via API sync.

## Architecture

### Core Components

- **`models/adf_lead.py`** - Extended CRM lead model with 50+ credit application fields and advanced income calculations
- **`views/adf_lead_view.xml`** - Comprehensive UI with organized Credit Application, Co-Applicant, and Vehicle Information tabs
- **`security/ir.model.access.csv`** - Access rights for the lead source model
- **`__manifest__.py`** - Module configuration and dependencies
- **API Integration**: Seamless sync with Chrome extension via `standalone_api.py`

### Key Processing Flow

1. **Chrome Extension Sync**: Primary method via `standalone_api.py` with comprehensive field mapping
2. **Email Processing**: `message_new()` method for ADF email processing (legacy support)
3. **Credit Application Processing**: Complete applicant/co-applicant data with income calculations
4. **UI Organization**: Enhanced tab structure with Internal Notes prioritization and Extra Information hiding

### Lead Types Supported

The module handles multiple lead source types defined in `x_lead_type` field:
- `carfax` - Carfax vehicle inquiries
- `facebook` - Facebook Messenger leads
- `podium` - Podium SMS/text leads  
- `vehicle_inquiry` - General vehicle inquiries
- `credit_app` - Credit applications (PDF processing)
- `sms` - SMS leads
- `contact_us` - Contact form submissions

### Custom Fields Structure (50+ Credit Application Fields)

**Lead Classification**: `x_lead_type`, `x_source_id`, `x_lead_source`, `x_preferred_contact`
**Customer Info**: `x_customer_name`, `x_first_name`, `x_last_name`, `x_date_of_birth`, `x_ssn`, `x_email_address`, `x_home_phone`, `x_mobile_phone`
**Applicant Address**: `x_address`, `x_city`, `x_state`, `x_zip`, `x_residence_type`, `x_time_at_residence`, `x_rent_mortgage`
**Driver License**: `x_dl_number`, `x_dl_state`, `x_dl_exp_date`
**Employment**: `x_employer`, `x_occupation`, `x_work_phone`, `x_time_on_job`, `x_employer_address`, `x_employer_city`
**Income (with Overtime)**: `x_monthly_income`, `x_hours_per_week`, `x_hourly_pay`, `x_regular_income`, `x_overtime_income`, `x_calculated_income`
**Co-Applicant (Full Mirror)**: Complete set of co-applicant fields (22+ fields) with `x_co_applicant_` prefix
**Vehicle Info**: `x_vehicle_year`, `x_vehicle_make`, `x_vehicle_model`, `x_vehicle_trim`, `x_vehicle_vin`, `x_vehicle_stock`, `x_vehicle_price`, `x_vehicle_sale_price`, `x_vehicle_mileage`, `x_vehicle_color`, `x_vehicle_down_total`
**Processing Metadata**: `x_request_date`, `x_credit_app_processed`, `x_credit_app_date`

## Development Commands

Since this is an Odoo 18 module, typical development involves:

```bash
# Install/upgrade the module in Odoo 18
# (performed through Odoo interface or odoo-bin command)

# Test XML parsing logic
python3 -c "from models.adf_lead import CrmLead; # test ADF processing"
```

## Key Processing Methods

### Income Calculation System
- **`_compute_calculated_income()`** - Advanced overtime calculation with 1.5x rate for hours over 40
- **`_compute_co_applicant_calculated_income()`** - Mirror calculation for co-applicant
- **Logic**: Regular hours (max 40) + overtime hours × 1.5 rate, multiplied by 4.3 weeks/month

### Legacy ADF Processing
- **`_determine_lead_type()`** - Classifies leads based on service/provider names
- **`_process_vehicle_data()`** - Extracts vehicle information from XML
- **`_format_description()`** - Creates formatted lead descriptions
- **`_clean_phone_number()`** - Standardizes phone number formats
- **`_extract_pdf_credit_app_data()`** - Parses PDF credit applications

### API Integration
- **Chrome Extension Sync**: Complete field mapping in `standalone_api.py`
- **Comprehensive Data Population**: All 50+ fields with proper co-applicant support
- **Automatic Timestamps**: Processing date/time with customer notes preservation

## Dependencies

- **Odoo 18 modules**: `crm`, `mail`
- **Python packages**: `PyPDF2` (for PDF processing)
- **Standard libraries**: `xml.etree.ElementTree`, `base64`, `re`, `logging`

## UI Enhancements (2025-08-27 Major Update)

### Enhanced Internal Notes Tab
- **Customer comments prioritized** - Original application comments appear first
- **Lead classification summary** - Type, source, contact preference (credit apps only)
- **Processing timestamp** - Automatic date/time when synced from Chrome extension
- **Extra Information tab hidden** - Removed "useless" tab for credit applications

### Organized Credit Application Tab
- **Personal Details**: Name, DOB, SSN, driver license (number, state, expiration)
- **Contact Information**: Email, home phone, mobile phone
- **Address & Housing**: Full address with residence type and monthly payment
- **Employment**: Employer details with complete address and work phone
- **Income Details**: Stated income, calculated income with overtime breakdown

### Co-Applicant Tab (Complete Mirror)
- Full applicant field set duplicated for co-applicant
- All address, employment, and income fields included
- Same overtime calculation logic applied

### Vehicle Information Tab
- Lead classification moved from Credit Application tab
- Complete vehicle details (year, make, model, trim, VIN, etc.)
- Pricing information (list price, sale price, down payment)

## Critical Income Calculation Logic

```python
# Regular hours (max 40) * 4.3 weeks per month * hourly rate
regular_hours = min(record.x_hours_per_week, 40)
record.x_regular_income = regular_hours * 4.3 * record.x_hourly_pay

# Overtime hours (anything over 40) * 4.3 weeks per month * hourly rate * 1.5
overtime_hours = max(record.x_hours_per_week - 40, 0)
record.x_overtime_income = overtime_hours * 4.3 * record.x_hourly_pay * 1.5

# Total = Regular + Overtime
record.x_calculated_income = record.x_regular_income + record.x_overtime_income
```

## Module Upgrade Requirements

When adding new fields (like DL numbers and overtime calculations):
1. **Restart Odoo server** - Required for new field recognition
2. **Upgrade module** - Creates new database columns
3. **Test integration** - Verify Chrome extension sync and calculations

## Recent Major Enhancements

### 2025-08-27: Comprehensive Credit Application System
- **50+ credit application fields** added to model
- **Advanced overtime calculations** (1.5x rate for hours over 40)
- **Complete co-applicant data support** with full field mirroring
- **Enhanced UI organization** with improved tab structure
- **Driver license fields** added for both applicant and co-applicant
- **API sync improvements** with comprehensive field mapping
- **Customer notes preservation** in Internal Notes prioritization

### Legacy Features
- ADF email processing support maintained
- XML parsing for vehicle inquiries
- PDF credit application processing (legacy method)

## Logging

The module uses extensive logging (`_logger`) for debugging ADF processing and Chrome extension sync. Log messages track processing flow, field mapping, and calculation results.