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

536 lines
34 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
_Документация создается поэтапно. Этот файл будет обновляться по мере добавления разделов._
Reference in New Issue View Git Blame Copy Permalink