flea/CONFIGURATION.md

# Руководство по конфигурации

Этот документ описывает, как настроить микросервисную систему NOCR для различных сценариев развертывания.

## Содержание

1. [Обзор системы конфигурации](#обзор-системы-конфигурации)
2. [Сценарии развертывания](#сценарии-развертывания)
   - [Локальная разработка (VS Code)](#локальная-разработка-vs-code)
   - [Docker Compose](#docker-compose)
   - [Kubernetes](#kubernetes)
3. [Приоритет конфигурации](#приоритет-конфигурации)
4. [Настройки для конкретных сервисов](#настройки-для-конкретных-сервисов)
5. [Режим отладки](#режим-отладки)
6. [Устранение неполадок](#устранение-неполадок)

---

## Обзор системы конфигурации

Система использует многоуровневый подход конфигурации ASP.NET Core со следующими источниками (от низшего к высшему приоритету):

1. `appsettings.json` - Базовая конфигурация (коммитится в git)
2. `appsettings.{Environment}.json` - Настройки для конкретного окружения (некоторые коммитятся, некоторые нет)
3. User Secrets - Секреты только для разработки (хранятся локально, не в git)
4. **Переменные окружения** - **Наивысший приоритет** (переопределяют всё)

### Важные примечания

- **Никогда не коммитьте секреты в git**
- Используйте файлы `.example` как шаблоны
- Переменные окружения всегда имеют наивысший приоритет
- Каждый сервис имеет свои требования к конфигурации

---

## Сценарии развертывания

### Локальная разработка (VS Code)

Для отладки отдельных сервисов в VS Code:

#### Шаг 1: Создание конфигурации для окружения

Для каждого сервиса, который вы хотите запустить, создайте `appsettings.Development.json` из примера:

```bash
# Telegram Listener
cd telegram-listener/src/Nocr.TelegramListener.Host
cp appsettings.Development.json.example appsettings.Development.json

# Text Matcher
cd text-matcher/src/Nocr.TextMatcher.Host
cp appsettings.Development.json.example appsettings.Development.json

# Users
cd users/src/Nocr.Users.Host
cp appsettings.Development.json.example appsettings.Development.json

# Telegram Client
cd telegram-client/src/Nocr.TelegramClient.Host
cp appsettings.Development.json.example appsettings.Development.json
```

#### Шаг 2: Заполните ваши значения

Отредактируйте каждый файл `appsettings.Development.json` и замените placeholder-значения на ваши реальные учетные данные.

**Пример для Telegram Listener:**
```json
{
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://admin:admin@localhost:5672/"
  },
  "WTelegramClientOptions": {
    "ApiId": "22101230",
    "ApiHash": "c72f884d8eb84cb7134a14362bff060b",
    "PhoneNumber": "79167310711"
  }
}
```

#### Шаг 3: Альтернатива - использование переменных окружения

Вместо создания `appsettings.Development.json`, вы можете использовать переменные окружения в `.vscode/launch.json`:

```json
{
  "name": "Запуск сервиса",
  "type": "coreclr",
  "request": "launch",
  "env": {
    "ASPNETCORE_ENVIRONMENT": "Development",
    "RebusRabbitMqOptions__ConnectionString": "amqp://admin:admin@localhost:5672/",
    "WTelegramClientOptions__ApiId": "22101230",
    "WTelegramClientOptions__ApiHash": "c72f884d8eb84cb7134a14362bff060b",
    "WTelegramClientOptions__PhoneNumber": "79167310711"
  }
}
```

**Примечание:** Используйте двойное подчеркивание `__` для представления вложенных секций конфигурации в переменных окружения.

#### Шаг 4: Запуск инфраструктуры

Вам нужны работающие RabbitMQ и базы данных:

```bash
# Запустить только инфраструктурные сервисы
docker-compose up nocr-rabbitmq nocr-text-matcher-db nocr-users-db -d
```

#### Шаг 5: Отладка в VS Code

Нажмите F5 или используйте панель Run and Debug для запуска вашего сервиса.

---

### Docker Compose

Для запуска всей системы локально с Docker:

#### Шаг 1: Создание файла .nocr.env

```bash
cd /путь/к/корню/проекта
cp .nocr.env.example .nocr.env
```

#### Шаг 2: Редактирование .nocr.env

Откройте `.nocr.env` и заполните ваши реальные учетные данные:

```bash
# Telegram Listener - получить на https://my.telegram.org/apps
WTelegramClientOptions__ApiId=22101230
WTelegramClientOptions__ApiHash=c72f884d8eb84cb7134a14362bff060b
WTelegramClientOptions__PhoneNumber=79167310711

# Telegram Client Bot - получить у @BotFather
TelegramBotOptions__Token=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# Опционально: включить отладочное логирование
# NOCR_DEBUG_MODE=true
```

#### Шаг 3: Создание конфигурационных файлов для DockerCompose

Каждому сервису нужен `appsettings.DockerCompose.json`:

```bash
# Для каждого сервиса
cd telegram-listener/src/Nocr.TelegramListener.Host
cp appsettings.DockerCompose.json.example appsettings.DockerCompose.json

cd text-matcher/src/Nocr.TextMatcher.Host
cp appsettings.DockerCompose.json.example appsettings.DockerCompose.json

cd users/src/Nocr.Users.Host
cp appsettings.DockerCompose.json.example appsettings.DockerCompose.json

cd telegram-client/src/Nocr.TelegramClient.Host
cp appsettings.DockerCompose.json.example appsettings.DockerCompose.json
```

**Примечание:** Эти файлы содержат имена хостов Docker-сети (например, `nocr-rabbitmq:5672` вместо `localhost:5672`).

#### Шаг 4: Запуск всех сервисов

```bash
docker-compose up
```

Или со сборкой:

```bash
docker-compose up --build
```

#### Шаг 5: Проверка работоспособности сервисов

- Telegram Listener: http://localhost:5040/health
- Text Matcher: http://localhost:5041/health
- Users: http://localhost:5042/health
- Telegram Client: http://localhost:5050/health
- RabbitMQ Management: http://localhost:15672 (admin/admin)

---

### Kubernetes

Для production-развертывания на Kubernetes:

#### Шаг 1: Создание Kubernetes Secrets

**НЕ используйте файл `.nocr.env` в K8s.** Вместо этого создайте Secrets:

```bash
# Создать namespace
kubectl create namespace nocr

# Создать secrets для Telegram Listener
kubectl create secret generic telegram-listener-secrets \
  --from-literal=WTelegramClientOptions__ApiId=22101230 \
  --from-literal=WTelegramClientOptions__ApiHash=c72f884d8eb84cb7134a14362bff060b \
  --from-literal=WTelegramClientOptions__PhoneNumber=79167310711 \
  -n nocr

# Создать secrets для Telegram Client
kubectl create secret generic telegram-client-secrets \
  --from-literal=TelegramBotOptions__Token=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz \
  -n nocr
```

#### Шаг 2: Ссылка на Secrets в Deployment

Пример манифеста Kubernetes deployment:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: telegram-listener
  namespace: nocr
spec:
  template:
    spec:
      containers:
      - name: telegram-listener
        image: nocr-telegram-listener:latest
        env:
        - name: ASPNETCORE_ENVIRONMENT
          value: "Production"
        envFrom:
        - secretRef:
            name: telegram-listener-secrets
```

#### Шаг 3: Создание appsettings.Production.json

Создайте production-конфигурационные файлы с именами сервисов K8s:

```json
{
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://admin:admin@rabbitmq-service:5672/"
  }
}
```

**Примечание:** Секреты из переменных окружения переопределят эти значения.

#### Шаг 4: Деплой

```bash
kubectl apply -f deployment/
```

---

## Приоритет конфигурации

Понимание приоритета критически важно при устранении проблем с конфигурацией.

### Порядок приоритета (от низшего к высшему)

1. ⬇️ `appsettings.json` (базовый)
2. ⬆️ `appsettings.{Environment}.json` (например, Development, DockerCompose, Production)
3. ⬆️ User Secrets (только Development)
4. ⬆️⬆️ **Переменные окружения (ВСЕГДА ВЫИГРЫВАЮТ)**

### Пример сценария

Если у вас есть:

- `appsettings.json`: `"ConnectionString": ""`
- `appsettings.DockerCompose.json`: `"ConnectionString": "amqp://admin:admin@nocr-rabbitmq:5672/"`
- Переменная окружения: `RebusRabbitMqOptions__ConnectionString=amqp://admin:admin@localhost:5672/`

**Результат:** Переменная окружения побеждает! Подключение будет использовать `localhost:5672`.

Именно поэтому мы удалили `appsettings.protected.json` - он неправильно переопределял настройки Docker Compose.

---

## Настройки для конкретных сервисов

### Telegram Listener

**Обязательная конфигурация:**

```json
{
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://user:pass@host:port/"
  },
  "WTelegramClientOptions": {
    "ApiId": "YOUR_API_ID",
    "ApiHash": "YOUR_API_HASH",
    "PhoneNumber": "YOUR_PHONE_NUMBER"
  }
}
```

**Как получить учетные данные Telegram:**
1. Посетите https://my.telegram.org/apps
2. Войдите с вашим номером телефона
3. Создайте новое приложение
4. Скопируйте `api_id` и `api_hash`

---

### Text Matcher

**Обязательная конфигурация:**

```json
{
  "ConnectionStrings": {
    "TextMatcherContext": "server=host;port=3306;database=nocr_text_matcher;uid=root;pwd=password"
  },
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://user:pass@host:port/"
  }
}
```

**Порты по окружениям:**
- Development: `localhost:3316`
- Docker Compose: `nocr-text-matcher-db:3306`
- Kubernetes: `text-matcher-db-service:3306`

---

### Users

**Обязательная конфигурация:**

```json
{
  "ConnectionStrings": {
    "UsersContext": "server=host;port=3306;database=nocr_users;uid=root;pwd=password"
  }
}
```

**Порты по окружениям:**
- Development: `localhost:3326`
- Docker Compose: `nocr-users-db:3306`
- Kubernetes: `users-db-service:3306`

---

### Telegram Client

**Обязательная конфигурация:**

```json
{
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://user:pass@host:port/"
  },
  "UsersRestEaseOptions": {
    "BasePath": "http://users-service:8080"
  },
  "TextMatcherRestEaseOptions": {
    "BasePath": "http://text-matcher-service:8080"
  },
  "TelegramBotOptions": {
    "Token": "YOUR_BOT_TOKEN"
  }
}
```

**Как получить Bot Token:**
1. Откройте Telegram и найдите @BotFather
2. Отправьте команду `/newbot`
3. Следуйте инструкциям для создания вашего бота
4. Скопируйте предоставленный токен

---

## Режим отладки

Включите режим отладки для вывода маскированных значений конфигурации при запуске.

### Как включить

Установите переменную окружения:

```bash
export NOCR_DEBUG_MODE=true
```

Или в `.nocr.env`:

```bash
NOCR_DEBUG_MODE=true
```

Или в `docker-compose.yml`:

```yaml
environment:
  NOCR_DEBUG_MODE: "true"
```

### Пример вывода

Когда режим отладки включен, вы увидите маскированную конфигурацию при запуске:

```
=== [NOCR_DEBUG] Значения конфигурации ===
[NOCR_DEBUG] RebusRabbitMqOptions:
[NOCR_DEBUG]   ConnectionString: amqp://admin:***@nocr-rabbitmq:5672/
[NOCR_DEBUG]   InputQueueName: nocr.telegram.listener.queue
[NOCR_DEBUG]   DirectExchangeName: nocr.direct
[NOCR_DEBUG]   TopicsExchangeName: nocr.topics
[NOCR_DEBUG] WTelegramClientOptions:
[NOCR_DEBUG]   ApiId: 22101230
[NOCR_DEBUG]   ApiHash: c7...0b
[NOCR_DEBUG]   PhoneNumber: 79...11
=== [NOCR_DEBUG] Конец конфигурации ===
```

**Безопасность:** Пароли и секреты автоматически маскируются для защиты конфиденциальных данных.

---

## Устранение неполадок

### Проблема: Сервис не может подключиться к RabbitMQ

**Симптомы:**
```
Connection refused to nocr-rabbitmq:5672
```

**Решение:**
1. Проверьте, работает ли RabbitMQ: `docker-compose ps nocr-rabbitmq`
2. Включите режим отладки: `NOCR_DEBUG_MODE=true`
3. Проверьте ConnectionString в выводе отладки
4. Для Docker Compose убедитесь, что hostname - `nocr-rabbitmq:5672`, НЕ `localhost:5672`
5. Проверьте, не переопределяет ли переменная окружения appsettings

---

### Проблема: Сервис не может подключиться к базе данных

**Симптомы:**
```
Unable to connect to any of the specified MySQL hosts
```

**Решение:**
1. Проверьте, что база данных запущена: `docker-compose ps nocr-text-matcher-db`
2. Включите режим отладки для просмотра маскированной строки подключения
3. Проверьте hostname в строке подключения:
   - Docker Compose: `nocr-text-matcher-db:3306`
   - Локальная разработка: `localhost:3316`
4. Подождите прохождения healthcheck (может занять 10-30 секунд при первом запуске)

---

### Проблема: Значения конфигурации не применяются

**Симптомы:**
- Настройки в `appsettings.Development.json` игнорируются
- Сервис использует неправильную конфигурацию

**Решение:**
1. Проверьте, что `ASPNETCORE_ENVIRONMENT` установлен правильно:
   - VS Code: `Development`
   - Docker Compose: `DockerCompose`
   - K8s: `Production`
2. Включите режим отладки для просмотра загруженных значений
3. Проверьте переменные окружения, переопределяющие ваши настройки
4. Помните: **Переменные окружения всегда выигрывают!**

---

### Проблема: Секреты раскрыты в логах

**Решение:**
- Режим отладки автоматически маскирует конфиденциальные значения
- Никогда не логируйте конфигурацию в production без маскировки
- Проверьте формат вывода отладки в `Startup.cs`:
  - Пароли: `amqp://user:***@host`
  - Секреты: `ab...yz` (только первые 2 + последние 2 символа)

---

### Проблема: Отсутствует файл .nocr.env

**Симптомы:**
```
docker-compose up падает с ошибкой отсутствующих переменных окружения
```

**Решение:**
1. Скопируйте файл-пример: `cp .nocr.env.example .nocr.env`
2. Заполните ваши реальные значения
3. Убедитесь, что `.nocr.env` находится в корне проекта (на том же уровне, что и `docker-compose.yml`)

---

## Краткая справка

### Соглашение об именовании переменных окружения

ASP.NET Core использует двойное подчеркивание `__` для представления вложенной JSON-структуры:

```bash
# JSON: { "Section": { "Key": "Value" } }
# Переменная окружения:
Section__Key=Value

# Примеры:
WTelegramClientOptions__ApiId=12345
RebusRabbitMqOptions__ConnectionString=amqp://localhost
```

### Расположение файлов

```
flea/                                   # Корень проекта
├── .nocr.env                          # Ваши секреты (gitignored)
├── .nocr.env.example                  # Шаблон (коммитится)
├── docker-compose.yml                 # Ссылается на .nocr.env
│
├── telegram-listener/
│   └── src/Nocr.TelegramListener.Host/
│       ├── appsettings.json                        # Базовый (коммитится)
│       ├── appsettings.Development.json            # Локальная разработка (gitignored)
│       ├── appsettings.Development.json.example    # Шаблон (коммитится)
│       ├── appsettings.DockerCompose.json          # Docker (gitignored)
│       └── appsettings.DockerCompose.json.example  # Шаблон (коммитится)
│
└── [та же структура для text-matcher, users, telegram-client]
```

---

## Рекомендации по безопасности

1. ✅ **Никогда не коммитьте секреты** - используйте файлы `.example` как шаблоны
2. ✅ **Используйте переменные окружения** для конфиденциальных данных в production
3. ✅ **Используйте K8s Secrets** для развертывания в Kubernetes
4. ✅ **Включайте режим отладки** только при устранении неполадок
5. ✅ **Ротируйте учетные данные** регулярно
6. ✅ **Используйте User Secrets** для локальной разработки (опционально)
7. ❌ **Не коммитьте** `.nocr.env` или `appsettings.*.json` (кроме файлов `.example`)
8. ❌ **Не используйте** `appsettings.protected.json` (удален из кода)

---

## Дополнительные ресурсы

- [Документация конфигурации ASP.NET Core](https://learn.microsoft.com/ru-ru/aspnet/core/fundamentals/configuration/)
- [Переменные окружения Docker Compose](https://docs.docker.com/compose/environment-variables/)
- [Kubernetes Secrets](https://kubernetes.io/ru/docs/concepts/configuration/secret/)
- [Документация Telegram API](https://core.telegram.org/api)
- [Telegram Bot API](https://core.telegram.org/bots/api)