AlexBordaraud: Created page with "Category:Complementary modules Category:TVANDF Category:Expense reports Category:VAT management Category:Multi-VAT {{TemplateDocDevEn}} {{TemplateDocUser}}..."

2026-05-04T06:52:15Z

Created page with "Category:Complementary modules Category:TVANDF Category:Expense reports Category:VAT management Category:Multi-VAT {{TemplateDocDevEn}} {{TemplateDocUser}}..."

New page

[[Category:Complementary modules]]
[[Category:TVANDF]]
[[Category:Expense reports]]
[[Category:VAT management]]
[[Category:Multi-VAT]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
=Informations=

{{TemplateModuleInfo
|modulename=Tvandf
|editor=Alex BORDARAUD - Lysis https://lysis.net
|webbuy=
|status=stable
|version=1.0.5
|minversion=19.0
|maxversion=
|note=Module ID: 142804 ([[List_of_modules_id]])
}}

'''TVANDF''' (technical module name: '''TvaNdf''', directory <code>tvandf</code>, ID '''142804''') is a complementary Dolibarr module that transforms '''multi-VAT expense report entry'''. It adds a '''matrix interface''' allowing expense breakdown across '''multiple VAT rates''' with '''single supporting document''' for the entire group. Technically, the module uses extrafield <code>tvandf_line_group</code> to group generated standard Dolibarr lines, providing '''full compatibility''' with the native accounting engine.

=Technical Architecture=

==Database Layer==
* '''No core table modifications''': Uses existing <code>expensereport_det</code> structure
* '''Extrafield integration''': <code>options_tvandf_line_group</code> UUID links related lines
* '''ECM compatibility''': Standard <code>fk_ecm_files</code> reference sharing across group members
* '''VAT dictionary binding''': Dynamic rate columns from active <code>c_tva</code> entries filtered by <code>mysoc->country_id</code>

==Hook Implementation==
* '''Context targeting''': <code>expensereportcard</code> hook injection points
* '''Asset loading''': CSS/JS via <code>printCommonFooter</code> with bootstrap data attributes
* '''Action buttons''': <code>addMoreActionsButtons</code> for matrix toggle and add-line functions
* '''Permission alignment''': Respects core <code>expensereport->creer</code> rights and draft/refused workflow

==Frontend Architecture==
* '''jQuery UI dialogs''': Matrix forms with VAT rate columns and shared metadata fields
* '''AJAX endpoints''': <code>ajax/expensereport_matrix.php</code> for CRUD operations on line groups
* '''File upload''': Integrated ECM document attachment with progress feedback
* '''View switching''': Seamless toggle between matrix UI and standard Dolibarr line table

=Description=

==English (Technical)==

'''Core Problem:''' Standard Dolibarr expense workflow (<code>expensereport/card.php</code>) processes entries through <code>ExpenseReportLine</code> objects with '''one VAT rate per database row'''. Multi-rate receipts require '''multiple line insertions''', duplicated context fields (<code>fk_projet</code>, <code>date</code>, <code>comments</code>), and separate ECM document associations following native <code>fk_element</code> patterns.

'''TVANDF Solution:''' Hook-based matrix UI overlaying the expense card context. Dynamic VAT grid populated from active tax dictionary, generating '''standard expense lines''' linked via technical extrafield. ECM integration uses shared document references across grouped lines.

'''Technical Benefits:'''
* '''Non-intrusive integration''': Hook system preserves core functionality
* '''Native line compatibility''': Generated <code>ExpenseReportLine</code> objects with standard fields
* '''Extrafield grouping''': UUID-based line association without schema modifications
* '''Permission compliance''': Core rights and status workflow preservation
* '''ECM integration''': Standard document management with reference sharing

==Français (Technique)==

'''Problème central :''' Le workflow natif Dolibarr (<code>expensereport/card.php</code>) traite les saisies via des objets <code>ExpenseReportLine</code> avec '''un taux de TVA par ligne en base'''. Les reçus multi-taux nécessitent '''plusieurs insertions de lignes''', la duplication des champs de contexte (<code>fk_projet</code>, <code>date</code>, <code>comments</code>), et des associations ECM séparées suivant les patterns natifs <code>fk_element</code>.

'''Solution TVANDF :''' Interface matricielle basée sur hooks superposée au contexte de fiche de frais. Grille TVA dynamique alimentée depuis le dictionnaire fiscal actif, générant des '''lignes de frais standard''' reliées via extrafield technique. L'intégration ECM utilise des références de documents partagées entre lignes groupées.

'''Avantages techniques :'''
* '''Intégration non-intrusive''': Le système de hooks préserve les fonctionnalités du cœur
* '''Compatibilité lignes natives''': Objets <code>ExpenseReportLine</code> générés avec champs standards
* '''Regroupement par extrafield''': Association de lignes par UUID sans modifications de schéma
* '''Conformité permissions''': Préservation des droits et workflow de statut du cœur
* '''Intégration ECM''': Gestion documentaire standard avec partage de références

=Fonctionnalités techniques=

==Matrix UI Components==
* '''Dynamic VAT columns''': Auto-generated from <code>c_tva</code> active entries for company country
* '''Shared metadata fields''': Date, expense type, project, description, quantity, mileage
* '''File attachment zone''': ECM upload with <code>fk_ecm_files</code> reference storage
* '''Calculation engine''': Real-time HT/TTC totals with VAT breakdown display
* '''Validation logic''': Field requirement checks aligned with Dolibarr expense configuration

==Backend Processing==
* '''Line group creation''': UUID generation and extrafield population on insert
* '''ECM file linking''': Document association across all group member lines
* '''Deletion cascade''': Group-level removal with confirmation dialog
* '''Edit synchronization''': Metadata updates propagated to all grouped lines
* '''Accounting integration''': Standard line generation preserving native booking logic

==Administration Interface==
* '''Setup tab''': Prerequisites explanation, extrafield documentation, native settings link
* '''About tab''': Module metadata, version info, editor contact
* '''Changelog tab''': Version history from <code>ChangeLog.md</code> with markdown rendering
* '''Dependency checks''': Core expense report module validation

=API Endpoints=

==AJAX Interface (<code>ajax/expensereport_matrix.php</code>)==
* '''<code>get_state</code>''': Load existing line groups with VAT rate breakdown
* '''<code>save_group</code>''': Create/update line group with metadata and VAT amounts
* '''<code>delete_group</code>''': Remove line group and all associated lines
* '''<code>upload_piece</code>''': ECM file upload with progress tracking
* '''<code>get_vat_rates</code>''': Dynamic VAT rate list for company configuration

==Security Model==
* '''Token validation''': CSRF protection on all AJAX endpoints
* '''Permission checks''': <code>expensereport->creer</code> validation per operation
* '''Entity filtering''': MultiCompany support with proper data isolation
* '''Status validation''': Draft/refused state enforcement for edit operations

=Installation and Configuration=

==Technical Requirements==
* '''Dolibarr version''': 19.0+ (see <code>modTvaNdf.class.php</code> for exact version)
* '''PHP version''': 7.1+ with standard extensions
* '''Database''': Compatible with all Dolibarr-supported databases
* '''Browser''': JavaScript-enabled for matrix UI functionality
* '''Dependencies''': Core expense report module mandatory

==Installation Process==
# Download <code>module_tvandf-x.y.z.zip</code> (ZIP root = single <code>tvandf/</code> directory)
# '''Home → Setup → Modules → Deploy/Import external module'''
# Activate '''TVANDF'''/'TvaNdf' module
# Verify extrafield creation: '''Setup → Dictionaries → Expense report lines - Extra fields'''
# Configure VAT rates in '''Setup → Dictionaries → VAT''' for proper matrix columns

==Configuration Notes==
* '''Extrafield preservation''': Do not delete <code>tvandf_line_group</code> while using matrix features
* '''VAT dictionary dependency''': Active rates determine available matrix columns
* '''ECM configuration''': Standard Dolibarr document management settings apply
* '''Permission setup''': Standard expense report rights control matrix access

=Developer Information=

==Module Structure==
* '''Core descriptor''': <code>core/modules/modTvaNdf.class.php</code>
* '''Hook implementation''': <code>class/actions_tvandf.class.php</code>
* '''Matrix logic''': <code>lib/tvandf_matrix.lib.php</code>
* '''AJAX handler''': <code>ajax/expensereport_matrix.php</code>
* '''Frontend assets''': <code>js/expensereport_matrix.js</code>, <code>css/expensereport_matrix.css</code>

==Customization Points==
* '''VAT rate filtering''': Modify <code>tvandf_matrix_list_vat_rates()</code> for custom rate logic
* '''Extrafield naming''': <code>TVANDF_EXTRA_LINE_GROUP</code> constant in <code>lib/tvandf.lib.php</code>
* '''UI labels''': Translation files in <code>langs/*/tvandf.lang</code>
* '''Matrix layout''': CSS customization in <code>css/expensereport_matrix.css</code>

==Extension Opportunities==
* '''Additional grouping fields''': Extend extrafield structure for complex scenarios
* '''Custom validation rules''': Hook into save logic for business-specific constraints
* '''Reporting integration''': Matrix data available through standard Dolibarr line queries
* '''API expansion''': Additional endpoints for external integration needs

=Compatibility and Limitations=

==Dolibarr Compatibility==
* '''Core versions''': Tested on Dolibarr 19.0 through 21.x series
* '''MultiCompany''': Full support with entity-based data isolation
* '''Accounting''': Compatible with all standard accounting export formats
* '''Themes''': Responsive design adapts to standard Dolibarr themes

==Known Limitations==
* '''JavaScript dependency''': Matrix UI requires enabled JavaScript
* '''Browser compatibility''': Modern browsers required for optimal experience
* '''Large VAT sets''': Performance considerations with 15+ active VAT rates
* '''Mobile optimization''': Matrix interface optimized for desktop/tablet use

=Support and Development=

==Professional Services==
* '''Installation assistance''': Configuration and deployment support
* '''Custom development''': Module extensions and integrations
* '''Training services''': User and administrator training programs
* '''Technical support''': Issue resolution and optimization guidance

==Community Resources==
* '''Documentation''': Complete technical documentation in module <code>doc/</code> directory
* '''Issue tracking''': Report bugs and feature requests to module maintainer
* '''Version updates''': Regular releases with Dolibarr compatibility updates
* '''Code contributions''': Community patches and improvements welcome

==Contact Information==
* '''Developer''': Alex BORDARAUD - Lysis
* '''Website''': https://lysis.net
* '''License''': GPLv3+
* '''Module ID''': 142804

=Related Modules and Integration=

==Dolibarr Core Integration==
* '''[[ModuleExpensesReports]]''': Core expense report functionality
* '''[[ModuleECM]]''': Document management system integration
* '''[[ModuleMultiCompany]]''': Multi-entity support compatibility
* '''[[ModuleAccounting]]''': Accounting export and journal integration

==Complementary Modules==
* VAT management modules for enhanced tax handling
* Project module integration for expense allocation
* HR modules for approval workflow enhancement
* Reporting modules for advanced expense analytics

=Technical Reference=

==Database Schema Extensions==
```sql
-- Extrafield on expensereport_det table
ALTER TABLE llx_expensereport_det_extrafields ADD COLUMN tvandf_line_group varchar(255);
```

==Key PHP Classes==
* <code>ActionsTvandf</code>: Main hook implementation class
* <code>ExpenseReportLine</code>: Native Dolibarr line object (preserved)
* <code>ExtraFields</code>: Dolibarr extrafield management (extended)

==JavaScript API==
* Matrix initialization: <code>TvandfMatrix.init()</code>
* Group operations: <code>TvandfMatrix.saveGroup()</code>, <code>TvandfMatrix.deleteGroup()</code>
* File upload: <code>TvandfMatrix.uploadFile()</code>

==Configuration Constants==
* <code>TVANDF_EXTRA_LINE_GROUP</code>: Extrafield name constant
* Module configuration accessible via <code>$conf->tvandf</code> global

=Version History=

See <code>ChangeLog.md</code> in module root for detailed version history and upgrade notes.

=See Also=

* [[List_of_modules_id|Dolibarr Module ID Registry]]
* [[ModuleExpensesReports|Core Expense Reports Documentation]]
* [[Hooks|Dolibarr Hook System Documentation]]
* [[ExtraFields|Dolibarr ExtraFields System]]

Module TvaNdf - Revision history

AlexBordaraud: Created page with "Category:Complementary modules Category:TVANDF Category:Expense reports Category:VAT management Category:Multi-VAT {{TemplateDocDevEn}} {{TemplateDocUser}}..."