wip7

2026-07-13 12:28:59 +08:00
parent 6c3de4b2ef
commit f0fe5409fa
1409 changed files with 11369 additions and 413 deletions
@@ -0,0 +1,206 @@
+# Инструкции для работы с репозиторием
+
+## Обзор проекта
+
+`iptvc` (IPTV Checker) — консольное приложение на Go для проверки IPTV-плейлистов в форматах M3U/M3U8. Программа умеет загружать плейлисты из локальных файлов, по URL и из ini-файла, проверять доступность плейлистов и отдельных каналов, выводить результаты в журнале или JSON, а также запускать встроенный веб-интерфейс.
+
+Проект является частью экосистемы `m3u.su`. Исходный код размещается на Gitea: `https://git.axenov.dev/IPTV/iptvc`.
+
+Основные технологии:
+
+- Go 1.23.6 или новее согласно `go.mod` и README.
+- Cobra для CLI-команд и флагов.
+- YAML для конфигурации.
+- INI для списка плейлистов.
+- Redis/KeyDB через `github.com/redis/go-redis/v9` для кеширования результатов.
+- `godotenv` для автоматической загрузки `.env`.
+- Docker и Docker Compose для контейнерного запуска.
+- Встроенный HTTP-веб-сервер для просмотра плейлистов и результатов проверки.
+
+## Структура репозитория
+
+- `main.go` — минимальная точка входа, передающая управление в пакет `cmd`.
+- `cmd/` — CLI-слой на Cobra: корневая команда, команды `check` и `serve`, флаги, версия и тесты флагов.
+- `app/` — прикладная логика приложения.
+- `app/checker/` — подготовка и проверка плейлистов и каналов.
+- `app/cache/` — абстракции и работа с кешем.
+- `app/config/` — структуры конфигурации, значения по умолчанию, YAML и переменные окружения.
+- `app/inifile/` — чтение ini-файлов со списками плейлистов.
+- `app/playlist/` — модели и обработка IPTV-плейлистов.
+- `app/tagfile/` — чтение файла тегов каналов.
+- `app/web/` — веб-сервер, маршруты и отображение данных.
+- `app/logger/` — настройка журналирования.
+- `app/utils/` — вспомогательные функции.
+- `cmd/keydb/` — вспомогательные материалы для KeyDB, если используются соответствующие компоненты.
+- `docker/keydb/` — конфигурация и entrypoint для контейнера KeyDB.
+- `channels.json` — пример или локальный файл тегов каналов.
+- `config.yml.example` — пример конфигурации приложения.
+- `.env.example` — пример переменных окружения.
+- `compose.yml` — окружение из приложения, документации и KeyDB.
+- `Dockerfile` — многоэтапная сборка бинарного файла и минимального Alpine-образа.
+- `Makefile` — очистка, кросс-компиляция и сборка релизных архивов.
+- `README.md` — пользовательская документация, команды запуска, конфигурация и API-маршруты.
+- `LICENSE` — лицензия MIT.
+
+## Архитектура и поток выполнения
+
+1. `main.go` вызывает `cmd.Execute()`.
+2. `cmd/root.go` регистрирует глобальные флаги и дочерние Cobra-команды.
+3. Команда `check` инициализирует приложение, применяет CLI-переопределения, подключает кеш, получает плейлисты и запускает проверку.
+4. Команда `serve` поднимает веб-сервер и при необходимости запускает фоновую проверку через флаг `--check` или настройку `check.start-on-serve`.
+5. Конфигурация загружается со следующим приоритетом: встроенные значения по умолчанию, `config.yml`, переменные окружения и явно переданные CLI-флаги.
+6. Результаты проверки могут сохраняться в KeyDB/Redis и отображаться веб-сервером. При недоступном кеше веб-интерфейс показывает неизвестный статус.
+
+Не следует помещать бизнес-логику в `main.go` или CLI-команды, если её можно разместить в соответствующем пакете `app/`. CLI-слой должен отвечать за разбор аргументов, инициализацию и координацию прикладных компонентов.
+
+## Сборка и запуск
+
+Для локальной разработки требуется Go версии 1.23.6 или новее. В `Dockerfile` используется `golang:1.25-alpine`, поэтому контейнерная сборка ориентируется на Go 1.25.
+
+Основные команды:
+
+```bash
+# Показать доступные цели Makefile
+make help
+
+# Быстро запустить приложение из исходников
+go run .
+
+# Запустить CLI-справку
+go run . help
+
+# Проверить локальный плейлист
+go run . check -f mypls.m3u
+
+# Проверить плейлист по URL
+go run . check -u https://example.com/playlist.m3u
+
+# Запустить веб-интерфейс на порту 8800
+go run . serve -p 8800
+
+# Запустить веб-интерфейс с фоновой проверкой
+go run . serve -i playlists.ini -p 8800 --check
+
+# Собрать текущую платформу
+go build -o iptvc .
+
+# Запустить тесты всех пакетов
+go test ./...
+
+# Проверить форматирование
+
+gofmt -w .
+```
+
+В блоке выше команда форматирования приведена как ориентир: `gofmt` следует запускать по Go-файлам, например `gofmt -w main.go cmd app`, если оболочка или используемая версия инструмента не поддерживает обработку директорий так, как ожидается.
+
+Цели Makefile:
+
+- `make clear` — удалить результаты сборки и очистить кеш Go.
+- `make linux GOARCH=amd64` — собрать Linux-бинарный файл и ZIP-архив.
+- `make win GOARCH=amd64` — собрать Windows-бинарный файл и ZIP-архив.
+- `make darwin GOARCH=amd64` — собрать macOS-бинарный файл и ZIP-архив.
+- `make release` — собрать архивы для Linux, Windows и macOS под `amd64` и `arm64`.
+
+Перед запуском приложения для конфигурации обычно следует скопировать `.env.example` в `.env`, а `config.yml.example` — в `config.yml`, после чего адаптировать значения под окружение. Не добавляйте реальные пароли, токены или локальные URL в Git.
+
+## Docker
+
+Для контейнерного окружения используется файл `compose.yml`, а не устаревшее имя `docker-compose.yml`.
+
+Ожидаемые локальные файлы для сервиса `iptvc`:
+
+- `playlists.ini` монтируется в `/app/playlists.ini`.
+- `channels.json` монтируется в `/app/channels.json`.
+- `config.yml` монтируется в `/app/config.yml`.
+- `.env` передаётся через `env_file`.
+
+Основные команды:
+
+```bash
+# Собрать и запустить сервисы в фоне
+docker compose up -d --build
+
+# Посмотреть логи приложения
+docker compose logs -f iptvc
+
+# Остановить окружение
+docker compose down
+```
+
+В compose-окружение входят:
+
+- `iptvc` — веб-интерфейс и фоновая проверка плейлистов.
+- `keydb` — хранилище результатов проверки.
+- `docs` — отдельный сервис документации, если его контекст доступен в окружении.
+
+Обратите внимание: текущий `compose.yml` ссылается на контексты `./iptvc` и `./docs`, поэтому запуск из каталога, содержащего только этот репозиторий, может потребовать внешней структуры проекта или корректировки контекстов.
+
+## Конфигурация
+
+Поддерживаются `config.yml`, `.env` и CLI-флаги. CLI-флаги имеют наивысший приоритет только при явной передаче.
+
+Ключевые группы настроек:
+
+- `app` — часовой пояс, режим отладки, уровень журнала и пути к `playlists.ini` и `channels.json`.
+- `server`/`site` — адрес и порт веб-сервера, базовый URL, размер страницы, ссылки сайта и заголовок.
+- `check.playlists` — User-Agent, тайм-ауты, задержки и параллелизм проверки плейлистов.
+- `check.channels` — User-Agent, тайм-аут, размер диапазона байтов, задержки и параллелизм проверки каналов.
+- `cache` — включение KeyDB/Redis, адрес подключения, база и TTL.
+
+Значения задержек и некоторых параметров могут задаваться как числом или диапазоном `[min, max]`. User-Agent может быть строкой или массивом строк; при массиве выбирается случайное значение.
+
+Веб-команда поддерживает как минимум следующие сценарии:
+
+```bash
+# Сервер без фоновой проверки
+./iptvc serve -i playlists.ini -p 8800
+
+# Сервер с бесконечной фоновой проверкой каждые 60 секунд
+./iptvc serve --check --repeat 0 --playlists-all-cooldown 60
+```
+
+Основные HTTP-маршруты описаны в README: `/`, `/page/{N}`, `/{code}`, `/{code}/details`, `/api/playlists/{code}`, `/api/version`, `/api/health` и `/api/stats`.
+
+## Тестирование
+
+Тесты находятся рядом с тестируемым кодом и используют стандартный пакет `testing`. Сейчас явно присутствуют тесты CLI-флагов в `cmd/flags_test.go`; они проверяют применение переопределений приложения, кеша и параметров проверки.
+
+Перед изменением CLI или конфигурации запускайте:
+
+```bash
+go test ./...
+go vet ./...
+```
+
+При обновлении конфигурационных структур синхронно проверяйте `config.yml.example`, `.env.example`, `README.md` и документацию в `docs/content/common/config/config.md`, `docs/content/iptvc/commands/check.md`, `docs/content/iptvc/commands/serve.md` и связанных страницах.
+
+При добавлении флага желательно добавить тесты на:
+
+- значение по умолчанию без флага;
+- явное включение и выключение boolean-флага;
+- переопределение значения из конфигурации;
+- корректный разбор чисел, диапазонов и списков;
+- взаимодействие с приоритетом `config.yml`, окружения и CLI.
+
+Отдельных интеграционных тестов веб-сервера, KeyDB и сетевой проверки плейлистов в просмотренных файлах не обнаружено. Такие тесты требуют изолированных фикстур и не должны зависеть от случайных внешних IPTV-ресурсов.
+
+## Стиль разработки
+
+- Соблюдайте стандартный стиль Go и форматируйте изменённые Go-файлы через `gofmt`.
+- Используйте имена пакетов и экспортируемых сущностей в соответствии с идиомами Go.
+- Сохраняйте существующие заголовки лицензии в файлах, где они уже присутствуют.
+- Комментарии к экспортируемым типам и функциям должны объяснять их назначение.
+- Не добавляйте секреты, реальные данные доступа к KeyDB/Redis и рабочие плейлисты в репозиторий.
+- Для ошибок и сетевых операций сохраняйте существующую практику явной обработки ошибок и логирования.
+- Не меняйте формат CLI, конфигурации или API-маршрутов без обновления README и соответствующих тестов.
+- При работе с конфигурацией учитывайте различие между отсутствующим CLI-флагом и флагом, переданным явно: в `cmd/serve.go` это используется для корректного переопределения порта и хоста.
+- Избегайте сетевых запросов и зависимости от внешних сервисов в модульных тестах.
+
+## Важные ограничения и наблюдения
+
+- `channels.json`, `playlists.ini`, `config.yml` и `.env` могут быть локальными входными данными; проверяйте их наличие перед запуском сценариев из документации.
+- Кеш по умолчанию отключён в конфигурации приложения, но compose-окружение запускает KeyDB и передаёт настройки через `.env`.
+- Бинарные файлы и архивы сборки создаются в `bin/` и не должны вручную добавляться в исходный код.
+- README указывает минимальную версию Go 1.23.6, а Dockerfile собирает проект на Go 1.25; при изменении зависимостей учитывайте обе среды.
+- При обновлении конфигурационных структур синхронно проверяйте `config.yml.example`, `.env.example`, README и тесты CLI-флагов.