fonts/ added to the repo, RobotoMonoNerdFont-Medium.ttf license allow…

…s redistribution

gitlab ci updated to use dind instead of docker socket

# Add PDF Receipt Generation Feature

## Summary

This MR implements asynchronous PDF receipt generation for fiscalized FINA transactions. PDF receipts are generated from Markdown templates and include QR codes compliant with Croatian tax authority specifications (ISO/IEC 15415).

**Key Design Principle:** PDF generation is completely decoupled from the fiscalization process to avoid any risks during critical FINA communication. If PDF generation fails, the fiscal receipt remains valid in FINA's system. Additionally, if receipt templates need updates in the future, PDFs can be regenerated without re-fiscalizing payments.

## What's New

### 1. Database Schema Changes
- **Migration:** `20260101_114936_add_pdf_columns_to_fina_receipt.sql`
- Added columns to `fina_receipt` table:
  - `s3_folder_path` (TEXT): Stores full S3 folder path for receipt files
  - `pdf_status` (VARCHAR): Tracks PDF generation status ('pending', 'processing', 'completed', 'failed')
  - `pdf_created` (TIMESTAMPTZ): Timestamp when PDF was successfully generated
- Added indexes on `pdf_status` and `s3_folder_path` for query optimization

### 2. CLI Tool Enhancements (`fina_cli.py`)
New commands added (~380 lines):
- `--generate-pdf <receipt_id>`: Generate PDF for a specific receipt
- `--generate-pending-pdfs`: Batch process all pending PDF receipts
- Both commands require `--template` and `--font` parameters

Example usage:
```bash
# Single receipt
python fina_cli.py --generate-pdf 123 --template example.md --font RobotoMonoNerdFont-Medium

# Batch processing
python fina_cli.py --generate-pending-pdfs --template example.md --font RobotoMonoNerdFont-Medium
```

### 3. Template System
- Markdown templates with Jinja2 variable substitution
- Template variables: `receipt_number`, `order_id`, `amount`, `payment_time`, `zki`, `jir`, `verification_link`, `qr_code`, `location_id`, `register_id`
- Templates stored in `templates/` directory (volume-mounted for dev, copied at build for production)
- Included example template: `templates/example.md`

### 4. QR Code Implementation
Compliant with Croatian tax authority requirements:
- Size: 20mm × 20mm (75 pixels at 96 DPI)
- Error Correction Level: L (7% error correction)
- Border: 4 modules (quiet zone)
- Content: Verification URL to Croatian tax authority portal
- Format: `https://porezna.gov.hr/rn?jir={JIR}&datv={YYYYMMDD_HHMM}&izn={cents}`

### 5. Font Support
- Unicode font support for Croatian characters (š, ć, č, ž, đ)
- Included font: `RobotoMonoNerdFont-Medium.ttf`
- Fonts stored in `fonts/` directory (volume-mounted for dev, copied at build for production)
- Alternative: DejaVuSans (not included but documented)

### 6. PDF Generation Pipeline
1. Fetch receipt data from database (validates status='completed' and JIR exists)
2. Generate verification URL and QR code
3. Render Jinja2 template with receipt data
4. Convert Markdown → HTML → PDF using fpdf2 and markdown-it-py
5. Embed QR code as PNG image in PDF
6. Upload PDF to S3 storage alongside fiscal receipt files
7. Update database: `pdf_status='completed'`, `pdf_created=CURRENT_TIMESTAMP`

### 7. S3 Storage Updates
- `fina.py`: Modified to store `s3_folder_path` during fiscalization
- PDF files uploaded to same folder as fiscal receipt XML/YAML files
- Filename format: `fina-receipt-{order_id}.pdf` (sanitized for S3 compatibility)

## Files Changed

- **Database:**
  - `migrations/20260101_114936_add_pdf_columns_to_fina_receipt.sql` (new)

- **Code:**
  - `fina_cli.py` (+378 lines): PDF generation functions and CLI commands
  - `fina.py` (+20 -11): Store S3 folder path during fiscalization

- **Dependencies:**
  - `requirements.txt`: Added fpdf2, markdown-it-py, qrcode, Pillow

- **Docker:**
  - `Dockerfile`: Copy `templates/` and `fonts/` directories
  - `compose.yaml`: Volume mount `templates/` and `fonts/` for dev

- **Assets:**
  - `templates/example.md` (new): Example receipt template
  - `.gitignore`: Exclude other font files and template variants

- **Documentation:**
  - `README.md` (+206 lines): Complete PDF generation documentation
  - `CLAUDE.md` (+69 lines): Technical context for AI assistant

## Dependencies Added

- `fpdf2==2.8.2` - PDF generation library
- `markdown-it-py==3.0.0` - Markdown to HTML converter
- `qrcode[pil]==8.0` - QR code generation
- `Pillow==11.0.0` - Image processing (required by qrcode)

## Breaking Changes

None. This is a purely additive feature.

## Migration Required

Yes - database migration adds three new columns to `fina_receipt` table. Migration runs automatically on container startup.

## Configuration Changes

None required. Uses existing environment variables (`FINA_TIMEZONE`, S3 credentials).

## Known Limitations

- Only supports one template at a time (template name passed as CLI argument)

# Merge Request: Error Resilience and Operational Improvements

## Summary

This branch implements comprehensive error resilience features, operational tools, and configuration improvements for the FINA fiscalization system. The changes focus on improving error handling, adding manual intervention capabilities, enhancing SSL security, and clarifying timestamp semantics in the database schema.

## Key Features

