artem.kokos/redmine-reporter

Fork 0

Files

Кокос Артем Николаевич 80faccb1f9 docs: add --commit documentation to README and CONFIG

2026-07-07 10:48:36 +07:00

11 KiB

Raw Blame History

Настройка redmine-reporter

Источники конфигурации

Приоритет, от высшего к низшему:

CLI-флаги  >  переменные окружения  >  .env  >  YAML  >  кодовые дефолты

Если значение не задано на верхнем уровне, берётся уровень ниже. .env и YAML работают одновременно — можно оставить оба, можно удалить .env после миграции.

YAML-конфиг

Основной файл: ~/.config/redmine-reporter/config.yml.

Создаётся с правами 0600 (владелец: чтение/запись, остальные: доступ запрещён). Директория ~/.config/redmine-reporter/ — с правами 0700.

Если права файла шире 0600, при запуске выводится предупреждение.

Структура

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) начинается со следующего дня.
datetime — период с точностью до секунды. При повторном запуске time entries с created_on и updated_on ранее last_used.to исключаются (AND-логика: запись исключается только если оба поля раньше cutoff). Это предотвращает дублирование при отправке отчёта внутри рабочего дня.

last_used.from / last_used.to записываются автоматически при --commit. Вручную редактировать не требуется.

`--commit` — автофиксация периода

Флаг --commit сохраняет использованный период в YAML-конфиг, чтобы следующий запуск автоматически начинался с нового периода.

Что делает:

Генерирует отчёт как обычно.
Сохраняет отчёт в файл:
- Если указан --output — по явному пути.
- Если --output не указан — по шаблону из output.dir / output.filename.
Записывает period.last_used.from / period.last_used.to в YAML-конфиг.
При period.precision: datetime сохраняет текущий момент времени (ISO с секундами).
При period.precision: date сохраняет даты периода.

Поведение period.dynamic:

dynamic: true — следующий запуск (без --date) вычисляет период от last_used:
- Полный календарный месяц → следующий полный месяц.
- Произвольный диапазон → та же длительность, начиная со дня после last_used.to.
dynamic: false — --commit перезаписывает default_from/default_to на использованный период.

Примеры:

# Июнь 2026 → следующий запуск (без --date) → июль 2026
redmine-reporter --date 2026-06-01--2026-06-30 --commit

# Произвольный диапазон: 15-20 июня → следующий запуск → 21-26 июня
redmine-reporter --date 2026-06-15--2026-06-20 --commit

# С datetime-точностью: повторный запуск не дублирует записи
redmine-reporter --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`

Неизвестные плейсхолдеры остаются в имени как есть.

Примеры:

# По умолчанию
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} — при загрузке оно заменяется на значение переменной окружения:

redmine:
  api_key: ${REDMINE_API_KEY}

email:
  smtp:
    password: ${SMTP_PASSWORD}

Это безопаснее, чем хранить секреты plaintext в YAML. Однако plaintext-секреты не запрещены — если вписать api_key: "abc123" напрямую, система примет. Права 0600 — основная защита.

Разрешение выходного пути

Функция resolve_output_path() определяет итоговый путь к файлу:

--output не указан → консольный вывод.
--output xlsx (bare format) → путь формируется как output.dir / output.filename с подстановкой {ext} = bare format и дат из периода.
--output /path/report (без расширения) → дописывается .output.default_format.
--output /path/report.csv (с расширением) → используется как есть.
--output /path/report.xyz (неизвестное расширение) → используется как есть, форматтер выбирается по расширению.

Миграция с `.env` на YAML

Быстрый старт

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

Проверка после миграции

# Запустить без .env в текущей директории
cd /tmp
redmine-reporter --date 2026-06-01--2026-06-30

Если отработал — YAML-конфиг читается корректно. Если REDMINE_URL is required — проверь права:

ls -la ~/.config/redmine-reporter/
# config.yml должно быть -rw------- (600)
# директория должна быть drwx------ (700)

Сосуществование `.env` и YAML

Можно оставить оба источника. .env имеет более высокий приоритет, чем YAML:

.env значения переопределяют YAML, если заданы
YAML работает как базовый слой для всего, что не в .env

Это safe — если с YAML что-то пойдёт не так, просто положи .env обратно.

Откат

rm ~/.config/redmine-reporter/config.yml

`.env` (legacy)

Для обратной совместимости .env продолжает работать без изменений.

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 или временных переопределений.

11 KiB Raw Blame History Unescape Escape