Notifications matrix

The cahier asks for notifications « Push, in-app, WhatsApp, SMS ou email selon le type d'événement » (cahier §8), « Notifications automatiques à chaque changement important » of an order (§4.4) and « Chaque changement de statut doit être daté et notifié » (§5.4); important events are also kept in the activity journal (§2.1). This page turns that into one table per domain: which event, who receives it, through which channels, in which preference category, where a tap leads, and which template renders it.

It covers NOT-01 to NOT-08, ORD-06, ORD-15 and SYN-07. It is the seed of the NotificationRule and NotificationTemplate tables built in SRV-08 and SRV-26, edited in the back-office on BO-58 (DSH-10), rendered by the apps in MOB-08, MRA-08, MRA-10 and MDA-11, and worded by DQA-10. After go-live, BO-58 is authoritative; changes made there are reported here.

Two product decisions taken by the team on 17 October 2026 shape this page: no order is confirmed automatically — every new order lands in the back-office « Commandes à confirmer » queue (ORD-14, BO-41); and every order status change reaches the reseller live and as a notification — the open reseller app or web updates through Server-Sent Events, and a push plus an inbox entry are always produced (ORD-15). Notifications never show stock quantities to resellers (STK-07).

HOCO's document 03 (18 October 2026) adds the smart notifications: every reseller notification gets a NotificationGroup (the section of the Notification Centre) and an action button, and rule-based commercial events are added (smart notifications, rows in Smart notifications).

How a notification is producedCopy Anchor Link

1. A module changes state and writes an OutboxEvent (eventKey, entityType, entityId, actorUserId, versioned payload) in the same database transaction. Nothing is sent from a request handler.
2. The worker dispatches each outbox row at least once to: the back-office SSE stream, the per-user SSE stream, analytics aggregates, CRM automation and the notification service.
3. The notification service loads the NotificationRule rows of the event key: for each recipient resolver, the channels, the category, the collapse key, the merge window and the time-to-live.
4. Recipients are resolved (table below), then filtered: actor rule, account status, preferences, quiet hours and caps.
5. Templates are rendered per recipient locale (fr in V1; ar and en keys exist and fall back to fr, NFR-06).
6. One Notification row (the inbox entry, channel IN_APP) is written per recipient, then one NotificationDelivery row per external channel, each sent from its own queue. The user's open apps receive notification.created on their SSE stream to update the badge.
7. Re-processing an outbox row never sends twice: NotificationDelivery is unique on (outboxEventId, recipientUserId, channel).

Live updates versus notificationsCopy Anchor Link

For an order status change the reseller receives all three: the SSE event refreshes the open screen within seconds, the push reaches a closed app, and the inbox keeps the dated history. When the app is in the foreground, it shows the push as an in-app banner instead of a system notification, and shows nothing if the user is already on that order's screen (the screen has just been refreshed by SSE). Both SSE streams resume with Last-Event-ID; events missed while the app was closed are not replayed — the app reloads the screen on resume and the inbox covers history.

Assumption — the return and claim events of the back-office stream (return.requested, ticket.created for AFTER_SALES) are named here and in SRV-26; they still have to be added to the event list of admin.events.stream in endpoints.json.

ChannelsCopy Anchor Link

SSE appears in the matrix as a reminder that the open app updates live; it is not a NotificationChannel and writes no inbox row.

Critical SMS whitelistCopy Anchor Link

SMS costs money per message and per segment, so it is reserved for one-time codes and for messages a user must receive even with no app installed or push blocked. The whitelist is a setting (notifications.smsEvents); adding an event to it is a cost decision for HOCO.

An announcement (message) whose sender ticks the SMS channel (communication.validate) is the one exception: that SMS goes out outside the whitelist, with the announcement's smsText — the cost decision is taken per announcement. Like an announcement's e-mail, it is on for a recipient unless they switched the channel off (SRV-42). Until the SMS gateway is chosen (D-13), SMS are simulated (logged) outside production and fail in production.

RecipientsCopy Anchor Link

Filters applied to every recipient:

1. Actor rule — the user who performed the action is not notified of it (the screen already confirms it), except SECURITY events and the reseller's own order.submitted (its push confirms reception when the app is closed right after checkout).
2. Account status — SUSPENDED and DISABLED users receive nothing but account.suspended and SECURITY messages.
3. Preferences — external channels only; the inbox always receives (preferences).
4. Quiet hours and caps — below.

The matrixCopy Anchor Link

Channels: IN_APP inbox · PUSH · SMS · EMAIL · SSE live update of the open app. Deep links give the screen and the in-app route ({…} are identifiers). Digest means the event is batched into the staff email digest of 08:00 rather than sent alone. Rel. is the product release.

OrdersCopy Anchor Link

Assumption — order.confirmation_overdue and its setting are proposed here because every order now waits for a human (§1b); they need adding to the settings catalogue.

Assisted ordersCopy Anchor Link

Returns and after-salesCopy Anchor Link

Returns and after-sales claims are V1 (ORD-13, SUP-04, FIN-08); the open reseller app follows them live through return.status_changed and ticket.replied.

