2026-04-02 17:05:45 +05:00
commit 5374c202d9
338 changed files with 81297 additions and 0 deletions
@@ -0,0 +1,25 @@
# Stage 1 - Foundation + Environments (Weeks 1-3)
## Goal
Prepare a runnable technical baseline: on-prem deployment patterns, CI/CD, API contracts, RBAC, service monitoring.
## Scope
- Gateway skeleton
- auth-service, users API, audit-service
- health endpoints for all services
- OpenAPI stage 1 contracts
- event schema baseline
- docker-compose + Kubernetes + Helm baseline
- CI workflow
## Deliverables
- `deployment/*`
- `.github/workflows/ci.yml`
- `contracts/openapi/stage1-auth-users-health-audit.yaml`
- `contracts/events/*.json`
## Gate 1 DoD
- Auto deploy path documented
- Login + roles work
- Health endpoints available
- API/event contracts frozen
@@ -0,0 +1,21 @@
# Stage 2 - Operator Core (Weeks 4-7)
## Goal
Deliver real operator flow for `voice + Telegram` with interaction lifecycle.
## Scope
- customer-service (cards/search/history)
- interaction-service (create/assign/status/escalate/timeline)
- routing-service (queues/rules/route)
- voice-adapter-service (Asterisk events)
- telegram-adapter-service (webhook/messages)
## Deliverables
- operator core APIs in services
- stage 2 OpenAPI contracts
- smoke scripts and tests for e2e API-level scenarios
## Gate 2 DoD
- Operator can process both channels from unified interaction model
- Status and history are consistent
- Escalation and assignment work without manual workaround
@@ -0,0 +1,20 @@
# Stage 3 - Supervisor + Reporting + KB-lite (Weeks 8-10)
## Goal
Add manageability and analytics: realtime supervisor view, KPI core reporting, knowledge base support.
## Scope
- supervisor-service realtime state
- reporting-service KPI aggregation: SL, ASA, AHT, Abandon, FCR
- kb-service categories/articles/search
- stage 3 OpenAPI contracts
## Deliverables
- dashboard-ready supervisor API
- reporting export endpoint
- KB-lite APIs for operational usage
## Gate 3 DoD
- Supervisor sees realtime operational state
- KPI reports reproducible
- KB usable in operator flow
@@ -0,0 +1,22 @@
# Stage 4 - Pilot Hardening + Acceptance (Weeks 11-12)
## Goal
Stabilize and pass pilot acceptance.
## Scope
- load tests up to 100/100
- backup/restore drills
- security hardening checks
- UAT protocol and defect closure (P1/P2)
- final documentation pack
## Deliverables
- test protocols
- UAT evidence
- operational runbooks
- accepted MVP v1 baseline
## Gate 4 DoD
- Pilot passed
- SLA/KPI acceptance criteria confirmed
- System ready for post-MVP expansion
@@ -0,0 +1,126 @@
# Wave 2 - Post-MVP Backlog
Wave 2 starts only after MVP pilot sign-off is complete and Gate 4 is formally closed.
This document captures the first prioritized expansion backlog so pilot defects and
new features do not mix.
## Priority Order
### 1. LDAP / SSO
Goal:
- replace local-only auth as the primary enterprise login path
Expected outputs:
- LDAP or SSO integration design
- role mapping rules
- operational runbook for identity integration
Acceptance:
- enterprise login works without breaking current RBAC behavior
- fallback admin access is documented
### 2. Additional Channels
Goal:
- expand beyond the current MVP channel baseline
Expected outputs:
- `webchat` handling flow
- `email` intake flow
- external messenger backlog after `webchat` and `email`
Acceptance:
- new channels reuse the unified interaction model
- routing, history, and KPI ingestion stay consistent
### 3. Dedicated Supervisor/Admin UI
Goal:
- move beyond the single operator shell and provide dedicated operational consoles
Expected outputs:
- supervisor UI for realtime monitoring, control, and reporting
- admin UI for users, queues, rules, and configuration
Acceptance:
- critical supervisor and admin workflows no longer depend on the operator shell
### 4. Recording and Audio Operations
Goal:
- turn the current event-level recording placeholders into a usable product block
Expected outputs:
- recording storage model
- playback/download flow
- access control and retention rules
Acceptance:
- supervisors can find, review, and export recording artifacts safely
### 5. Advanced IVR and Voice Flow
Goal:
- introduce configurable IVR flows beyond current baseline voice event intake
Expected outputs:
- IVR flow model
- editable configuration or builder
- routing integration for IVR outcomes
Acceptance:
- IVR outcomes are traceable in interaction lifecycle and routing decisions
### 6. Full KPI Catalog
Goal:
- expand reporting from MVP core KPIs to the wider target metric model
Expected outputs:
- KPI mapping backlog based on the extended specification
- data model updates
- report coverage matrix
Acceptance:
- KPI definitions are reproducible and traceable to the specification
### 7. Scale-Up and Hardening
Goal:
- move from MVP pilot performance to target production scale
Expected outputs:
- capacity plan
- higher load targets
- scale validation on the target deployment profile
Acceptance:
- agreed performance target is met with documented evidence
### 8. Event Bus and Integrations
Goal:
- evolve the platform from contract-ready integration to operational event exchange
Expected outputs:
- message bus integration design
- service event publishing/consumption plan
- external integration sequencing
Acceptance:
- core domain events are delivered through the selected bus without contract drift
## Delivery Rules
- Wave 2 must be planned as a separate delivery track from MVP pilot closure.
- MVP defects remain in the MVP remediation lane until sign-off is complete.
- New Wave 2 scope is approved only after MVP accepted baseline is frozen.
## Status Update (2026-03-05)
- Track 9 (Asterisk AMI lab bridge) is accepted in QA evidence packs.
- Track 9.2 cutover prep is ready; production execute requires target context/secrets window.
- Track 10 is closed:
  - see `docs/acceptance/track10/track10-acceptance.md`.
