Initial commit: VoIdeaAI - voice-first AI idea assistant

template/docs/09-logging.md

@@ -0,0 +1,78 @@
+# Логирование
+
+---
+
+## Формат строки лога
+
+```
+[ISO8601] [LEVEL] [component] message key=val
+```
+
+Пример:
+```
+2026-05-10T14:30:00.000Z INFO [auth] User logged in user_id=abc123
+2026-05-10T14:30:01.000Z WARNING [ai] Yandex GPT timeout retry=1 max_retries=2
+2026-05-10T14:30:02.000Z ERROR [sync] Sync failed for user_id=abc123 error="Connection refused"
+```
+
+---
+
+## Уровни по слоям
+
+| Слой | DEBUG | INFO | WARNING | ERROR |
+|------|-------|------|---------|-------|
+| **API** | Параметры запроса | Request обработан | — | 5xx ошибки |
+| **Service** | Входные данные | Операция выполнена | Превышен лимит | Ошибка БД |
+| **Integration** | Raw ответ провайдера | Успешный вызов | Timeout, retry | Внешний API ошибка |
+| **Agent** | Checksum вычислен | Агент выполнен | Версия не совпала | Ошибка выполнения |
+
+---
+
+## Правила
+
+- **Запрещены f-строки в logger.** Только %s (lazy evaluation):
+  ```python
+  # ПЛОХО:
+  logger.info(f"User {user_id} logged in")
+  
+  # ХОРОШО:
+  logger.info("User %s logged in", user_id)
+  ```
+
+- **Структурированные данные** передавайте как extra:
+  ```python
+  logger.info("Idea analyzed", extra={"idea_id": idea_id, "duration_ms": duration})
+  ```
+
+---
+
+## Sensitive Data
+
+**Никогда не логировать:**
+- Пароли (даже хэш)
+- JWT токены
+- API keys и секреты
+- Email в открытом виде (логировать user_id)
+- IP адреса полностью (маскировать: 195.208.*.*)
+
+---
+
+## Конфигурация
+
+```python
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s.%(msecs)03dZ %(levelname)s [%(name)s] %(message)s",
+    datefmt="%Y-%m-%dT%H:%M:%S",
+)
+```
+
+---
+
+## [ASK] Вопросы по логированию
+
+- Структурированное логирование (JSON) или текстовое? (JSON — для production)
+- Отправлять логи в централизованную систему? (рекомендуется для production)
+- Нужен ли audit log для операций с данными? (да, если регуляторные требования)