redmine-reporter/docs/CONFIG.md

# Настройка 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 или временных переопределений.