149 lines
3.7 KiB
Markdown
149 lines
3.7 KiB
Markdown
# PDF Service - Modular Architecture
|
|
|
|
## Overview
|
|
This is a modular PDF generation service designed for scalability and AI integration. Each module handles specific business domains and can be easily extended.
|
|
|
|
## Structure
|
|
```
|
|
app/services/pdf/
|
|
├── __init__.py
|
|
├── base_pdf_service.py # Base classes and main service
|
|
├── modules/ # Business domain modules
|
|
│ ├── __init__.py
|
|
│ └── marketing/ # Marketing & referrals module
|
|
│ ├── __init__.py
|
|
│ ├── marketing_module.py # Module implementation
|
|
│ └── templates/ # HTML templates
|
|
│ └── marketing_referrals.html
|
|
└── README.md
|
|
```
|
|
|
|
## Adding New Modules
|
|
|
|
### 1. Create Module Directory
|
|
```bash
|
|
mkdir -p app/services/pdf/modules/your_module/templates
|
|
```
|
|
|
|
### 2. Implement Module Class
|
|
```python
|
|
# app/services/pdf/modules/your_module/your_module.py
|
|
from ..base_pdf_service import BasePDFModule
|
|
from app.core.calendar import CalendarType
|
|
|
|
class YourModulePDFModule(BasePDFModule):
|
|
def __init__(self):
|
|
super().__init__("your_module")
|
|
|
|
def generate_pdf(self, data, calendar_type="jalali", locale="fa"):
|
|
# Your PDF generation logic
|
|
pass
|
|
|
|
def generate_excel_data(self, data, calendar_type="jalali", locale="fa"):
|
|
# Your Excel data generation logic
|
|
pass
|
|
```
|
|
|
|
### 3. Register Module
|
|
Add to `base_pdf_service.py`:
|
|
```python
|
|
def _register_modules(self):
|
|
from .modules.marketing.marketing_module import MarketingPDFModule
|
|
from .modules.your_module.your_module import YourModulePDFModule
|
|
self.modules['marketing'] = MarketingPDFModule()
|
|
self.modules['your_module'] = YourModulePDFModule()
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Generate PDF
|
|
```python
|
|
from app.services.pdf import PDFService
|
|
|
|
pdf_service = PDFService()
|
|
pdf_bytes = pdf_service.generate_pdf(
|
|
module_name='marketing',
|
|
data=your_data,
|
|
calendar_type='jalali',
|
|
locale='fa'
|
|
)
|
|
```
|
|
|
|
### Generate Excel Data
|
|
```python
|
|
excel_data = pdf_service.generate_excel_data(
|
|
module_name='marketing',
|
|
data=your_data,
|
|
calendar_type='jalali',
|
|
locale='fa'
|
|
)
|
|
```
|
|
|
|
## Features
|
|
|
|
### 1. Calendar Support
|
|
- Automatic Jalali/Gregorian conversion
|
|
- Configurable via `calendar_type` parameter
|
|
|
|
### 2. Internationalization
|
|
- Built-in translation support
|
|
- Template-level translation integration
|
|
- Configurable via `locale` parameter
|
|
|
|
### 3. Modular Design
|
|
- Easy to add new business domains
|
|
- Clean separation of concerns
|
|
- Reusable base classes
|
|
|
|
### 4. AI Integration Ready
|
|
- Function calling compatible
|
|
- Clear module boundaries
|
|
- Extensible architecture
|
|
|
|
## Template Development
|
|
|
|
### Using Translations
|
|
```html
|
|
<!-- In your template -->
|
|
<h1>{{ t('yourTranslationKey') }}</h1>
|
|
<div>{{ t('anotherKey') }}</div>
|
|
```
|
|
|
|
### Calendar Formatting
|
|
```python
|
|
# In your module
|
|
formatted_date = self.format_datetime(datetime_obj, calendar_type)
|
|
```
|
|
|
|
### Data Formatting
|
|
```python
|
|
# In your module
|
|
formatted_data = self._format_data_for_template(data, calendar_type, translator)
|
|
```
|
|
|
|
## Future Extensions
|
|
|
|
### AI Integration
|
|
Each module can be exposed as a function for AI systems:
|
|
```python
|
|
# Example AI function definition
|
|
{
|
|
"name": "generate_marketing_pdf",
|
|
"description": "Generate marketing referrals PDF report",
|
|
"parameters": {
|
|
"type": "object",
|
|
"properties": {
|
|
"user_id": {"type": "integer"},
|
|
"filters": {"type": "object"},
|
|
"calendar_type": {"type": "string", "enum": ["jalali", "gregorian"]}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Additional Modules
|
|
- `invoices/` - Invoice generation
|
|
- `reports/` - General reports
|
|
- `analytics/` - Analytics dashboards
|
|
- `notifications/` - Notification templates
|