call-center/docs/runbooks/.env.production.checklist.md

.env.production Checklist (Track 9/11 QA Lab)

Use this checklist before enabling ASTERISK_BRIDGE_ENABLED=1.

1) File handling and secret hygiene

• Create local .env.production from .env.production.template.
• Keep .env.production out of git (it is ignored in .gitignore).
• Replace all placeholder values:
  • <replace-me>
  • <asterisk-linux-vm-host>
  • <platform_queue_id>
  • <platform_ai_queue_id_or_same_queue_id>
  • <postgres-host>
  • <rabbitmq-host>
• Verify that AMI/SFTP credentials are not copied into docs, commits, or screenshots.

2) Required environment variables

Core

• DATABASE_URL points to PostgreSQL (not SQLite).
• INTERACTION_SERVICE_URL is reachable from asterisk-bridge-service.
• VOICE_ADAPTER_SERVICE_URL is reachable.
• RECORDING_SERVICE_URL is reachable.

Track 9 bridge

• ASTERISK_BRIDGE_ENABLED=1
• ASTERISK_AMI_HOST / ASTERISK_AMI_PORT are correct.
• ASTERISK_AMI_USERNAME / ASTERISK_AMI_SECRET are correct.
• ASTERISK_AMI_EVENT_PREFIX=MVPCC unless your dialplan intentionally changed it.
• ASTERISK_QUEUE_MAP_JSON contains valid JSON object.
• Every queue_code in dialplan has a mapped platform queue_id.
• ASTERISK_BRIDGE_AUTH_MODE chosen intentionally:
  • legacy_headers for Track 9 QA baseline
  • bearer_first for transition hardening
  • bearer for strict service-token mode
• If bearer mode is used, APP_TOKEN_SECRET is the same across gateway/services/bridge runtime.
• ASTERISK_BRIDGE_AUTH_USER / ASTERISK_BRIDGE_AUTH_ROLE match expected service identity.
• VOICE_ADAPTER_TRUSTED_SERVICE_SUBJECTS includes svc:asterisk-bridge.
• RECORDING_IMPORT_TRUSTED_SERVICE_SUBJECTS includes svc:asterisk-bridge.
• For strict Track 9.1 mode, set RECORDING_IMPORT_ALLOW_ADMIN=0.

Track 11 call-control

• ASTERISK_CALLCONTROL_ENABLED=1 (в QA, если проверяете операторское управление звонком).
• ASTERISK_CALLCONTROL_ACTION_TIMEOUT_SECONDS задан (рекомендуемо 10).
• ASTERISK_OPERATOR_EXTENSION_MAP_JSON содержит mapping operator -> extension.
  • пример: {"operator_a":"2001","operator_b":"2002"}
• ASTERISK_TRANSFER_TARGET_MAP_JSON содержит mapping queue_code -> extension для blind transfer.
  • пример: {"voice_lab":"2001"}
• ASTERISK_CALLCONTROL_CLAIM_CONTEXT и ASTERISK_CALLCONTROL_TRANSFER_CONTEXT совпадают с dialplan contexts.

SFTP pickup

• ASTERISK_SFTP_HOST / ASTERISK_SFTP_PORT are correct.
• ASTERISK_SFTP_USERNAME / ASTERISK_SFTP_PASSWORD are correct.
• ASTERISK_SFTP_BASE_PATH points to the recording directory (default /var/spool/asterisk/monitor).

Voice AI V1 staging

• AI_VOICE_ENABLED=1 only for the pilot queues you intend to test.
• AI_VOICE_QUEUE_CONFIG_JSON contains the AI-first queue code from the dialplan.
  • example: {"voice_lab_ai":{"mode":"ai_first","agent_profile":"voice_support","handoff_queue_code":"voice_lab","language":"ru"}}
• AI_VOICE_RUNTIME_SERVICE_URL points to the HTTP runtime service, not the AudioSocket media endpoint.
• AI_VOICE_RUNTIME_TRUSTED_SERVICE_SUBJECTS includes svc:ai-voice-runtime.
• AI_VOICE_ASR_PROVIDER / AI_VOICE_TTS_PROVIDER are set intentionally.
• ASTERISK_TRANSFER_TARGET_MAP_JSON includes both the human and AI queue codes when they can hand off to the same operator group.
  • example: {"voice_lab":"2001","voice_lab_ai":"2001"}
• On the Asterisk VM, leave MVPCC_AI_AUDIOSOCKET_SERVICE= blank until the media listener is ready.
• After the media listener is available, verify app_audiosocket.so is loaded and MVPCC_AI_AUDIOSOCKET_SERVICE=<media-host>:<port> uses the raw AudioSocket address.

Event bus baseline (Track 8 compatibility)

• EVENT_BUS_ENABLED=1 in QA.
• EVENT_BUS_URL resolves to reachable RabbitMQ.

3) Preflight checks before first call

• Run migrations:
  • python scripts\migrate_core_db.py
• Run full regression:
  • pytest -q
• Start stack with production env loaded:
  • powershell -ExecutionPolicy Bypass -File scripts\start_track9_qa.ps1
• Bridge health:
  • GET /proxy/asterisk-bridge/health returns ok
• Bridge status:
  • GET /proxy/asterisk-bridge/asterisk/status shows ami_connected=true

4) Acceptance checks after test call 1001 -> 7000

• voice interaction created from Asterisk event flow.
• voice_events contain:
  • call.started with payload.source = "asterisk"
  • call.ended for the same call_id
• MVPCCRecordingReady led to uploaded recording in recording-service.
• Playback works in supervisor.
• Для Track 11:
  • оператор видит звонок в /operator -> блок Живые звонки
  • claim работает и пишет action log
  • hangup работает
  • blind transfer работает
• Run:
  • python scripts\asterisk_lab_smoke.py --base-url <gateway> --database-url <db> --require-recording
  • python scripts\track9_check.py --base-url <gateway> --database-url <db> --require-recording
  • python scripts\track9_collect_evidence.py --base-url <gateway> --database-url <db> --run-checks --require-recording

4.1) Voice AI control-plane smoke after test call 1001 -> 7100

• MVPCCCallStarted used QueueCode=voice_lab_ai.
• voice_ai_sessions row created for the call.
• ai_sessions row created with channel=voice.
• Interaction timeline contains ai.session_started.
• Operator UI shows an AI badge on the live or recent voice call card.
• GET /proxy/asterisk-bridge/asterisk/live-calls/{call_id}/ai-summary returns 200 once the AI summary exists.
• Human fallback path still works if MVPCC_AI_AUDIOSOCKET_SERVICE= is blank.

5) Failure policy

• If failed bridge events exist, inspect:
  • GET /proxy/asterisk-bridge/asterisk/events?status=failed
• Retry after fixing root cause:
  • POST /proxy/asterisk-bridge/asterisk/events/{bridge_event_id}/retry
• Do not mark Track 9 accepted until failed bridge events are resolved or explicitly waived.

6) Track 9.2 cutover handoff

• Prepare track9-cutover-sheet.template.md.
• Follow track9-2-production-cutover.md for controlled Helm rollout.
• Use scripts\track9_2_cutover.ps1 first in dry-run mode, then with -Execute during the approved window.