```markdown
# 📋 Генератор технологических карт санитарной обработки

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
[![Flask](https://img.shields.io/badge/Flask-2.0+-green.svg)](https://flask.palletsprojects.com/)
[![SQLite](https://img.shields.io/badge/SQLite-3.0+-blue.svg)](https://www.sqlite.org/)
[![Status](https://img.shields.io/badge/status-production-green.svg)]()
[![Version](https://img.shields.io/badge/version-4.1.0-blue.svg)]()

Автоматическая генерация технологических карт санитарной обработки помещений из чек-листов в формате `.docx` с веб-интерфейсом в стиле Chemitech. Поддержка категорий помещений для выбора разных инструкций.

---

## 📑 ОГЛАВЛЕНИЕ

- [Возможности](#-возможности)
- [Установка](#-установка)
- [Быстрый старт](#-быстрый-старт)
- [Структура проекта](#-структура-проекта)
- [Использование](#-использование)
- [Веб-интерфейс](#-веб-интерфейс)
- [Режимы генерации](#-режимы-генерации)
- [База данных](#-база-данных)
- [Категории помещений](#-категории-помещений)
- [Формат чек-листа](#-формат-чек-листа)
- [Группировка и объединение ячеек](#-группировка-и-объединение-ячеек)
- [Порядок способов обработки](#-порядок-способов-обработки)
- [Администрирование](#-администрирование)
- [Настройка](#-настройка)
- [Импорт/экспорт данных](#-импортэкспорт-данных)
- [API](#-api)
- [Docker-развёртывание](#-docker-развёртывание)
- [Устранение неполадок](#-устранение-неполадок)
- [Производительность](#-производительность)

---

## 🚀 ВОЗМОЖНОСТИ

### Парсинг и генерация
- ✅ **Автоматический парсинг** чек-листов `.docx`
- ✅ **Поддержка двух типов чек-боксов**: SDT (Structured Document Tags) и Unicode-символы (☒/☐)
- ✅ **Обработка объектов с модификаторами** (любое количество)
- ✅ **Автоматическое определение категорий** из базы данных
- ✅ **Парсинг выпадающих списков** (dropDownList) для категорий помещений
- ✅ **Цветовое кодирование** моющих средств в техкарте (по бренду ХИМИТЕК)
- ✅ **Два режима генерации**: по категориям и по приоритету (сверху вниз)
- ✅ **Группировка объектов** с одинаковыми полными наборами инструкций
- ✅ **Вертикальное объединение соседних ячеек** с одинаковыми значениями
- ✅ **Фиксированный порядок способов обработки**: обеспыливание → очистка → мойка → ополаскивание → дезинфекция

### Веб-интерфейс
- ✅ **Drag & Drop** загрузка файлов
- ✅ **Мультизагрузка**: несколько `.docx` + `.zip` одновременно
- ✅ **Прогресс-бар** с этапами и процентами
- ✅ **История генераций** с пагинацией (100 записей на страницу)
- ✅ **Скачивание ZIP-архивом** («Скачать все одним архивом»)
- ✅ **Админ-панель** для управления БД через веб

### Администрирование БД
- ✅ **CRUD объекты**: создание, редактирование, удаление
- ✅ **CRUD инструкции**: неограниченное количество, создание/редактирование/удаление
- ✅ **Выбор категории помещения** для инструкций (общая / производственная / складская / инженерная / вспомогательная)
- ✅ **Поиск и сортировка** по колонкам
- ✅ **Импорт CSV** через веб (3 режима)
- ✅ **Экспорт CSV** всей БД с категориями помещений
- ✅ **История генераций**: удаление выбранных или старше даты
- ✅ **Автоочистка** загруженных файлов (24 часа)

### Производительность
- ✅ **Оптимизированные запросы** к БД (3 запроса на всю техкарту)
- ✅ **Пакетная обработка** через CLI и веб
- ✅ **Веб-сервер** на Flask с API
- ✅ **Docker-развёртывание** с persistent volume для данных

---

## 📦 УСТАНОВКА

### 1. Клонирование репозитория

```bash
git clone <url-репозитория>
cd AUTO-GEN-FINAL-VERSION
```

### 2. Создание виртуального окружения

```bash
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate
```

### 3. Установка зависимостей

```bash
pip install -r requirements.txt
```

### 4. Инициализация базы данных

```bash
python -m db.init_db
```

### 5. Импорт данных (опционально)

```bash
# Через веб-интерфейс: Админ-панель → Импорт CSV
# Или через CLI:
python import_csv_to_db.py db_export_all1111.csv --mode 1
```

---

## ⚡ БЫСТРЫЙ СТАРТ

### Запуск веб-интерфейса

```bash
python app.py
```

Открыть в браузере:
- **Главная**: http://localhost:5000
- **Админ-панель**: http://localhost:5000/admin
- **История**: http://localhost:5000/history

### CLI (командная строка)

```bash
# Режим 1 (по категориям)
python test_generator.py --single "checklists/файл.docx" --mode 1

