diff --git a/README.md b/README.md index 7876662..c6c713e 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,11 @@ CLI-инструмент для генерации отчётов по зада - Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx). - Excel-отчёт с merge-ячейками по проекту/версии, итогами, автошириной, автофильтром и закреплённой шапкой. - Сводка по времени (`--summary`). -- YAML-конфиг (`~/.config/redmine-reporter/config.yml`): шаблон имени файла, путь по умолчанию, период, SMTP. +- YAML-конфиг (`~/.config/redmine-reporter/config.yml`): шаблон имени файла, путь по умолчанию, период, email. - Умное разрешение `--output`: bare-формат (`xlsx`) → путь по шаблону, без расширения → автодописывание. - `--commit`: автосохранение отчёта в файл + фиксация периода в YAML-конфиге для следующего запуска. -- Понятные сообщения об ошибках Redmine API (401/403/5xx, таймаут, сеть). +- `--send`: отправка отчёта по email через SMTP сразу после генерации. +- Понятные сообщения об ошибках Redmine API, SMTP и файловой системы. - Загрузка альтернативного `.env` через `--config`. ## Установка @@ -89,11 +90,17 @@ email: from: bot@example.com to: - boss@example.com + cc: [] + bcc: [] subject: "Отчёт {author} за {period}" + body_text: "Во вложении отчёт." + attach: true ``` Шаблон `output.filename` поддерживает `{author}`, `{from}`, `{to}`, `{date}` (DD_MM_YYYY), `{ext}`. +Шаблоны `email.subject` и `email.body_text` поддерживают `{author}`, `{period}` (строка диапазона, например `2026-06-01--2026-06-30`). + Подробнее: [docs/CONFIG.md](docs/CONFIG.md). ### `.env` (legacy) @@ -125,6 +132,8 @@ DEFAULT_TO_DATE=2026-01-31 source .venv/bin/activate ``` +### Основные сценарии + Отчёт за период по умолчанию: ```bash @@ -164,41 +173,46 @@ redmine-reporter --compact redmine-reporter --debug ``` -Экспорт с явным путём: +### Экспорт в файл + +Явный путь: ```bash redmine-reporter --output report.xlsx redmine-reporter --output /path/to/report.odt ``` -Экспорт — только формат (путь и имя берутся из YAML-шаблона): +Только формат (путь и имя берутся из YAML-шаблона): ```bash redmine-reporter --output xlsx # → output.dir/отчёт_01_07_2026.xlsx redmine-reporter --output odt # → output.dir/отчёт_01_07_2026.odt ``` -Экспорт — путь без расширения (дописывается `default_format` из конфига): +Путь без расширения (дописывается `default_format` из конфига): ```bash redmine-reporter --output /tmp/report # → /tmp/report.xlsx (если default_format: xlsx) ``` -Без времени / с разбивкой по активностям: +### Отправка по email (`--send`) + +Отправить отчёт на email, указанный в YAML-конфиге (секция `email`): ```bash -redmine-reporter --no-time -redmine-reporter --by-activity -redmine-reporter --by-activity --summary +# Сохранить по шаблону и отправить +redmine-reporter --date 2026-06-01--2026-06-30 --send + +# С явным путём +redmine-reporter --date 2026-06-01--2026-06-30 --output ~/report.xlsx --send + +# Вместе с фиксацией периода +redmine-reporter --date 2026-06-01--2026-06-30 --send --commit ``` -Сводка: +Если секция `email` не настроена — ошибка с пояснением. При ошибке SMTP файл отчёта остаётся на диске, данные не теряются. Поддерживаются `to`, `cc`, `bcc`, TLS, отключение вложения (`attach: false`). -```bash -redmine-reporter --summary -``` - -Фиксация периода (`--commit`): +### Фиксация периода (`--commit`) ```bash # Сгенерировать, сохранить в файл по шаблону, запомнить период @@ -215,6 +229,22 @@ redmine-reporter redmine-reporter --commit ``` +### Сводка и опции + +Без времени / с разбивкой по активностям: + +```bash +redmine-reporter --no-time +redmine-reporter --by-activity +redmine-reporter --by-activity --summary +``` + +Сводка: + +```bash +redmine-reporter --summary +``` + ## Форматы вывода | Формат | Особенности | @@ -226,6 +256,33 @@ redmine-reporter --commit | **JSON** | Массив объектов: `project`, `version`, `issue_id`, `subject`, `status`, `time`. | | **Excel (.xlsx)** | Merge cells, колонки `Hours`/`Spent Time`, итоги, автоширина, автофильтр, freeze panes. | +## Полный список флагов + +``` +--date DATE Диапазон дат: YYYY-MM-DD--YYYY-MM-DD +--compact Компактный текстовый вывод вместо таблицы +--output PATH/FMT Путь к файлу (.odt/.csv/.md/.html/.json/.xlsx) + или bare-формат (xlsx/odt/...) — путь из конфига +--author NAME Переопределить имя автора +--no-time Не включать затраченное время в таблицу +--url URL Переопределить Redmine URL +--api-key KEY Переопределить Redmine API key +--config PATH Путь к альтернативному .env-файлу +--verbose Подробный вывод +--debug Отладочный вывод +--version Показать версию и выйти +--summary Вывести сводку по времени в stderr +--user-id ID Redmine ID пользователя для отчёта +--user-login LOGIN Логин пользователя Redmine +--user-name NAME Полное имя пользователя Redmine +--by-activity Разбить время по типам активности +--init-config Сгенерировать YAML-конфиг и выйти +--force Перезаписать существующий конфиг (с --init-config) +--config-path PATH Путь к YAML-конфигу (по умолчанию ~/.config/redmine-reporter/config.yml) +--commit Сохранить отчёт в файл и зафиксировать период в конфиге +--send Отправить отчёт по email после сохранения +``` + ## Разработка Проверки перед коммитом: @@ -233,8 +290,7 @@ redmine-reporter --commit ```bash pytest ruff check redmine_reporter tests -black --check redmine_reporter tests -isort --check-only redmine_reporter tests +ruff format --check redmine_reporter tests mypy redmine_reporter ``` diff --git a/docs/CONFIG.md b/docs/CONFIG.md index 9ca390b..a448ef6 100644 --- a/docs/CONFIG.md +++ b/docs/CONFIG.md @@ -103,6 +103,119 @@ redmine-reporter --date 2026-06-15--2026-06-20 --commit redmine-reporter --commit ``` +### `email` — настройка отправки по почте + +Секция `email` используется флагом `--send`. Если секция не настроена или `smtp.host` +пуст, `--send` завершится с ошибкой «Email не настроен». + +**Все поля:** + +| Поле | Тип | По умолчанию | Описание | +|---|---|---|---| +| `smtp.host` | строка | `""` | Адрес SMTP-сервера | +| `smtp.port` | число | `587` | Порт SMTP | +| `smtp.user` | строка | `""` | Логин для аутентификации | +| `smtp.password` | строка | `""` | Пароль (рекомендуется `${SMTP_PASSWORD}`) | +| `smtp.tls` | bool | `true` | Использовать STARTTLS | +| `from` | строка | `""` | Адрес отправителя | +| `to` | список | `[]` | Основные получатели | +| `cc` | список | `[]` | Копия | +| `bcc` | список | `[]` | Скрытая копия (не отображается в заголовках письма) | +| `subject` | строка | `"Отчёт {author} за {period}"` | Тема письма | +| `body_text` | строка | `"Во вложении отчёт."` | Текст письма (plain text) | +| `attach` | bool | `true` | Прикреплять файл отчёта. Если `false` — только текст | + +**Подстановки в `subject` и `body_text`:** + +| Плейсхолдер | Описание | Пример | +|---|---|---| +| `{author}` | Имя автора из конфига или `--author` | `Кокос А.А.` | +| `{period}` | Строка диапазона дат | `2026-06-01--2026-06-30` | + +**MIME-тип вложения** определяется по расширению файла: + +| Расширение | MIME-тип | +|---|---| +| `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | +| `.odt` | `application/vnd.oasis.opendocument.text` | +| `.csv` | `text/csv` | +| `.html` | `text/html` | +| `.json` | `application/json` | +| `.md` | `text/markdown` | + +Неизвестное расширение → `application/octet-stream`. + +**Пример конфигурации:** + +```yaml +email: + smtp: + host: smtp.example.com + port: 587 + user: bot@example.com + password: ${SMTP_PASSWORD} + tls: true + from: bot@example.com + to: + - boss@example.com + - team-lead@example.com + cc: + - manager@example.com + bcc: [] + subject: "Отчёт {author} за {period}" + body_text: "Во вложении отчёт за период {period}." + attach: true +``` + +### `--send` — отправка отчёта по email + +Флаг `--send` отправляет сгенерированный отчёт через SMTP сразу после сохранения +в файл. Требует настроенную секцию `email` в YAML-конфиге. + +**Что делает:** + +1. Генерирует отчёт как обычно. +2. Сохраняет отчёт в файл: + - Если указан `--output` — по явному пути. + - Если `--output` не указан — по шаблону из `output.dir` / `output.filename`. +3. Формирует MIME-письмо: тема, текст, вложение (с корректным MIME-типом). +4. Отправляет через SMTP с TLS (таймаут 30 секунд). + +**Файл отчёта сохраняется до попытки отправки** — при ошибке SMTP файл остаётся +на диске, данные не теряются. + +**Ошибки SMTP:** + +- Нет соединения → `"Не удалось подключиться к SMTP-серверу host:port"` +- Неверный логин/пароль → `"Ошибка аутентификации SMTP. Проверьте логин и пароль."` +- Таймаут → `"Таймаут соединения с SMTP-сервером."` +- Другая ошибка → `"Ошибка отправки письма: <детали>"` + +Все ошибки выводятся в stderr, код возврата 1. + +**Примеры:** + +```bash +# Отправить отчёт за июнь (сохранится по шаблону output.filename) +redmine-reporter --date 2026-06-01--2026-06-30 --send + +# С явным путём +redmine-reporter --date 2026-06-01--2026-06-30 --output ~/report.xlsx --send + +# Отправить и зафиксировать период +redmine-reporter --date 2026-06-01--2026-06-30 --send --commit +``` + +**Совместимость с другими флагами:** + +| Комбинация | Поведение | +|---|---| +| `--send` | Сохранить по шаблону → отправить | +| `--send --output X` | Сохранить в X → отправить | +| `--send --commit` | Сохранить → отправить → зафиксировать период | +| `--send` без `email` в конфиге | Ошибка, exit 1 | +| `--send` при ошибке SMTP | Файл сохранён, ошибка в stderr, exit 1 | + ### `output` — путь и имя файла по умолчанию Секция управляет тем, куда и с каким именем сохраняется отчёт, когда `--output` не содержит полного пути. diff --git a/pyproject.toml b/pyproject.toml index 7f62d98..d3137bc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,8 +30,6 @@ dependencies = [ [project.optional-dependencies] dev = [ "pytest>=7.0", - "black>=23.0", - "isort>=5.12", "mypy>=1.0", "ruff>=0.1.0", ] @@ -46,14 +44,6 @@ include = ["redmine_reporter*"] [tool.setuptools.package-data] "redmine_reporter" = ["templates/template.odt"] -[tool.black] -line-length = 100 -target-version = ['py39'] - -[tool.isort] -profile = "black" -multi_line_output = 3 - [tool.mypy] warn_unused_configs = true