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:

A. TVA collectée (Output VAT – amounts due)

Box	Label	Description	PCG Accounts
01	Livraisons de biens et prestations de services imposables en France	Domestic sales at 20% (or reduced rates)	7xxxx (Sales) → 44571x (TVA collectée à 20%), 44572x (10%), 44573x (5,5%), 44574x (2,1%)
02	Autres opérations imposables	Other taxable domestic operations	Same 4457xx depending on rate
03	Acquisitions intracommunautaires	Intra-EU purchases (autoliquidation)	Base: 6xxxx purchases / 2xxxx immobilisations. VAT due: 4452xxx (TVA due intracom)
05	Importations	Imports from outside EU	4452xxx (TVA due sur importations)
08	Autres opérations imposables	Specific operations (reverse charge on services, etc.)	4452xxx

B. TVA déductible (Input VAT – amounts reclaimable)

Box	Label	Description	PCG Accounts
20	TVA déductible sur immobilisations	Deductible VAT on capital goods (fixed assets)	44562x
21	TVA déductible sur autres biens et services	Deductible VAT on operating expenses	44566x
22	TVA déductible sur importations	Deductible VAT self-assessed on imports	44566x / 44562x (depending on expense vs immobilisation)

C. Résultat (Result)

Box	Label	Description	PCG Accounts
25	TVA brute due	Sum of boxes 01 + 02 + 03 + 05 + 08	4457xx (collected) + 4452xx (autoliquidated VAT due)
26	TVA déductible totale	Sum of 20 + 21 + 22	4456xx (deductible)
28	TVA nette due	25 – 26 if positive	Transfer to 445510 (État – TVA à décaisser)
29	Crédit de TVA	If deductible > due	Transfer to 445670 (État – Crédit de TVA à reporter ou rembourser)

Technical Requirements

Database Structure

• Main table: llx_declarationtva_config - Stores PCG account mappings
• Declaration table: llx_declarationtva_declarations - Stores generated declarations
• Period table: llx_declarationtva_periods - Manages declaration periods

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

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
├── 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