# Режим 2 (по приоритету)
python test_generator.py --single "checklists/файл.docx" --mode 2

# Пакетная обработка
python test_generator.py --input "checklists" --output "tech_cards" --mode 2
```

---

## 📁 СТРУКТУРА ПРОЕКТА

```
AUTO-GEN-FINAL-VERSION/
├── app.py                          # Flask веб-приложение (API + рендеринг)
├── test_generator.py               # CLI для пакетной генерации
├── requirements.txt                # Зависимости Python
├── Dockerfile                      # Docker-образ
├── entrypoint.sh                   # Точка входа Docker
│
├── parser/                         # Парсер чек-листов
│   ├── models.py                   # ChecklistData, ChecklistItem, Category
│   ├── utils.py                    # Вспомогательные функции
│   └── xml_parser.py               # Основной парсер (SDT + Unicode + dropDownList)
│
├── generator/                      # Генератор техкарт
│   ├── docx_generator.py           # Генерация .docx (цвета, группировка, объединение)
│   └── mapper.py                   # Маппинг категорий
│
├── db/                             # Работа с БД
│   ├── models.py                   # SQLAlchemy: Category, Object, Instruction, RoomCategory
│   ├── database.py                 # Подключение к SQLite
│   ├── crud.py                     # CRUD операции
│   ├── init_db.py                  # Инициализация БД (таблицы + категории + категории помещений)
│   ├── import_csv_to_db.py         # Импорт из CSV (с поддержкой room_category_name)
│   ├── import_json.py              # Импорт из JSON
│   └── export_json.py              # Экспорт в JSON
│
├── export_db_to_single_csv.py      # Экспорт БД в CSV
│
├── static/                         # Статические файлы (веб-интерфейс)
│   ├── css/
│   │   └── style.css               # Стили Chemitech
│   └── js/
│       ├── app.js                  # Vue.js: главная страница
│       ├── admin.js                # Vue.js: админ-панель
│       └── history.js              # Vue.js: история
│
├── templates/                      # HTML шаблоны
│   ├── index.html                  # Главная (Drag & Drop, прогресс-бар)
│   ├── admin.html                  # Админ-панель (CRUD объекты/инструкции, импорт CSV)
│   └── history.html                # История (пагинация, удаление)
│
├── tech_card_templates/            # Шаблоны
│   └── шаблон.docx                 # Основной шаблон (Arial 9)
│
├── checklists/                     # Входные чек-листы
├── tech_cards/                     # Сгенерированные техкарты
├── uploads/                        # Временные файлы (автоочистка)
├── data/                           # Persistent данные (БД, история)
│
├── tech_cards.db                   # База данных SQLite
└── generation_history.json         # История генераций
```

---

## 🖥️ ВЕБ-ИНТЕРФЕЙС

### Главная страница (`/`)

| Элемент | Описание |
|---------|----------|
| **Drag & Drop зона** | Загрузка файлов перетаскиванием или кликом |
| **Мультизагрузка** | Можно выбрать несколько `.docx` + `.zip` |
| **Выбор режима** | Карточки «По категориям» / «По приоритету» |
| **Прогресс-бар** | 5 этапов: парсинг → БД → группировка → Word → сохранение |
| **Результат** | Таблица с файлами, кнопки скачивания |
| **ZIP-архив** | «Скачать все одним архивом» (при >1 файла) |
| **Новая генерация** | Кнопка сброса для повторной загрузки |

### Админ-панель (`/admin`)

| Функция | Описание |
|---------|----------|
| **Таблица объектов** | ID, категория, название, инструкции, приоритет |
| **Поиск** | По названию, категории, normalized_name |
| **Сортировка** | По любой колонке (клик по заголовку) |
| **Добавление** | Модальное окно с формой |
| **Редактирование** | Модальное окно с предзаполненными полями |
| **Удаление** | С подтверждением |
| **Инструкции** | Просмотр, редактирование, добавление новых с выбором категории помещения |
| **Импорт CSV** | Выбор файла + режима (1/2/3) |
| **Экспорт CSV** | Скачивание всей БД |

### История (`/history`)

| Функция | Описание |
|---------|----------|
| **Таблица** | Дата, название, объектов, размер, скачать |
| **Пагинация** | 100 записей на страницу |
| **Удаление** | Выборочное (чекбоксы) или старше даты |

---

## 📊 РЕЖИМЫ ГЕНЕРАЦИИ

| Режим | Описание | Флаг |
|-------|----------|------|
| **1** | По категориям (с заголовками, по алфавиту) | `mode=1` (по умолчанию) |
| **2** | По приоритету (единый список, сверху вниз) | `mode=2` |

### Порядок объектов в режиме 2

| Приоритет | Зона |
|-----------|------|
| 10-50 | Потолок и всё на нём |
| 55-90 | Стены и всё на них |
| 100-130 | Сантехника и санитарный пост |
| 130-150 | Мебель |
| 150-170 | Оборудование и инвентарь |
| 170 | Моечный инвентарь |
| 175-200 | Пол и всё на нём |

---

## 🗄️ БАЗА ДАННЫХ

### Структура

| Таблица | Назначение |
|---------|------------|
| `categories` | 15 категорий объектов с порядком сортировки |
| `room_categories` | Категории помещений (производственное, складское, инженерное, вспомогательное) |
| `objects` | Объекты обработки (~200 записей) |
| `instructions` | Инструкции с привязкой к категории помещения (room_category_id) |

### Категории объектов

1. Поверхности
2. Сантехническое оборудование
3. Санитарный пост
4. Мебель
5. Офисная техника
6. Многоразовые резиновые СИЗ
7. Бытовая техника
8. Инвентарь, посуда и т.д.
9. Моечный, уборочный инвентарь и оборудование
10. Посудомоечное оборудование
11. Холодильное оборудование
12. Дозирующее оборудование
13. Тепловое оборудование
14. Технологическое оборудование
15. Упаковочное оборудование

### Ключевые поля

| Поле | Описание |
|------|----------|
| `normalized_name` | Нормализованное имя для поиска |
| `display_name` | Красивое имя для вывода в техкарту |
| `sort_priority` | Приоритет для сортировки (10-200) |
| `room_category_id` | Привязка инструкции к типу помещения (NULL = общая) |

---

## 🏢 КАТЕГОРИИ ПОМЕЩЕНИЙ

Инструкции могут быть привязаны к типу помещения. Если для конкретного типа помещения инструкция не найдена — используется общая (`room_category_id IS NULL`).

| Категория | Описание |
|-----------|----------|
| **Производственное** | Цеха, производственные участки |
| **Складское** | Склады сырья, готовой продукции |
| **Инженерное** | Инженерные помещения, серверные |
| **Вспомогательное** | Коридоры, бытовки, санузлы |

### Как это работает

1. В чек-лист добавляется элемент управления «раскрывающийся список» (dropDownList) с выбором категории помещения
2. При парсинге чек-листа значение автоматически считывается
3. При генерации техкарты для каждого объекта выбираются инструкции, соответствующие категории помещения
4. Если специфичная инструкция не найдена — используется общая

---

## 📄 ФОРМАТ ЧЕК-ЛИСТА

### Требования

- Формат `.docx`
- Чек-боксы: SDT или Unicode (☒/☐)
- Выпадающий список (dropDownList) для выбора категории помещения

### Структура ячейки

| Тип | Пример |
|-----|--------|
| **Одиночный объект** | `☒ светильники` |
| **Объект с модификаторами** | `☒ потолок ☒ П ☒ ОК` |

### Логика обработки

| Ситуация | Результат |
|----------|-----------|
| 1 чек-бокс в ячейке | Одиночный объект → в свою категорию |
| 2+ чек-боксов | Объект с модификаторами |
| Базовый ✅ + модификаторы ✅ | Каждый модификатор в свою категорию |
| Базовый ✅ + модификаторы ⬜ | Базовый в «Прочее» |
| Базовый ⬜ | Не добавляется |

---

## 📋 ГРУППИРОВКА И ОБЪЕДИНЕНИЕ ЯЧЕЕК

### Группировка объектов

Объекты объединяются в одной ячейке через запятую **только при полном совпадении всех инструкций одновременно** (мойка + дезинфекция + ...).

### Вертикальное объединение

| Колонка | Индекс | Условие объединения |
|---------|--------|---------------------|
| Объект обработки | 0 | Всегда (для сгруппированных объектов) |
| Инвентарь | 8 | Соседние строки с одинаковыми значениями |
| Периодичность | 9 | Соседние строки с одинаковыми значениями |
| Исполнитель | 10 | Соседние строки с одинаковыми значениями |
| Метод контроля | 11 | Соседние строки с одинаковыми значениями |

> **Важно:** Объединение происходит для последовательных строк с одинаковыми значениями. Например: `"12 мес"`, `"12 мес"`, `"3 мес"` → первые две объединяются, третья остаётся отдельно.

---

## 🔄 ПОРЯДОК СПОСОБОВ ОБРАБОТКИ

Инструкции в техкарте всегда выводятся в фиксированном порядке, независимо от их расположения в базе данных:

| № | Способ обработки |
|---|-----------------|
| 1 | Обеспыливание |
| 2 | Очистка |
| 3 | Мойка |
| 4 | Ополаскивание |
| 5 | Дезинфекция |

Если какой-либо способ отсутствует — он пропускается.

---

## ⚙️ АДМИНИСТРИРОВАНИЕ

### CRUD операции (веб)

1. Открыть `/admin`
2. **Добавить**: кнопка «Добавить» → заполнить форму → «Создать»
3. **Редактировать**: кнопка ✏️ → изменить поля → «Сохранить»
4. **Удалить**: кнопка 🗑️ → подтвердить
5. **Инструкции**: кнопка 📋 → «Добавить» → выбрать категорию помещения → заполнить → «Сохранить»

### Импорт CSV (веб)

1. Открыть `/admin` → «Импорт CSV»
2. Выбрать файл `.csv`
3. Выбрать режим:
   - **1** — Добавление новых (пропуск дубликатов)
   - **2** — Очистка данных + добавление
   - **3** — Пересоздание БД
4. Нажать «Загрузить»

### История

1. Открыть `/history`
2. Просмотр, скачивание, удаление
3. «Удалить старше даты» — выбрать дату → удалить

---

## ⚙️ НАСТРОЙКА

### Настройка шаблона (шрифт)

1. Открыть `tech_card_templates/шаблон.docx` в Word
2. `Ctrl+A` → шрифт **Arial**, размер **9**
3. Обновить стиль «Основной текст»
4. Сохранить

| Действие | Результат |
|----------|-----------|
| Шаблон настроен | Шрифт Arial автоматически |
| Шаблон не настроен | Cambria вместо Arial |

### Добавление цвета для средства

В `generator/docx_generator.py`:

```python
PRODUCT_COLORS = {
    "НОВОЕ СРЕДСТВО": "FFAA00",  # HEX-код
}
```

### Добавление категории помещения

Через API или админ-панель (эндпоинт `/api/room-categories`).

---

## 📥 ИМПОРТ/ЭКСПОРТ ДАННЫХ

### Экспорт CSV

```bash
# CLI
python export_db_to_single_csv.py

