ca89832d74
- #23: add JSONFormatter and XLSXFormatter - add openpyxl dependency for .xlsx export - #22: add --summary flag and calculate_summary() in report_builder - ReportRow now carries raw hours for summary calculations - update CLI help and README with .json/.xlsx formats and --summary - add tests for new formatters and summary computation Closes #22, closes #23
210 lines
7.6 KiB
Markdown
210 lines
7.6 KiB
Markdown
# 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.
|