160 lines
5.6 KiB
Markdown
160 lines
5.6 KiB
Markdown
# Tax Articles Normalization
|
||
|
||
## Проблема
|
||
|
||
В Tax Articles были обнаружены проблемы с кодировкой символов, которые приводили к тому, что отчет **Tax Articles Revenue Report** показывал 0 вместо реальных сумм для некоторых статей.
|
||
|
||
### Две найденные проблемы:
|
||
|
||
#### 1. Типографские кавычки (Curly Quotes)
|
||
|
||
**Проблема:** В базе данных использовались типографские (curly) кавычки `"` `"` (Unicode U+201C/U+201D), а в коде Python - обычные прямые кавычки `"` (ASCII 0x22).
|
||
|
||
**Пример:**
|
||
```
|
||
БД: "Məşğulluq haqqında" (типографские)
|
||
Код: "Məşğulluq haqqında" (прямые)
|
||
```
|
||
|
||
**Затронутые статьи:**
|
||
- VM 164.1.42 - "Məşğulluq haqqında"
|
||
- VM 164.1.51 - "Tibbi sığorta haqqında"
|
||
- Vergi Məcəlləsinin 102.1-ci
|
||
- Vergi Məcəlləsinin 106.1.24-cü
|
||
- Vergi Məcəlləsinin 207.7-ci
|
||
|
||
#### 2. Unicode Нормализация (NFD vs NFC)
|
||
|
||
**Проблема:** В базе данных использовалась NFD форма (decomposed - буква + диакритический знак), а в коде - NFC форма (composed - готовая буква).
|
||
|
||
**Пример:**
|
||
```
|
||
NFD: s + cedilla (2 символа) = ş
|
||
NFC: ş (1 символ)
|
||
```
|
||
|
||
**Затронутые статьи:**
|
||
- VM 164.1.34-1
|
||
- VM 164.1.41-2
|
||
- VM 164.1.47
|
||
- Vergi Məcəlləsinin 106.1.5-ci
|
||
|
||
## Решение
|
||
|
||
### Автоматическое исправление
|
||
|
||
Создан скрипт `taxes_az/normalize_tax_articles.py`, который автоматически:
|
||
|
||
1. **Заменяет типографские кавычки на прямые**
|
||
- Использует SQL REPLACE с HEX значениями для точной замены байтов
|
||
- `E2809C` (U+201C) → `22` (ASCII ")
|
||
- `E2809D` (U+201D) → `22` (ASCII ")
|
||
|
||
2. **Нормализует Unicode в форму NFC**
|
||
- Конвертирует разложенные символы в композитные
|
||
- Обеспечивает соответствие с кодом Python
|
||
|
||
### Запуск скрипта
|
||
|
||
Скрипт запускается автоматически после каждой миграции благодаря хуку в `hooks.py`:
|
||
|
||
```python
|
||
after_migrate = [
|
||
"taxes_az.master_data.sync.sync_item_groups",
|
||
"taxes_az.normalize_tax_articles.normalize_on_migrate"
|
||
]
|
||
```
|
||
|
||
### Ручной запуск
|
||
|
||
Если нужно запустить вручную:
|
||
|
||
```bash
|
||
cd /home/frappe/frappe-bench
|
||
bench --site [site-name] execute "
|
||
from taxes_az.normalize_tax_articles import normalize_tax_articles
|
||
normalize_tax_articles()
|
||
"
|
||
```
|
||
|
||
## Установка на новой машине
|
||
|
||
При установке приложения на новой машине:
|
||
|
||
1. **Установите приложение:**
|
||
```bash
|
||
bench get-app https://github.com/your-repo/taxes_az
|
||
bench --site [site-name] install-app taxes_az
|
||
```
|
||
|
||
2. **Скрипт нормализации запустится автоматически** во время установки (через after_migrate hook)
|
||
|
||
3. **Проверьте логи:**
|
||
```bash
|
||
bench --site [site-name] console
|
||
```
|
||
Вы должны увидеть:
|
||
```
|
||
Tax Articles normalized: X curly quotes fixed, Y NFC normalized
|
||
```
|
||
|
||
## Проверка
|
||
|
||
Для проверки что все исправлено правильно:
|
||
|
||
```bash
|
||
cd /home/frappe/frappe-bench
|
||
bench --site [site-name] mariadb --execute "
|
||
SELECT COUNT(*) as remaining_problems
|
||
FROM \`tabTax Article\`
|
||
WHERE HEX(article_name) LIKE '%E2809C%'
|
||
OR HEX(article_name) LIKE '%E2809D%';
|
||
"
|
||
```
|
||
|
||
Результат должен быть: `remaining_problems: 0`
|
||
|
||
## Fixtures
|
||
|
||
Файл fixtures (`taxes_az/fixtures/tax_article.json`) также был обновлен:
|
||
- Заменены типографские кавычки на прямые
|
||
- Применена NFC нормализация
|
||
|
||
При экспорте новых fixtures они будут автоматически в правильном формате, так как данные в БД уже нормализованы.
|
||
|
||
## Технические детали
|
||
|
||
### Файлы
|
||
|
||
- **Скрипт нормализации:** `taxes_az/normalize_tax_articles.py`
|
||
- **Hooks конфигурация:** `taxes_az/hooks.py`
|
||
- **Fixtures (обновлен):** `taxes_az/fixtures/tax_article.json`
|
||
- **Отчет использующий маппинг:** `taxes_az/report/tax_articles_revenue_report/`
|
||
|
||
### HEX коды
|
||
|
||
| Тип кавычки | Символ | Unicode | UTF-8 HEX |
|
||
|-------------|--------|---------|-----------|
|
||
| Левая типографская | " | U+201C | E2 80 9C |
|
||
| Правая типографская | " | U+201D | E2 80 9D |
|
||
| Прямая | " | ASCII 0x22 | 22 |
|
||
|
||
### Логирование
|
||
|
||
Все действия логируются в Frappe Error Log с заголовком "Tax Article Normalization".
|
||
|
||
## История изменений
|
||
|
||
**2026-02-02:** Первая версия
|
||
- Исправлено 5 статей с кавычками
|
||
- Исправлено 4 статьи с NFD нормализацией
|
||
- Добавлен автоматический скрипт в hooks
|
||
- Обновлены fixtures
|
||
|
||
## Поддержка
|
||
|
||
При проблемах проверьте:
|
||
1. Логи миграции: `bench --site [site-name] migrate`
|
||
2. Error Log в интерфейсе Frappe
|
||
3. Запустите скрипт вручную для диагностики
|