docs: update README, CONFIG and pyproject.toml for --send feature
- README: add --send flag to features, usage examples, full flag list; replace black/isort with ruff in dev section; add email config template variables docs - CONFIG: new email section with all fields documented, --send usage examples, error handling and flag compatibility table - pyproject.toml: remove unused black and isort from dev dependencies and their tool configs (project uses ruff for both lint and format)
This commit is contained in:
113
docs/CONFIG.md
113
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` не содержит полного пути.
|
||||
|
||||
Reference in New Issue
Block a user