# Telegram Archiver — Сводка по проекту

## ✅ Статус: Phase 0 MVP завершён

**Дата:** 6 марта 2026 г.  
**Версия:** 1.0.0 (MVP)

---

## 🎯 Достигнутые результаты

### Протестировано на боевом канале
- **Канал:** dedinit (Дед in АйТи)
- **Постов заархивировано:** 992
- **Время выполнения:** 7335 секунд (~2 часа)
- **Медиафайлов скачано:** 454
- **Успешность:** 95% (50 таймаутов из 992)

### Реализованный функционал
- ✅ Авторизация через MTProto (Telethon)
- ✅ Парсинг каналов без ограничений
- ✅ Конвертация в Markdown с front-matter для Hugo
- ✅ Извлечение хэштегов и добавление в теги
- ✅ Hugo shortcodes для медиа (`{{< figure >}}`, `{{< video >}}`, `{{< audio >}}`)
- ✅ Скачивание медиа: фото, видео, аудио, документы
- ✅ Обработка таймаутов (30с на файл) — процесс не застревает
- ✅ Дедупликация: повторный запуск пропускает скачанные посты
- ✅ Прогресс-логирование: каждые 50 постов
- ✅ Обработка ошибок: проблемные посты пропускаются

---

## 📁 Структура проекта

```
telegram-archiver/
├── app/
│   ├── __init__.py
│   ├── main.py              # CLI + FastAPI entry point
│   ├── telethon_client.py   # Telethon wrapper с таймаутами
│   ├── archiver.py          # Основная логика архивации
│   ├── models.py            # Pydantic модели
│   └── logger.py            # Логирование
├── archives/                 # Выходные данные (игнорируется git)
├── .env                      # Конфигурация (API ключи)
├── .gitignore
├── FAQ.md                    # Ответы на вопросы
├── README.md                 # Документация
├── requirements.txt
├── run_archiver.py           # CLI скрипт
├── login_interactive.py      # Скрипт авторизации
└── test_*.py                 # Тестовые скрипты
```

---

## 🚀 Быстрый старт

### 1. Установка зависимостей
```bash
cd telegram-archiver
uv venv
uv pip install -r requirements.txt
```

### 2. Настройка .env
```bash
cp .env.example .env
# Отредактируй .env: API_ID, API_HASH, PHONE
```

### 3. Авторизация
```bash
python login_interactive.py
# Введи код из Telegram
```

### 4. Запуск архивации
```bash
# Тестовый прогон (5 постов)
python run_archiver.py -c dedinit --limit 5

# Полный канал
python run_archiver.py -c dedinit

# С конкретного ID
python run_archiver.py -c dedinit --from-message-id 500
```

---

## 📊 Выходные данные

### Структура
```
archives/dedinit/
├── 1042/
│   ├── index.md              # Post content + front-matter
│   └── photo_20260305_070924.jpg
├── 1043/
│   └── index.md
└── 2big2get.md               # Отчёт о больших файлах
```

### Front-matter
```yaml
---
message_id: 1044
date: '2026-03-05T18:05:47+00:00'
author: Дед in АйТи
tags: [debian, linux]
media_files:
  - filename: photo.jpg
    type: photo
    caption: Описание
    size: 87853
---

{{< figure src="photo.jpg" alt="Описание" >}}

Текст поста...
```

---

## 🔧 Известные проблемы (задачи на будущее)

| Задача | Описание | Приоритет |
|--------|----------|-----------|
| **0.10** | Посты без index.md (только медиа) | Высокий |
| **0.13** | Временная зона UTC вместо Москвы | Высокий |
| **0.15** | Размер файла = 0 во front-matter | Высокий |
| **0.21** | Resume прерванной архивации | Высокий |
| **0.9** | Прямые ссылки на посты | Средний |
| **0.14** | Прямые ссылки на файлы | Средний |
| **0.16** | Расширенный front-matter | Средний |
| **0.11** | Видео-кружки как .bin | Низкий |
| **0.17** | Многопоточное скачивание | Низкий |
| **0.19** | Очередь на скачивание | Низкий |
| **0.20** | Audio: duration, waveform | Низкий |
| **0.22** | Формат тегов inline | Низкий |
| **0.23** | Обработка трансляций | Низкий |
| **0.24** | Голосовые сообщения | Низкий |

---

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

| Метрика | Значение |
|---------|----------|
| Скорость | ~500 постов/час |
| Время на 1 пост | ~7.4 секунды |
| Время на 1 медиа | ~15-30 секунд |
| Таймауты | ~5% |
| Успех | 95% |

---

## 📚 Документация

- **[README.md](telegram-archiver/README.md)** — Полная документация
- **[FAQ.md](telegram-archiver/FAQ.md)** — Ответы на вопросы
- **[ROADMAP.md](../ROADMAP.md)** — Дорожная карта проекта

---

## 🎯 Следующие шаги

1. Исправить критичные баги (0.10, 0.13, 0.15)
2. Добавить resume (0.21)
3. Добавить отчёт о таймаутах (0.12)
4. Многопоточность (0.17, 0.19)

---

*Проект готов к использованию в текущем виде. Все критичные функции работают.*