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 (Notice 4722 - 3310-CA3-SD)

##### A. Opérations imposables (Taxable Operations) - Notice 4722

| CA-3 Line | Label | Description | PCG Accounts |
|-----------|-------|-------------|---------------|
| **A1** | Montant HT des opérations imposables normales | HT amount of all taxable operations that form normal sales (goods + services taxable in France at 20%, 10%, 5,5%, 2,1%) | Sales: 7xxxx; VAT: 44571x / 44572x / 44573x / 44574x |
| **A2** | Montant HT des opérations imposables spéciales | HT amount of special taxable operations not part of ordinary turnover (e.g. cessions d'immobilisations, livraisons à soi-même) | 775xxx (gains on disposal), 72xxx (production immobilisée), VAT: 44571x |
| **A3** | Montant HT des services achetés à des prestataires non établis | HT amount of services purchased from providers not established in France but taxable in France (reverse charge for foreign services) | 6xxxx (services purchased), 4452xxx (TVA due autoliquidée) |
| **A4** | Montant HT des importations imposables en France | HT amount of imports taxable in France (non-EU), excluding petroleum products | 6xxxx / 2xxxx purchases or assets; VAT: 4452xxx (import VAT) |
| **A5** | Montant HT des opérations à la sortie d'un régime suspensif | HT amount of taxable operations at exit from a suspensive fiscal regime (customs regimes, free zones, etc.) | Specific 6xxxx/2xxxx depending on goods; VAT: 4452xxx |

##### B. Décompte de la TVA due (VAT Due Calculation) - Notice 4722

| CA-3 Line | Label | Description | PCG Accounts |
|-----------|-------|-------------|---------------|
| **08** | TVA due au taux de 20% | VAT amounts due, calculated on A1/A2 bases at 20% rate | 44571x (TVA collectée à 20%) |
| **09** | TVA due au taux de 10% | VAT amounts due, calculated on A1/A2 bases at 10% rate | 44572x (TVA collectée à 10%) |
| **9B** | TVA due aux taux réduits (5,5% et 2,1%) | VAT amounts due, calculated on A1/A2 bases at reduced rates (5,5% and 2,1%) | 44573x (5,5%) / 44574x (2,1%) (TVA collectée aux taux réduits) |
| **17** | TVA due au titre des acquisitions intracommunautaires | VAT due on intra-EU acquisitions (autoliquidation) | 4452xxx (TVA due intracommunautaire) |

##### C. Décompte de la TVA déductible (Deductible VAT Calculation) - Notice 4722

| CA-3 Line | Label | Description | PCG Accounts |
|-----------|-------|-------------|---------------|
| **20** | TVA déductible sur immobilisations | Deductible VAT on capital goods (fixed assets) | 44562x (TVA déductible sur immobilisations) |
| **21** | TVA déductible sur autres biens et services | Deductible VAT on other goods and services (operating expenses) | 44566x (TVA déductible sur autres biens et services) |
| **22** | TVA déductible sur importations | Deductible VAT on imports | 44566x / 44562x (TVA déductible sur importations) |

##### D. Résultat (Result) - Notice 4722

| CA-3 Line | Label | Description | PCG Accounts |
|-----------|-------|-------------|---------------|
| **25** | TVA brute due (Total TVA due) | Total VAT due (sum of all VAT due amounts) | Sum of 08 + 09 + 9B + 17 |
| **26** | TVA déductible totale (Total deductible VAT) | Total deductible VAT (sum of all deductible VAT amounts) | Sum of 20 + 21 + 22 |
| **28** | TVA nette à payer | Net VAT to pay (if total due > total deductible) | 445510 (État - TVA à décaisser) |
| **29** | Crédit de TVA à reporter ou remboursement | VAT credit to carry forward or refund (if total deductible > total due) | 445670 (État - Crédit de TVA à reporter ou rembourser) |

### 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