DeclarationTVA/TASK.md

DeclarationTVA - Task List

Project: French CA-3 VAT Declaration Module for Dolibarr

Created: 2025-01-27
Status: In Development
Priority: High

---

Phase 1: Foundation & Database (Week 1-2)

1.1 Database Schema Design

• Task 1.1.1: Design database schema for PCG account mappings

  • Create llx_declarationtva_config table structure
  • Define fields for CA-3 box mappings (01, 02, 03, 05, 08)
  • Add support for multiple VAT rates (20%, 10%, 5.5%, 2.1%)
  • Estimated: 4 hours
  • Dependencies: None

• Task 1.1.2: Design declaration storage schema

  • Create llx_declarationtva_declarations table
  • Add period management fields
  • Include status tracking (draft, submitted, approved)
  • Estimated: 3 hours
  • Dependencies: Task 1.1.1

• Task 1.1.3: Create period management table

  • Design llx_declarationtva_periods table
  • Support quarterly and monthly periods
  • Add period status and validation
  • Estimated: 2 hours
  • Dependencies: None

1.2 Core Class Structure

• Task 1.2.1: Create DeclarationTVA main class

  • File: core/class/declarationtva.class.php
  • Basic CRUD operations
  • Period management methods
  • Estimated: 6 hours
  • Dependencies: Task 1.1.1, 1.1.2

• Task 1.2.2: Create DeclarationTVA_Config class

  • File: core/class/declarationtva_config.class.php
  • PCG account mapping management
  • Validation methods
  • Estimated: 4 hours
  • Dependencies: Task 1.1.1

• Task 1.2.3: Create DeclarationTVA_Period class

  • File: core/class/declarationtva_period.class.php
  • Period creation and validation
  • Date range management
  • Estimated: 3 hours
  • Dependencies: Task 1.1.3

1.3 Database Implementation

• Task 1.3.1: Update SQL schema file

  • File: sql/dolibarr_allversions.sql
  • Add all table creation statements
  • Include indexes and constraints
  • Estimated: 2 hours
  • Dependencies: Tasks 1.1.1, 1.1.2, 1.1.3

• Task 1.3.2: Create database migration scripts

  • Handle version upgrades
  • Data migration procedures
  • Estimated: 3 hours
  • Dependencies: Task 1.3.1

---

Phase 2: Configuration Interface (Week 3-4)

2.1 Setup Page Enhancement

• Task 2.1.1: Redesign admin setup page

  • File: admin/setup.php
  • Replace generic parameters with CA-3 specific configuration
  • Add PCG account selection interface
  • Estimated: 8 hours
  • Dependencies: Task 1.2.2

• Task 2.1.2: Create PCG account mapping interface

  • Multi-select dropdown for each CA-3 line
  • Account search and filtering from Dolibarr's chart of accounts
  • Account validation against existing accounts
  • Rate selection (20%, 10%, 5.5%, 2.1%)
  • Account weighting and grouping
  • Estimated: 15 hours
  • Dependencies: Task 2.1.1

• Task 2.1.3: Implement multiple account selection

  • Connect to Dolibarr's llx_accounting_account table
  • Multi-select interface with search functionality
  • Account preview with current balances
  • Bulk operations for account management
  • Estimated: 12 hours
  • Dependencies: Task 2.1.2

• Task 2.1.4: Add period configuration

  • Quarterly/monthly period selection
  • Default period settings
  • Estimated: 4 hours
  • Dependencies: Task 1.2.3

2.2 User Interface Components

• Task 2.2.1: Create main declaration interface

  • File: declarationtvaindex.php
  • Period selection dropdown
  • Declaration status display
  • Estimated: 6 hours
  • Dependencies: Task 1.2.1

• Task 2.2.2: Add declaration creation wizard

  • Step-by-step process
  • Data validation at each step
  • Estimated: 8 hours
  • Dependencies: Task 2.2.1

---

Phase 3: Data Processing (Week 5-6)

3.1 Accounting Data Extraction

• Task 3.1.1: Create data extraction methods

  • Query Dolibarr accounting tables
  • Filter by PCG account codes
  • Handle different VAT rates
  • Estimated: 12 hours
  • Dependencies: Task 1.2.1

• Task 3.1.2: Implement CA-3 calculation logic

  • Section A (Output VAT): Boxes 01, 02, 03, 05, 08
  • Section B (Input VAT): Boxes 20, 21, 22
  • Section C (Result): Boxes 25, 26, 28, 29
  • Automatic calculation of totals and net amounts
  • Estimated: 20 hours
  • Dependencies: Task 3.1.1

• Task 3.1.3: Add data validation

  • Cross-check calculations
  • Validate against French tax rules
  • Error reporting
  • Estimated: 8 hours
  • Dependencies: Task 3.1.2

