DeclarationTVA/PLANNING.md

# DeclarationTVA - French CA-3 VAT Declaration Module

## Project Overview

This Dolibarr module creates the French VAT declaration CA-3 (Déclaration de TVA CA3) with PCG account mapping functionality. The module allows users to configure PCG (Plan Comptable Général) accounts for each CA-3 box and generates the appropriate VAT declaration.

## Architecture

### Core Components
- **Module Class**: `modDeclarationTVA.class.php` - Main module descriptor
- **Setup Interface**: `admin/setup.php` - Configuration page for PCG account mapping
- **Database Schema**: `sql/dolibarr_allversions.sql` - Database structure
- **Language Support**: Bilingual (French/English) interface
- **Main Interface**: `declarationtvaindex.php` - Main module page

### CA-3 Box Structure
The module handles the complete French CA-3 VAT declaration structure:

#### CA-3 Form Structure (n° 3310-CA3-SD)

##### A. Opérations imposables (Taxable Operations)

| CA-3 Line | Label | Description | PCG Accounts | Form Mapping |
|-----------|-------|-------------|---------------|--------------|
| **A1** | Montant hors TVA des opérations imposables | Base HT of taxable operations (sales/services) | 7xxxx (Sales) | Domestic sales base amounts |
| **A2** | Opérations imposables mais ne relevant pas du CA courant | Special taxable operations (asset sales, self-deliveries) | 7xxxx (Special sales) | Non-ordinary taxable operations |
| **B1** | Répartition 20% (base + taxe) | 20% VAT operations (base + VAT) | 7xxxx → 44571x | Standard rate operations |
| **B2** | Répartition 10% (base + taxe) | 10% VAT operations (base + VAT) | 7xxxx → 44572x | Reduced rate operations |
| **B3** | Répartition 5,5% (base + taxe) | 5.5% VAT operations (base + VAT) | 7xxxx → 44573x | Reduced rate operations |
| **B4** | Répartition 2,1% (base + taxe) | 2.1% VAT operations (base + VAT) | 7xxxx → 44574x | Reduced rate operations |

##### A. Opérations intracommunautaires (Intra-EU Operations)

| CA-3 Line | Label | Description | PCG Accounts | Form Mapping |
|-----------|-------|-------------|---------------|--------------|
| **05** | Livraisons intracommunautaires (B2B) | Intra-EU sales to businesses (no French VAT) | 7xxxx (EU sales) | Base HT only, no VAT |
| **06** | Prestations intracommunautaires (B2B) | Intra-EU services to businesses (no French VAT) | 7xxxx (EU services) | Base HT only, no VAT |
| **B2C** | Ventes B2C intracommunautaires | Intra-EU sales to individuals (French VAT) | 7xxxx → 4457xx | Normal French VAT rules |

##### B. TVA due (VAT Due)

| CA-3 Line | Label | Description | PCG Accounts | Form Mapping |
|-----------|-------|-------------|---------------|--------------|
| **17** | TVA due au titre des acquisitions intracommunautaires | VAT due on intra-EU acquisitions (autoliquidation) | 4452xxx (TVA due intracom) | Reverse charge VAT |

##### C. TVA déductible (Deductible VAT)

| CA-3 Line | Label | Description | PCG Accounts | Form Mapping |
|-----------|-------|-------------|---------------|--------------|
| **20** | TVA déductible sur immobilisations | Deductible VAT on capital goods | 44562x | Fixed assets VAT |
| **21** | TVA déductible sur autres biens et services | Deductible VAT on other goods and services | 44566x | Operating expenses VAT |

##### D. Résultat (Result)

| CA-3 Line | Label | Description | PCG Accounts | Form Mapping |
|-----------|-------|-------------|---------------|--------------|
| **22** | Crédit de TVA reportable | VAT credit to carry forward | 445670 | If deductible > due |
| **28** | TVA nette à payer | Net VAT to pay | 445510 | If due > deductible |
| **29** | Crédit de TVA à reporter ou remboursement | VAT credit to carry forward or refund | 445670 | Credit amount |

### EU Transaction Handling

#### 1️⃣ Incoming Invoices (EU Purchases)
- **Scenario**: Supplier in another EU country invoices HT (no VAT)
- **French Treatment**: Self-assess VAT (autoliquidation)
- **Accounting**: Book both VAT due (4452xxx) and VAT deductible (44566x/44562x)
- **Net Effect**: Zero if fully deductible
- **CA-3 Impact**: Line 17 (VAT due) and Lines 20/21 (VAT deductible)

