ali
/
invoice_az
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: remove unnecessary bundle file and old docs 

- Remove invoice_az.bundle.js (not needed, app uses doctype_js)
- Remove OPTIMIZATION_SUMMARY.md (outdated)
- Remove claude.md (replaced by CLAUDE.md)

The patches.txt file is sufficient to make the app recognizable by Frappe.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Ali 2026-02-11 14:21:12 +04:00
parent 27c4c0aaa4
commit aa2cab8b22
3 changed files with 0 additions and 753 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

216
OPTIMIZATION_SUMMARY.md
View File

@ -1,216 +0,0 @@
# API Optimization Summary
## Overview
The original `api.py` file (43K+ tokens) has been optimized with significant performance improvements, better error handling, and enhanced maintainability. The optimized version demonstrates best practices for large-scale API development.
## Key Optimizations Implemented
### 1. **Caching Layer (Performance Boost: 70-90%)**
```python
@lru_cache(maxsize=10)
def get_cached_settings() -> Optional[Document]:
"""Get cached active E-Taxes settings"""
@lru_cache(maxsize=5)
def get_cached_asan_login(name: str = None) -> Optional[Document]:
"""Get cached ASAN login document"""
@lru_cache(maxsize=1000)
def normalize_azeri_text(text: str) -> Tuple[str, str]:
"""Cached normalization of Azerbaijani text"""
```
**Benefits:**
- Settings queries reduced from ~100/min to ~1/min
- Text normalization cached for repeated operations
- Authentication document caching eliminates redundant DB calls
### 2. **Bulk Database Operations (Performance Boost: 80-95%)**
```python
class BulkDBOperations:
@staticmethod
def bulk_exists_check(doctype: str, field_values: List[Dict[str, Any]]) -> Dict[str, bool]:
"""Check existence of multiple records in bulk"""
@staticmethod
def bulk_insert(doctype: str, records: List[Dict[str, Any]], batch_size: int = BATCH_SIZE) -> Tuple[int, int]:
"""Insert multiple records in batches"""
```
**Benefits:**
- Reduces database queries from O(n) to O(1) for existence checks
- Batch inserts with configurable batch sizes (default: 50)
- Transaction management for data integrity
### 3. **Standardized Error Handling**
```python
def handle_api_errors(func):
"""Decorator for consistent API error handling"""
def create_error_response(error_type: str, message: str, status_code: int = None) -> Dict[str, Any]:
"""Create standardized error response"""
class APIError(Exception):
"""Custom exception for API errors"""
```
**Benefits:**
- Consistent error responses across all endpoints
- Centralized error logging
- Proper HTTP status code handling
### 4. **Type Hints and Modern Python Features**
```python
def load_parties_from_invoices(date_from: str, date_to: str, max_count: int = 200,
offset: int = 0, invoice_type: str = "purchase") -> Dict[str, Any]:
```
**Benefits:**
- Better IDE support and debugging
- Improved code documentation
- Easier maintenance and refactoring
### 5. **Memory and Performance Optimizations**
- **Rate Limiting**: 50ms delays between API calls to prevent overload
- **Batch Processing**: Configurable batch sizes for large datasets
- **Memory Management**: Efficient data structures and garbage collection
- **Connection Pooling**: Optimized request handling
## Performance Improvements
### Before Optimization:
- **Database Queries**: 500-1000 queries for 100 invoice processing
- **Memory Usage**: 200-400MB for large operations
- **Processing Time**: 5-10 minutes for 1000 invoices
- **Error Rate**: 15-20% due to timeout and connection issues
### After Optimization:
- **Database Queries**: 50-100 queries for 100 invoice processing (**90% reduction**)
- **Memory Usage**: 50-100MB for large operations (**75% reduction**)
- **Processing Time**: 1-2 minutes for 1000 invoices (**80% improvement**)
- **Error Rate**: 2-5% with better retry logic (**85% improvement**)
## Code Quality Improvements
### 1. **Reduced Code Duplication**
- Common error handling patterns extracted to decorators
- Shared database operations in utility classes
- Standardized response formats
### 2. **Better Separation of Concerns**
- Authentication logic separated from business logic
- Database operations abstracted into utility classes
- API response handling standardized
### 3. **Enhanced Maintainability**
- Type hints for all function parameters and returns
- Comprehensive logging and error tracking
- Clear function documentation and comments
## Migration Strategy
### Step 1: Gradual Migration
```python
# Keep both files during transition
# api.py (original) - for production
# api_optimized.py (new) - for testing
```
### Step 2: Testing Phase
- Run optimized functions in parallel with original
- Compare results and performance metrics
- Monitor error rates and system stability
### Step 3: Full Migration
- Replace imports in client code
- Update hook configurations
- Monitor system performance
## Configuration Changes Required
### 1. **Update hooks.py**
```python
# Change API references
scheduler_events = {
"cron": {
"*/4 * * * *": [
"invoice_az.api_optimized.renew_token" # Changed from api.renew_token
]
}
}
```
### 2. **Client-side JavaScript Updates**
```javascript
// Update API endpoints
frappe.call({
method: 'invoice_az.api_optimized.load_parties_from_invoices', // Updated
args: { ... }
});
```
### 3. **Environment Variables**
```bash
# Add to site_config.json
{
"api_rate_limit_delay": 0.05,
"bulk_operation_batch_size": 50,
"cache_timeout": 3600
}
```
## Monitoring and Analytics
### Performance Metrics to Track:
1. **Response Times**: API endpoint response times
2. **Cache Hit Rates**: LRU cache effectiveness
3. **Database Query Count**: Before/after optimization
4. **Memory Usage**: Peak and average memory consumption
5. **Error Rates**: API failure rates and types
### Monitoring Functions:
```python
@frappe.whitelist()
def get_optimization_stats():
"""Get statistics about optimizations"""
return {
"cache_info": {
"settings_cache": get_cached_settings.cache_info()._asdict(),
# ... other cache stats
}
}
```
## Benefits Summary
### Performance Benefits:
- **90% reduction** in database queries
- **80% faster** invoice processing
- **75% lower** memory usage
- **85% fewer** API errors
### Development Benefits:
- Better code organization and maintainability
- Standardized error handling and logging
- Type safety and IDE support
- Easier testing and debugging
### Operational Benefits:
- Reduced server load and resource usage
- Better system stability and reliability
- Improved user experience with faster responses
- Enhanced monitoring and troubleshooting capabilities
## Next Steps
1. **Testing**: Comprehensive testing in development environment
2. **Performance Benchmarking**: Detailed before/after measurements
3. **Gradual Rollout**: Phase-wise deployment to production
4. **Monitoring Setup**: Implement performance tracking
5. **Documentation**: Update user and developer documentation
## Files Created:
- `api_optimized.py` - Optimized version of the main API file
- `OPTIMIZATION_SUMMARY.md` - This comprehensive optimization guide
The optimized code maintains 100% functional compatibility while providing significant performance improvements and better maintainability.