- Next execution step: Track 11 (live voice control scope).
@@ -0,0 +1,65 @@
# Wave 2 / Track 10 - Live Voice Reliability and Realtime SLA
Track 10 starts after Track 9 QA acceptance is collected and frozen.
## Status Update (2026-03-05)
- Track 10 is closed using acceptance package:
  - `docs/acceptance/track10/track10-acceptance.md`
- Closure mode: `GO with exception`
  - direct p95 `started->ended` measured `33s` vs target `30s`
  - reliability gates for stuck lifecycle/import are green (`active_no_end=0`, `ended_no_recording_upload=0`)
- Follow-up latency tightening is moved to the next track.
## Goal
Move from "Asterisk integration works" to "voice lifecycle is predictably near-realtime".
Required outcome:
- `call.started` appears in supervisor flow quickly and consistently.
- `call.ended` is not delayed by reconciliation paths.
- recording upload latency is measured and controlled.
## Scope
In scope:
- latency/SLA instrumentation for voice lifecycle (`started -> ended -> recording`),
- stricter reconcile behavior for stale AMI events,
- automated latency report as an acceptance artifact,
- Track 10 acceptance checklist and evidence structure.
Out of scope:
- ARI call control,
- operator softphone controls,
- new business voice features.
## Baseline SLO (Track 10 target)
- p95 `call.started -> call.ended` <= `30s` for lab calls.
- p95 `call.ended -> recording uploaded` <= `45s`.
- unresolved `failed bridge events` = `0` for acceptance window.
## Deliverables
1. Latency report script:
   - `scripts/track10_voice_latency_report.py`
2. Runbook:
   - `docs/runbooks/track10-live-voice-reliability.md`
3. Acceptance evidence folder:
   - `docs/acceptance/track10/<timestamp>/`
4. Final decision doc:
   - `docs/acceptance/track10/track10-acceptance.md`
## Phase 1 (implemented slice)
Completed:
- added Track 10 latency report script with SLO thresholds and JSON artifacts,
- added `direct` vs `reconciled` split in latency metrics,
- updated bridge path so `recording.ready` can close call lifecycle immediately when `call.ended` is missing.
## Acceptance
Track 10 is accepted when:
- latency report is generated from real calls,
- all mandatory checks pass for the acceptance window,
- `GO` is signed in `track10-acceptance.md`.
@@ -0,0 +1,60 @@
# Wave 2 / Track 11 - Live Operator Voice Control
Status: `Accepted`
Track 11 introduced the first real operator call-control loop on top of the accepted Asterisk bridge.
## Goal
Move from event-only voice integration to operator-controlled live calls in the existing operator shell.
Accepted control path:
- operator sees a live inbound call in `/operator`
- operator answers media in external `MicroSIP/Zoiper`
- operator fixes ownership in the browser with `Принять в работу`
- operator can `Завершить` or `Передать`
Voice media stays outside the browser. No WebRTC in this track.
## Scope
In scope:
- bridge live-call routes under `/asterisk/live-calls`
- own-call RBAC for `operator`
- operator live-call block
- action log and replay-safe behavior
- Asterisk event `MVPCCOperatorConnected`
- QA acceptance with real call and recording playback
Out of scope:
- ARI
- attended transfer or conference
- embedded browser softphone
- business API redesign
## Deliverables
1. Migrations:
   - `migrations/sql/0011_track11_voice_control_sqlite.sql`
   - `migrations/sql/0011_track11_voice_control_postgres.sql`
2. Backend:
   - `services/asterisk_bridge_service/app.py`
3. Operator UI:
   - `ui/operator/index.html`
   - `ui/operator/app.js`
4. Asterisk templates:
   - `deployment/asterisk/pjsip.conf`
   - `deployment/asterisk/extensions.conf`
