feat: filename template expansion with {date} placeholder
- Add expand_filename_template() to yaml_config.py
- Supports {author}, {from}, {to}, {date}, {ext} placeholders
- {date} formats as DD_MM_YYYY (e.g. 31_03_2026)
- Spaces in author replaced with underscores for safe filenames
- Unknown placeholders left as-is
- Add comprehensive CONFIG.md documentation covering YAML setup, migration, and template syntax
This commit is contained in:
Кокос Артем Николаевич
188
docs/CONFIG.md
Normal file
188
docs/CONFIG.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Настройка redmine-reporter
|
||||
|
||||
## Источники конфигурации
|
||||
|
||||
Приоритет, от высшего к низшему:
|
||||
|
||||
```
|
||||
CLI-флаги > переменные окружения > .env > YAML > кодовые дефолты
|
||||
```
|
||||
|
||||
Если значение не задано на верхнем уровне, берётся уровень ниже. `.env` и YAML
|
||||
работают одновременно — можно оставить оба, можно удалить `.env` после миграции.
|
||||
|
||||
## YAML-конфиг
|
||||
|
||||
Основной файл: `~/.config/redmine-reporter/config.yml`.
|
||||
|
||||
Создаётся с правами `0600` (владелец: чтение/запись, остальные: доступ запрещён).
|
||||
Директория `~/.config/redmine-reporter/` — с правами `0700`.
|
||||
|
||||
Если права файла шире `0600`, при запуске выводится предупреждение.
|
||||
|
||||
### Структура
|
||||
|
||||
```yaml
|
||||
redmine:
|
||||
url: https://red.eltex.loc # URL инстанса Redmine
|
||||
api_key: ${REDMINE_API_KEY} # API-ключ (или plaintext)
|
||||
author: "Кокос А.А." # Имя автора для отчёта
|
||||
verify_ssl: true # Проверка SSL-сертификата
|
||||
|
||||
period:
|
||||
precision: date # date | datetime
|
||||
default_from: "2026-06-01" # Начало периода по умолчанию
|
||||
default_to: "2026-06-30" # Конец периода по умолчанию
|
||||
dynamic: false # Автоматически сдвигать период
|
||||
|
||||
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}` | Начало периода, `YYYY-MM-DD` | `2026-06-01` |
|
||||
| `{to}` | Конец периода, `YYYY-MM-DD` | `2026-06-30` |
|
||||
| `{date}` | Конец периода, `DD_MM_YYYY` | `30_06_2026` |
|
||||
| `{ext}` | Расширение файла без точки | `xlsx` |
|
||||
|
||||
Неизвестные плейсхолдеры остаются в имени как есть.
|
||||
|
||||
Примеры шаблонов:
|
||||
|
||||
```yaml
|
||||
# По умолчанию
|
||||
filename: "{author}_{from}_{to}.{ext}" # → Кокос_А.А._2026-06-01_2026-06-30.xlsx
|
||||
|
||||
# Русский формат даты
|
||||
filename: "отчёт_{date}.{ext}" # → отчёт_30_06_2026.xlsx
|
||||
|
||||
# Без автора, только диапазон
|
||||
filename: "report_{from}--{to}.{ext}" # → report_2026-06-01--2026-06-30.xlsx
|
||||
```
|
||||
|
||||
### Подстановка переменных окружения
|
||||
|
||||
В любом строковом значении YAML можно использовать `${VAR}` — при загрузке
|
||||
оно заменяется на значение переменной окружения:
|
||||
|
||||
```yaml
|
||||
redmine:
|
||||
api_key: ${REDMINE_API_KEY}
|
||||
|
||||
email:
|
||||
smtp:
|
||||
password: ${SMTP_PASSWORD}
|
||||
```
|
||||
|
||||
Это безопаснее, чем хранить секреты plaintext в YAML. Однако plaintext-секреты
|
||||
**не запрещены** — если вписать `api_key: "abc123"` напрямую, система примет.
|
||||
Права `0600` — единственная защита.
|
||||
|
||||
## Миграция с `.env` на YAML
|
||||
|
||||
### Быстрый старт
|
||||
|
||||
```bash
|
||||
# 1. Генерируем YAML из текущего .env
|
||||
redmine-reporter --init-config
|
||||
|
||||
# 2. Проверяем, что создалось
|
||||
cat ~/.config/redmine-reporter/config.yml
|
||||
|
||||
# 3. Редактируем под себя (шаблон имени, почту, etc.)
|
||||
vim ~/.config/redmine-reporter/config.yml
|
||||
```
|
||||
|
||||
### Что делает `--init-config`
|
||||
|
||||
- Читает текущие значения из `.env` и переменных окружения.
|
||||
- Формирует YAML со всеми секциями (`redmine`, `period`, `output`, `email`).
|
||||
- Секреты (`REDMINE_API_KEY`, `SMTP_PASSWORD`) записывает как `${VAR}`, если
|
||||
переменная существует, иначе — пустая строка.
|
||||
- Создаёт файл с правами `0600`, директорию — с `0700`.
|
||||
|
||||
### Флаги миграции
|
||||
|
||||
| Флаг | Назначение |
|
||||
|-----------------------|-------------------------------------------------|
|
||||
| `--init-config` | Создать YAML и выйти |
|
||||
| `--init-config --force` | Перезаписать существующий YAML |
|
||||
| `--config-path PATH` | Сохранить YAML по указанному пути (по умолчанию `~/.config/redmine-reporter/config.yml`) |
|
||||
|
||||
### Проверка после миграции
|
||||
|
||||
```bash
|
||||
# Запустить без .env в текущей директории
|
||||
cd /tmp
|
||||
redmine-reporter --date 2026-06-01--2026-06-30
|
||||
```
|
||||
|
||||
Если отработал — YAML-конфиг читается корректно. Если `REDMINE_URL is required` —
|
||||
проверь права:
|
||||
|
||||
```bash
|
||||
ls -la ~/.config/redmine-reporter/
|
||||
# config.yml должно быть -rw------- (600)
|
||||
# директория должна быть drwx------ (700)
|
||||
```
|
||||
|
||||
### Сосуществование `.env` и YAML
|
||||
|
||||
Можно оставить оба источника. `.env` имеет **более высокий приоритет**, чем YAML:
|
||||
|
||||
```
|
||||
.env значения переопределяют YAML, если заданы
|
||||
YAML работает как базовый слой для всего, что не в .env
|
||||
```
|
||||
|
||||
Это safe — если с YAML что-то пойдёт не так, просто положи `.env` обратно.
|
||||
|
||||
### Откат
|
||||
|
||||
```bash
|
||||
# Удалить YAML-конфиг — система вернётся на .env
|
||||
rm ~/.config/redmine-reporter/config.yml
|
||||
```
|
||||
|
||||
## `.env` (legacy)
|
||||
|
||||
Для обратной совместимости `.env` продолжает работать без изменений.
|
||||
|
||||
```ini
|
||||
REDMINE_URL=https://red.eltex.loc
|
||||
REDMINE_API_KEY=your-api-key
|
||||
REDMINE_AUTHOR=Кокос А.А.
|
||||
DEFAULT_FROM_DATE=2026-06-01
|
||||
DEFAULT_TO_DATE=2026-06-30
|
||||
```
|
||||
|
||||
Если ни `.env`, ни YAML не заданы — используются кодовые дефолты (текущий месяц
|
||||
как период, стандартный путь сертификатов, пустой автор).
|
||||
|
||||
## Безопасность
|
||||
|
||||
- YAML-конфиг: права `0600`, директория `0700`.
|
||||
- Права шире `0600` → warning в stderr при каждом запуске.
|
||||
- Секреты рекомендуется хранить через `${VAR}`, а не plaintext.
|
||||
- `.env` **не рекомендуется** для постоянных настроек — оставьте его только
|
||||
для CI/CD или временных переопределений.
|
||||
Reference in New Issue
Block a user