#### 2️⃣ Outgoing Invoices (EU Sales)

##### Case A: B2B Intra-EU Sales (Business Customers)
- **Invoice Treatment**: No French VAT charged
- **Invoice Text**: "Exonération de TVA, article 138" (goods) or "Autoliquidation par le preneur, article 196" (services)
- **Accounting**: No 4457xxx VAT output booked
- **CA-3 Declaration**: Lines 05/06 (base HT only, no VAT)
- **Additional**: DEB/DES declarations required

##### Case B: B2C Intra-EU Sales (Individual Customers)
- **Under OSS Threshold (€10,000)**: Charge French VAT (4457xx)
- **Over OSS Threshold**: Register for OSS/IOSS, charge customer's country VAT rate
- **CA-3 Declaration**: Normal French VAT rules or OSS portal

##### Case C: Special Reverse Charge Cases
- **Construction Services**: Subcontractor invoices HT, contractor self-assesses
- **Energy Products**: Specific reverse charge rules
- **Accounting**: Similar to EU purchases (4452xxx + 4456xx)

#### 3️⃣ DEB/DES Integration
- **DEB (Déclaration d'échanges de biens)**: Goods movement declarations
- **DES (Déclaration d'échanges de services)**: Services movement declarations
- **Integration**: Link CA-3 lines 05/06 with DEB/DES data
- **Validation**: Cross-check amounts between CA-3 and DEB/DES

## Technical Requirements

### Database Structure

#### Core Tables
- **`llx_declarationtva_config`**: Module configuration and settings
- **`llx_declarationtva_account_mappings`**: PCG account mappings for CA-3 lines
- **`llx_declarationtva_periods`**: Declaration period management
- **`llx_declarationtva_declarations`**: Main declarations storage
- **`llx_declarationtva_ca3_lines`**: CA-3 form lines data
- **`llx_declarationtva_account_details`**: Detailed account breakdown

#### EU Transaction Tables
- **`llx_declarationtva_eu_suppliers`**: EU supplier configuration
- **`llx_declarationtva_eu_transactions`**: EU transaction tracking

#### Workflow Integration Tables
- **`llx_declarationtva_workflow_log`**: Workflow triggers and automation
- **`llx_declarationtva_audit_trail`**: Complete audit trail
- **`llx_declarationtva_compliance`**: Compliance validation results

#### Export and Integration Tables
- **`llx_declarationtva_exports`**: Export history and tracking

#### Performance Features
- **Comprehensive Indexing**: Optimized for large datasets
- **Foreign Key Constraints**: Data integrity enforcement
- **Reporting Views**: Pre-built views for analytics
- **Multi-Entity Support**: Full entity isolation

### PCG Account Mapping System

#### Multiple Account Selection
Each CA-3 line can be mapped to **multiple PCG accounts** from Dolibarr's existing chart of accounts:

- **Account Selection Interface**: Multi-select dropdown from Dolibarr's `llx_accounting_account` table
- **Account Validation**: Real-time validation against existing chart of accounts
- **Account Grouping**: Group multiple accounts by CA-3 line
- **Account Weighting**: Optional weighting for account importance
- **Account Filtering**: Filter accounts by type (7xxxx, 4457xx, 4456xx, etc.)

#### Account Mapping Structure
```sql
-- PCG Account Mappings Table
llx_declarationtva_account_mappings:
- id (Primary Key)
- ca3_line (VARCHAR) -- A1, A2, B1, B2, B3, B4, 05, 06, 17, 20, 21, 22, 28, 29
- account_code (VARCHAR) -- PCG account code from llx_accounting_account
- account_label (VARCHAR) -- Account description
- vat_rate (DECIMAL) -- VAT rate (20%, 10%, 5.5%, 2.1%, 0%)
- account_type (VARCHAR) -- base, vat_collected, vat_deductible, vat_due
- is_active (BOOLEAN) -- Enable/disable this mapping
- weight (DECIMAL) -- Optional weighting (default 1.0)
- created_date (DATETIME)
- modified_date (DATETIME)
```

#### Account Selection Interface
- **Multi-Select Dropdown**: Select multiple accounts for each CA-3 line
- **Account Search**: Search accounts by code or description
- **Account Filtering**: Filter by account type (7xxxx, 4457xx, etc.)
- **Account Preview**: Show account details and current balances
- **Account Validation**: Ensure accounts exist and are active
- **Bulk Operations**: Add/remove multiple accounts at once

### Key Features
1. **PCG Account Configuration**: Setup page to map PCG accounts to CA-3 boxes
2. **Period Management**: Handle quarterly/monthly declaration periods
3. **Data Extraction**: Query Dolibarr accounting data based on PCG mappings
4. **Declaration Generation**: Create CA-3 format declarations
5. **Export Functionality**: Export to various formats (PDF, XML, CSV)
6. **Bilingual Interface**: French and English language support

### Advanced Features
7. **Draft System**: All declarations start as drafts with detailed account breakdowns
8. **Validation Workflow**: User validation with detailed verification
9. **Accounting Integration**: Automatic journal entry generation for validated declarations
10. **Audit Trail**: Complete history of changes and validations
11. **Comparison Tools**: Compare declarations across periods
12. **Exception Handling**: Flag unusual amounts or missing data
13. **Multi-Entity Support**: Handle multiple companies/entities
14. **Automated Calculations**: Real-time calculation updates
15. **Document Management**: Attach supporting documents
16. **Notification System**: Email alerts for deadlines and status changes
17. **Reporting Dashboard**: Visual analytics and trends
18. **Backup/Restore**: Declaration data backup and recovery
19. **Integration APIs**: Connect with external tax systems
20. **Mobile Support**: Responsive design for mobile access

### Dolibarr Workflow Integration
21. **Autoliquidation Automation**: Automatic EU VAT autoliquidation on invoice transfer
22. **Hook System Integration**: Extend Dolibarr core functionality
23. **Invoice Processing Hooks**: Intercept invoice accounting transfers
24. **Supplier Invoice Automation**: Auto-detect EU suppliers and apply autoliquidation
25. **Customer Invoice Automation**: Auto-apply EU transaction rules
26. **Accounting Entry Automation**: Generate VAT entries during transfer to accounting
27. **Workflow Triggers**: Automatic VAT processing based on invoice status
28. **Custom Fields Integration**: Extend invoices with VAT-specific fields
29. **Status Change Automation**: Trigger VAT processing on invoice validation
30. **Batch Processing**: Handle multiple invoices for VAT processing

### Advanced Analytics & Intelligence
31. **VAT Forecasting**: Predict future VAT obligations based on historical data
32. **Anomaly Detection**: AI-powered detection of unusual VAT patterns
33. **Cash Flow Impact**: Calculate VAT impact on cash flow projections
34. **VAT Optimization**: Suggest strategies to minimize VAT payments
35. **Trend Analysis**: Identify VAT trends and seasonal patterns
36. **Benchmarking**: Compare VAT performance against industry standards
37. **Risk Assessment**: Flag potential VAT compliance risks
38. **Predictive Alerts**: Early warning system for VAT issues

### Tax Authority Integration
39. **Direct Submission**: Submit CA-3 declarations directly to French tax authorities
40. **API Integration**: Connect with French tax authority APIs
41. **Real-time Validation**: Validate declarations against tax authority systems
42. **Electronic Signatures**: Digital signature for declaration submission
43. **Receipt Management**: Store and manage tax authority receipts
44. **Status Tracking**: Track declaration status with tax authorities
45. **Amendment Handling**: Process declaration amendments and corrections
46. **Payment Integration**: Direct payment of VAT obligations

### Advanced Reporting & Compliance
47. **Multi-Period Analysis**: Compare VAT across multiple periods
48. **VAT Reconciliation**: Reconcile VAT with general ledger
49. **Audit Trail**: Complete audit trail for tax authorities
50. **Compliance Dashboard**: Real-time compliance status monitoring
51. **Regulatory Updates**: Automatic updates for tax law changes
52. **Penalty Calculation**: Calculate potential penalties for late submissions
53. **Deadline Management**: Automated deadline tracking and reminders
54. **Document Generation**: Auto-generate supporting documentation

### Business Intelligence
55. **VAT Analytics**: Deep insights into VAT patterns and trends
56. **Cost Analysis**: Analyze VAT impact on business costs
57. **Profitability Impact**: Show how VAT affects product profitability
58. **Customer VAT Analysis**: Analyze VAT by customer segments
59. **Supplier VAT Analysis**: Analyze VAT by supplier categories
60. **Geographic Analysis**: VAT analysis by geographic regions
61. **Product Analysis**: VAT analysis by product categories
62. **Seasonal Analysis**: Identify seasonal VAT patterns

### Integration & Connectivity
63. **ERP Integration**: Connect with other ERP systems
64. **Banking Integration**: Direct bank account integration for VAT payments
65. **Accounting Software**: Integration with other accounting software
66. **CRM Integration**: Connect with customer relationship management
67. **E-commerce Integration**: Connect with e-commerce platforms
68. **API Gateway**: Centralized API for external integrations
69. **Webhook Support**: Real-time notifications to external systems
70. **Data Synchronization**: Sync data across multiple systems

### Dolibarr Hook Integration

#### Available Hooks for VAT Automation
- **`invoice_validate`**: Trigger when invoice is validated
- **`invoice_accountancy_transfer`**: Trigger when invoice is transferred to accounting
- **`supplier_invoice_validate`**: Trigger when supplier invoice is validated
- **`supplier_invoice_accountancy_transfer`**: Trigger when supplier invoice is transferred
- **`invoice_paid`**: Trigger when invoice is marked as paid
- **`invoice_unpaid`**: Trigger when invoice is marked as unpaid
- **`invoice_cancel`**: Trigger when invoice is cancelled

#### Automation Workflow
1. **Invoice Creation**: User creates supplier invoice from EU supplier
2. **Hook Trigger**: `supplier_invoice_validate` hook fires
3. **EU Detection**: Module checks if supplier is EU-based
4. **Autoliquidation**: Automatically creates VAT due (4452xxx) and VAT deductible (4456xx) entries
5. **Accounting Transfer**: When transferred to accounting, entries are already created
6. **CA-3 Integration**: Entries automatically appear in CA-3 calculations

#### Custom Fields for VAT Processing
- **EU Supplier Flag**: Mark suppliers as EU-based
- **VAT Treatment**: Specify autoliquidation vs normal VAT
- **Transaction Type**: B2B, B2C, special cases
- **OSS Threshold**: Track B2C sales thresholds
- **DEB/DES Required**: Flag invoices requiring exchange declarations

### File Structure
```
declarationtva/
├── admin/
│   ├── setup.php (Enhanced with PCG configuration)
│   └── about.php
├── core/
│   ├── modules/modDeclarationTVA.class.php
│   ├── class/
│   │   ├── declarationtva.class.php
│   │   ├── declarationtva_config.class.php
│   │   └── declarationtva_period.class.php
│   └── triggers/
│       ├── interface_99_modDeclarationTVA_DeclarationTVATrigger.class.php
│       └── action_99_modDeclarationTVA_DeclarationTVAAction.class.php
├── lib/
│   └── declarationtva.lib.php
├── langs/
│   ├── en_US/declarationtva.lang
│   └── fr_FR/declarationtva.lang
├── sql/
│   └── dolibarr_allversions.sql
├── templates/
│   └── declarationtva/
│       ├── ca3_form.tpl
│       └── ca3_pdf.tpl
└── declarationtvaindex.php
```

## Development Phases

### Phase 1: Foundation (Week 1-2)
- Database schema design and implementation
- Core class structure
- Basic module setup and configuration

### Phase 2: Configuration Interface (Week 3-4)
- PCG account mapping interface
- Period management
- User permissions and access control

### Phase 3: Data Processing (Week 5-6)
- Accounting data extraction
- CA-3 calculation logic
- Data validation and error handling

### Phase 4: User Interface (Week 7-8)
- Main declaration interface
- Period selection and management
- Declaration preview and editing

### Phase 5: Export and Reporting (Week 9-10)
- PDF generation
- XML export for tax authorities
- CSV export for analysis

### Phase 6: Testing and Documentation (Week 11-12)
- Unit testing
- Integration testing
- User documentation
- French tax compliance validation

## Success Criteria

1. **Functional Requirements**
   - Complete CA-3 form generation
   - Accurate PCG account mapping
   - Proper period management
   - Export functionality

2. **Technical Requirements**
   - Dolibarr compatibility (v19+)
   - Bilingual interface (FR/EN)
   - Database integrity
   - Performance optimization

3. **Compliance Requirements**
   - French tax authority format compliance
   - Data accuracy and validation
   - Audit trail maintenance

## Risk Mitigation

1. **Tax Compliance**: Regular validation with French tax requirements
2. **Data Accuracy**: Comprehensive testing with real accounting data
3. **Performance**: Optimization for large datasets
4. **User Experience**: Intuitive interface for non-technical users

## Future Enhancements

1. **Automated Submission**: Direct submission to tax authorities
2. **Advanced Analytics**: VAT analysis and reporting
3. **Multi-Entity Support**: Support for multiple companies
4. **Integration**: Enhanced integration with other Dolibarr modules