iralex-backend/QR_CODE_README.md

QR Code Integration for Invoice System

Overview

This implementation adds QR code generation functionality to the invoice system, specifically for Trust Fund Request documents (type 2) using the main2_2.html template.

Features

• Automatic QR Code Generation: When a Trust Fund Request (type 2) is generated, the system automatically creates a QR code from the lhdn_qrcode field
• Base64 Encoding: QR codes are converted to base64 format and embedded directly in the HTML
• Responsive Design: QR codes are displayed with appropriate sizing and styling
• Error Handling: Graceful fallback if QR code generation fails

Technical Implementation

Dependencies Added

• qrcode==7.4.2 - For generating QR codes
• Pillow - Already available, used for image processing

Code Changes

1. billing/models.py

• Added imports for qrcode, base64, and BytesIO
• Modified BillHtml() method to generate QR codes for type 2 documents
• QR codes are generated with the following specifications:
  • Version: 1
  • Error correction: L (Low)
  • Box size: 10
  • Border: 4
  • Colors: Black on white

2. assets/invoices/main2_2.html

• Added QR code display section at the bottom of the template
• Includes styling and title for the QR code section
• Uses {bill_qr_code} placeholder for dynamic content

How It Works

1. Detection: When BillHtml(temType) is called with type 2 (Trust Fund Request)
2. QR Generation: If lhdn_qrcode field contains data, a QR code is generated
3. Base64 Conversion: The QR code image is converted to base64 format
4. HTML Embedding: The base64 data is embedded as an HTML img tag
5. Template Rendering: The HTML template is rendered with the QR code included

QR Code Specifications

• Format: PNG
• Size: 150px width, auto height, max-width 200px
• Border: 1px solid #ddd
• Error Correction: Low (7% recovery)
• Data Capacity: Suitable for URLs, text, and small data

Usage

For Developers

1. Ensure the lhdn_qrcode field contains the data you want to encode
2. Call BillHtml(temType) on a type 2 Bill object
3. The QR code will be automatically generated and included in the HTML

For Users

1. Create a Trust Fund Request (type 2) with data in the lhdn_qrcode field
2. Generate the HTML invoice using the existing workflow
3. The QR code will appear at the bottom of the generated document

Error Handling

• If QR code generation fails, an empty string is returned
• Errors are logged to the console for debugging
• The invoice generation continues normally even if QR code fails

Testing

A test script test_qr.py is provided to verify QR code functionality:

python test_qr.py

Future Enhancements

• Customizable QR code colors and sizes
• Support for different QR code formats (SVG, etc.)
• QR code positioning options in templates
• Batch QR code generation for multiple documents

Notes

• QR codes are only generated for Trust Fund Request documents (type 2)
• The system uses the existing lhdn_qrcode field as the data source
• Base64 encoding ensures the QR code is self-contained in the HTML
• No external image files are required