# Веб
# /admin → «Экспорт CSV»
```

Формат CSV включает колонку `room_category_name` для инструкций с привязкой к категории помещения.

### Импорт CSV

```bash
# CLI
python import_csv_to_db.py db_export_all1111.csv --mode 1

# Веб
# /admin → «Импорт CSV» → выбор режима → загрузка
```

CSV должен содержать колонку `room_category_name` (пустая = общая инструкция).

---

## 🔌 API

### Генерация и история

| Эндпоинт | Метод | Назначение |
|----------|-------|------------|
| `/api/generate` | POST | Генерация (один/мульти/zip) |
| `/api/history` | GET | История (пагинация) |
| `/api/history/delete` | POST | Удаление техкарт |
| `/download/<filename>` | GET | Скачать файл |

### Объекты

| Эндпоинт | Метод | Назначение |
|----------|-------|------------|
| `/api/objects` | GET | Список объектов |
| `/api/objects` | POST | Создание объекта |
| `/api/objects/<id>` | PUT | Обновление объекта |
| `/api/objects/<id>` | DELETE | Удаление объекта |

### Инструкции

| Эндпоинт | Метод | Назначение |
|----------|-------|------------|
| `/api/objects/<id>/instructions` | GET | Инструкции объекта |
| `/api/objects/<id>/instructions` | POST | Добавить инструкцию |
| `/api/instructions/<id>` | PUT | Обновить инструкцию |
| `/api/instructions/<id>` | DELETE | Удалить инструкцию |

### Категории

| Эндпоинт | Метод | Назначение |
|----------|-------|------------|
| `/api/categories` | GET | Список категорий объектов |
| `/api/room-categories` | GET | Список категорий помещений |
| `/api/room-categories` | POST | Создать категорию помещения |
| `/api/room-categories/<id>` | PUT | Обновить категорию помещения |
| `/api/room-categories/<id>` | DELETE | Удалить категорию помещения |

### Импорт/экспорт

| Эндпоинт | Метод | Назначение |
|----------|-------|------------|
| `/api/export_csv` | GET | Экспорт CSV (с room_category_name) |
| `/api/import_csv` | POST | Импорт CSV |

---

## 🐳 DOCKER-РАЗВЁРТЫВАНИЕ

### Сборка образа

```bash
docker build -t tech-card-generator .
```

### Запуск контейнера

```bash
docker run -d \
  --name tech-cards \
  -p 5000:5000 \
  -v tech-cards-data:/app/data \
  tech-card-generator
