c8df40fe5c
- README.md: 324 -> 106 lines, clickable TOC, quick start, formats table, full check suite + CI; flags/env/YAML reference moved to docs - docs/USER_GUIDE.md: new user guide (install, periods, users, export, email, monthly --commit cycle, 21-flag reference, troubleshooting) - docs/CONFIG.md: clickable TOC + accuracy fixes verified against code (dedup logic was described backwards, missing report section in --init-config, conditional STARTTLS, full --config-path role, datetime --date ranges, --config override nuance, comment loss on --commit, default_to without default_from is ignored) - client.py: dedup docstring/comment now match actual behavior
107 lines
5.9 KiB
Markdown
107 lines
5.9 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`, переменные окружения, YAML-конфиг, по умолчанию — текущий месяц.
|
||
- `--commit`: сохранение отчёта в файл и фиксация периода в конфиге для следующего запуска.
|
||
- `--send`: отправка отчёта по email через SMTP (plain-text или HTML-письмо).
|
||
- 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
|
||
```
|
||
|
||
## Документация
|
||
|
||
- [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` (по умолчанию), `false` (предупреждение о MITM-риске при старте) или путь к CA-bundle.
|
||
- Конфиг создаётся с правами `0600`, директория — `0700`; при более широких правах выводится предупреждение.
|
||
- Секреты храните через `${VAR}` в YAML или в переменных окружения, не в открытом виде.
|
||
- Инструмент только читает данные из Redmine и ничего в нём не изменяет.
|
||
|
||
## Лицензия
|
||
|
||
MIT, см. [LICENSE](LICENSE).
|