67b5d093d9
- Remove duplicated --config bullet. - Update Excel section to reflect production-grade XLSX features. - Add --no-time note for file formats. - Add readable API error messaging to feature list. - Fix development commands: use --check flags and add mypy. - Replace verbose per-format sections with a summary table. - Bump pyproject.toml version to 1.6.1.
170 lines
5.5 KiB
Markdown
170 lines
5.5 KiB
Markdown
# 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
|
||
```
|
||
|
||
Переопределить 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.
|