Initial commit: VoIdeaAI - voice-first AI idea assistant

docs/env-management.md

@@ -0,0 +1,60 @@
+# Управление переменными окружения
+
+## Принцип
+
+Все настройки, которые меняются между окружениями — в переменных окружения. Никаких hardcoded значений.
+
+## Формат: .env
+
+```bash
+# === Core ===
+PROJECT_NAME=VoIdea
+PROJECT_ENV=production
+
+# === Server ===
+SERVER_HOST=0.0.0.0
+SERVER_PORT=8020
+
+# === Database (PostgreSQL only) ===
+DATABASE_URL=postgresql+asyncpg://voidea:password@localhost:5432/voidea
+
+# === JWT ===
+JWT_SECRET_KEY=your-secret-key
+JWT_ALGORITHM=HS256
+
+# === AI ===
+AI_YANDEX_KEY=
+AI_YANDEX_FOLDER_ID=
+AI_GIGACHAT_CLIENT_ID=
+AI_GIGACHAT_SECRET=
+```
+
+## Валидация при старте
+
+```python
+# app/core/config.py
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    database_url: str = "postgresql+asyncpg://voidea:password@localhost:5432/voidea"
+    jwt_secret_key: str = ""
+
+    @property
+    def sync_database_url(self) -> str:
+        return self.database_url.replace("+asyncpg", "")
+```
+
+## Синхронизация .env.example
+
+- `.env.example` в репозитории
+- Обновляется при каждом добавлении переменной
+- Все переменные с комментариями
+- Чувствительные значения пустые
+- Секции разделены `# === Name ===`
+
+## Secrets management
+
+| Окружение | Где хранить |
+|-----------|-------------|
+| Local | `.env` (в .gitignore) |
+| Production | GitHub Secrets / 1Password |