my_converterbot/README.md

# 📄 My Converter Bot

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![aiogram](https://img.shields.io/badge/aiogram-3.x-00ADD8.svg)](https://docs.aiogram.dev/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Телеграм-бот для автоматизированной конвертации документов с поддержкой форматирования по ГОСТ 7.32-2017 и анализа структуры проектов.

## 🎯 Функциональные возможности

### Конвертация Markdown → DOCX
- **Полная поддержка ГОСТ 7.32-2017**: автоматическое форматирование научно-технической документации
- **Интеллектуальная обработка синтаксиса**: заголовки, списки, таблицы, блоки кода
- **Автоматическая нумерация**: иерархическая нумерация разделов (1.1.1, 1.1.2)
- **Управление сносками**: интеграция footnotes с автоматическим форматированием
- **Настраиваемая типографика**: Times New Roman 14pt, межстрочный интервал 1.5

### Анализ архивов → TXT
- **Древовидная визуализация**: полная структура проекта с UTF-8 оформлением
- **Извлечение содержимого**: автоматический экспорт кода из всех текстовых файлов
- **Интеллектуальная фильтрация**: игнорирование служебных директорий (node_modules, __pycache__)
- **Обработка бинарных файлов**: детектирование и генерация placeholder для медиа

## 🔧 Технологический стек

| Компонент | Технология | Назначение |
|-----------|------------|------------|
| **Bot Framework** | aiogram 3.x | Асинхронная обработка Telegram API |
| **Document Processing** | python-docx | Генерация DOCX с программным управлением стилями |
| **Parsing Engine** | re (regex) | Парсинг Markdown синтаксиса |
| **Archive Handling** | zipfile | Распаковка и анализ архивов |
| **Async Runtime** | asyncio | Конкурентная обработка запросов |

## 📦 Установка и развертывание

### Системные требования
- Python 3.10 или выше
- pip package manager
- Telegram Bot Token (получить у [@BotFather](https://t.me/botfather))

### Процедура установки

```bash
# Клонирование репозитория
git clone https://github.com/EDeev/my_converterbot.git
cd my_converterbot

# Установка зависимостей
pip install -r requirements.txt

# Конфигурация токена
# Отредактируйте bot.py, установите ваш BOT_TOKEN
# BOT_TOKEN = "your_telegram_bot_token_here"

# Запуск бота
python bot.py
```

## 🚀 Использование

### Базовые команды
- `/start` — инициализация и приветственное сообщение
- `/help` — детальная документация по функциям

### Рабочий процесс

#### Markdown → DOCX конвертация
1. Отправьте `.md` файл боту
2. Система автоматически применит ГОСТ форматирование
3. Получите готовый `.docx` документ

**Пример входного Markdown:**
```markdown
# Введение

Основной текст с **жирным** и *курсивным* форматированием[^1].

## 1. Методология

- Пункт списка 1
- Пункт списка 2

[^1]: Текст сноски
```

#### ZIP → TXT анализ
1. Отправьте `.zip` архив с проектом
2. Бот извлечет и проанализирует структуру
3. Получите `project_structure.txt` с полным содержимым

## ⚙️ Архитектурные особенности

### Модульная структура

```
my_converterbot/
├── bot.py              # Основной модуль Telegram бота
├── md_to_docx.py       # Конвертер Markdown с ГОСТ движком
├── rep_to_txt.py       # Анализатор проектных структур
├── requirements.txt    # Спецификация зависимостей
└── README.md          # Текущая документация
```

### DocumentSettings: Параметрическая конфигурация

Класс `DocumentSettings` обеспечивает гранулярное управление:
- Размеры шрифтов (14pt основной текст, 16pt заголовки первого уровня)
- Отступы документа (левый: 3.0 см для переплета)
- Режимы нумерации (decimal: 1.1.1 или simple: 1)
- Позиционирование номеров страниц

### Интеллектуальная обработка

**Алгоритм обработки списков:**
- Распознавание вложенности через отступы
- Автоматическая замена bullet points на длинное тире (ГОСТ)
- Сохранение иерархической структуры

**Система обработки сносок:**
- Inline маркеры `[^1]` → верхний индекс в тексте
- Автоматическая агрегация определений
- Размещение в конце документа с разделителем

## 🔒 Ограничения и constraints

- **Максимальный размер файла**: 20 МБ (Telegram API limitation)
- **Поддерживаемые форматы входных данных**: `.md`, `.zip`
- **Кодировки**: UTF-8, UTF-8-sig, CP1251, Latin1 (fallback цепочка)

## 📊 Производительность

- **Обработка Markdown**: ~0.5-2 сек для документов до 50 страниц
- **Анализ ZIP архивов**: ~1-5 сек для проектов до 1000 файлов
- **Конкурентная обработка**: до 10 одновременных запросов

## 🛠️ Расширение функциональности

### Кастомизация ГОСТ параметров

```python
from md_to_docx import MarkdownToDocxConverter, DocumentSettings

settings = DocumentSettings()
settings.font_name = "Times New Roman"
settings.font_size = 14
settings.line_spacing = 1.5
settings.margin_left = 3.0
settings.auto_numbering_headings = True
settings.numbering_format = "decimal"

converter = MarkdownToDocxConverter(settings)
converter.convert("input.md", "output.docx")
```

## 📄 Лицензия

Этот проект является некоммерческим и распространяется под лицензией MIT.

## 👨‍💻 Автор

**Деев Егор Викторович** - Backend Developer  
- GitHub: [@EDeev](https://github.com/EDeev)
- Email: egor@deev.space
- Telegram: [@Egor_Deev](https://t.me/Egor_Deev)

---

<div align="center">
  <sub>⭐ Если проект оказался полезным, поставьте звездочку на GitHub!</sub>
  <p><sub>Создано с ❤️ от вашего дорогого - deev.space ©</sub></p>
</div>