docs: rewrite README, add user guide, sync CONFIG.md with code

- README.md: 324 -> 106 lines, clickable TOC, quick start, formats table, full check suite + CI; flags/env/YAML reference moved to docs - docs/USER_GUIDE.md: new user guide (install, periods, users, export, email, monthly --commit cycle, 21-flag reference, troubleshooting) - docs/CONFIG.md: clickable TOC + accuracy fixes verified against code (dedup logic was described backwards, missing report section in --init-config, conditional STARTTLS, full --config-path role, datetime --date ranges, --config override nuance, comment loss on --commit, default_to without default_from is ignored) - client.py: dedup docstring/comment now match actual behavior
2026-07-17 17:48:52 +07:00
parent 1dc19f8c1a
commit c8df40fe5c
4 changed files with 421 additions and 274 deletions
--- a/README.md
+++ b/README.md
@@ -2,33 +2,32 @@

 [![checks](https://git.akokos.ru/artem.kokos/redmine-reporter/actions/workflows/checks.yaml/badge.svg)](https://git.akokos.ru/artem.kokos/redmine-reporter/actions)

-CLI-инструмент для генерации отчётов по задачам Redmine на основе записей о затраченном времени.
+- [Возможности](#возможности)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+- [Документация](#документация)
+- [Форматы вывода](#форматы-вывода)
+- [Разработка](#разработка)
+- [Безопасность](#безопасность)
+- [Лицензия](#лицензия)

-Проект предназначен для внутреннего использования с `https://red.eltex.loc/`.
-
-Лицензия: MIT.
+CLI-инструмент для генерации отчётов по задачам Redmine на основе записей о затраченном времени. Читает time entries текущего или указанного пользователя, группирует задачи по проекту и версии, выводит отчёт в консоль или экспортирует в файл. Предназначен для внутреннего использования с `https://red.eltex.loc/`.

 ## Возможности

- Получение time entries **текущего** или **указанного** пользователя из Redmine.
- Авторизация через Redmine API token или логин/пароль.
- Группировка задач по проекту и версии.
- Перевод статусов задач на русский язык.
- Разбивка по типам активности (`--by-activity`).
- Вывод в консоль (таблица / компактный вид).
- Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx).
- Excel-отчёт с merge-ячейками по проекту/версии, итогами, автошириной, автофильтром и закреплённой шапкой.
- Сводка по времени (`--summary`).
- YAML-конфиг (`~/.config/redmine-reporter/config.yml`): шаблон имени файла, путь по умолчанию, период, email, настройки содержимого отчёта (`report.no_time`).
- Умное разрешение `--output`: bare-формат (`xlsx`) → путь по шаблону, без расширения → автодописывание.
- `--commit`: автосохранение отчёта в файл + фиксация периода в YAML-конфиге для следующего запуска.
- `--send`: отправка отчёта по email через SMTP сразу после генерации.
- HTML-версия тела письма при `--send`, если включено в YAML-конфиге (`email.html: true`).
- Понятные сообщения об ошибках Redmine API, SMTP и файловой системы.
- Загрузка альтернативного `.env` через `--config`.
+- Отчёт по time entries текущего или указанного пользователя (`--user-id`, `--user-login`, `--user-name`).
+- Группировка задач по проекту и версии, перевод статусов на русский язык.
+- Вывод в консоль (таблица или компактный вид) и экспорт в ODT, CSV, Markdown, HTML, JSON, XLSX.
+- Разбивка времени по типам активности (`--by-activity`), сводка (`--summary`), скрытие времени (`--no-time`).
+- Гибкий выбор периода: `--date`, переменные окружения, YAML-конфиг, по умолчанию — текущий месяц.
+- `--commit`: сохранение отчёта в файл и фиксация периода в конфиге для следующего запуска.
+- `--send`: отправка отчёта по email через SMTP (plain-text или HTML-письмо).
+- YAML-конфиг с секретами через `${VAR}`; приоритет: CLI-флаги > env > .env > YAML > дефолты (нюанс с `--config` — см. docs/CONFIG.md).

 ## Установка

+Требуется Python >= 3.10.
+
 ```bash
 git clone https://git.akokos.ru/artem.kokos/redmine-reporter.git
 cd redmine-reporter
@@ -44,263 +43,40 @@ pip install .
 pip install -e ".[dev]"
 ```

-## Настройка
-
-Источники конфигурации (от высшего приоритета к низшему):
-
-```
-CLI-флаги  >  переменные окружения  >  .env  >  YAML-конфиг  >  кодовые дефолты
-```
-
-### YAML-конфиг (основной способ)
+## Быстрый старт

 ```bash
-# Сгенерировать YAML из текущего .env
+# Сгенерировать конфиг ~/.config/redmine-reporter/config.yml
 redmine-reporter --init-config

-# Редактировать под себя
+# Заполнить redmine.url, redmine.api_key (или ${REDMINE_API_KEY}), redmine.author
 vim ~/.config/redmine-reporter/config.yml
-```

-Структура:
-
-```yaml
-redmine:
-  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 можно не указывать — конец периода будет сегодня
-  default_to: "2026-06-30"
-  dynamic: false
-  # last_used заполняется --commit (см. docs/CONFIG.md)
-
-output:
-  dir: ~/reports
-  filename: "{author}_{from}_{to}.{ext}"
-  default_format: xlsx
-
-report:
-  no_time: false
-
-email:
-  html: false
-  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
-```
-
-Шаблон `output.filename` поддерживает `{author}`, `{from}`, `{to}`, `{date}` (DD_MM_YYYY), `{ext}`.
-
-Шаблоны `email.subject` и `email.body_text` поддерживают `{author}`, `{period}` (строка диапазона, например `2026-06-01--2026-06-30`).
-
-Подробнее: [docs/CONFIG.md](docs/CONFIG.md).
-
-### `.env` (legacy)
-
-```ini
-REDMINE_URL=https://red.eltex.loc/
-REDMINE_API_KEY=ваш_api_token
-REDMINE_AUTHOR=Иванов Иван Иванович
-DEFAULT_FROM_DATE=2026-01-01
-# DEFAULT_TO_DATE можно не задавать — тогда конец периода будет сегодня
-DEFAULT_TO_DATE=2026-01-31
-```
-
-Переменные окружения:
-
-| Переменная | Обязательность | Описание |
-| --- | --- | --- |
-| `REDMINE_URL` | Да | URL Redmine. |
-| `REDMINE_API_KEY` | Да, если нет логина и пароля | Redmine API token. |
-| `REDMINE_USER` | Да, если нет токена | Логин Redmine. |
-| `REDMINE_PASSWORD` | Да, если нет токена | Пароль Redmine. |
-| `REDMINE_AUTHOR` | Нет | Имя автора для отчёта. |
-| `DEFAULT_FROM_DATE` | Нет | Начальная дата периода по умолчанию (`YYYY-MM-DD`). Если не задана (и нет в YAML) — 1-е число текущего месяца. |
-| `DEFAULT_TO_DATE` | Нет | Конечная дата периода по умолчанию (`YYYY-MM-DD`). Если не задана, а `DEFAULT_FROM_DATE` задана — используется сегодняшняя дата. |
-| `REDMINE_VERIFY` | Нет | TLS-проверка: `true` (по умолчанию — стандартная проверка средствами requests) / `false` / путь к CA bundle. Семантика совпадает с `redmine.verify_ssl` в YAML. |
-
-## Использование
-
-```bash
-source .venv/bin/activate
-```
-
-### Основные сценарии
-
-Отчёт за период по умолчанию — текущий месяц (с 1-го числа по сегодня),
-если период не задан через `--date`, env или YAML:
-
-```bash
-redmine-reporter
-```
-
-Произвольный период:
-
-```bash
-redmine-reporter --date 2026-02-01--2026-02-28
-```
-
-Другой пользователь:
-
-```bash
-redmine-reporter --user-id 42
-redmine-reporter --user-login ivanov
-redmine-reporter --user-name "Иванов И.И."
-```
-
-Переопределить URL / API-ключ:
-
-```bash
-redmine-reporter --url https://red.example.com --api-key ваш_токен
-```
-
-Альтернативный `.env`:
-
-```bash
-redmine-reporter --config /path/to/.env
-```
-
-Компактный / отладочный вывод:
-
-```bash
-redmine-reporter --compact
-redmine-reporter --debug
-```
-
-### Экспорт в файл
-
-Явный путь:
-
-```bash
-redmine-reporter --output report.xlsx
-redmine-reporter --output /path/to/report.odt
-```
-
-Только формат (путь и имя берутся из YAML-шаблона):
-
-```bash
-redmine-reporter --output xlsx          # → output.dir/отчёт_01_07_2026.xlsx
-redmine-reporter --output odt           # → output.dir/отчёт_01_07_2026.odt
-```
-
-Путь без расширения (дописывается `default_format` из конфига):
-
-```bash
-redmine-reporter --output /tmp/report   # → /tmp/report.xlsx (если default_format: xlsx)
-```
-
-### Отправка по email (`--send`)
-
-Отправить отчёт на email, указанный в YAML-конфиге (секция `email`):
-
-```bash
-# Сохранить по шаблону и отправить
-redmine-reporter --date 2026-06-01--2026-06-30 --send
-
-# С явным путём
-redmine-reporter --date 2026-06-01--2026-06-30 --output ~/report.xlsx --send
-
-# Вместе с фиксацией периода
-redmine-reporter --date 2026-06-01--2026-06-30 --send --commit
-```
-
-Если в секции `email` установить `html: true`, письмо будет отправлено в двух версиях: plain-text и HTML (таблица отчёта прямо в теле письма). Файл отчёта всё равно прикрепляется, если `attach: true`.
-
-```yaml
-email:
-  html: true
-```
-
-Если секция `email` не настроена — ошибка с пояснением. При ошибке SMTP файл отчёта остаётся на диске, данные не теряются. Поддерживаются `to`, `cc`, `bcc`, TLS, отключение вложения (`attach: false`).
-
-### Фиксация периода (`--commit`)
-
-```bash
-# Сгенерировать, сохранить в файл по шаблону, запомнить период
-redmine-reporter --commit
-
-# С явным путём
-redmine-reporter --commit --output report.xlsx
-
-# Следующий запуск (без --date) возьмёт следующий период автоматически
+# Отчёт за текущий месяц в консоль
 redmine-reporter

-# При precision=datetime запоминает момент времени
-# (предотвращает дублирование записей внутри дня)
+# Сохранить в файл и зафиксировать период для следующего запуска
 redmine-reporter --commit
 ```

-### Сводка и опции
+## Документация

-Без времени / с разбивкой по активностям:
-
-```bash
-redmine-reporter --no-time
-redmine-reporter --by-activity
-redmine-reporter --by-activity --summary
-```
-
-`--no-time` можно задать в YAML-конфиге (`report.no_time: true`), чтобы автоматические режимы (`--commit`, `--send`) не включали затраченное время без явного флага. При ручном `--output` YAML-значение не применяется — только CLI-флаг `--no-time`.
-
-Сводка:
-
-```bash
-redmine-reporter --summary
-```
+- [docs/USER_GUIDE.md](docs/USER_GUIDE.md) — руководство пользователя: сценарии использования, справочник всех CLI-флагов, устранение неполадок.
+- [docs/CONFIG.md](docs/CONFIG.md) — справочник конфигурации: YAML-структура, переменные окружения, приоритеты, безопасность.

 ## Форматы вывода

 | Формат | Особенности |
 | --- | --- |
-| **ODT** | Заголовок с автором и месяцем, группировка по проекту/версии. |
-| **CSV** | UTF-8 с BOM, полные значения `project`/`version` в каждой строке. |
-| **Markdown** | Компактная таблица, повторяющиеся группы скрыты. |
-| **HTML** | Полноценный HTML-документ с `meta charset="utf-8"`. |
-| **JSON** | Массив объектов: `project`, `version`, `issue_id`, `subject`, `status`, `time`. |
-| **Excel (.xlsx)** | Merge cells, колонки `Hours`/`Spent Time`, итоги, автоширина, автофильтр, freeze panes. |
+| Консоль | Таблица или компактный вид (`--compact`). |
+| ODT | Требуется `odfpy`; формирование по шаблону. |
+| CSV | UTF-8 с BOM; полные значения `project`/`version` в каждой строке. |
+| Markdown | Компактная таблица. |
+| HTML | Полный HTML-документ; объединение ячеек групп через rowspan. |
+| JSON | Объекты `project`, `version`, `issue_id`, `subject`, `status`, `time` + опционально `activities`. |
+| XLSX | Объединение ячеек по проекту/версии, итоги, автоширина (максимум 80), автофильтр, freeze panes. |

-## Полный список флагов
-
-```
--date DATE          Диапазон дат: YYYY-MM-DD--YYYY-MM-DD
--compact            Компактный текстовый вывод вместо таблицы
--output PATH/FMT    Путь к файлу (.odt/.csv/.md/.html/.json/.xlsx)
-                     или bare-формат (xlsx/odt/...) — путь из конфига
--author NAME        Переопределить имя автора
--no-time            Не включать затраченное время в таблицу
--url URL            Переопределить Redmine URL
--api-key KEY        Переопределить Redmine API key
--config PATH        Путь к альтернативному .env-файлу
--verbose            Подробный вывод
--debug              Отладочный вывод
--version            Показать версию и выйти
--summary            Вывести сводку по времени в stderr
--user-id ID         Redmine ID пользователя для отчёта
--user-login LOGIN   Логин пользователя Redmine
--user-name NAME     Полное имя пользователя Redmine
--by-activity        Разбить время по типам активности
--init-config        Сгенерировать YAML-конфиг и выйти
--force              Перезаписать существующий конфиг (с --init-config)
--config-path PATH   Путь к YAML-конфигу (по умолчанию ~/.config/redmine-reporter/config.yml)
--commit             Сохранить отчёт в файл и зафиксировать период в конфиге
--send               Отправить отчёт по email после сохранения
-```
+Нюанс `--no-time`: физически удаляет колонку времени только CSV; в XLSX колонки остаются, но пустыми и без итогов; в остальных форматах — пустые значения.

 ## Разработка

@@ -308,17 +84,23 @@ redmine-reporter --summary

 ```bash
 pytest
+isort --check-only redmine_reporter tests
+black --check redmine_reporter tests
 ruff check redmine_reporter tests
 ruff format --check redmine_reporter tests
 mypy redmine_reporter
 ```

+CI — Gitea Actions (`.gitea/workflows/checks.yaml`): все шесть проверок на матрице Python 3.10–3.13.
+
 ## Безопасность

- Не коммитьте `.env`, API token, пароль или логин.
- YAML-конфиг имеет права `0600`, директория — `0700`.
- Рекомендуется хранить секреты через `${VAR}`, а не plaintext.
- Используйте аккаунт с минимальными правами, достаточными для чтения time entries и задач.
- Инструмент работает только в режиме чтения и не изменяет данные в Redmine.
- `REDMINE_URL` обязан использовать HTTPS: API-ключ передаётся в заголовках запроса, и без TLS он может быть перехвачен.
- `REDMINE_VERIFY=false` (или `verify_ssl: false`) отключает проверку TLS-сертификата — соединение уязвимо для MITM-атак; при старте выводится предупреждение. Используйте только в доверенной сети.
+- `REDMINE_URL` обязан использовать HTTPS: валидация отклоняет остальное, API-ключ передаётся в заголовках.
+- `verify_ssl` / `REDMINE_VERIFY`: `true` (по умолчанию), `false` (предупреждение о MITM-риске при старте) или путь к CA-bundle.
+- Конфиг создаётся с правами `0600`, директория — `0700`; при более широких правах выводится предупреждение.
+- Секреты храните через `${VAR}` в YAML или в переменных окружения, не в открытом виде.
+- Инструмент только читает данные из Redmine и ничего в нём не изменяет.
+
+## Лицензия
+
+MIT, см. [LICENSE](LICENSE).