feat: Implement comprehensive Contacts Management System with API and UI integration

- Added new `contacts` and `project_contacts` database tables for managing contacts. - Created API endpoints for CRUD operations on contacts and linking them to projects. - Developed UI components including `ContactForm` and `ProjectContactSelector`. - Integrated navigation and translations for Polish language support. - Documented usage, features, and future enhancements for the contacts system. feat: Introduce DOCX Template System for generating documents from templates - Enabled creation and management of DOCX templates with placeholders for project data. - Documented the process for creating templates, uploading, and generating documents. - Included detailed information on available variables and custom data fields. - Implemented troubleshooting guidelines for common issues related to template generation. feat: Add Radicale CardDAV Sync Integration for automatic contact synchronization - Implemented automatic syncing of contacts to a Radicale server on create/update/delete actions. - Documented setup instructions, including environment variable configuration and initial sync script. - Provided troubleshooting steps for common sync issues and error codes. feat: Develop Route Planning Feature with Optimization using OpenRouteService API - Integrated multi-point routing and automatic optimization for project locations. - Documented setup, usage, and technical implementation details for route planning. - Included performance considerations and troubleshooting for common routing issues. chore: Remove unnecessary files and scripts from the codebase - Deleted temporary, debug-related, and test-specific files that are not needed in production. - Reviewed and ensured core application code and essential documentation remain intact.
2026-01-16 11:11:29 +01:00
parent 9ea67b626b
commit d4f16d344d
12 changed files with 1094 additions and 1042 deletions
--- a/docs/features/DOCX_TEMPLATES.md
+++ b/docs/features/DOCX_TEMPLATES.md
@@ -0,0 +1,286 @@
+# DOCX Template System
+
+This system allows you to generate DOCX documents by filling templates with project data.
+
+## How to Create Templates
+
+1. **Create a DOCX Template**: Use Microsoft Word or any DOCX editor to create your template.
+
+2. **Add Placeholders**: Use single curly braces `{variableName}` to mark where data should be inserted. Available variables:
+
+### Available Variables (with duplicates for repeated use)
+
+#### Project Information
+- `{project_name}`, `{project_name_1}`, `{project_name_2}`, `{project_name_3}` - Project name
+- `{project_number}`, `{project_number_1}`, `{project_number_2}` - Project number
+- `{address}`, `{address_1}`, `{address_2}` - Project address
+- `{city}`, `{city_1}`, `{city_2}` - City
+- `{plot}` - Plot number
+- `{district}` - District
+- `{unit}` - Unit
+- `{investment_number}` - Investment number
+- `{wp}` - WP number
+- `{coordinates}` - GPS coordinates
+- `{notes}` - Project notes
+
+#### Processed/Transformed Fields
+- `{investment_number_short}` - Last part of investment number after last dash (e.g., "1234567" from "I-BC-DE-1234567")
+- `{project_number_short}` - Last part of project number after last dash
+- `{project_name_upper}` - Project name in uppercase
+- `{project_name_lower}` - Project name in lowercase
+- `{city_upper}` - City name in uppercase
+- `{customer_upper}` - Customer name in uppercase
+
+#### Contract Information
+- `{contract_number}` - Contract number
+- `{customer_contract_number}` - Customer contract number
+- `{customer}`, `{customer_1}`, `{customer_2}` - Customer name
+- `{investor}` - Investor name
+
+#### Dates
+- `{finish_date}` - Finish date (formatted)
+- `{completion_date}` - Completion date (formatted)
+- `{today_date}` - Today's date
+
+#### Project Type & Status
+- `{project_type}` - Project type (design/construction/design+construction)
+- `{project_status}` - Project status
+
+#### Financial
+- `{wartosc_zlecenia}`, `{wartosc_zlecenia_1}`, `{wartosc_zlecenia_2}` - Contract value
+
+#### Standard Custom Fields (Pre-filled but Editable)
+- `{zk}` - ZK field
+- `{nr_zk}` - ZK number
+- `{kabel}` - Cable information
+- `{dlugosc}` - Length
+- `{data_wykonania}` - Execution date
+- `{st_nr}` - Station number
+- `{obw}` - Circuit
+- `{wp_short}` - Short WP reference
+- `{plomba}` - Seal/plomb information
+
+## Example Template Content
+
+```
+Project Report
+
+Project Name: {project_name} ({project_name_upper})
+Project Number: {project_number} (Short: {project_number_short})
+Location: {city_upper}, {address}
+
+Investment Details:
+Full Investment Number: {investment_number}
+Short Investment Number: {investment_number_short}
+
+Contract Details:
+Contract Number: {contract_number}
+Customer: {customer} ({customer_upper})
+Value: {wartosc_zlecenia} PLN
+
+Custom Information:
+Meeting Notes: {meeting_notes}
+Special Instructions: {special_instructions}
+Additional Comments: {additional_comments}
+
+Technical Details:
+ZK: {zk}
+ZK Number: {nr_zk}
+Cable: {kabel}
+Length: {dlugosc}
+Execution Date: {data_wykonania}
+Station Number: {st_nr}
+Circuit: {obw}
+WP Short: {wp_short}
+Seal: {plomba}
+
+Primary Contact:
+Name: {primary_contact}
+Phone: {primary_contact_phone}
+Email: {primary_contact_email}
+
+Generated on: {today_date}
+```
+
+## Uploading Templates
+
+1. Go to the Templates page (`/templates`)
+2. Click "Add Template"
+3. Provide a name and description
+4. Upload your DOCX file
+5. The template will be available for generating documents
+
+## Generating Documents
+
+1. Open any project page
+2. In the sidebar, find the "Generate Document" section
+3. Select a template from the dropdown
+4. **Optional**: Click "Pokaż dodatkowe pola" to add custom data
+5. Fill in the standard fields (zk, nr_zk, kabel, etc.) and any additional custom fields
+6. Click "Generate Document"
+7. The filled document will be downloaded automatically with filename: `{template_name}_{project_name}_{timestamp}.docx`
+
+## Custom Data Fields
+
+During document generation, you can add custom data that will be merged with the project data:
+
+### Standard Fields (Pre-filled but Fully Editable)
+These fields are pre-filled with common names but can be modified or removed:
+- `zk`, `nr_zk`, `kabel`, `dlugosc`, `data_wykonania`, `st_nr`, `obw`, `wp_short`, `plomba`
+
+### Additional Custom Fields
+- **Custom fields** override project data if they have the same name
+- Use descriptive names like `meeting_notes`, `special_instructions`, `custom_date`
+- Custom fields are available in templates as `{custom_field_name}`
+- Empty custom fields are ignored
+- All fields can be removed if not needed
+
+### Example Custom Fields:
+- `meeting_notes`: "Please bring project documentation"
+- `special_instructions`: "Use company letterhead"
+- `custom_date`: "2025-01-15"
+- `additional_comments`: "Follow up required"
+
+## Template Syntax
+
+The system uses `docxtemplater` library which supports:
+- Simple variable replacement: `{variable}`
+- Loops: `{#contacts}{name}{/contacts}`
+- Conditions: `{#primary_contact}Primary: {name}{/primary_contact}`
+- Formatting and styling from your DOCX template is preserved
+
+## Data Processing & Transformations
+
+The system automatically provides processed versions of common fields:
+
+- **Short codes**: `{investment_number_short}` extracts the last segment after dashes (e.g., "1234567" from "I-BC-DE-1234567")
+- **Case transformations**: `{project_name_upper}`, `{city_upper}`, `{customer_upper}` for uppercase versions
+- **Duplicate fields**: Multiple versions of the same field for repeated use (`{project_name_1}`, `{project_name_2}`, etc.)
+
+If you need additional transformations (like extracting different parts of codes, custom formatting, calculations, etc.), please let us know and we can add them to the system.
+
+## Tips
+
+- Test your templates with sample data first
+- Use descriptive variable names
+- Keep formatting simple for best results
+- Save templates with `.docx` extension only
+- Maximum file size: 10MB
+- **For repeated information**: If you need the same data to appear multiple times, create unique placeholders like `{project_name_header}` and `{project_name_footer}` and provide the same value for both
+
+## Storage & Persistence
+
+Templates are stored in two locations for persistence in Docker environments:
+
+### Database Storage
+- **Location**: `data/database.sqlite` (table: `docx_templates`)
+- **Content**: Template metadata (name, description, file paths, timestamps)
+- **Persistence**: Handled by Docker volume mount `./data:/app/data`
+
+### File Storage
+- **Location**: `templates/` (host) → `/app/templates/` (container)
+- **Content**: Actual DOCX template files
+- **Persistence**: Handled by Docker volume mount `./templates:/app/templates`
+- **Web Access**: Files are served via `/api/templates/download/{filename}`
+
+### Docker Volume Mounts
+Both development and production Docker setups include volume mounts to ensure template persistence across container restarts:
+
+```yaml
+volumes:
+  - ./data:/app/data                    # Database
+  - ./templates:/app/templates          # Template files
+  - ./uploads:/app/public/uploads       # Other uploads
+  - ./backups:/app/backups              # Backup files
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**Problem: "Duplicate tag" error during generation**
+- **Cause**: Using the same placeholder multiple times (e.g., `{project_name}` twice)
+- **Solution**: Use numbered variants like `{project_name}`, `{project_name_1}`, `{project_name_2}` OR add the same value to custom fields with different names
+
+**Problem: Template not rendering correctly**
+- **Cause**: Invalid placeholder syntax
+- **Solution**: Ensure all placeholders use single curly braces `{variable}` (not double `{{}}`)
+- **Verify**: Check for typos in variable names
+
+**Problem: Missing data in generated document**
+- **Cause**: Project missing required fields or custom data not provided
+- **Solution**: Fill in all required project information or provide custom data during generation
+- **Check**: Review project details before generating
+
+**Problem: Formatting lost in generated document**
+- **Cause**: Complex Word formatting or incompatible styles
+- **Solution**: 
+  - Simplify template formatting
+  - Avoid complex tables or text boxes
+  - Use basic styles (bold, italic, underline work best)
+  - Test with minimal formatting first
+
+**Problem: Generated file not downloading**
+- **Cause**: Browser popup blocker or network issue
+- **Solution**: 
+  - Allow popups for this site
+  - Check browser console for errors (F12)
+  - Try different browser
+  - Check file size < 10MB
+
+**Problem: Template upload fails**
+- **Cause**: File too large or invalid format
+- **Solution**:
+  - Ensure file is .docx format (not .doc)
+  - File size must be under 10MB
+  - Re-save file in Word to fix corruption
+  - Check file isn't password-protected
+
+**Problem: Custom fields not appearing**
+- **Cause**: Field name mismatch between template and custom data
+- **Solution**: 
+  - Ensure exact match (case-sensitive)
+  - Example: `{meeting_notes}` in template requires `meeting_notes` in custom data
+  - Check for spaces in field names
+
+**Problem: Dates not formatted correctly**
+- **Cause**: Date format differences
+- **Solution**: Dates are auto-formatted as YYYY-MM-DD
+- **Tip**: Use `{today_date}` for current date
+
+### Getting Help
+
+If you encounter other issues:
+1. Check browser console (F12) for error messages
+2. Verify template file is valid .docx
+3. Test with simpler template first
+4. Contact system administrator with error details
+
+---
+
+## 📋 Quick Reference
+
+### File Limits
+- Maximum template size: 10MB
+- Supported format: .docx only
+- Unlimited templates per project
+
+### Available Endpoints
+- `GET /api/templates` - List all templates
+- `POST /api/templates` - Upload new template
+- `POST /api/templates/generate` - Generate document
+- `GET /api/templates/download/{filename}` - Download template
+
+### Best Practices
+✅ Test templates with sample data first  
+✅ Use descriptive placeholder names  
+✅ Keep formatting simple  
+✅ Use numbered variants for repeated data  
+✅ Provide meaningful template descriptions  
+❌ Don't use same placeholder twice  
+❌ Don't use complex Word features (macros, forms)  
+❌ Don't upload non-.docx files  
+
+---
+
+**See Also**: [Main README](../../README.md#-document-generation) | [API Documentation](../../README.md#templates-docx)