A replacement order created by REPLACEMENT is an order like any other: it enters the « Commandes à confirmer » queue and produces the order events above.

Accounts and usersCopy Anchor Link

FinanceCopy Anchor Link

The OVERDUE status itself exists in V1 (finance dashboard); only the reminders are V2 (FIN-07).

StockCopy Anchor Link

Stock events go to staff only. Resellers and guests never receive a quantity — not in notifications, not in the apps; at most a product shown « En rupture » (STK-07).

PromotionsCopy Anchor Link

Guests receive no notification (no account, no device registration with a user).

Smart notificationsCopy Anchor Link

From HOCO's document 03 (18 October 2026), specified on smart notifications (NOT-09 to NOT-17). Every row is PROMOTIONAL, goes to resellers only, carries a NotificationGroup and an action, and is subject to the caps and priority. None uses SMS. The Action column gives the default button label.

The French copy of these templates is on smart notifications.

Smart notification settingsCopy Anchor Link

Business settings (BO-64, admin.settings) that tune the rows above; defaults from HOCO's document 03 (D-39, D-43, D-44).

Field operationsCopy Anchor Link

Support and communicationCopy Anchor Link

SecurityCopy Anchor Link

Platform jobsCopy Anchor Link

Deliberately not notifiedCopy Anchor Link

French copyCopy Anchor Link

Proposed copy for every template, to be finalised by Akram in DQA-10 and loaded as the fr seed. Rules:

1. Lengths are measured on the rendered text with typical values: push/in-app title ≤ 40 characters, body ≤ 120; SMS ≤ 160 characters in the GSM-7 alphabet (one segment); email subject ≤ 70.
2. Variables are written {{camelCase}}. Free-text variables are truncated by the renderer: reason and subject to 40 characters, excerpt to 50, store names to 25, product names to 30 — with an ellipsis.
3. Formats: amounts 125 000,00 DA (TTC unless stated); dates 03/11/2026 or 03/11; times 14:32 (24 h, Africa/Algiers); business numbers as stored (CMD-2026-000158).
4. Tone: vous, short, factual, one action per message; no quantity of stock; no personal data beyond the store name in a push (pushes transit through Google); never a code or a password in a push.
5. SMS use only GSM-7 characters: é, è, à, ù and straight apostrophes are fine; avoid ê, â, î, ô, û, ç, curly apostrophes and « » — one such character switches the SMS to UCS-2 (70 characters per segment) and doubles the cost. Arabic SMS are always UCS-2.

Typical values used for the length check: orderNumber CMD-2026-000158 · totalTtc 125 000,00 DA · storeName Phone Center Bahia Oran · delegateFirstName Abdelkader · reason 40 characters · productName BOROFONE BX51 câble USB-C 1 m · expiresAt 05/11 à 14:32.

Orders and assisted ordersCopy Anchor Link

Returns and after-salesCopy Anchor Link

Accounts, finance, stock and promotionsCopy Anchor Link

stock.low and stock.out are staff-only; they are the only templates that may carry a quantity.

Field, support, security and platformCopy Anchor Link

The OTP SMS may end with the 11-character app hash of the Android SMS Retriever API so the reseller app fills the code automatically; one hash exists per signing key and flavor. Without it the app uses the SMS User Consent API (a system prompt, no hash).

Quiet hoursCopy Anchor Link

Quiet hours are 21:00–08:00 Africa/Algiers (setting notifications.quietHours); the inbox row is always written immediately — only external channels wait.

Assumption — Friday morning and the Ramadan window (no promotional push from one hour before to one hour after sunset) are proposals to validate with HOCO; the Ramadan profile is a second quiet-hours setting enabled by date range.

The apps create one Android notification channel per category at first launch, named with the French labels of NotificationCategory (Commandes et compte, Sécurité, Activité terrain, Offres et promotions, Annonces) plus Commandes et compte (silencieux) for quiet hours. Users can mute a channel in Android settings; the app reflects a muted channel in its own preferences screen.

De-duplication and groupingCopy Anchor Link

1. Exactly once per channel — NotificationDelivery is unique on (outboxEventId, recipientUserId, channel); a replayed outbox row or a retried job never sends twice.
2. Collapse per entity — pushes carry collapse_key and Android tag = order:{orderId} (or ticket:…, return:…, tour:…): a newer status replaces the older one in the notification tray; the inbox keeps every row.
3. Merge window — same recipient, same entity, events within 60 seconds → one notification with the latest state (order.modified followed by order.validated becomes « Commande confirmée » with the modification summary in the body).
4. One assisted-order notification — assisted_order.confirmed and the following order.submitted for the same order are merged for the reseller.
5. Digests — task.due (one per assignee per morning), stock.low (immediate in-app, email in the 08:00 digest), staff email notifications (one digest.daily), invitation steps reached within 10 minutes (one notification with the furthest step).
6. Hysteresis — stock.low fires once per variant and warehouse until available stock goes back above the threshold.
7. Promotional caps — at most one PROMOTIONAL push per reseller per day (setting notifications.promotionalDailyCap, default 1) and three per rolling 7 days (notifications.promotionalWeeklyCap, default 3, D-39); several offers the same day become daily_offer.published.grouped. Over the cap the inbox row is still written; the push slot goes to the highest-priority candidate (anti-fatigue rules).
8. Queue resolution — queue notifications (order.submitted.staff, account.pending_validation.staff, payment.declared.staff, return.requested.staff, ticket.created.*) are marked read for every holder when the item is handled.

