485be063d2
- 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
226 lines
9.2 KiB
Markdown
226 lines
9.2 KiB
Markdown
# Настройка 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
|
||
api_key: ${REDMINE_API_KEY}
|
||
author: "Кокос А.А."
|
||
verify_ssl: true
|
||
|
||
period:
|
||
precision: date
|
||
default_from: "2026-06-01"
|
||
default_to: "2026-06-30"
|
||
dynamic: false
|
||
last_used:
|
||
from: "2026-06-30T09:00:00"
|
||
to: "2026-06-30T12:00:00"
|
||
|
||
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
|
||
cc: []
|
||
bcc: []
|
||
subject: "Отчёт {author} за {period}"
|
||
body_text: "Во вложении отчёт."
|
||
attach: true
|
||
```
|
||
|
||
### `period.precision` — точность периода
|
||
|
||
Определяет, как вычисляется следующий период после фиксации:
|
||
|
||
- `date` (по умолчанию) — период с точностью до дня. Следующий запуск (после `--commit`, #44) начинается со следующего дня.
|
||
- `datetime` — период с точностью до секунды. При повторном запуске time entries с `created_on` и `updated_on` ранее `last_used.to` исключаются (AND-логика: запись исключается только если **оба** поля раньше cutoff). Это предотвращает дублирование при отправке отчёта внутри рабочего дня.
|
||
|
||
`last_used.from` / `last_used.to` записываются автоматически при `--commit`. Вручную редактировать не требуется.
|
||
|
||
### `output` — путь и имя файла по умолчанию
|
||
|
||
Секция управляет тем, куда и с каким именем сохраняется отчёт, когда `--output` не содержит полного пути.
|
||
|
||
**Правила разрешения `--output`:**
|
||
|
||
| Аргумент `--output` | Поведение |
|
||
|---|---|
|
||
| `/полный/путь/report.xlsx` | Используется как есть, конфиг игнорируется |
|
||
| `xlsx` (bare format: `xlsx`, `odt`, `csv`, `md`, `html`, `json`) | Путь = `output.dir` + `output.filename`, расширение = bare format |
|
||
| `/tmp/report` (путь без расширения) | Дописывается `.default_format` → `/tmp/report.xlsx` |
|
||
|
||
**Шаблон имени файла:**
|
||
|
||
`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` — основная защита.
|
||
|
||
## Разрешение выходного пути
|
||
|
||
Функция `resolve_output_path()` определяет итоговый путь к файлу:
|
||
|
||
1. `--output` не указан → консольный вывод.
|
||
2. `--output xlsx` (bare format) → путь формируется как `output.dir / output.filename` с подстановкой `{ext}` = bare format и дат из периода.
|
||
3. `--output /path/report` (без расширения) → дописывается `.output.default_format`.
|
||
4. `--output /path/report.csv` (с расширением) → используется как есть.
|
||
5. `--output /path/report.xyz` (неизвестное расширение) → используется как есть, форматтер выбирается по расширению.
|
||
|
||
## Миграция с `.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
|
||
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 или временных переопределений.
|