f00c6705ba
Tasks in the "Wishlist" bucket version are now excluded from the list and summary entirely (no due date, noise backlog); exact case match, tasks without a version are unaffected. Document --my-tasks in README and the user guide (sorting, summary metrics, OSC 8 links, stream separation); all examples use synthetic data. Declare ruff known-first-party in pyproject so the lint result is CWD-independent.
111 lines
6.6 KiB
Markdown
111 lines
6.6 KiB
Markdown
# redmine-reporter
|
||
|
||
[](https://git.akokos.ru/artem.kokos/redmine-reporter/actions)
|
||
|
||
- [Возможности](#возможности)
|
||
- [Установка](#установка)
|
||
- [Быстрый старт](#быстрый-старт)
|
||
- [Документация](#документация)
|
||
- [Форматы вывода](#форматы-вывода)
|
||
- [Разработка](#разработка)
|
||
- [Безопасность](#безопасность)
|
||
- [Лицензия](#лицензия)
|
||
|
||
CLI-инструмент для генерации отчётов по задачам Redmine на основе записей о затраченном времени. Читает time entries текущего или указанного пользователя, группирует задачи по проекту и версии, выводит отчёт в консоль или экспортирует в файл. Предназначен для внутреннего использования с `https://red.eltex.loc/`.
|
||
|
||
## Возможности
|
||
|
||
- Отчёт по time entries текущего или указанного пользователя (`--user-id`, `--user-login`, `--user-name`).
|
||
- Группировка задач по проекту и версии, перевод статусов на русский язык.
|
||
- Вывод в консоль (таблица или компактный вид) и экспорт в ODT, CSV, Markdown, HTML, JSON, XLSX.
|
||
- Разбивка времени по типам активности (`--by-activity`), сводка (`--summary`), скрытие времени (`--no-time`).
|
||
- Гибкий выбор периода: `--date`, env `FROM_DATE`, YAML `period.from`, по умолчанию — текущий месяц.
|
||
- `--commit`: сохранение отчёта в файл и авто-сдвиг начала периода в конфиге для следующего запуска.
|
||
- `--send`: отправка отчёта по email через SMTP (plain-text или HTML-письмо) с авто-сдвигом начала периода при успешной отправке.
|
||
- `--my-tasks`: список назначенных вам открытых задач -- таблица с сортировкой по срочности (приоритет, срок версии) и сводкой; см. [руководство](docs/USER_GUIDE.md#список-открытых-задач).
|
||
- YAML-конфиг с секретами через `${VAR}`; приоритет: CLI-флаги > env > .env > YAML > дефолты (нюанс с `--config` — см. docs/CONFIG.md).
|
||
|
||
## Установка
|
||
|
||
Требуется Python >= 3.10.
|
||
|
||
```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]"
|
||
```
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
# Сгенерировать конфиг ~/.config/redmine-reporter/config.yml
|
||
redmine-reporter --init-config
|
||
|
||
# Заполнить redmine.url, redmine.api_key (или ${REDMINE_API_KEY}), redmine.author
|
||
vim ~/.config/redmine-reporter/config.yml
|
||
|
||
# Отчёт за текущий месяц в консоль
|
||
redmine-reporter
|
||
|
||
# Сохранить в файл и сдвинуть начало периода для следующего запуска
|
||
redmine-reporter --commit
|
||
|
||
# Список ваших открытых задач (сортировка по срочности)
|
||
redmine-reporter --my-tasks
|
||
```
|
||
|
||
## Документация
|
||
|
||
- [docs/USER_GUIDE.md](docs/USER_GUIDE.md) — руководство пользователя: сценарии использования, справочник всех CLI-флагов, устранение неполадок.
|
||
- [docs/CONFIG.md](docs/CONFIG.md) — справочник конфигурации: YAML-структура, переменные окружения, приоритеты, безопасность.
|
||
|
||
## Форматы вывода
|
||
|
||
| Формат | Особенности |
|
||
| --- | --- |
|
||
| Консоль | Таблица или компактный вид (`--compact`). |
|
||
| ODT | Требуется `odfpy`; формирование по шаблону. |
|
||
| CSV | UTF-8 с BOM; полные значения `project`/`version` в каждой строке. |
|
||
| Markdown | Компактная таблица. |
|
||
| HTML | Полный HTML-документ; объединение ячеек групп через rowspan. |
|
||
| JSON | Объекты `project`, `version`, `issue_id`, `subject`, `status`, `time` + опционально `activities`. |
|
||
| XLSX | Объединение ячеек по проекту/версии, итоги, автоширина (максимум 80), автофильтр, freeze panes. |
|
||
|
||
Нюанс `--no-time`: физически удаляет колонку времени только CSV; в XLSX колонки остаются, но пустыми и без итогов; в остальных форматах — пустые значения.
|
||
|
||
## Разработка
|
||
|
||
Проверки перед коммитом:
|
||
|
||
```bash
|
||
pytest
|
||
isort --check-only redmine_reporter tests
|
||
black --check redmine_reporter tests
|
||
ruff check redmine_reporter tests
|
||
ruff format --check redmine_reporter tests
|
||
mypy redmine_reporter
|
||
```
|
||
|
||
CI — Gitea Actions (`.gitea/workflows/checks.yaml`): все шесть проверок на матрице Python 3.10–3.13.
|
||
|
||
## Безопасность
|
||
|
||
- `REDMINE_URL` обязан использовать HTTPS: валидация отклоняет остальное, API-ключ передаётся в заголовках.
|
||
- `verify_ssl` / `REDMINE_VERIFY`: `true` (по умолчанию — проверка по системному хранилищу CA операционной системы через truststore, корпоративные CA из ОС работают), `false` (предупреждение о MITM-риске при старте) или путь к CA-bundle.
|
||
- Конфиг создаётся с правами `0600`, директория — `0700`; при более широких правах выводится предупреждение.
|
||
- Секреты храните через `${VAR}` в YAML или в переменных окружения, не в открытом виде.
|
||
- Инструмент только читает данные из Redmine и ничего в нём не изменяет.
|
||
|
||
## Лицензия
|
||
|
||
MIT, см. [LICENSE](LICENSE).
|