# redmine-reporter

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

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

Лицензия: MIT.

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

- Получение time entries **текущего** или **указанного** пользователя из Redmine.
- Авторизация через Redmine API token или логин/пароль.
- Группировка задач по проекту и версии.
- Перевод статусов задач на русский язык.
- Вывод в консоль (таблица / компактный вид).
- Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx).
- Excel-отчёт с merge-ячейками по проекту/версии, итогами, автошириной, автофильтром и закреплённой шапкой.
- Сводка по времени (`--summary`).
- Понятные сообщения об ошибках Redmine API (401/403/5xx, таймаут, сеть).
- Загрузка альтернативного `.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 .
```

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

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

## Настройка

Создайте файл `.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
```

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

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

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

| Переменная | Обязательность | Описание |
| --- | --- | --- |
| `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-проверка: `true` / `false` / путь к CA bundle. |

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

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

Отчёт за период по умолчанию:

```bash
redmine-reporter
```

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

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

Отчёт по другому пользователю:

```bash
redmine-reporter --user-id 42
redmine-reporter --user-login ivanov
redmine-reporter --user-name "Иванов И.И."
```

`--user-name` требует точного совпадения; если найдено несколько пользователей, CLI сообщает об ошибке и просит использовать `--user-id`.

Переопределить 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 --debug
```

Экспорт:

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

Отчёт без затраченного времени (работает для всех форматов):

```bash
redmine-reporter --no-time
redmine-reporter --no-time --output report.xlsx
```

Сводка по времени:

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

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

| Формат | Особенности |
| --- | --- |
| **ODT** | Заголовок с автором и месяцем, группировка по проекту/версии. |
| **CSV** | UTF-8 с BOM, полные значения `project`/`version` в каждой строке. |
| **Markdown** | Компактная таблица, повторяющиеся группы скрыты. |
| **HTML** | Полноценный HTML-документ с `meta charset="utf-8"`. |
| **JSON** | Массив объектов: `project`, `version`, `issue_id`, `subject`, `status`, `time`. |
| **Excel (.xlsx)** | Merge cells, колонки `Hours`/`Spent Time`, итоги, автоширина, автофильтр, freeze panes. |

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

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

```bash
pytest
ruff check redmine_reporter tests
black --check redmine_reporter tests
isort --check-only redmine_reporter tests
mypy redmine_reporter
```

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

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