```

### Docker Compose

```yaml
services:
  app:
    build: ../..
    ports:
      - "5000:5000"
    volumes:
      - app-data:/app/data
    environment:
      - DB_DIR=/app/data
      - HISTORY_DIR=/app/data

volumes:
  app-data:
```

### Особенности

- БД хранится в `/app/data/tech_cards.db`
- История — `/app/data/generation_history.json`
- При первом запуске БД создаётся автоматически
- При перезапуске данные сохраняются в volume

---

## 🔧 УСТРАНЕНИЕ НЕПОЛАДОК

### Объекты попадают в «Прочее»

**Причина:** `normalized_name` в БД не совпадает с парсером.

**Решение:** Открыть `/admin` → найти объект → ✏️ → исправить `normalized_name`.

### Инструкции возвращаются после удаления

**Причина:** База данных не сохранена в persistent volume.

**Решение:** Настроить volume монтирование `/app/data` или использовать `DB_DIR=/app/data`.

### Медленная генерация

**Причина:** Много запросов к БД.

**Решение:** Убедиться, что используется `docx_generator.py` с 3 запросами.

### Не отображается дезинфекция

**Причина:** Неправильная группировка или неверный `room_category_id`.

**Решение:** Проверить инструкции объекта через админ-панель, убедиться что `room_category_id` корректен.

### Файл не открывается в Word

**Причина:** Повреждённая структура XML.

**Решение:** Проверить логи консоли, перезапустить генерацию.

### Ошибка 404 для static

**Причина:** Отсутствует папка `static/`.

**Решение:**
```bash
mkdir static\css
mkdir static\js
```

### Ошибка «no such table: room_categories»

**Причина:** Старая БД без новых таблиц.

**Решение:**
```bash
python -m db.init_db
```

---

## 📊 ПРОИЗВОДИТЕЛЬНОСТЬ

| Показатель | Значение |
|-----------|----------|
| Парсинг чек-листа (200 объектов) | ~0.3 сек |
| Загрузка из БД | ~0.01 сек |
| Генерация техкарты | ~3-5 сек |
| Запросы к БД на техкарту | 3 запроса |
| Размер выходного файла | ~50-60 KB |
| История (JSON) | до 1000 записей |
| Автоочистка uploads | 24 часа |

---

## 📝 ЗАВИСИМОСТИ

| Пакет | Версия | Назначение |
|-------|--------|------------|
| Flask | 2.0+ | Веб-фреймворк |
| SQLAlchemy | 1.4+ | ORM для БД |
| lxml | 4.6+ | Парсинг XML |
| python-docx | 0.8+ | Генерация .docx |
| openpyxl | 3.0+ | Чтение Excel |
| Vue.js | 3.x (CDN) | Фронтенд |
| Bootstrap | 5.3 (CDN) | UI-фреймворк |
| Bootstrap Icons | 1.11 (CDN) | Иконки |
| Toastify.js | 1.x (CDN) | Уведомления |
| Montserrat | Google Fonts | Шрифт |

---

## 📄 ЛИЦЕНЗИЯ

Проприетарное программное обеспечение. Все права защищены.

---

## 👥 КОНТАКТЫ

По вопросам использования и доработки обращаться к разработчику.

---

**Версия:** 4.1.0  
**Последнее обновление:** 27 апреля 2026 г.
```