toreadeck/README.md

# Readeck Importer

Локальное веб-приложение для добавления статей и файлов в [Readeck](https://readeck.org/) — self-hosted сервис «прочитать позже».

Readeck импортирует материалы по URL. Приложение подготавливает контент, временно публикует его по доступному в локальной сети адресу и создаёт закладку через Readeck API. Поэтому в библиотеку можно отправлять и локальные файлы.

## Возможности

- Импорт статьи по URL с извлечением основного содержания (`trafilatura`).
- Загрузка файлов `.txt`, `.html`, `.htm`, `.md`, `.markdown`, включая drag & drop.
- Автоопределение UTF-8 и Windows-1251 для локальных файлов.
- Форматы содержимого: HTML, Markdown и простой текст.
- Перевод через Google Translate с разбиением длинного текста на безопасные части.
- Автозаполнение метаданных: заголовок, автор, описание, дата и сайт.
- Предпросмотр итоговой статьи перед отправкой.
- Санитизация HTML перед публикацией (`bleach`).
- Проверка соединения с Readeck в настройках.
- Локальная библиотека: отдельное окно для просмотра файлов из выбранной папки.
- Отправка открытого в Локальной библиотеке файла в основное окно для последующей отправки в Readeck.
- Светлая и тёмная темы, автосохранение черновика, счётчики символов и слов.
- Интерфейс на русском, английском и казахском языках.

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

- Python 3.9+ (проект проверялся на Python 3.12).
- Доступный сервер Readeck и API-токен.
- Сетевой доступ Readeck к машине с этим приложением, если Readeck расположен на другом хосте.

## Установка

### Windows: быстрый запуск

В каталоге проекта есть `run.bat`. Он запускает приложение через `.venv\Scripts\python.exe` и очищает унаследованные `PYTHONPATH` / `PYTHONHOME`.

Перед первым запуском создайте виртуальное окружение и установите зависимости:

```bat
py -3.12 -m venv .venv
.venv\Scripts\python -m pip install fastapi uvicorn pydantic beautifulsoup4 lxml httpx deep-translator markdown bleach trafilatura python-multipart
run.bat
```

### Универсальный запуск

```bash
python -m pip install fastapi uvicorn pydantic beautifulsoup4 lxml httpx deep-translator markdown bleach trafilatura python-multipart
python main.py
```

Сервис слушает `0.0.0.0:8142`, а браузер автоматически открывает `http://127.0.0.1:8142`.

## Первоначальная настройка

При первом запуске откроется окно **Настройки**. Укажите:

- **Readeck URL** — адрес Readeck, например `http://192.168.1.10:8000`.
- **API Токен** — токен Readeck; приложение передаёт его в заголовке `Authorization: Bearer …`.
- **Ваш LAN IP** — IP машины с приложением, доступный для Readeck. Он используется в callback-ссылке с материалом.
- **Папка локальной библиотеки** — папка, в которой нужно искать файлы для чтения.
- **Язык интерфейса**.

Нажмите **Проверить подключение**, затем **Сохранить**. Настройки записываются в `config.json`.

## Работа с материалами

1. В основном окне вставьте текст, загрузите файл или введите URL статьи.
2. При необходимости выберите формат и переведите содержимое.
3. Заполните метаданные вручную либо используйте **Автозаполнение**.
4. Добавьте теги и нужные флаги Readeck.
5. Откройте предпросмотр и нажмите **Создать закладку**.

### Локальная библиотека

1. Откройте **Локальная библиотека** в шапке основного окна.
2. В отдельном окне появится список поддерживаемых файлов из выбранной папки и всех её подпапок.
3. Нажмите **Открыть**, чтобы перейти в режим чтения. Файлы не загружаются целиком на странице списка, поэтому библиотека остаётся отзывчивой и с крупными каталогами.
4. На странице чтения используйте **Отправить в Readeck**. Содержимое и заголовок будут переданы в главное окно приложения.
5. Проверьте метаданные и создайте закладку обычным способом.

Поддерживаются `.txt`, `.md`, `.markdown`, `.html` и `.htm`. Переход за пределы выбранной директории заблокирован.

## Тестирование

Регрессионные тесты не требуют сети или настоящего Readeck:

```bash
# Windows Git Bash / POSIX shell
PYTHONPATH= PYTHONHOME= .venv/Scripts/python.exe -m unittest tests.test_reader -v

# Windows cmd.exe
set PYTHONPATH=
set PYTHONHOME=
.venv\Scripts\python.exe -m unittest tests.test_reader -v
```

Проверяются настройки Локальной библиотеки, безопасное открытие файлов, передача текста в основное окно и наличие общей дизайн-системы интерфейса.

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

- `main.py` — FastAPI-бэкенд, API и встроенный интерфейс Vue 3 / Tailwind.
- `run.bat` — запуск приложения в Windows.
- `config.json` — локальные настройки подключения и Локальной библиотеки. **Не храните здесь рабочие токены в репозитории.**
- `lang/` — локализации интерфейса.
- `tests/test_reader.py` — автоматические тесты Локальной библиотеки и UI.
- `LOCALIZATION.md` — сведения о локализации.

## Локализация

Доступны:

- English
- Русский
- Қазақша

Чтобы добавить язык, создайте `lang/<код>.json`, скопируйте структуру `lang/en.json` или `lang/ru.json`, переведите значения без изменения ключей и перезапустите приложение.

Подробнее: `lang/README.md` и `LOCALIZATION.md`.

## Безопасность

- `config.json` содержит API-токен в открытом виде. Не публикуйте реальный токен и перевыпустите его при утечке.
- Сервис доступен в локальной сети на порту `8142`, без собственной аутентификации.
- Импорт по URL загружает произвольный адрес, то есть потенциально допускает SSRF. Не публикуйте приложение в интернете без ограничения доступа и дополнительной защиты.
- Readeck должен иметь возможность обратиться по callback-адресу к указанному LAN IP и порту `8142`.