5. Evidence and docs:
   - `docs/runbooks/track11-live-operator-call-control.md`
   - `docs/acceptance/track11/track11-acceptance.md`
## Accepted baseline
Track 11 is frozen with these guarantees:
- live inbound call visibility works in `/operator`
- `claim`, `hangup`, and `blind transfer` persist in bridge action logs
- `call.connected` and `call.transferred` are written as voice events
- recording import and supervisor playback stay green
For the current operator UX, use the Track 12 runbook. Track 11 remains the control-path baseline.
@@ -0,0 +1,57 @@
# Wave 2 / Track 12 - Operator Voice UX Hardening
Status: `Accepted`
Track 12 hardens the accepted Track 11 voice-control baseline without changing the telephony architecture.
## Goal
Keep the current Asterisk plus `MicroSIP/Zoiper` model, but make the operator voice flow predictable and readable.
Accepted outcome:
- `/operator` shows only real bridge-backed calls
- active and recently ended calls are separated
- browser actions behave consistently
- recent calls stay visible briefly instead of disappearing immediately
## Scope
In scope:
- `GET /asterisk/recent-calls`
- additive live-call metadata
- operator UI split into `Активные звонки` and `Только что завершённые`
- clearer labels and SIP-versus-browser hint text
- removal of interaction-based live-call guessing
- QA acceptance for active/recent call behavior
Out of scope:
- WebRTC or browser softphone
- claim-first telephony redesign
- ARI
- attended transfer or conference
- production cutover
## Deliverables
1. Backend:
   - `services/asterisk_bridge_service/app.py`
   - `services/shared/models.py`
   - `gateway/app.py`
2. Operator UI:
   - `ui/operator/index.html`
   - `ui/operator/app.js`
   - `ui/operator/styles.css`
3. Evidence and docs:
   - `docs/runbooks/track12-operator-voice-ux.md`
   - `docs/acceptance/track12/track12-acceptance.template.md`
## Accepted baseline
Track 12 is frozen with these guarantees:
- `Живые звонки` never falls back to `interaction:int_*` placeholder cards
- `reconciled` service traces do not remove an active call early
- `hangup` and `blind transfer` move the card into the recent bucket
- recent cards stay visible for the short configured window
- Track 11 control-path behavior and recording playback remain green
This is the current operator voice UX baseline.
@@ -0,0 +1,45 @@
# Wave 2 / Track 14 - Browser Softphone (WebRTC, QA First)
Status: `Implemented, QA validation pending`
Track 14 adds the first browser-native operator media path on top of the accepted Track 11 and Track 12 voice baseline.
## Goal
Keep the accepted bridge-backed live-call model and move the operator media path into the browser for the first QA slice.
Implemented direction:
- direct Asterisk WSS
- inbound MVP only
- browser softphone coexists with `MicroSIP/Zoiper`
- existing bridge `claim/hangup/recent-calls` remains authoritative
## Deliverables
1. Bridge:
   - additive route: `/asterisk/browser-softphone/config`
   - additive status fields: `webrtc_enabled`, `webrtc_ws_url`
2. Operator shell:
   - `Browser Softphone` block
   - register/disconnect state
   - incoming call banner
   - `Answer`, `Hang up`, `Mute/Unmute`
   - microphone and speaker selectors
3. Asterisk lab assets:
   - `deployment/asterisk/http.conf`
   - `deployment/asterisk/rtp.conf`
   - updated `deployment/asterisk/pjsip.conf`
## Boundaries
Track 14 does not introduce:
- production cutover
- ARI
- browser-only mandatory mode
- DB schema changes
- WebRTC backend service outside Asterisk
The accepted voice system of record remains:
- bridge live/recent calls
- bridge action log
- recording import and supervisor playback
@@ -0,0 +1,30 @@
# Track 15 - Telegram Chat
Status: `implemented`
## Scope
- real Telegram Bot API webhook
- one persistent thread per `chat_id`
- 2-way text chat
- separate `Telegram` page in `/operator`
## What changed
- `telegram-adapter-service` now owns Telegram threads and thread messages
- new thread/message routes exist under `/integrations/telegram/threads/*`
- inbound messages reuse the same thread and linked interaction
- a closed Telegram interaction is reactivated on new inbound activity
- operator replies go through Telegram `sendMessage`
## Out of scope
- Telegram voice/video calls
- media/file workflow
- admin UI for bot setup
## Acceptance focus
- first inbound message creates thread + interaction
- repeated inbound on the same `chat_id` reuses the same thread
- operator can claim and reply from the dedicated `Telegram` page
@@ -0,0 +1,11 @@
# Sequential Execution Rules
1. Stages are executed strictly in sequence.
2. A stage starts only when previous gate is formally closed.
3. Scope changes are deferred to the next stage backlog.
4. Weekly checkpoint + demo is mandatory.
5. Every stage has:
   - scope
   - deliverables
   - tests
   - gate checklist