Services runbook (gateway + gRPC)

Каноническая модель

• Внешний ingress: только gateway (http://127.0.0.1:3000).
• Frontend (microfrontend/host) ходит только в /api (Vite proxy -> gateway).
• JWT проверяется только на gateway.
• Вызовы gateway -> сервисы идут только по gRPC, с x-service-api-key и контекстными metadata.

Актуальный набор сервисов и порты

Сервис	HTTP (health/admin)	gRPC	Статус интеграции в gateway
gateway	3000	-	ingress
auth	3001	5001	подключен
control	3002	5002	подключен
contact	3003	5003	подключен
company	3004	5004	подключен
pipe	3005	5005	подключен
orders	3006	5006	подключен
product	3007	5007	подключен
activity	3008	5008	подключен
platform	3009	5009	подключен
documents	3010	5010	подключен
reports	3011	5011	подключен
automation	3012	5012	подключен
search	3013	5013	подключен
audit	3014	5014	подключен
notification	3015	5015	подключен
billing	3016	5016	подключен

Обязательные переменные окружения

Где	Переменные
gateway	GATEWAY_SERVICE_API_KEY, GATEWAY_API_KEY_ID, JWT_SECRET, AUTH_GRPC_URL..PLATFORM_GRPC_URL, DATABASE_URL
доменные сервисы	AUTH_GRPC_URL для валидации service API key через ApiKeyGrpc.ValidateServiceApiKey
новые сервисы (B-пакет)	собственные GRPC_*_PORT/HTTP_PORT, storage/queue vars по домену

Локальный порядок запуска

1. cd fairflow/services
2. Infra: npm run start:infra
3. Seed gateway key: задать SEED_GATEWAY_SERVICE_API_KEY, выполнить npm run db:seed:auth, скопировать GATEWAY_SERVICE_API_KEY и GATEWAY_API_KEY_ID в gateway/.env
4. DB (если нужно): npm run db:provision
5. Core chain: auth -> control -> contact -> company -> pipe -> orders -> product -> activity -> platform -> gateway
6. Дополнительно поднимать documents/reports/automation/search/audit/notification/billing по необходимости

JWT_SECRET должен совпадать как минимум между auth и gateway.

Reflection и proto

• GRPC_REFLECTION_ENABLED=true включает reflection на сервисе (только dev).
• В production reflection держать выключенным.
• После изменений в .proto: npm run proto:descriptors.

Smoke-check

• GET /healthz на gateway и на HTTP health-портах сервисов -> 200.
• Прямые бизнес-запросы в сервисы (мимо gateway) не используются клиентом.
• В gateway логах видны outbound gRPC вызовы с x-request-id/traceparent.

Примечание по migration-state

• crm-grpc как агрегирующий сервис выведен из канонического runbook.
• Gateway уже содержит gRPC-клиентов и REST BFF endpoints для documents, reports, automation, search, audit, notification, billing.