SRV-26 — Real-time events — back-office stream and reseller live order status (SSE)
Two permission-filtered SSE streams fed by the outbox: the back-office stream (orders, check-ins, tours, positions, stock alerts, pending accounts, returns, claims) and each user's own stream for the reseller app and web (order status changes, assisted orders, ticket replies, returns).
| Field | Details |
|---|---|
| Task code | SRV-26 |
| Phase | P1 — V1 build & integration |
| Product scope | V1 |
| Status | Done (Mon 19 Oct 2026) |
| Start | Mon 19 Oct 2026 |
| Due | Mon 19 Oct 2026 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | — |
| Effort | 0.5 person-day(s) planned · 3 from scratch · size XS |
| Area · app | Server · server |
| Depends on | SRV-16, SRV-21 |
| Unblocks | DSH-08, MOB-12 |
| Milestones | Server V1 feature-complete |
Summary
Two permission-filtered SSE streams fed by the outbox: the back-office stream (orders, check-ins, tours, positions, stock alerts, pending accounts, returns, claims) and each user's own stream for the reseller app and web (order status changes, assisted orders, ticket replies, returns).
Description
Decision 3 makes order status real-time for resellers, and the back-office needs live supervision of orders and the field (SYN-07, FLD-13, ORD-15; cahier §5.3, §6.4). This task delivers two Server-Sent Events streams fed by the outbox dispatcher: the back-office stream admin.events.stream (/v1/admin/events) carrying orders to confirm and status changes, check-ins, tour starts/suspensions/closings, throttled delegate positions, stock alerts, pending accounts, return requests and after-sales claims — each event filtered by the viewer's permissions and scope — and each user's own stream events.stream (/v1/events) used by the reseller app and web for their order status changes, assisted orders awaiting confirmation, ticket replies, return updates and unread-count changes. It uses Redis pub/sub for fan-out across api instances, per-user Redis streams for Last-Event-ID resume, heartbeats, and proxy settings that disable buffering. Out of scope: notifications themselves (SRV-08) and the UI consuming the streams (DSH-08, WEB-04, Imad's apps).
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | SSE endpoint helpers on Express (text/event-stream responses) with auth by cookie or bearer, heartbeat every 25 s and per-user connection limit | Anis |
| 2 | Outbox → Redis pub/sub publisher with event envelopes (id, type, occurredAt, payload) defined in packages/contracts | Anis |
| 3 | Back-office event catalogue and permission/scope filter (orders.view, field.view, stock.view, crm.validate, support.view) | Anis |
| 4 | Reseller event catalogue: order.status_changed, order.assisted_pending, ticket.replied, return.status_changed, notifications.unread_count | Anis |
| 5 | Per-user/per-channel Redis stream with bounded retention for Last-Event-ID resume; reset event when the id is too old | Anis |
| 6 | Position throttling (one position event per delegate per 30 s) for the live map | Anis |
| 7 | Traefik/Dokploy configuration: no response buffering, long timeouts for /v1/events and /v1/admin/events | Anis |
| 8 | Flutter SSE client behaviour (reconnect with backoff, refetch on reset, close when backgrounded) | Imad |
Deliverables
- apps/server/src/modules/notifications/realtime/{sse.ts,publisher.ts,admin-stream.ts,user-stream.ts,filters.ts}
- packages/contracts/src/events.ts (event envelope and event type schemas)
- Proxy configuration notes in /docs/srs/deployment-and-operations
Acceptance criteria
- A back-office status change reaches the reseller's open web page within 2 seconds (ORD-15)
- A delegate check-in appears on the back-office stream of users with field.view only (FLD-13, ACL-05)
- A reseller never receives an event about another reseller's order
- After a 2-minute disconnect, reconnecting with Last-Event-ID replays the missed events in order; an id older than retention yields a reset event
- The connection stays open behind the production proxy for more than 30 minutes with heartbeats
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| SYN-07 | Real-time events: to the back-office (orders, visits, tours, positions) and to the reseller apps (their own order status changes) | V1 |
| FLD-13 | Live follow-up in the back-office: delegates on tour, positions, visit progress | V1 |
| ORD-15 | Order status changes reach the reseller in real time (live update in the app and web) and as a notification | V1 |
Screens
API surface
| Endpoint group | Operations |
|---|---|
| Real-time events (SSE) | 1 |
| Notifications & announcements | 10 |
Test measures
- Integration test with two api instances and Redis: event published on one, delivered via the other
- Leakage test: two resellers and a delegate connected, events checked per recipient
- Soak test with 500 concurrent SSE connections on staging
Risks
- Mobile networks drop long-lived connections — clients always refetch the order on reconnect, and push notifications remain the delivery guarantee
- Many idle connections exhaust api resources — connection limits per user and horizontal scaling of the api app
KPI
- Delivered by Mon 19 Oct 2026 within 0.5 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.
SRV-20 — Returns & after-sales (SAV) module
Return requests on delivered orders, approval, reception with automatic RETURN stock movements, credit notes; after-sales claims as tickets on order items with photos, resolved by replacement order, return, credit note, repair or rejection.
SRV-40 — Smart notification triggers & jobs (V1 types, caps, priority, merge)
Rule-based triggers for the V1 smart notifications of document 03 — new arrival, back in stock, limited quantity, flash sale, price drop, commercial push, new catalogue, trending, abandoned cart, reorder reminder, complementary product — plus the anti-fatigue layer (weekly cap, priority, merge, per-product cool-down, group opt-out) and action labels.