535
claude.md
View File

@ -1,535 +0,0 @@
# Invoice Az - Система интеграции с электронными налогами Азербайджана
**Версия:** 0.0.1
**Автор:** Jey ERP (info@jeyerp.az)
**Лицензия:** Unlicense (Public Domain)
**Минимальная версия Python:** 3.10+
**Фреймворк:** Frappe/ERPNext
**Последнее обновление:** 2025-12-15
---
## Оглавление
1. [Введение и обзор проекта](#1-введение-и-обзор-проекта)
- 1.1 [Назначение приложения](#11-назначение-приложения)
- 1.2 [Ключевые возможности](#12-ключевые-возможности)
- 1.3 [Целевая аудитория](#13-целевая-аудитория)
- 1.4 [Бизнес-ценность](#14-бизнес-ценность)
2. [Архитектура системы](#2-архитектура-системы)
- 2.1 [Общая архитектура](#21-общая-архитектура)
- 2.2 [Слои приложения](#22-слои-приложения)
- 2.3 [Поток данных](#23-поток-данных)
- 2.4 [Технологический стек](#24-технологический-стек)
3. [Система аутентификации (auth.py)](#3-система-аутентификации-authpy)
- 3.1 [Поток ASAN Login](#31-поток-asan-login)
- 3.2 [Документация функций](#32-документация-функций)
- 3.3 [Управление токенами](#33-управление-токенами)
4. [API для накладных на покупку (api.py)](#4-api-для-накладных-на-покупку-apipy)
- 4.1 [Категория A: Получение накладных](#41-категория-a-получение-накладных)
- 4.2 [Категория B: Управление товарами](#42-категория-b-управление-товарами)
- 4.3 [Категория C: Управление единицами измерения](#43-категория-c-управление-единицами-измерения)
- 4.4 [Категория D: Управление контрагентами](#44-категория-d-управление-контрагентами)
- 4.5 [Категория E: Создание документов покупки](#45-категория-e-создание-документов-покупки)
- 4.6 [Категория F: Интеграция E-Taxes Purchase](#46-категория-f-интеграция-e-taxes-purchase)
- 4.7 [Категория G: Комбинированная загрузка данных](#47-категория-g-комбинированная-загрузка-данных)
- 4.8 [Категория H: Управление справочными данными](#48-категория-h-управление-справочными-данными)
- 4.9 [Категория I: Вспомогательные функции](#49-категория-i-вспомогательные-функции)
5. [API для накладных на продажу (sales_api.py)](#5-api-для-накладных-на-продажу-sales_apipy)
- 5.1 [Общие функции](#51-общие-функции)
- 5.2 [Функции получения данных](#52-функции-получения-данных)
- 5.3 [Функции создания документов](#53-функции-создания-документов)
6. [Документация DocTypes](#6-документация-doctypes)
- 6.1 [Конфигурационные DocTypes](#61-конфигурационные-doctypes)
- 6.2 [Справочные данные](#62-справочные-данные)
- 6.3 [Маппинг DocTypes](#63-маппинг-doctypes)
7. [Frontend JavaScript документация](#7-frontend-javascript-документация)
- 7.1 [Общий модуль (etaxes_common.js)](#71-общий-модуль-etaxes_commonjs)
- 7.2 [Документо-специфический JavaScript](#72-документо-специфический-javascript)
- 7.3 [List View JavaScript](#73-list-view-javascript)
8. [Интеграция и хуки](#8-интеграция-и-хуки)
- 8.1 [Frappe Hooks](#81-frappe-hooks)
- 8.2 [Пользовательские поля](#82-пользовательские-поля)
9. [Конфигурация и руководство по настройке](#9-конфигурация-и-руководство-по-настройке)
- 9.1 [Установка](#91-установка)
- 9.2 [Начальная конфигурация](#92-начальная-конфигурация)
- 9.3 [Устранение неполадок](#93-устранение-неполадок)
10. [Примеры использования и рабочие процессы](#10-примеры-использования-и-рабочие-процессы)
- 10.1 [Рабочий процесс импорта накладной на покупку](#101-рабочий-процесс-импорта-накладной-на-покупку)
- 10.2 [Рабочий процесс экспорта накладной на продажу](#102-рабочий-процесс-экспорта-накладной-на-продажу)
- 10.3 [Массовая загрузка справочных данных](#103-массовая-загрузка-справочных-данных)
- 10.4 [Управление маппингом](#104-управление-маппингом)
11. [Справочник API и модели данных](#11-справочник-api-и-модели-данных)
- 11.1 [Конечные точки E-Taxes API](#111-конечные-точки-e-taxes-api)
- 11.2 [Модели данных](#112-модели-данных)
12. [Продвинутые темы](#12-продвинутые-темы)
- 12.1 [Оптимизация производительности](#121-оптимизация-производительности)
- 12.2 [Паттерны обработки ошибок](#122-паттерны-обработки-ошибок)
- 12.3 [Соображения безопасности](#123-соображения-безопасности)
- 12.4 [Нормализация азербайджанских символов](#124-нормализация-азербайджанских-символов)
- 12.5 [Расширяемость](#125-расширяемость)
13. [Приложения](#13-приложения)
- 13.1 [Примеры кода](#131-примеры-кода)
- 13.2 [FAQ (Часто задаваемые вопросы)](#132-faq-часто-задаваемые-вопросы)
- 13.3 [Глоссарий](#133-глоссарий)
- 13.4 [Журнал изменений](#134-журнал-изменений)
---
## 1. Введение и обзор проекта
### 1.1 Назначение приложения
**Invoice Az** — это специализированное приложение для Frappe/ERPNext, предназначенное для интеграции с государственной системой электронного налогообложения Азербайджана (**E-Taxes**, доступна по адресу [https://new.e-taxes.gov.az](https://new.e-taxes.gov.az)).
Приложение обеспечивает полный цикл работы с электронными налоговыми накладными:
- **Автоматическое получение** входящих накладных от поставщиков (inbox/покупки)
- **Загрузка исходящих** накладных для клиентов (outbox/продажи)
- **Извлечение справочных данных** (товары, единицы измерения, контрагенты)
- **Интеллектуальный маппинг** между данными E-Taxes и ERPNext
- **Автоматическое создание** документов Purchase Order, Purchase Invoice, Sales Order, Sales Invoice
### 1.2 Ключевые возможности
#### Двунаправленная синхронизация
- **Входящие накладные (Inbox):** Автоматическая загрузка накладных от поставщиков с возможностью создания Purchase Orders и Purchase Invoices
- **Исходящие накладные (Outbox):** Загрузка накладных, отправленных клиентам, с созданием Sales Orders и Sales Invoices
#### Аутентификация через ASAN Login
- Интеграция с системой **ASAN** (Azerbaijan State Authentication and Notification)
- Многошаговая аутентификация с подтверждением через мобильное приложение
- Выбор цифрового сертификата и налогоплательщика
- Автоматическое обновление токенов каждые 4 минуты
#### Интеллектуальный маппинг данных
- **Fuzzy matching** (нечеткое сопоставление) с порогом схожести 95%
- Поддержка азербайджанских символов (ə, ö, ü, ğ, ş, ç, ı)
- Автоматическое создание товаров, единиц измерения, клиентов и поставщиков
- Ручное управление маппингом через удобный интерфейс
#### Массовая обработка данных
- Пакетная загрузка до 200 накладных за запрос
- Поддержка пагинации для больших объемов данных
- Прогресс-бары и возможность отмены длительных операций
- Кэширование для оптимизации производительности (5-минутный кэш)
#### Отслеживание и логирование
- Детальное логирование всех операций с E-Taxes API
- Отслеживание активности пользователей
- Сохранение истории маппинга
- Связывание документов ERPNext с записями E-Taxes
### 1.3 Целевая аудитория
Приложение предназначено для:
1. **Азербайджанских компаний**, использующих Frappe/ERPNext для управления бизнесом
2. **Бухгалтеров и финансистов**, работающих с электронными налоговыми накладными
3. **Системных администраторов**, настраивающих интеграцию между ERP и государственными системами
4. **Разработчиков**, желающих расширить функциональность или понять архитектуру интеграции
**Предварительные требования:**
- Знание Frappe/ERPNext framework
- Понимание бизнес-процессов закупок и продаж
- Базовые знания о системе E-Taxes Азербайджана
- Зарегистрированный аккаунт ASAN Login
### 1.4 Бизнес-ценность
#### Экономия времени
- **Автоматизация ввода данных:** Устраняет необходимость ручного переноса данных из E-Taxes в ERPNext
- **Массовая обработка:** Одновременная загрузка сотен накладных вместо ручной обработки каждой
- **Автоматический маппинг:** Интеллектуальное сопоставление товаров и контрагентов с точностью 95%
#### Снижение ошибок
- **Исключение человеческого фактора:** Данные переносятся напрямую из E-Taxes без ручного ввода
- **Валидация данных:** Автоматическая проверка корректности товаров, цен, контрагентов
- **Отслеживание истории:** Все операции логируются для аудита
#### Соответствие требованиям
- **Налоговая отчетность:** Полное соответствие требованиям налоговой службы Азербайджана
- **Своевременность:** Оперативное получение и обработка налоговых накладных
- **Прозрачность:** Четкая связь между документами ERPNext и записями в E-Taxes
#### Масштабируемость
- **Большие объемы:** Обработка тысяч накладных в месяц
- **Множество контрагентов:** Автоматическое создание и маппинг сотен поставщиков и клиентов
- **Расширяемость:** Возможность добавления пользовательской логики обработки
---
## 2. Архитектура системы
### 2.1 Общая архитектура
Invoice Az построено по принципу многослойной архитектуры, обеспечивающей четкое разделение ответственности между компонентами:
```
┌─────────────────────────────────────────────────────────────────┐
│ ВНЕШНИЙ СЛОЙ │
│ E-Taxes API (new.e-taxes.gov.az) │
│ - Аутентификация (ASAN Login) │
│ - Накладные (inbox/outbox) │
│ - Справочники (товары, единицы, контрагенты) │
└────────────────────────┬────────────────────────────────────────┘
│ HTTPS REST API
│ Bearer Token Authentication
▼
┌─────────────────────────────────────────────────────────────────┐
│ СЛОЙ АУТЕНТИФИКАЦИИ │
│ auth.py (17 функций) │
│ - Получение токенов │
│ - Автообновление (каждые 4 минуты) │
│ - Управление сертификатами │
│ - Отслеживание активности │
└────────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ BACKEND СЛОЙ │
│ ┌───────────────┬──────────────────┬─────────────────┐ │
│ │ api.py │ sales_api.py │ hooks.py │ │
│ │ 42 функции │ 10 функций │ Интеграция │ │
│ │ - Получение │ - Продажи │ - События │ │
│ │ - Маппинг │ - Outbox │ - Cron │ │
│ │ - Создание │ - SO/SI │ - Клиент JS │ │
│ │ документов │ создание │ │ │
│ └───────────────┴──────────────────┴─────────────────┘ │
└────────────────────────┬────────────────────────────────────────┘
│ Frappe ORM
▼
┌─────────────────────────────────────────────────────────────────┐
│ СЛОЙ ДАННЫХ │
│ 16 Custom DocTypes │
│ ┌─────────────────┬──────────────────┬───────────────────┐ │
│ │ Конфигурация │ Справочники │ Маппинг │ │
│ │ - Asan Login │ - E-Taxes Item │ - Item Mapping │ │
│ │ - E-Taxes │ - E-Taxes Unit │ - Unit Mapping │ │
│ │ Settings │ - E-Taxes │ - Customer │ │
│ │ - E-Taxes │ Customers │ Mappings │ │
│ │ Purchase │ - E-Taxes │ - Supplier │ │
│ │ - E-Taxes Sales │ Suppliers │ Mappings │ │
│ │ │ - E-Taxes │ - Party Mapping │ │
│ │ │ Parties │ │ │
│ └─────────────────┴──────────────────┴───────────────────┘ │
│ MariaDB через Frappe ORM │
└────────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ FRONTEND СЛОЙ │
│ JavaScript Client Scripts (21 файл, ~8000 строк) │
│ ┌────────────────────┬─────────────────┬──────────────────┐ │
│ │ Общие утилиты │ Документы │ List Views │ │
│ │ etaxes_common.js │ - PO (1532 л.) │ - Items (979 л.) │ │
│ │ (1052 строки) │ - SO (1585 л.) │ - Units (905 л.) │ │
│ │ - Кэш │ - PI (47 л.) │ - Customers │ │
│ │ - Диалоги │ - SI (47 л.) │ (915 л.) │ │
│ │ - API вызовы │ │ - Suppliers │ │
│ │ - Форматирование │ │ (915 л.) │ │
│ └────────────────────┴─────────────────┴──────────────────┘ │
│ Frappe UI Framework │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ ИНТЕГРАЦИОННЫЙ СЛОЙ │
│ Frappe Hooks & Event Handlers │
│ - doc_events: PO/SO on_trash, on_cancel │
│ - scheduler_events: Token renewal (*/4 * * * *) │
│ - doctype_js: Custom client scripts │
│ - doctype_list_js: Custom list views │
│ - after_install/migrate: Setup scheduler │
└─────────────────────────────────────────────────────────────────┘
```
### 2.2 Слои приложения
#### Внешний слой: E-Taxes API
**Описание:** Государственная система электронного налогообложения Азербайджана.
**Конечные точки API:**
- `POST /api/po/auth/public/v1/...` — Аутентификация и управление токенами
- `POST /api/po/invoice/public/v2/invoice/find.inbox` — Получение входящих накладных
- `POST /api/po/invoice/public/v2/invoice/find.outbox` — Получение исходящих накладных
- `GET /api/po/invoice/public/v2/invoice/{id}` — Детали накладной
**Аутентификация:** Bearer Token в заголовке `x-authorization`
#### Слой аутентификации: auth.py
**Ответственность:**
- Получение bearer токена через ASAN Login
- Автоматическое обновление main_token каждые 4 минуты через cron
- Управление цифровыми сертификатами
- Выбор налогоплательщика
- Отслеживание активности пользователя
- Обработка ошибок 401 Unauthorized
**Ключевые компоненты:**
- 17 функций аутентификации
- Retry логика (до 3 попыток)
- Activity timeout (настраиваемый параметр)
#### Backend слой: Python модули
**api.py (4,320 строк, 42 функции):**
- Получение накладных с фильтрацией
- Извлечение товаров, единиц измерения, контрагентов
- Интеллектуальный маппинг (fuzzy matching, 95% threshold)
- Создание Purchase Orders и Purchase Invoices
- Массовая обработка данных
**sales_api.py (887 строк, 10 функций):**
- Получение исходящих накладных (outbox)
- Создание Sales Orders и Sales Invoices
- Маппинг клиентов
- Обработка продаж аналогично покупкам
**hooks.py:**
- Регистрация обработчиков событий
- Настройка cron заданий
- Интеграция клиентских скриптов
- Инициализация при установке/обновлении
#### Слой данных: 16 Custom DocTypes
**Конфигурационные (4):**
- Asan Login — хранение токенов и сертификатов
- E-Taxes Settings — центральная конфигурация
- E-Taxes Purchase — отслеживание покупок
- E-Taxes Sales — отслеживание продаж
**Справочные данные (5):**
- E-Taxes Item — товары из E-Taxes
- E-Taxes Unit — единицы измерения
- E-Taxes Customers — клиенты
- E-Taxes Suppliers — поставщики
- E-Taxes Parties — универсальные контрагенты
**Маппинг (5 дочерних таблиц):**
- E-Taxes Item Mapping
- E-Taxes Unit Mapping
- E-Taxes Customer Mappings
- E-Taxes Supplier Mappings
- E-Taxes Party Mapping
**Тестирование (1):**
- TestAPI — для разработки и отладки
#### Frontend слой: JavaScript
**Общие утилиты (etaxes_common.js, 1052 строки):**
- Кэширование (5 минут)
- Управление диалогами (прогресс, ошибки)
- API вызовы с обработкой ошибок
- Форматирование валюты (AZN)
- Rate limiting
**Документо-специфические скрипты:**
- purchase_order.js (1,532 строки) — "Load from E-Taxes", браузер накладных, импорт
- sales_order.js (1,585 строк) — аналогично для продаж
- purchase_invoice.js, sales_invoice.js — легкая интеграция
**List View скрипты:**
- Массовый маппинг через UI
- Автоматическое сопоставление
- Создание новых записей
- Индикаторы статуса (New/Mapped/Processing)
#### Интеграционный слой: Frappe Hooks
- **doc_events:** Автоматическая очистка связей при удалении PO/SO
- **scheduler_events:** Cron задание обновления токена (*/4 * * * *)
- **doctype_js/list_js:** Подключение клиентских скриптов
- **after_install/migrate:** Настройка планировщика
### 2.3 Поток данных
#### Входящий поток (Покупки / Inbox)
```
1. Пользователь открывает Purchase Order
↓
2. Нажимает кнопку "Load from E-Taxes" (JavaScript)
↓
3. Frontend → Backend: load_items_from_invoices()
↓
4. auth.py: record_etaxes_activity()
↓
5. auth.py: get_default_asan_login() [с кэшем 5 мин]
↓
6. api.py: get_invoices(token, filters)
↓
7. E-Taxes API: POST /invoice/find.inbox
↓
8. E-Taxes возвращает список накладных
↓
9. Если 401: автоматический refresh токена и повтор
↓
10. Frontend отображает список накладных
↓
11. Пользователь выбирает накладную → get_invoice_details()
↓
12. E-Taxes API возвращает детали (товары, цены, контрагент)
↓
13. Пользователь нажимает "Import"
↓
14. import_invoice_with_mapping() проверяет маппинг:
- Товары: etaxes_item_name → erp_item
- Контрагент: etaxes_party_name → mapped_supplier
- Единицы: etaxes_unit_name → mapped_unit
↓
15. Если есть несопоставленные:
- Показать диалог маппинга
- Пользователь выбирает/создает товары
↓
16. Создание Purchase Order:
- Supplier из маппинга
- Items с quantities/rates
- Warehouse, schedule_date
↓
17. Создание E-Taxes Purchase record
↓
18. Связывание PO ↔ E-Taxes Purchase
↓
19. Сохранение, отображение результата
```
#### Исходящий поток (Продажи / Outbox)
```
1. Аналогично входящему, но:
- get_sales_invoices() вместо get_invoices()
- /invoice/find.outbox endpoint
- Customer mapping вместо Supplier
- Sales Order/Invoice вместо Purchase Order/Invoice
```
#### Поток справочных данных
```
1. Пользователь открывает E-Taxes Settings
↓
2. Выбирает вкладку "Items" / "Parties" / "Units"
↓
3. Устанавливает date_from, date_to
↓
4. Нажимает "Load Items from E-Taxes"
↓
5. load_combined_data_from_etaxes() запускается:
- Загрузка накладных пакетами (200 шт.)
- Извлечение товаров из каждой накладной
- process_single_invoice_for_items()
↓
6. Создание E-Taxes Item records (status: New)
↓
7. Пользователь нажимает "Match Similar Items"
↓
8. match_similar_items():
- Нормализация азербайджанских символов
- SequenceMatcher с threshold 95%
- Автоматическое создание маппинга
↓
9. Обновление статусов: New → Mapped
↓
10. Для оставшихся: create_unmapped_items()
- Создание новых Item в ERPNext
- Автоматический маппинг
```
#### Поток обновления токена (Cron)
```
Каждые 4 минуты (*/4 * * * *):
↓
1. renew_token() вызывается планировщиком
↓
2. check_recent_activity():
- Если нет активности > ACTIVITY_TIMEOUT → skip
↓
3. Получение текущего токена из Asan Login
↓
4. POST /api/po/auth/public/v1/renew
Headers: { x-authorization: Bearer {current_token} }
↓
5. E-Taxes возвращает новый токен в заголовке x-authorization
↓
6. Обновление main_token в БД через frappe.db.set_value()
↓
7. Commit транзакции
↓
8. Если 401: установить auth_status = "Not Authenticated"
Если 500: retry с экспоненциальной задержкой (до 3 раз)
```
### 2.4 Технологический стек
#### Backend
- **Python 3.10+** — основной язык программирования
- **Frappe Framework** — фреймворк для бизнес-приложений
- **Frappe ORM** — объектно-реляционное отображение для работы с БД
- **requests** library — HTTP клиент для вызовов E-Taxes API
- **difflib.SequenceMatcher** — fuzzy matching для маппинга
- **re (regex)** — обработка строк и валидация
- **json** — сериализация/десериализация данных
#### Frontend
- **JavaScript ES6+** — клиентская логика
- **Frappe UI Framework** — компоненты интерфейса
- **jQuery** (через Frappe) — DOM манипуляции
- **frappe.call()** — AJAX вызовы к backend
#### База данных
- **MariaDB** — основная БД
- **InnoDB engine** — для всех doctypes
- **Индексы** на etaxes_item_name, etaxes_unit_name, etaxes_party_name
#### Внешние API
- **E-Taxes REST API** (new.e-taxes.gov.az)
- Authentication: Bearer Token
- Format: JSON
- Protocol: HTTPS
- Rate limiting: 100ms между запросами
#### Инструменты разработки
- **ruff** — Python linting
- **eslint** — JavaScript linting
- **prettier** — форматирование кода
- **pyupgrade** — модернизация Python синтаксиса
- **pre-commit** — hooks для контроля качества кода
#### Планировщик
- **Frappe Scheduler** — cron-like задания
- **Background Jobs** — длительные операции
- **Queue Workers** — асинхронная обработка
#### Логирование и мониторинг
- **frappe.log_error()** — логирование ошибок в Error Log doctype
- **frappe.logger()** — информационное логирование
- **Activity tracking** — отслеживание времени последней активности
---
_Документ продолжается... (это только первые 2 раздела из 13)_
_Размер текущего документа: ~1,400 строк_
_Оценка финального размера: ~15,000-20,000 строк_
_Прогресс: 7% завершено_
---
**Следующие разделы:**
- Раздел 3: Подробная документация всех 17 функций auth.py
- Раздел 4: Подробная документация всех 42 функций api.py
- Раздел 5: Подробная документация всех 10 функций sales_api.py
- Разделы 6-13: DocTypes, JavaScript, руководства, примеры, FAQ
_Документация создается поэтапно. Этот файл будет обновляться по мере добавления разделов._

2
invoice_az/public/js/invoice_az.bundle.js
View File

@ -1,2 +0,0 @@
// Empty bundle file for invoice_az
// This file is required for the build process