• Task 3.1.4: Implement complete CA-3 form structure (n° 3310-CA3-SD)

  • Section A: Opérations imposables - Lines A1, A2, B1-B4 (base + tax by rate)
  • Section B: TVA due - Line 17 (intra-EU acquisitions)
  • Section C: TVA déductible - Lines 20, 21 (capital goods, expenses)
  • Section D: Résultat - Lines 22, 28, 29 (credit/payment)
  • Automatic form line calculations and mapping
  • Estimated: 15 hours
  • Dependencies: Task 3.1.2

• Task 3.1.5: Implement CA-3 form line mapping

  • Map PCG accounts to specific CA-3 form lines
  • Handle base amounts (HT) and VAT amounts separately
  • Support all VAT rates (20%, 10%, 5.5%, 2.1%)
  • Special operations handling (A2 line)
  • Estimated: 12 hours
  • Dependencies: Task 3.1.4

• Task 3.1.6: Create detailed account breakdown system

  • Show source account for each amount in draft declarations
  • Display transaction details behind each CA-3 line
  • Allow drill-down from form lines to individual transactions
  • Export detailed breakdown reports
  • Estimated: 10 hours
  • Dependencies: Task 3.1.5

• Task 3.1.7: Implement EU transaction handling

  • Incoming EU invoices: autoliquidation (4452xxx + 4456xx)
  • B2B EU sales: no French VAT, lines 05/06 (base HT only)
  • B2C EU sales: OSS threshold handling (€10,000)
  • Special cases: construction, energy reverse charge
  • Estimated: 15 hours
  • Dependencies: Task 3.1.5

• Task 3.1.8: Add DEB/DES integration

  • Link CA-3 lines 05/06 with DEB/DES data
  • Cross-validation between CA-3 and exchange declarations
  • Automatic DEB/DES data import
  • Estimated: 12 hours
  • Dependencies: Task 3.1.7

3.2 Period Management

• Task 3.2.1: Implement period calculation

  • Automatic period detection
  • Date range validation
  • Estimated: 4 hours
  • Dependencies: Task 1.2.3

• Task 3.2.2: Add period locking mechanism

  • Prevent modifications to submitted periods
  • Audit trail
  • Estimated: 3 hours
  • Dependencies: Task 3.2.1

---

Phase 4: User Interface (Week 7-8)

4.1 Main Interface Development

• Task 4.1.1: Create declaration list view

  • Show all declarations by period
  • Status indicators
  • Action buttons (edit, delete, export)
  • Estimated: 6 hours
  • Dependencies: Task 2.2.1

• Task 4.1.2: Add declaration detail view

  • CA-3 form display
  • Editable fields
  • Calculation summary
  • Estimated: 8 hours
  • Dependencies: Task 3.1.2

• Task 4.1.3: Create period management interface

  • Period creation
  • Period status management
  • Estimated: 4 hours
  • Dependencies: Task 3.2.1

4.2 Form Handling

• Task 4.2.1: Implement form validation

  • Client-side validation
  • Server-side validation
  • Error message display
  • Estimated: 6 hours
  • Dependencies: Task 4.1.2

• Task 4.2.2: Add auto-save functionality

  • Save draft declarations
  • Restore previous sessions
  • Estimated: 4 hours
  • Dependencies: Task 4.2.1

---

Phase 5: Export and Reporting (Week 9-10)

5.1 PDF Generation

• Task 5.1.1: Create PDF template

  • File: templates/declarationtva/ca3_pdf.tpl
  • Official CA-3 form layout
  • Company information header
  • Estimated: 8 hours
  • Dependencies: Task 4.1.2

• Task 5.1.2: Implement PDF generation

  • Use Dolibarr PDF engine
  • Data population
  • Formatting and styling
  • Estimated: 6 hours
  • Dependencies: Task 5.1.1

5.2 Export Formats

• Task 5.2.1: Create XML export

  • French tax authority format
  • Data structure compliance
  • Estimated: 6 hours
  • Dependencies: Task 3.1.2

• Task 5.2.2: Create CSV export

  • Data analysis format
  • Customizable fields
  • Estimated: 3 hours
  • Dependencies: Task 3.1.2

5.3 Reporting Features

• Task 5.3.1: Add declaration history

  • Previous periods view
  • Comparison functionality
  • Estimated: 4 hours
  • Dependencies: Task 4.1.1

• Task 5.3.2: Create summary reports

  • Annual VAT summary
  • Trend analysis
  • Estimated: 5 hours
  • Dependencies: Task 5.3.1

---

Phase 6: Testing and Documentation (Week 11-12)

6.1 Unit Testing

