redmine-reporter/README.md

redmine-reporter

• Возможности
• Установка
• Быстрый старт
• Документация
• Форматы вывода
• Разработка
• Безопасность
• Лицензия

CLI-инструмент для генерации отчётов по задачам Redmine на основе записей о затраченном времени. Читает time entries текущего или указанного пользователя, группирует задачи по проекту и версии, выводит отчёт в консоль или экспортирует в файл. Предназначен для внутреннего использования с https://red.eltex.loc/.

Возможности

• Отчёт по time entries текущего или указанного пользователя (--user-id, --user-login, --user-name).
• Группировка задач по проекту и версии, перевод статусов на русский язык.
• Вывод в консоль (таблица или компактный вид) и экспорт в ODT, CSV, Markdown, HTML, JSON, XLSX.
• Разбивка времени по типам активности (--by-activity), сводка (--summary), скрытие времени (--no-time).
• Гибкий выбор периода: --date, env FROM_DATE, YAML period.from, по умолчанию — текущий месяц.
• --commit: сохранение отчёта в файл и авто-сдвиг начала периода в конфиге для следующего запуска.
• --send: отправка отчёта по email через SMTP (plain-text или HTML-письмо) с авто-сдвигом начала периода при успешной отправке.
• YAML-конфиг с секретами через ${VAR}; приоритет: CLI-флаги > env > .env > YAML > дефолты (нюанс с --config — см. docs/CONFIG.md).

Установка

Требуется Python >= 3.10.

git clone https://git.akokos.ru/artem.kokos/redmine-reporter.git
cd redmine-reporter
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install .

Для разработки:

pip install -e ".[dev]"

Быстрый старт

# Сгенерировать конфиг ~/.config/redmine-reporter/config.yml
redmine-reporter --init-config

# Заполнить redmine.url, redmine.api_key (или ${REDMINE_API_KEY}), redmine.author
vim ~/.config/redmine-reporter/config.yml

# Отчёт за текущий месяц в консоль
redmine-reporter

# Сохранить в файл и сдвинуть начало периода для следующего запуска
redmine-reporter --commit

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

• docs/USER_GUIDE.md — руководство пользователя: сценарии использования, справочник всех CLI-флагов, устранение неполадок.
• docs/CONFIG.md — справочник конфигурации: YAML-структура, переменные окружения, приоритеты, безопасность.

Форматы вывода

Формат	Особенности
Консоль	Таблица или компактный вид (--compact).
ODT	Требуется odfpy; формирование по шаблону.
CSV	UTF-8 с BOM; полные значения project/version в каждой строке.
Markdown	Компактная таблица.
HTML	Полный HTML-документ; объединение ячеек групп через rowspan.
JSON	Объекты project, version, issue_id, subject, status, time + опционально activities.
XLSX	Объединение ячеек по проекту/версии, итоги, автоширина (максимум 80), автофильтр, freeze panes.

Нюанс --no-time: физически удаляет колонку времени только CSV; в XLSX колонки остаются, но пустыми и без итогов; в остальных форматах — пустые значения.

Разработка

Проверки перед коммитом:

pytest
isort --check-only redmine_reporter tests
black --check redmine_reporter tests
ruff check redmine_reporter tests
ruff format --check redmine_reporter tests
mypy redmine_reporter

CI — Gitea Actions (.gitea/workflows/checks.yaml): все шесть проверок на матрице Python 3.10–3.13.

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

• REDMINE_URL обязан использовать HTTPS: валидация отклоняет остальное, API-ключ передаётся в заголовках.
• verify_ssl / REDMINE_VERIFY: true (по умолчанию — проверка по системному хранилищу CA операционной системы через truststore, корпоративные CA из ОС работают), false (предупреждение о MITM-риске при старте) или путь к CA-bundle.
• Конфиг создаётся с правами 0600, директория — 0700; при более широких правах выводится предупреждение.
• Секреты храните через ${VAR} в YAML или в переменных окружения, не в открытом виде.
• Инструмент только читает данные из Redmine и ничего в нём не изменяет.

Лицензия

MIT, см. LICENSE.