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/docs/CONFIG.md
+++ b/docs/CONFIG.md
@@ -24,21 +24,24 @@ CLI-флаги  >  переменные окружения  >  .env  >  YAML  >

 ```yaml
 redmine:
-  url: https://red.eltex.loc          # URL инстанса Redmine
-  api_key: ${REDMINE_API_KEY}         # API-ключ (или plaintext)
-  author: "Кокос А.А."               # Имя автора для отчёта
-  verify_ssl: true                    # Проверка SSL-сертификата
+  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                      # Автоматически сдвигать период
+  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                # Формат по умолчанию
+  dir: ~/reports
+  filename: "{author}_{from}_{to}.{ext}"
+  default_format: xlsx

 email:
  smtp:
@@ -50,24 +53,49 @@ email:
  from: bot@example.com
  to:
    - boss@example.com
+  cc: []
+  bcc: []
  subject: "Отчёт {author} за {period}"
+  body_text: "Во вложении отчёт."
+  attach: true
 ```

-### Шаблон имени файла
+### `period.precision` — точность периода

-Поле `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`                 |
+- `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
 # По умолчанию
@@ -96,7 +124,17 @@ email:

 Это безопаснее, чем хранить секреты plaintext в YAML. Однако plaintext-секреты
 **не запрещены** — если вписать `api_key: "abc123"` напрямую, система примет.
-Права `0600` — единственная защита.
+Права `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

@@ -109,7 +147,7 @@ redmine-reporter --init-config
 # 2. Проверяем, что создалось
 cat ~/.config/redmine-reporter/config.yml

-# 3. Редактируем под себя (шаблон имени, почту, etc.)
+# 3. Редактируем под себя (шаблон имени, период, etc.)
 vim ~/.config/redmine-reporter/config.yml
 ```

@@ -123,11 +161,11 @@ vim ~/.config/redmine-reporter/config.yml

 ### Флаги миграции

-| Флаг                  | Назначение                                      |
-|-----------------------|-------------------------------------------------|
-| `--init-config`       | Создать YAML и выйти                            |
-| `--init-config --force` | Перезаписать существующий YAML                |
-| `--config-path PATH`  | Сохранить YAML по указанному пути (по умолчанию `~/.config/redmine-reporter/config.yml`) |
+| Флаг | Назначение |
+|---|---|
+| `--init-config` | Создать YAML и выйти |
+| `--init-config --force` | Перезаписать существующий YAML |
+| `--config-path PATH` | Сохранить YAML по указанному пути (по умолчанию `~/.config/redmine-reporter/config.yml`) |

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

@@ -160,7 +198,6 @@ YAML работает как базовый слой для всего, что
 ### Откат

 ```bash
-# Удалить YAML-конфиг — система вернётся на .env
 rm ~/.config/redmine-reporter/config.yml
 ```