• Task 6.1.1: Create test suite

  • File: test/phpunit/
  • Test all core classes
  • Test calculation logic
  • Estimated: 8 hours
  • Dependencies: All previous tasks

• Task 6.1.2: Integration testing

  • Test with real Dolibarr data
  • Performance testing
  • Estimated: 6 hours
  • Dependencies: Task 6.1.1

6.2 Documentation

• Task 6.2.1: Create user manual

  • Setup instructions
  • Usage guide
  • Troubleshooting
  • Estimated: 6 hours
  • Dependencies: All previous tasks

• Task 6.2.2: Create developer documentation

  • API documentation
  • Code comments
  • Architecture overview
  • Estimated: 4 hours
  • Dependencies: All previous tasks

6.3 French Compliance

• Task 6.3.1: Validate tax compliance

  • Review with French tax expert
  • Format validation
  • Estimated: 4 hours
  • Dependencies: Task 5.2.1

• Task 6.3.2: Final testing

  • End-to-end testing
  • User acceptance testing
  • Estimated: 6 hours
  • Dependencies: Task 6.3.1

---

Language Support

6.4 Bilingual Interface

• Task 6.4.1: Complete French translations

  • File: langs/fr_FR/declarationtva.lang
  • All interface elements
  • Error messages
  • Estimated: 4 hours
  • Dependencies: All UI tasks

• Task 6.4.2: Complete English translations

  • File: langs/en_US/declarationtva.lang
  • Update existing translations
  • Estimated: 2 hours
  • Dependencies: Task 6.4.1

---

Advanced Features (Phase 7 - Week 13-14)

7.1 Draft System and Validation Workflow

• Task 7.1.1: Implement draft declaration system

  • All declarations start as drafts
  • Detailed account breakdown display
  • Edit capabilities before validation
  • Estimated: 8 hours
  • Dependencies: Task 4.1.2

• Task 7.1.2: Create validation workflow

  • User validation interface
  • Validation checklist
  • Approval process
  • Estimated: 6 hours
  • Dependencies: Task 7.1.1

• Task 7.1.3: Add audit trail system

  • Track all changes and validations
  • User activity logging
  • Version history
  • Estimated: 4 hours
  • Dependencies: Task 7.1.2

7.2 Accounting Integration

• Task 7.2.1: Create journal entry generation

  • Automatic accounting entries for validated declarations
  • Transfer to 445510 (TVA à décaisser) or 445670 (Crédit de TVA)
  • Integration with Dolibarr accounting
  • Estimated: 10 hours
  • Dependencies: Task 7.1.2

• Task 7.2.2: Add accounting validation

  • Check journal entry accuracy
  • Balance verification
  • Estimated: 4 hours
  • Dependencies: Task 7.2.1

7.3 Advanced Analytics and Reporting

• Task 7.3.1: Create comparison tools

  • Compare declarations across periods
  • Variance analysis
  • Trend reporting
  • Estimated: 8 hours
  • Dependencies: Task 5.3.1

• Task 7.3.2: Build reporting dashboard

  • Visual analytics and trends
  • Key performance indicators
  • Interactive charts
  • Estimated: 10 hours
  • Dependencies: Task 7.3.1

• Task 7.3.3: Add exception handling

  • Flag unusual amounts
  • Missing data detection
  • Automated alerts
  • Estimated: 6 hours
  • Dependencies: Task 3.1.3

7.4 Document and Notification Management

• Task 7.4.1: Implement document management

  • Attach supporting documents
  • File organization
  • Document versioning
  • Estimated: 6 hours
  • Dependencies: Task 4.1.2

• Task 7.4.2: Create notification system

  • Email alerts for deadlines
  • Status change notifications
  • Reminder system
  • Estimated: 8 hours
  • Dependencies: Task 7.1.2

7.5 Multi-Entity and Integration Features

• Task 7.5.1: Add multi-entity support

  • Handle multiple companies
  • Entity-specific configurations
  • Consolidated reporting
  • Estimated: 12 hours
  • Dependencies: Task 1.2.1

• Task 7.5.2: Create integration APIs

  • Connect with external tax systems
  • API documentation
  • Webhook support
  • Estimated: 10 hours
  • Dependencies: Task 7.2.1

• Task 7.5.3: Implement backup/restore

  • Declaration data backup
  • Recovery procedures
  • Data migration tools
  • Estimated: 6 hours
  • Dependencies: Task 7.1.3

7.6 Mobile and User Experience

• Task 7.6.1: Add mobile support

  • Responsive design
  • Mobile-optimized interface
  • Touch-friendly controls
  • Estimated: 8 hours
  • Dependencies: Task 4.1.1

• Task 7.6.2: Enhance user experience

  • Improved navigation
  • Keyboard shortcuts
  • Accessibility features
  • Estimated: 6 hours
  • Dependencies: Task 7.6.1

