docs: update README and CONFIG for #43 #47

- README: add YAML config section, --by-activity, bare format --output, output without extension, period.precision - CONFIG: document period.last_used, period.precision (date/datetime), output path resolution rules, resolve_output_path() behavior
2026-07-07 10:34:49 +07:00
parent 47152f8f04
commit 485be063d2
2 changed files with 150 additions and 63 deletions
--- a/README.md
+++ b/README.md
@@ -12,10 +12,13 @@ CLI-инструмент для генерации отчётов по зада
 - Авторизация через Redmine API token или логин/пароль.
 - Группировка задач по проекту и версии.
 - Перевод статусов задач на русский язык.
+- Разбивка по типам активности (`--by-activity`).
 - Вывод в консоль (таблица / компактный вид).
 - Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx).
 - Excel-отчёт с merge-ячейками по проекту/версии, итогами, автошириной, автофильтром и закреплённой шапкой.
 - Сводка по времени (`--summary`).
+- YAML-конфиг (`~/.config/redmine-reporter/config.yml`): шаблон имени файла, путь по умолчанию, период, SMTP.
+- Умное разрешение `--output`: bare-формат (`xlsx`) → путь по шаблону, без расширения → автодописывание.
 - Понятные сообщения об ошибках Redmine API (401/403/5xx, таймаут, сеть).
 - Загрузка альтернативного `.env` через `--config`.

@@ -38,28 +41,70 @@ pip install -e ".[dev]"

 ## Настройка

-Создайте файл `.env` в корне проекта. Он не должен попадать в git.
+Источники конфигурации (от высшего приоритета к низшему):

-Рекомендуемый вариант авторизации:
+```
+CLI-флаги  >  переменные окружения  >  .env  >  YAML-конфиг  >  кодовые дефолты
+```
+
+### YAML-конфиг (основной способ)
+
+```bash
+# Сгенерировать YAML из текущего .env
+redmine-reporter --init-config
+
+# Редактировать под себя
+vim ~/.config/redmine-reporter/config.yml
+```
+
+Структура:
+
+```yaml
+redmine:
+  url: https://red.eltex.loc
+  api_key: ${REDMINE_API_KEY}
+  author: "Кокос А.А."
+  verify_ssl: true
+
+period:
+  precision: date                   # date | datetime
+  default_from: "2026-06-01"
+  default_to: "2026-06-30"
+  dynamic: false
+  # last_used заполняется --commit (см. docs/CONFIG.md)
+
+output:
+  dir: ~/reports
+  filename: "{author}_{from}_{to}.{ext}"
+  default_format: xlsx
+
+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
+  subject: "Отчёт {author} за {period}"
+```
+
+Шаблон `output.filename` поддерживает `{author}`, `{from}`, `{to}`, `{date}` (DD_MM_YYYY), `{ext}`.
+
+Подробнее: [docs/CONFIG.md](docs/CONFIG.md).
+
+### `.env` (legacy)

 ```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
 ```

-Резервный вариант:
-
-```ini
-REDMINE_URL=https://red.eltex.loc/
-REDMINE_USER=ваш.логин
-REDMINE_PASSWORD=ваш_пароль
-REDMINE_AUTHOR=Иванов Иван Иванович
-```
-
 Переменные окружения:

 | Переменная | Обязательность | Описание |
@@ -68,7 +113,7 @@ REDMINE_AUTHOR=Иванов Иван Иванович
 | `REDMINE_API_KEY` | Да, если нет логина и пароля | Redmine API token. |
 | `REDMINE_USER` | Да, если нет токена | Логин Redmine. |
 | `REDMINE_PASSWORD` | Да, если нет токена | Пароль Redmine. |
-| `REDMINE_AUTHOR` | Нет | Имя автора для ODT-отчёта. |
+| `REDMINE_AUTHOR` | Нет | Имя автора для отчёта. |
 | `DEFAULT_FROM_DATE` | Нет | Начальная дата периода по умолчанию (`YYYY-MM-DD`). |
 | `DEFAULT_TO_DATE` | Нет | Конечная дата периода по умолчанию (`YYYY-MM-DD`). |
 | `REDMINE_VERIFY` | Нет | TLS-проверка: `true` / `false` / путь к CA bundle. |
@@ -85,13 +130,13 @@ source .venv/bin/activate
 redmine-reporter
 ```

-Отчёт за произвольный период:
+Произвольный период:

 ```bash
 redmine-reporter --date 2026-02-01--2026-02-28
 ```

-Отчёт по другому пользователю:
+Другой пользователь:

 ```bash
 redmine-reporter --user-id 42
@@ -99,51 +144,54 @@ redmine-reporter --user-login ivanov
 redmine-reporter --user-name "Иванов И.И."
 ```

-`--user-name` требует точного совпадения; если найдено несколько пользователей, CLI сообщает об ошибке и просит использовать `--user-id`.
-
-Переопределить URL/API-ключ из `.env`:
+Переопределить URL / API-ключ:

 ```bash
 redmine-reporter --url https://red.example.com --api-key ваш_токен
 ```

-Альтернативный конфигурационный файл:
+Альтернативный `.env`:

 ```bash
 redmine-reporter --config /path/to/.env
 ```

-Компактный вывод:
+Компактный / отладочный вывод:

 ```bash
 redmine-reporter --compact
-```
-
-Отладочный вывод:
-
-```bash
 redmine-reporter --debug
 ```

-Экспорт:
+Экспорт с явным путём:

 ```bash
-redmine-reporter --output report.odt
-redmine-reporter --output report.csv
-redmine-reporter --output report.md
-redmine-reporter --output report.html
-redmine-reporter --output report.json
 redmine-reporter --output report.xlsx
+redmine-reporter --output /path/to/report.odt
 ```

-Отчёт без затраченного времени (работает для всех форматов):
+Экспорт — только формат (путь и имя берутся из YAML-шаблона):
+
+```bash
+redmine-reporter --output xlsx          # → output.dir/отчёт_01_07_2026.xlsx
+redmine-reporter --output odt           # → output.dir/отчёт_01_07_2026.odt
+```
+
+Экспорт — путь без расширения (дописывается `default_format` из конфига):
+
+```bash
+redmine-reporter --output /tmp/report   # → /tmp/report.xlsx (если default_format: xlsx)
+```
+
+Без времени / с разбивкой по активностям:

 ```bash
 redmine-reporter --no-time
-redmine-reporter --no-time --output report.xlsx
+redmine-reporter --by-activity
+redmine-reporter --by-activity --summary
 ```

-Сводка по времени:
+Сводка:

 ```bash
 redmine-reporter --summary
@@ -175,5 +223,7 @@ mypy redmine_reporter
 ## Безопасность

 - Не коммитьте `.env`, API token, пароль или логин.
+- YAML-конфиг имеет права `0600`, директория — `0700`.
+- Рекомендуется хранить секреты через `${VAR}`, а не plaintext.
 - Используйте аккаунт с минимальными правами, достаточными для чтения time entries и задач.
 - Инструмент работает только в режиме чтения и не изменяет данные в Redmine.