feat: add local library and refresh interface

README.md

@@ -1,83 +1,124 @@
-# Readeck Local Importer
+# Readeck Importer
 
-Локальный веб-сервис для импорта статей в [Readeck](https://readeck.org/) (self-hosted сервис «прочитать позже»). Позволяет загрузить текст, файл или статью по ссылке, перевести её, отредактировать метаданные и одной кнопкой создать закладку в Readeck.
+Локальное веб-приложение для добавления статей и файлов в [Readeck](https://readeck.org/) — self-hosted сервис «прочитать позже».
 
-Readeck умеет сохранять закладки только по URL, поэтому приложение поднимает временную ссылку на ваш контент в локальной сети и передаёт её Readeck — так локальный текст попадает в библиотеку как обычная статья.
+Readeck импортирует материалы по URL. Приложение подготавливает контент, временно публикует его по доступному в локальной сети адресу и создаёт закладку через Readeck API. Поэтому в библиотеку можно отправлять и локальные файлы.
 
 ## Возможности
 
-- **Импорт по ссылке** — скачивает страницу и извлекает чистый текст статьи (`trafilatura`).
-- **Загрузка файлов** `.txt`, `.html`, `.md` (+ drag & drop), автоопределение кодировки.
-- **Форматы контента** — HTML, Markdown, простой текст.
-- **Перевод** через Google (22 языка) с учётом лимитов на длину запроса.
-- **Автозаполнение метаданных** из HTML-метатегов (заголовок, автор, описание, дата, сайт).
-- **Предпросмотр** статьи ровно в том виде, в каком её увидит Readeck.
-- **Санитизация HTML** перед публикацией (`bleach`).
-- **Тест подключения** к Readeck прямо из настроек.
-- **Локализация интерфейса** — поддержка нескольких языков с возможностью добавления новых.
-- Тёмная тема, счётчик символов/слов, автосохранение черновика.
+- Импорт статьи по URL с извлечением основного содержания (`trafilatura`).
+- Загрузка файлов `.txt`, `.html`, `.htm`, `.md`, `.markdown`, включая drag & drop.
+- Автоопределение UTF-8 и Windows-1251 для локальных файлов.
+- Форматы содержимого: HTML, Markdown и простой текст.
+- Перевод через Google Translate с разбиением длинного текста на безопасные части.
+- Автозаполнение метаданных: заголовок, автор, описание, дата и сайт.
+- Предпросмотр итоговой статьи перед отправкой.
+- Санитизация HTML перед публикацией (`bleach`).
+- Проверка соединения с Readeck в настройках.
+- Локальная библиотека: отдельное окно для просмотра файлов из выбранной папки.
+- Отправка открытого в Локальной библиотеке файла в основное окно для последующей отправки в Readeck.
+- Светлая и тёмная темы, автосохранение черновика, счётчики символов и слов.
+- Интерфейс на русском, английском и казахском языках.
 
 ## Требования
 
-- Python 3.9+
-- Доступный сервер Readeck и API-токен к нему
+- Python 3.9+ (проект проверялся на Python 3.12).
+- Доступный сервер Readeck и API-токен.
+- Сетевой доступ Readeck к машине с этим приложением, если Readeck расположен на другом хосте.
 
 ## Установка
 
-```bash
-pip install fastapi uvicorn pydantic beautifulsoup4 lxml httpx deep-translator markdown bleach trafilatura
+### 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
 ```
 
-Сервер стартует на `http://0.0.0.0:8142`, браузер откроется автоматически на `http://127.0.0.1:8142`.
+Сервис слушает `0.0.0.0:8142`, а браузер автоматически открывает `http://127.0.0.1:8142`.
 
-При первом запуске откроется окно настроек — укажите:
+## Первоначальная настройка
 
-- **Readeck URL** — адрес вашего сервера Readeck (например `http://192.168.1.10:8000`)
-- **API Токен** — токен из настроек Readeck (`Bearer`)
-- **LAN IP** — IP этой машины в локальной сети (для callback-ссылки, по которой Readeck заберёт контент)
+При первом запуске откроется окно **Настройки**. Укажите:
 
-Нажмите «Проверить подключение», чтобы убедиться, что сервер и токен валидны, затем сохраните. Настройки записываются в `config.json`.
+- **Readeck URL** — адрес Readeck, например `http://192.168.1.10:8000`.
+- **API Токен** — токен Readeck; приложение передаёт его в заголовке `Authorization: Bearer …`.
+- **Ваш LAN IP** — IP машины с приложением, доступный для Readeck. Он используется в callback-ссылке с материалом.
+- **Папка локальной библиотеки** — папка, в которой нужно искать файлы для чтения.
+- **Язык интерфейса**.
 
-## Использование
+Нажмите **Проверить подключение**, затем **Сохранить**. Настройки записываются в `config.json`.
 
-1. Вставьте текст, загрузите/перетащите файл или импортируйте статью по ссылке.
-2. При необходимости переведите контент и выберите его формат.
-3. Заполните или автозаполните метаданные, добавьте теги.
-4. Посмотрите предпросмотр и нажмите «Создать закладку».
+## Работа с материалами
 
-## Файлы
+1. В основном окне вставьте текст, загрузите файл или введите URL статьи.
+2. При необходимости выберите формат и переведите содержимое.
+3. Заполните метаданные вручную либо используйте **Автозаполнение**.
+4. Добавьте теги и нужные флаги Readeck.
+5. Откройте предпросмотр и нажмите **Создать закладку**.
 
-- `main.py` — всё приложение (бэкенд FastAPI + фронтенд на Vue 3 / Tailwind).
-- `config.json` — настройки подключения к Readeck и выбранный язык интерфейса.
-- `lang/` — папка с файлами локализации интерфейса.
+### Локальная библиотека
+
+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
-- 🇷🇺 Русский
-- 🇰🇿 Қазақша (Казахский)
+Доступны:
 
-### Смена языка
-1. Откройте настройки (⚙️)
-2. Выберите язык в списке "🌍 Язык интерфейса"
-3. Язык изменится мгновенно
+- English
+- Русский
+- Қазақша
 
-### Добавление нового языка
-1. Создайте файл `lang/код_языка.json` (например, `de.json`)
-2. Скопируйте структуру из `lang/en.json` или `lang/ru.json`
-3. Переведите все значения (не меняя ключи)
-4. Перезапустите приложение — новый язык появится автоматически!
+Чтобы добавить язык, создайте `lang/<код>.json`, скопируйте структуру `lang/en.json` или `lang/ru.json`, переведите значения без изменения ключей и перезапустите приложение.
 
-Подробнее см. `lang/README.md` и `LOCALIZATION.md`.
+Подробнее: `lang/README.md` и `LOCALIZATION.md`.
 
-## Примечания по безопасности
+## Безопасность
 
-- `config.json` хранит API-токен в открытом виде. Не коммитьте файл в git; при необходимости перевыпустите токен.
-- Сервис слушает `0.0.0.0:8142` **без аутентификации** и доступен всем в локальной сети. Эндпоинт импорта по URL скачивает произвольные адреса (потенциальный SSRF). Для домашней сети это обычно приемлемо; не выставляйте сервис в интернет без авторизации.
+- `config.json` содержит API-токен в открытом виде. Не публикуйте реальный токен и перевыпустите его при утечке.
+- Сервис доступен в локальной сети на порту `8142`, без собственной аутентификации.
+- Импорт по URL загружает произвольный адрес, то есть потенциально допускает SSRF. Не публикуйте приложение в интернете без ограничения доступа и дополнительной защиты.
+- Readeck должен иметь возможность обратиться по callback-адресу к указанному LAN IP и порту `8142`.