7.7 Dolibarr Workflow Integration

• Task 7.7.1: Create Dolibarr hook system

  • File: core/triggers/interface_99_modDeclarationTVA_DeclarationTVATrigger.class.php
  • Implement hook interface
  • Register hooks for invoice processing
  • Estimated: 8 hours
  • Dependencies: Task 1.2.1

• Task 7.7.2: Implement autoliquidation automation

  • Hook into supplier_invoice_validate
  • Auto-detect EU suppliers
  • Create VAT due and deductible entries
  • Estimated: 12 hours
  • Dependencies: Task 7.7.1

• Task 7.7.3: Add EU transaction automation

  • Hook into invoice_validate for customer invoices
  • Auto-apply EU transaction rules
  • Handle B2B vs B2C scenarios
  • Estimated: 10 hours
  • Dependencies: Task 7.7.2

• Task 7.7.4: Create custom fields for VAT processing

  • EU supplier flag
  • VAT treatment selection
  • Transaction type classification
  • Estimated: 6 hours
  • Dependencies: Task 7.7.1

• Task 7.7.5: Implement batch processing

  • Handle multiple invoices
  • Bulk VAT processing
  • Progress tracking
  • Estimated: 8 hours
  • Dependencies: Task 7.7.3

Advanced Intelligence Features (Phase 9 - Week 15-16)

9.1 VAT Forecasting & Analytics

• Task 9.1.1: Implement VAT forecasting

  • Historical data analysis
  • Predictive modeling for future VAT obligations
  • Seasonal pattern recognition
  • Estimated: 12 hours
  • Dependencies: Task 5.3.2

• Task 9.1.2: Add anomaly detection

  • AI-powered unusual pattern detection
  • Automated alerts for suspicious transactions
  • Machine learning for VAT optimization
  • Estimated: 15 hours
  • Dependencies: Task 9.1.1

• Task 9.1.3: Create cash flow impact analysis

  • VAT impact on cash flow projections
  • Payment timing optimization
  • Working capital analysis
  • Estimated: 8 hours
  • Dependencies: Task 9.1.1

9.2 Tax Authority Integration

• Task 9.2.1: Implement direct submission

  • Connect with French tax authority APIs
  • Direct CA-3 submission
  • Real-time validation
  • Estimated: 20 hours
  • Dependencies: Task 5.2.1

• Task 9.2.2: Add electronic signatures

  • Digital signature for declarations
  • Secure submission process
  • Receipt management
  • Estimated: 10 hours
  • Dependencies: Task 9.2.1

• Task 9.2.3: Create payment integration

  • Direct VAT payment processing
  • Bank account integration
  • Payment status tracking
  • Estimated: 12 hours
  • Dependencies: Task 9.2.1

9.3 Advanced Compliance

• Task 9.3.1: Implement regulatory updates

  • Automatic tax law change detection
  • Rule update notifications
  • Compliance impact analysis
  • Estimated: 8 hours
  • Dependencies: Task 6.3.1

• Task 9.3.2: Add penalty calculation

  • Late submission penalty calculation
  • Interest calculation
  • Compliance risk assessment
  • Estimated: 6 hours
  • Dependencies: Task 9.3.1

9.4 Business Intelligence

• Task 9.4.1: Create advanced analytics

  • VAT analytics by customer/supplier
  • Geographic VAT analysis
  • Product category VAT analysis
  • Estimated: 15 hours
  • Dependencies: Task 7.3.2

• Task 9.4.2: Implement profitability analysis

  • VAT impact on product profitability
  • Cost analysis with VAT
  • Pricing optimization suggestions
  • Estimated: 10 hours
  • Dependencies: Task 9.4.1

Discovered During Work

Tasks discovered during development will be added here

---

Notes

• All tasks should include proper error handling
• Code must follow Dolibarr coding standards
• All user-facing text must be translatable
• Database changes must be backward compatible
• Performance optimization for large datasets
• Security considerations for financial data

Total Estimated Time: 577+ hours

Breakdown by Phase:

• Phase 1-2: Foundation & Configuration (40 hours)
• Phase 3: Data Processing (87 hours)
• Phase 4: User Interface (30 hours)
• Phase 5: Export & Reporting (25 hours)
• Phase 6: Testing & Documentation (25 hours)
• Phase 7: Advanced Features (80 hours)
• Phase 8: Dolibarr Workflow Integration (44 hours)
• Phase 9: Advanced Intelligence (106 hours)
• Multiple Account Selection: +27 hours
• Buffer & Integration: 140 hours

Priority Order:

1. Database schema and core classes
2. Configuration interface
3. Data processing and calculations
4. User interface
5. Export functionality
6. Testing and documentation