diff --git a/.qwen/PROJECT_SUMMARY.md b/.qwen/PROJECT_SUMMARY.md new file mode 100644 index 0000000..d9d5e94 --- /dev/null +++ b/.qwen/PROJECT_SUMMARY.md @@ -0,0 +1,157 @@ +The user wants me to create a comprehensive project summary based on the entire conversation history. Let me analyze what we've accomplished and create a well-structured markdown summary. + +Key points from the conversation: +1. Project is Chronicle - a platform for technical creators to archive and publish content +2. We created telegram-archiver microservice +3. There were issues with pushing without testing - this was corrected +4. The service uses FastAPI, Telethon, Pydantic +5. Virtual environment setup with uv +6. Tests were created +7. Server was tested and works + +Let me create a comprehensive summary.# Project Summary + +## Overall Goal +Build **Chronicle** — "The Operating System for Technical Creators" — a unified platform that solves content fragmentation for technical authors by providing a Markdown editor with code syntax highlighting, cross-posting to multiple platforms, and personal archive on their own domain. + +## Key Knowledge + +### Project Structure +``` +chronicle.nixg.ru/ +├── telegram-archiver/ # MVP: Telegram channel archiver microservice +│ ├── app/ +│ │ ├── main.py # FastAPI + CLI entry point +│ │ ├── telethon_client.py # Telegram MTProto client +│ │ ├── archiver.py # Core archiving logic +│ │ ├── models.py # Pydantic data models +│ │ └── logger.py # Logging with OpenTelemetry support +│ ├── config.py # Settings management (.env based) +│ ├── tests/ # Pytest tests +│ ├── pyproject.toml # Project metadata & tool configs +│ └── requirements.txt # Dependencies +├── ROADMAP.md # 5-phase development plan +├── QWEN.md # AI assistant context (includes GIT PUSH RULES) +└── todo.md # Immediate tasks +``` + +### Technology Stack (telegram-archiver MVP) +| Component | Technology | +|-----------|------------| +| Framework | FastAPI 0.109 + CLI (Click) | +| Telegram API | Telethon 1.34 (MTProto) | +| Data Validation | Pydantic 2.5 | +| Config | pydantic-settings + .env | +| Virtual Environment | `uv venv` | +| Testing | pytest + pytest-asyncio | +| Linting | ruff + mypy + pre-commit | + +### Architecture Decisions +- **Bundle structure**: `//index.md + media files` +- **Front-matter**: YAML format compatible with Hugo (message_id, date, author, reply_to, repost_from, media_files) +- **Deduplication**: By message_id (skip if bundle directory exists) +- **Large files**: >200MB (configurable) → skip download, log to `2big2get.md` +- **Credentials**: Stored in `.env`, never committed (git-ignored) +- **Graceful degradation**: Server starts without .env but /archive returns 503 + +### Critical Rules (from QWEN.md) +**GIT PUSH RULES — ЗАПРЕЩЕНО пушить без:** +1. ✅ `pip install -r requirements.txt` — зависимости установлены +2. ✅ `python -m py_compile` — синтаксис валиден +3. ✅ Запуск CLI или API — работает без ошибок +4. ✅ Проверка эндпойнтов (для API) — возвращают 200 OK + +### Development Workflow +```bash +# Setup +uv venv +.venv\Scripts\activate # Windows +uv pip install -r requirements.txt + +# Run CLI +python -m telegram-archiver --channel dedinit + +# Run API +uvicorn app.main:app --host 0.0.0.0 --port 8000 + +# Test +pytest +ruff check . +mypy app/ +``` + +## Recent Actions + +### Session 1: Project Initialization +- **Created QWEN.md** — AI assistant context file with project overview, roadmap, brand identity +- **Committed documentation**: ROADMAP.md, todo.md, QWEN.md +- **Pushed to remote**: gitea.nixg.ru:estorozhenko/c7e.ru + +### Session 2: telegram-archiver MVP Development +- **Created microservice structure** (13 files, ~1635 lines) +- **Implemented components**: + - TelethonArchiver: Telegram MTProto client with media download + - ChannelArchiver: Core logic for bundle creation, markdown generation + - FastAPI app: REST API with /health, /archive, /docs endpoints + - CLI interface: Full-featured command-line tool + - Pydantic models: PostData, MediaFile, ArchiveRequest/Response +- **❌ ERROR**: Pushed without testing — user correction received + +### Session 3: Fix & Testing (Current) +- **Fixed configuration**: Made credentials optional, added graceful startup +- **Added development tools**: + - pyproject.toml with ruff/mypy/pytest configs + - .pre-commit-config.yaml for code quality hooks + - DEVELOPMENT.md with setup instructions + - tests/test_models.py, tests/test_config.py +- **Tested thoroughly**: + - Syntax check: all files pass `python -m py_compile` + - Imports verified in virtual environment + - FastAPI server starts without .env + - GET /health → 200 (status: disconnected) + - GET / → 200 (API info) + - POST /archive → 503 (helpful error message) +- **Updated QWEN.md**: Added GIT PUSH RULES section +- **Pushed successfully**: Commit `1d23afd` + +## Current Plan + +### telegram-archiver MVP +| Task | Status | Notes | +|------|--------|-------| +| Project structure | [DONE] | All files created | +| Telethon client | [DONE] | MTProto connection, media download | +| Archiver logic | [DONE] | Bundle creation, markdown generation | +| FastAPI endpoints | [DONE] | /health, /archive, /docs | +| CLI interface | [DONE] | Full-featured with Click | +| Configuration | [DONE] | .env based, graceful degradation | +| Testing | [DONE] | Basic tests, server tested | +| Documentation | [DONE] | README.md, DEVELOPMENT.md | +| **First real archive test** | [TODO] | Need .env with real credentials | +| Hugo integration test | [TODO] | Verify generated markdown works | + +### Next Steps (from todo.md) +1. [ ] Get Telegram API credentials from my.telegram.org +2. [ ] Create .env file with API_ID, API_HASH, PHONE +3. [ ] Test full archive run on dedinit channel +4. [ ] Verify Hugo compatibility of generated markdown +5. [ ] SSL certificate for c7e.ru (Caddy / Let's Encrypt) +6. [ ] Landing page on c7e.ru +7. [ ] GitHub/Gitea repository with README + +### Future Phases (from ROADMAP.md) +- **Phase 1**: Брендинг + сайт (c7e.ru, лендинг, GitHub) +- **Phase 2**: Редактор с кодом (Monaco Editor, Markdown, WYSIWYG) +- **Phase 3**: Интеграция (редактор + архив, поиск, версионность) +- **Phase 4**: Кросс-постинг (Telegram, VK, Habr, календарь) +- **Phase 5**: Аналитика (статистика, комментарии, API) + +### Open Questions +- Final domain choice: chronicle.dev vs getchronicle.com vs chronicle.space +- Logo design: hourglass, timeline, or stylized "C" +- Color scheme: warm paper tones vs tech minimalism + +--- + +## Summary Metadata +**Update time**: 2026-02-19T19:24:14.640Z diff --git a/telegram-archiver/SETUP_CREDENTIALS.md b/telegram-archiver/SETUP_CREDENTIALS.md new file mode 100644 index 0000000..1b5a639 --- /dev/null +++ b/telegram-archiver/SETUP_CREDENTIALS.md @@ -0,0 +1,202 @@ +# Telegram Archiver — Настройка credentials + +## 1. Получение API ключей + +### Шаг 1.1: Зайди на my.telegram.org + +1. Открой https://my.telegram.org/auth +2. Введи свой номер телефона в формате `+79991234567` +3. Нажми "Next" + +### Шаг 1.2: Введи код из Telegram + +1. Открой Telegram (десктоп или мобильное приложение) +2. Найди сообщение от **Telegram** с кодом подтверждения +3. Введи код на сайте + +### Шаг 1.3: Создай приложение + +1. Перейди на https://my.telegram.org/apps +2. Нажми **"Create application"** +3. Заполни форму: + - **App title**: `Telegram Archiver` (или любое название) + - **Short name**: `tg-archiver` (или любое) + - **Platform**: выбери `Desktop` + - **Description**: `Archive Telegram channels to Markdown` (можно любое) +4. Нажми **"Create application"** + +### Шаг 1.4: Скопируй credentials + +После создания приложения увидишь: + +``` +Api ID: 12345678 +Api hash: abcdef1234567890abcdef1234567890 +``` + +**Скопируй эти значения!** + +--- + +## 2. Настройка .env файла + +### Шаг 2.1: Создай .env + +В корне проекта `telegram-archiver/`: + +```bash +cd telegram-archiver +copy .env.example .env +``` + +### Шаг 2.2: Заполни .env + +Открой `.env` и вставь свои данные: + +```env +# Telegram API credentials +API_ID=12345678 +API_HASH=abcdef1234567890abcdef1234567890 +PHONE=+79991234567 + +# Session name (will create telegram-archiver.session file) +SESSION_NAME=telegram-archiver + +# Max file size to download (in bytes) +# Default: 200 MB = 209715200 +MAX_FILE_SIZE=209715200 + +# Output directory for archives +OUTPUT_DIR=./archives + +# Log level: DEBUG, INFO, WARNING, ERROR +LOG_LEVEL=INFO +``` + +**Важно:** +- `PHONE` должен начинаться с `+` +- Не коммить `.env` в git (он в .gitignore) + +--- + +## 3. Первый запуск + +### Шаг 3.1: Активируй виртуальное окружение + +```bash +# Windows (PowerShell) +.venv\Scripts\Activate.ps1 + +# Windows (cmd) +.venv\Scripts\activate +``` + +### Шаг 3.2: Запусти архивацию + +```bash +# Тестовый запуск (первые 10 постов) +python -m telegram-archiver --channel dedinit --limit 10 + +# Или полный архив канала +python -m telegram-archiver --channel dedinit +``` + +### Шаг 3.3: Первая авторизация + +При первом запуске: + +1. Скрипт попросит ввести код из Telegram +2. Открой Telegram → найди сообщение от **Telegram** с кодом +3. Введи код в консоль + +``` +Code sent to +79991234567 +Enter the code you received: 12345 +``` + +**После успешной авторизации:** +- Создается файл `telegram-archiver.session` +- Сессия сохраняется для следующих запусков + +--- + +## 4. Проверка результата + +### Структура выходных данных + +После архивации: + +``` +archives/ +└── dedinit/ + ├── 12345/ + │ ├── index.md + │ └── photo.jpg + ├── 12346/ + │ └── index.md + └── 2big2get.md (если есть большие файлы) +``` + +### Проверка index.md + +Открой любой `index.md`: + +```markdown +--- +message_id: 12345 +date: 2024-02-19T14:30:00 +author: "Dedinit" +media_files: + - filename: photo.jpg + type: photo + size: 102400 +--- + +Текст поста в Markdown +``` + +--- + +## 5. Возможные проблемы + +### Ошибка: "PHONE must start with +" + +**Решение:** Добавь `+` в начало номера в `.env` + +### Ошибка: "API_ID must be a positive integer" + +**Решение:** Проверь что API_ID — число без кавычек + +### Ошибка: "No module named 'telethon'" + +**Решение:** +```bash +.venv\Scripts\activate +uv pip install -r requirements.txt +``` + +### Ошибка авторизации (код не приходит) + +**Решение:** +1. Подожди 1-2 минуты +2. Проверь что номер телефона правильный +3. Попробуй запросить код ещё раз + +### Flood wait error + +Telegram ограничивает частоту запросов. + +**Решение:** Подожди указанное время (обычно 1-5 минут) + +--- + +## 6. Что дальше? + +После успешного тестирования: + +1. ✅ Проверь структуру bundle +2. ✅ Проверь front-matter +3. ✅ Проверь скачанные медиа +4. ✅ Посмотри логи (`YYYYMMDD-dedinit.log`) + +Если всё ок — готово! Можно двигаться дальше. 🎉