# redmine-reporter

[![checks](https://git.akokos.ru/artem.kokos/redmine-reporter/actions/workflows/checks.yaml/badge.svg)](https://git.akokos.ru/artem.kokos/redmine-reporter/actions)

- [Возможности](#возможности)
- [Установка](#установка)
- [Быстрый старт](#быстрый-старт)
- [Документация](#документация)
- [Форматы вывода](#форматы-вывода)
- [Разработка](#разработка)
- [Безопасность](#безопасность)
- [Лицензия](#лицензия)

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`, переменные окружения, YAML-конфиг, по умолчанию — текущий месяц.
- `--commit`: сохранение отчёта в файл и фиксация периода в конфиге для следующего запуска.
- `--send`: отправка отчёта по email через SMTP (plain-text или HTML-письмо).
- YAML-конфиг с секретами через `${VAR}`; приоритет: CLI-флаги > env > .env > YAML > дефолты (нюанс с `--config` — см. docs/CONFIG.md).

## Установка

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

```bash
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 .
```

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

```bash
pip install -e ".[dev]"
```

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

```bash
# Сгенерировать конфиг ~/.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](docs/USER_GUIDE.md) — руководство пользователя: сценарии использования, справочник всех CLI-флагов, устранение неполадок.
- [docs/CONFIG.md](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 колонки остаются, но пустыми и без итогов; в остальных форматах — пустые значения.

## Разработка

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

```bash
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](LICENSE).