# redmine-reporter

CLI-инструмент для генерации отчётов по задачам Redmine на основе записей о затраченном времени.

Проект предназначен для внутреннего использования с `https://red.eltex.loc/`.

Лицензия: MIT.

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

- Получение time entries текущего пользователя из Redmine.
- Авторизация через Redmine API token.
- Резервная авторизация через логин и пароль для обратной совместимости.
- Группировка задач по проекту и версии.
- Перевод статусов задач на русский язык.
- Вывод в консоль в табличном или компактном виде.
- Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx).
- Сводка по затраченному времени (итоги и разбивка по проектам/версиям).
- Автоматическое определение месяца ODT-отчёта по конечной дате периода.
- Настройка периода отчёта по умолчанию через `.env` (или автоматически — текущий месяц).
- Переопределение URL и API-ключа через CLI.
- Загрузка альтернативного `.env` через `--config`.
- Загрузка альтернативного `.env` через `--config`.

## Установка

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

## Настройка

Создайте файл `.env` в корне проекта. Файл не должен попадать в git.

Рекомендуемый вариант авторизации:

```ini
REDMINE_URL=https://red.eltex.loc/
REDMINE_API_KEY=ваш_api_token
REDMINE_AUTHOR=Иванов Иван Иванович

DEFAULT_FROM_DATE=2026-01-01
DEFAULT_TO_DATE=2026-01-31
```

Если задан `REDMINE_API_KEY`, он используется в первую очередь. Значения из `.env` можно переопределить через CLI: `--url`, `--api-key`, `--author`, а также загрузить другой файл конфигурации через `--config`.

Резервный вариант авторизации:

```ini
REDMINE_URL=https://red.eltex.loc/
REDMINE_USER=ваш.логин
REDMINE_PASSWORD=ваш_пароль
REDMINE_AUTHOR=Иванов Иван Иванович

DEFAULT_FROM_DATE=2026-01-01
DEFAULT_TO_DATE=2026-01-31
```

Переменные окружения:

| Переменная | Обязательность | Описание |
| --- | --- | --- |
| `REDMINE_URL` | Да | URL Redmine. |
| `REDMINE_API_KEY` | Да, если нет логина и пароля | Redmine API token. |
| `REDMINE_USER` | Да, если нет токена | Логин Redmine. |
| `REDMINE_PASSWORD` | Да, если нет токена | Пароль Redmine. |
| `REDMINE_AUTHOR` | Нет | Имя автора для ODT-отчёта. |
| `DEFAULT_FROM_DATE` | Нет | Начальная дата периода по умолчанию в формате `YYYY-MM-DD`. |
| `DEFAULT_TO_DATE` | Нет | Конечная дата периода по умолчанию в формате `YYYY-MM-DD`. |
| `REDMINE_VERIFY` | Нет | Настройка TLS-проверки для Redmine API. |

`REDMINE_VERIFY` поддерживает значения:

- пустое значение или отсутствие переменной: `/etc/ssl/certs/ca-certificates.crt`;
- `true`, `1`, `yes`, `on`: стандартная проверка сертификатов `requests`;
- `false`, `0`, `no`, `off`: отключить проверку сертификатов;
- любой другой текст: путь к CA bundle.

Отключать проверку сертификатов не рекомендуется.

## Использование

```bash
source .venv/bin/activate
```

Отчёт за период по умолчанию (текущий месяц или из `.env`):

```bash
redmine-reporter
```

Отчёт за произвольный период:

```bash
redmine-reporter --date 2026-02-01--2026-02-28
```

Период должен быть задан в формате `YYYY-MM-DD--YYYY-MM-DD`. Начальная дата не может быть позже конечной.

Переопределение URL и API-ключа из `.env`:

```bash
redmine-reporter --url https://red.example.com --api-key ваш_токен
```

Использование альтернативного конфигурационного файла:

```bash
redmine-reporter --config /path/to/.env
```

Компактный вывод:

```bash
redmine-reporter --compact
```

Подробный или отладочный вывод:

```bash
redmine-reporter --verbose
redmine-reporter --debug
```

Вывод версии:

```bash
redmine-reporter --version
```

Экспорт:

```bash
redmine-reporter --output report.odt
redmine-reporter --output report.csv
redmine-reporter --output report.md
redmine-reporter --output report.html
redmine-reporter --output report.json
redmine-reporter --output report.xlsx
```

JSON-отчёт:

- массив объектов с полями `project`, `version`, `issue_id`, `subject`, `status`, `time`;
- UTF-8, читаемый машиной.

Excel-отчёт (.xlsx):

- одна таблица с заголовками и строками данных;
- шапка выделена жирным;
- каждая строка содержит полные значения проекта и версии.

CSV-отчёт:

- файл сохраняется в UTF-8 с BOM (`utf-8-sig`) для корректного отображения кириллицы в Microsoft Excel;
- каждая строка содержит полные значения проекта и версии (в отличие от консольного и Markdown-вывода, где повторяющиеся значения скрыты для компактности).

HTML-отчёт:

- полноценный HTML-документ с `<meta charset="utf-8">`;
- корректно отображается в браузере и почтовых клиентах.

ODT-отчёт:

- месяц в заголовке определяется по `to_date`;
- имя автора берётся из `--author`, затем из `REDMINE_AUTHOR`;
- если автор не задан, поле автора остаётся пустым.

Вывод без затраченного времени:

```bash
redmine-reporter --no-time
```

Сводка по времени (итоги и разбивка по проектам):

```bash
redmine-reporter --summary
```

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

Установка зависимостей для разработки:

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

Проверки:

```bash
pytest
ruff check redmine_reporter tests
black redmine_reporter tests
isort redmine_reporter tests
```

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

- Не коммитьте `.env`, API token, пароль или логин.
- Используйте аккаунт с минимальными правами, достаточными для чтения time entries и задач.
- Инструмент работает только в режиме чтения и не изменяет данные в Redmine.