Tighten configuration and export handling
This commit is contained in:
Кокос Артем Николаевич
220
README.md
220
README.md
@@ -1,171 +1,151 @@
|
||||
# redmine-reporter
|
||||
|
||||
Инструмент для генерации отчётов по задачам в Redmine на основе ваших записей о затраченном времени.
|
||||
> Предназначен для внутреннего использования в Eltex. Работает с `https://red.eltex.loc/`.
|
||||
CLI-инструмент для генерации отчётов по задачам Redmine на основе записей о затраченном времени.
|
||||
|
||||
📄 **Лицензия**: [MIT](./LICENSE) — делайте что угодно.
|
||||
Проект предназначен для внутреннего использования с `https://red.eltex.loc/`.
|
||||
|
||||
---
|
||||
Лицензия: MIT.
|
||||
|
||||
## 🔧 Возможности
|
||||
## Возможности
|
||||
|
||||
- Безопасная передача учётных данных через переменные окружения или `.env`
|
||||
- Авторизация через Redmine API token или через логин/пароль для обратной совместимости
|
||||
- Группировка задач по проекту и версии
|
||||
- Поддержка нескольких форматов экспорта: **ODT**, **CSV**, **Markdown**, **HTML**
|
||||
- Два режима вывода в консоль: табличный (красивая таблица) и компактный (для копирования)
|
||||
- Перевод статусов задач на русский язык
|
||||
- Автоматическое определение месяца отчёта по дате окончания периода (для **ODT**)
|
||||
- Простой CLI с понятными аргументами
|
||||
- Поддержка настройки диапазона дат по умолчанию через `.env`
|
||||
- Получение time entries текущего пользователя из Redmine.
|
||||
- Авторизация через Redmine API token.
|
||||
- Резервная авторизация через логин и пароль для обратной совместимости.
|
||||
- Группировка задач по проекту и версии.
|
||||
- Перевод статусов задач на русский язык.
|
||||
- Вывод в консоль в табличном или компактном виде.
|
||||
- Экспорт в ODT, CSV, Markdown и HTML.
|
||||
- Автоматическое определение месяца ODT-отчёта по конечной дате периода.
|
||||
- Настройка периода отчёта по умолчанию через `.env`.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Установка и настройка
|
||||
|
||||
### 1. Клонируйте репозиторий
|
||||
## Установка
|
||||
|
||||
```bash
|
||||
git clone https://git.akokos.ru/artem.kokos/redmine-reporter.git
|
||||
cd redmine-reporter
|
||||
```
|
||||
|
||||
### 2. Создайте виртуальное окружение и установите зависимости
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install --upgrade pip
|
||||
pip install .
|
||||
```
|
||||
|
||||
> 💡 Установка в виртуальное окружение — стандарт для Python-инструментов. Это безопасно и не влияет на систему.
|
||||
## Настройка
|
||||
|
||||
### 3. Настройте доверие к корпоративному сертификату (обязательно!)
|
||||
Создайте файл `.env` в корне проекта. Файл не должен попадать в git.
|
||||
|
||||
По умолчанию Python использует собственный набор сертификатов (`certifi`), который **не включает** внутренние CA Eltex.
|
||||
Чтобы избежать ошибки `CERTIFICATE_VERIFY_FAILED`, выполните **один раз**:
|
||||
|
||||
```bash
|
||||
cat /etc/ssl/certs/ca-certificates.crt >> $(python -m certifi)
|
||||
```
|
||||
|
||||
> ✅ Это безопасно: вы просто добавляете доверенные системные сертификаты к Python.
|
||||
> ❌ Не используйте `verify=False` — это создаёт уязвимость.
|
||||
|
||||
### 4. Настройте учётные данные
|
||||
|
||||
Создайте файл `.env` в корне проекта (**никогда не коммитьте его!**):
|
||||
Рекомендуемый вариант авторизации:
|
||||
|
||||
```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` задан, он используется в первую очередь. Старый способ с логином и паролем остаётся доступен для обратной совместимости:
|
||||
Если задан `REDMINE_API_KEY`, он используется в первую очередь.
|
||||
|
||||
Резервный вариант авторизации:
|
||||
|
||||
```ini
|
||||
REDMINE_URL=https://red.eltex.loc/
|
||||
REDMINE_USER=ваш.логин
|
||||
REDMINE_PASSWORD=ваш_пароль
|
||||
REDMINE_AUTHOR=Иванов Иван Иванович
|
||||
```
|
||||
|
||||
Альтернатива — задать переменные вручную:
|
||||
|
||||
```bash
|
||||
export REDMINE_URL=https://red.eltex.loc/
|
||||
export REDMINE_API_KEY=...
|
||||
export REDMINE_AUTHOR="Иванов Иван Иванович"
|
||||
```
|
||||
|
||||
> 🔐 Рекомендуется использовать аккаунт с минимальными правами (только чтение time entries и задач).
|
||||
|
||||
---
|
||||
|
||||
## ▶️ Использование
|
||||
|
||||
Перед каждым запуском активируйте окружение:
|
||||
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
Затем:
|
||||
|
||||
```bash
|
||||
# Отчёт за период по умолчанию (из .env или встроенный)
|
||||
redmine-reporter
|
||||
|
||||
# Отчёт за произвольный период
|
||||
redmine-reporter --date 2026-02-01--2026-02-28
|
||||
|
||||
# Компактный вывод (удобно копировать в письмо)
|
||||
redmine-reporter --compact
|
||||
|
||||
# Экспорт в ODT
|
||||
redmine-reporter --output report.odt
|
||||
|
||||
# Экспорт в CSV
|
||||
redmine-reporter --output report.csv
|
||||
|
||||
# Экспорт в Markdown
|
||||
redmine-reporter --output report.md
|
||||
|
||||
# Экспорт в HTML
|
||||
redmine-reporter --output report.html
|
||||
```
|
||||
|
||||
> 💡 **Автоматика в ODT-отчёте**:
|
||||
> - Месяц в заголовке определяется **автоматически** по дате окончания периода (`to_date`).
|
||||
> Например: `2025-12-20--2026-01-15` → **«Январь»**.
|
||||
> - Имя автора берётся из `REDMINE_AUTHOR` (в `.env`) или CLI-аргумента `--author`.
|
||||
|
||||
Пример содержимого `.env`:
|
||||
|
||||
```ini
|
||||
REDMINE_URL=https://red.eltex.loc/
|
||||
REDMINE_API_KEY=supersecret_api_token
|
||||
REDMINE_AUTHOR=Иванов Иван
|
||||
|
||||
DEFAULT_FROM_DATE=2026-01-01
|
||||
DEFAULT_TO_DATE=2026-01-31
|
||||
```
|
||||
|
||||
Пример консольного вывода:
|
||||
Переменные окружения:
|
||||
|
||||
```
|
||||
✅ Total issues: 7 [2026-01-01--2026-01-31]
|
||||
╒════════════╤═══════════╤══════════════════════════════════════╤═══════════╤════════════╕
|
||||
│ Проект │ Версия │ Задача │ Статус │ Затрачено │
|
||||
╞════════════╪═══════════╪══════════════════════════════════════╪═══════════╪════════════╡
|
||||
│ Камеры │ v2.5.0 │ 12345. Поддержка нового датчика │ В работе │ 2ч 30м │
|
||||
│ │ │ 12346. Исправить утечку памяти │ Решена │ 2ч │
|
||||
│ ПО │ <N/A> │ 12350. Обновить документацию │ Ожидание │ 12ч │
|
||||
╘════════════╧═══════════╧══════════════════════════════════════╧═══════════╧════════════╛
|
||||
| Переменная | Обязательность | Описание |
|
||||
| --- | --- | --- |
|
||||
| `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
|
||||
```
|
||||
|
||||
---
|
||||
Отчёт за период по умолчанию:
|
||||
|
||||
## 🛠 Разработка
|
||||
```bash
|
||||
redmine-reporter
|
||||
```
|
||||
|
||||
Для участия в разработке:
|
||||
Отчёт за произвольный период:
|
||||
|
||||
```bash
|
||||
redmine-reporter --date 2026-02-01--2026-02-28
|
||||
```
|
||||
|
||||
Период должен быть задан в формате `YYYY-MM-DD--YYYY-MM-DD`. Начальная дата не может быть позже конечной.
|
||||
|
||||
Компактный вывод:
|
||||
|
||||
```bash
|
||||
redmine-reporter --compact
|
||||
```
|
||||
|
||||
Экспорт:
|
||||
|
||||
```bash
|
||||
redmine-reporter --output report.odt
|
||||
redmine-reporter --output report.csv
|
||||
redmine-reporter --output report.md
|
||||
redmine-reporter --output report.html
|
||||
```
|
||||
|
||||
ODT-отчёт:
|
||||
|
||||
- месяц в заголовке определяется по `to_date`;
|
||||
- имя автора берётся из `--author`, затем из `REDMINE_AUTHOR`;
|
||||
- если автор не задан, поле автора остаётся пустым.
|
||||
|
||||
Вывод без затраченного времени:
|
||||
|
||||
```bash
|
||||
redmine-reporter --no-time
|
||||
```
|
||||
|
||||
## Разработка
|
||||
|
||||
Установка зависимостей для разработки:
|
||||
|
||||
```bash
|
||||
pip install -e ".[dev]"
|
||||
pytest
|
||||
black .
|
||||
isort .
|
||||
```
|
||||
|
||||
---
|
||||
Проверки:
|
||||
|
||||
> 🔒 **Важно**:
|
||||
> - Никогда не коммитьте `.env`, API token, пароли или логины.
|
||||
> - Файл `.gitignore` уже исключает все чувствительные артефакты.
|
||||
> - Инструмент работает только в режиме **чтения** — он не может изменять данные в Redmine.
|
||||
```bash
|
||||
pytest
|
||||
ruff check redmine_reporter tests
|
||||
black redmine_reporter tests
|
||||
isort redmine_reporter tests
|
||||
```
|
||||
|
||||
## Безопасность
|
||||
|
||||
- Не коммитьте `.env`, API token, пароль или логин.
|
||||
- Используйте аккаунт с минимальными правами, достаточными для чтения time entries и задач.
|
||||
- Инструмент работает только в режиме чтения и не изменяет данные в Redmine.
|
||||
|
||||
Reference in New Issue
Block a user