DeclarationTVA/TEMPLATE_MAINTENANCE_MANUAL.md

# Template Maintenance Manual
## DeclarationTVA Module - Official Template Management

### Overview
This manual explains how to maintain and update the official CA-3 template for the DeclarationTVA module. The system supports both online template updates and local template management.

---

## 📋 Table of Contents
1. [Template System Overview](#template-system-overview)
2. [Updating the Official Template](#updating-the-official-template)
3. [Version Management](#version-management)
4. [File Structure](#file-structure)
5. [Troubleshooting](#troubleshooting)
6. [Best Practices](#best-practices)

---

## 🏗️ Template System Overview

### How It Works
- **Official Template**: Stored in `templates/declarationtva/ca3_official_template.pdf`
- **Custom Templates**: Users can upload custom templates (stored as `ca3_custom_template.pdf`)
- **Version Control**: Template versions are managed through `manifest.json`
- **Online Updates**: Other installations can check for template updates via Gitea

### Key Files
- `templates/declarationtva/ca3_official_template.pdf` - Official template file
- `templates/manifest.json` - Version and update information
- `core/class/declarationtva_pdf.class.php` - Template management logic

---

## 🔄 Updating the Official Template

### Step 1: Prepare Your New Template
1. **Obtain the new official template** (e.g., from government sources)
2. **Ensure it's a valid PDF** and follows the expected format
3. **Name it appropriately** (e.g., `3310-ca3-sd_4931.pdf`)

### Step 2: Replace the Template File
```bash
# Navigate to the module directory
cd /path/to/dolibarr/htdocs/custom/declarationtva

# Replace the official template
cp /path/to/your/new/template.pdf templates/declarationtva/ca3_official_template.pdf
```

### Step 3: Update Version Information (if needed)
If this is a new version of the template, update the version in the code:

**File: `core/class/declarationtva_pdf.class.php`**
```php
// Line 67 - Update the version number
public $template_version = '30';  // Change to new version if needed
```

**File: `templates/manifest.json`**
```json
{
  "templates": {
    "ca3": {
      "current_version": "30",  // Update if new version
      "document_number": "10963*30",  // Update document number if changed
      "description": "Official CA-3 VAT Declaration Template",
      "releases": {
        "30": {
          "download_url": "https://git.covago.com/frank/DeclarationTVA/raw/branch/main/templates/declarationtva/ca3_official_template.pdf",
          "checksum": "sha256:placeholder_checksum_here",
          "release_date": "2025-01-27",  // Update to current date
          "description": "Official CA-3 template version 30"
        }
      }
    }
  }
}
```

### Step 4: Commit and Push Changes
```bash
# Add the new template file
git add templates/declarationtva/ca3_official_template.pdf

# Add any manifest changes
git add templates/manifest.json

# Add any code changes
git add core/class/declarationtva_pdf.class.php

# Commit the changes
git commit -m "Update official CA-3 template to version X

- Replace ca3_official_template.pdf with new government template
- Update version information in manifest.json
- Update template version in PDF class"

# Push to repository
git push origin main
```

---

## 📊 Version Management

### When to Update Versions
- **Government Template Changes**: When the official government template is updated
- **Format Changes**: When the PDF structure changes significantly
- **Field Changes**: When form fields are added, removed, or modified

### Version Number Guidelines
- **Major Version**: Use the official government version number (e.g., "30")
- **Minor Version**: Use for fixes and improvements (e.g., "30.1", "30.2")
- **Format**: `major.minor` (e.g., "30.1" for government version 30 with fixes)
- **Document Changes**: Always document what changed in the commit message

### Version Update Process
1. **Check if template actually changed** (compare with current version)
2. **If changed**: Update version numbers in both files
3. **If unchanged**: Just replace the file, keep same version

### Minor Version System
The system uses a `major.minor` version format:

- **Major Version (30)**: Official government version
- **Minor Version (.1, .2, .3)**: Your fixes and improvements

**Examples:**
- `30.0` - Original government template
- `30.1` - Government template + field fixes
- `30.2` - Government template + additional improvements
- `31.0` - New government template (when available)

**Benefits:**
- ✅ Keep government version as major number
- ✅ Track your improvements with minor numbers
- ✅ Other installations get automatic updates
- ✅ Clear version history

### Practical Example
**Scenario**: You need to fix field positioning in the official template

1. **Current version**: `30.1`
2. **Fix the template**: Update PDF file with corrected fields
3. **Update version**: Change to `30.2`
4. **Update manifest**: Add new release entry for `30.2`
5. **Commit and push**: All installations will auto-update to `30.2`

**Result**: 
- Government version stays `30` (major)
- Your fixes are tracked as `30.2` (minor)
- All installations get the improved template automatically

---

## 📁 File Structure

```
templates/
├── declarationtva/
│   ├── ca3_official_template.pdf    # Official template (replace this)
│   ├── ca3_custom_template.pdf      # User custom template (auto-generated)
│   └── README.md                    # Template documentation
├── manifest.json                    # Version and update info
└── README.md                       # Template system documentation

core/class/
└── declarationtva_pdf.class.php       # Template management logic
```

### Key Files to Edit

#### 1. Template File
- **Location**: `templates/declarationtva/ca3_official_template.pdf`
- **Purpose**: The actual PDF template file
- **Action**: Replace with new template

#### 2. Manifest File
- **Location**: `templates/manifest.json`
- **Purpose**: Version information and download URLs
- **Action**: Update version, date, description if needed

#### 3. PDF Class
- **Location**: `core/class/declarationtva_pdf.class.php`
- **Purpose**: Template version and management logic
- **Action**: Update `$template_version` if new version

---

## 🔧 Troubleshooting

### Common Issues

#### Template Not Updating
**Problem**: Users don't see template updates
**Solution**: 
1. Check if manifest.json is accessible online
2. Verify template file is in correct location
3. Clear any caches

#### Version Mismatch
**Problem**: Version numbers don't match
**Solution**:
1. Ensure `$template_version` in PDF class matches manifest
2. Check that both files are committed and pushed

#### Template Upload Fails
**Problem**: Users can't upload custom templates
**Solution**:
1. Check file permissions on template directory
2. Verify template path is correct
3. Check PHP upload limits

### Debug Steps
1. **Check Template Status**: Go to Configuration → Template Management tab
2. **Check Logs**: Look for DeclarationTVA log entries
3. **Verify Files**: Ensure template files exist in correct locations
4. **Test Reset**: Try "REVENIR AU MODELE OFFICIEL" button

---

## ✅ Best Practices

### Template Updates
1. **Always test** the new template before deploying
2. **Keep backups** of previous template versions
3. **Document changes** in commit messages
4. **Update version numbers** only when necessary

### Version Management
1. **Use government version numbers** when available
2. **Don't increment versions** for minor fixes
3. **Document version changes** clearly
4. **Test version detection** after updates

### File Management
1. **Use descriptive commit messages**
2. **Tag important releases** if needed
3. **Keep template files organized**
4. **Document any special requirements**

### Testing
1. **Test template upload** functionality
2. **Test template reset** functionality
3. **Test version detection** on other installations
4. **Verify online updates** work correctly

---

## 🚀 Quick Update Checklist

When updating the official template:

- [ ] **Obtain new template file** from official source
- [ ] **Replace** `templates/declarationtva/ca3_official_template.pdf`
- [ ] **Check if version needs updating** (usually keep same version)
- [ ] **Update manifest.json** if version changed
- [ ] **Update PDF class** if version changed
- [ ] **Test template functionality** locally
- [ ] **Commit and push** changes
- [ ] **Verify online access** to template file
- [ ] **Test on other installations** if possible

---

## 📞 Support

If you encounter issues:
1. **Check the logs** for error messages
2. **Verify file permissions** and paths
3. **Test template functionality** step by step
4. **Check online accessibility** of template files

---

*Last updated: January 2025*
*Template system version: 2.3.0*