### 1. Receipt Status Tracking & Error Resilience
- **Status field added to `fina_receipt` table**: Tracks receipt processing lifecycle (`pending`, `processing`, `completed`, `failed`)
- **Automatic stale record cleanup**: Prevents stuck receipts by marking processing records as failed after 30 minutes
- **Better error recovery**: Failed receipts can now be identified and retried manually

### 2. CLI Tools for Manual Operations
- **`fina_cli.py`**: New command-line tool for manual FINA operations
  - `--retry-receipt <number>`: Retry fiscalization for failed receipts (network issues, FINA downtime, etc.)
  - `--create-receipt --amount <amount>`: Create fiscal receipts for non-Stripe payments (bank transfers, cash, manual corrections)
  - Supports custom payment times, order IDs, and payment identifiers
  - All operations save data to S3 storage with organized folder structure

- **`test_ssl_connection.py`**: SSL connection testing utility
  - Verify FINA endpoint connectivity before deployment
  - Test CA certificate configuration (demo vs production)
  - Safe to run against production (no fiscal data transmitted)

### 3. Enhanced SSL Security
- **CA certificate bundle support**: Properly validates FINA SSL certificates using CA bundle
- **Removed development-only SSL bypass**: All environments now use proper SSL verification
- **Dynamic CA loading**: Loads all `.pem` files from `FINA_CA_DIR_PATH` directory
- **Better error messages**: Clear errors when CA certificates are missing or misconfigured

### 4. Database Schema Improvements
- **Migration `20250115_000001_rename_created_at_add_receipt_timestamps.sql`**:
  - Renamed `created_at` → `payment_time` (clarifies this is the original Stripe payment timestamp)
  - Added `receipt_created` (database row creation timestamp)
  - Added `receipt_updated` (last modification timestamp)
  - Proper timestamp semantics for audit trail and debugging

### 5. Configuration & Environment Variables
- **Renamed `TIMEZONE` → `FINA_TIMEZONE`**: More explicit naming (this is specifically for FINA fiscalization requirements)
- **New required variable `FINA_CA_DIR_PATH`**: Directory containing CA certificates for SSL verification
- **Updated health check endpoint**: Validates new environment variables

### 6. FINA Request Timestamp Separation
- **Zaglavlje timestamp** (`request_time`): Current time when request is created
- **Receipt timestamp** (`payment_time`): Original payment transaction time
- Previously both used the same timestamp, which was incorrect per FINA specification

### 7. Documentation Updates
- **README.md**: Comprehensive documentation for all new features
  - CLI tools usage examples
  - SSL connection testing guide
  - Retry receipt workflow
  - Manual receipt creation scenarios

- **CLAUDE.md**: Updated with accurate schema, file structure, and environment variables
- **Updated FINA specification**: Included version 2.5 technical documentation

## Technical Details

### Files Changed (10 files, +733 insertions, -43 deletions)

**Core Application:**
- `app.py`: Environment variable rename (`TIMEZONE` → `FINA_TIMEZONE`), health check updates
- `fina.py`: Status tracking, SSL verification improvements, timestamp separation, CA bundle support

**New Tools:**
- `fina_cli.py`: CLI tool for manual operations (295 lines)
- `test_ssl_connection.py`: SSL testing utility (186 lines)

**Database:**
- `migrations/20250115_000001_rename_created_at_add_receipt_timestamps.sql`: Schema improvements

**Documentation:**
- `README.md`: Major expansion with CLI tools, troubleshooting, and deployment guides
- `CLAUDE.md`: Updated for consistency with current implementation
- `.env.example`: Added new environment variables

**Specification:**
- `doc/fina/`: Updated FINA technical specification documents (2.3 → 2.5)

## Migration Notes

### Environment Variables
⚠️ **Breaking Change**: Environment variable renamed
- **Old**: `TIMEZONE=Europe/Zagreb`
- **New**: `FINA_TIMEZONE=Europe/Zagreb`

⚠️ **New Required Variable**:
- `FINA_CA_DIR_PATH=cert/ca_demo` (or `cert/ca` for production)

### Database Migration
Migration `20250115_000001_rename_created_at_add_receipt_timestamps.sql` will run automatically on deployment:
- Renames existing column (backward compatible)
- Adds new columns with defaults
- Backfills existing data
- No manual intervention required

### Certificate Configuration
Ensure CA certificates are properly configured:
- Demo environment: Place CA certs in `cert/ca_demo/` directory
- Production environment: Place CA certs in `cert/ca/` directory
- All certificates must be in `.pem` format
- Use `test_ssl_connection.py` to verify configuration before deployment

## Testing Recommendations

1. **Verify environment variables**: Check `.env` file has `FINA_TIMEZONE` and `FINA_CA_DIR_PATH`
2. **Test SSL connection**: Run `test_ssl_connection.py` against target FINA endpoint
3. **Test webhook processing**: Trigger test payment and verify status tracking
4. **Test CLI tools**: Create manual receipt and verify S3 storage
5. **Test failure recovery**: Simulate failure and retry using `--retry-receipt`

## Benefits

- ✅ **Better error visibility**: Status tracking makes failed receipts obvious
- ✅ **Manual intervention capability**: Can fix issues without code changes
- ✅ **Improved security**: Proper SSL verification for all environments
- ✅ **Clearer semantics**: Timestamp columns now have explicit meanings
- ✅ **Operational flexibility**: Manual receipts for edge cases
- ✅ **Better debugging**: Comprehensive logs and file organization
- ✅ **Production readiness**: SSL testing before deployment prevents surprises

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)

initial commit before opensourcing