Retries and fallbacksCopy Anchor Link

Time-to-live: OTP 5 min · PROMOTIONAL 12 h · FIELD 12 h · TRANSACTIONAL and SECURITY 24 h · ANNOUNCEMENT 72 h. A message past its TTL is dropped, not delivered late (FCM ttl, SMS validity period). FCM delivery is weakened by aggressive battery savers on several Android brands common in Algeria; the delegate app's onboarding asks to exclude it from battery optimisation (DA-04).

PreferencesCopy Anchor Link

Preferences are stored in NotificationPreference (user × category × channel) and edited on RA-35, RW-12 and DA-26 through notifications.preferences.update (NOT-06).

Since change request 03, resellers can also mute push per NotificationGroup — Promotions, Nouveautés, Suggestions (V2 Points et niveaux); Urgent is locked (NOT-17).

Rules: preferences gate external channels only — the inbox always receives; locked toggles are shown disabled with « Indispensable au suivi de vos commandes » or « Indispensable à la sécurité de votre compte »; an opt-out applies from the next dispatch; marketing over SMS or WhatsApp (V2) requires a prior opt-in recorded with its date (to validate with HOCO's counsel under Law 18-07, see cross-cutting requirements).

Cost notes per channelCopy Anchor Link

Formula for the SMS budget HOCO validates (cahier §11 « Dépendances externes », INT-07): monthly cost = Σ (messages × segments × unit price per network).

Push payload and deep linksCopy Anchor Link

{
  "message": {
    "token": "fcm-device-token",
    "notification": {
      "title": "Commande confirmée",
      "body": "Votre commande CMD-2026-000158 de 125 000,00 DA est confirmée. Nous la préparons."
    },
    "android": {
      "collapse_key": "order:0192f4b8-7c1e-7a10-9f00-5b6d2c8e1a01",
      "ttl": "86400s",
      "priority": "high",
      "notification": {
        "channel_id": "transactional",
        "tag": "order:0192f4b8-7c1e-7a10-9f00-5b6d2c8e1a01"
      }
    },
    "data": {
      "notificationId": "0192f4c1-2b3a-7d44-8e21-3f9a0c7d5e02",
      "eventKey": "order.validated",
      "route": "/orders/0192f4b8-7c1e-7a10-9f00-5b6d2c8e1a01",
      "entityType": "ORDER",
      "entityId": "0192f4b8-7c1e-7a10-9f00-5b6d2c8e1a01"
    }
  }
}

Rules for the apps:

1. data values are strings (FCM requirement). The app routes on route; when the route is unknown to its version, it opens the inbox (RA-26, DA-23).
2. Opening a notification marks it read (notifications.markRead) with notificationId.
3. The reseller app and the reseller web use the same route paths (/orders/{orderId}, /returns/{returnId}, /support/tickets/{ticketId}, /promotions/{promotionId}, /finance/invoices/{invoiceId}), so one template serves both; email links are https://app.hoco.dz + route. Assumption — route names are proposals; the apps' routers own them and the payload change is a template edit.
4. The route only identifies the record; the app always fetches it with the user's own session, so a notification opened on a device where another account is signed in shows « Cette notification concerne un autre compte » and nothing else.
5. Data-only messages (tour.updated on a tour IN_PROGRESS, tour.reopened) carry {"type": "sync", "scope": "tours"} and trigger sync.delta; they always accompany a visible notification because Android throttles silent high-priority messages.
6. If iOS is decided (D-10), the same message adds apns.headers.apns-collapse-id equal to the Android tag.

Adding a new eventCopy Anchor Link

1. Name it <entity>.<past_participle> in snake case (return.received), unique, never reused; add it to the emitting module in the service catalogue.
2. Emit it as an OutboxEvent in the same transaction as the state change, with a versioned payload of identifiers and display values only — no secrets, no codes, no stock quantity for reseller-facing events.
3. Decide the audience and channels with Anis: recipient resolvers, category, whether it is a queue notification, SMS only if it meets the whitelist rule (cost approved by HOCO).
4. Write the rule in the seed (NotificationRule: channels, category, collapse key, merge window, TTL, quiet-hours policy) and expose it in BO-58.
5. Write the copy for each channel in fr (and empty ar, en keys that fall back), respecting the copy rules; run the length and GSM-7 check.
6. Wire the deep link in RA, RW, DA or BO, with the inbox fallback; add the SSE event to events.stream or admin.events.stream if open screens must update live.
7. Update this page (matrix row and copy row) in the same pull request, and the copy deck of DQA-10.
8. Test it: unit test of recipient resolution and preference filtering; contract snapshot of the payload; integration test asserting one inbox row and one delivery per channel through the dev simulators of SRV-08; a deep-link check in AT-29.
9. Re-estimate costs if SMS, email or WhatsApp volume changes, and tell HOCO.