Notifications & messaging

This area covers how users are told about events: the in-app inbox of every app, push notifications, SMS and email, the configurable event → channel → recipient matrix, preferences and back-office announcements (cahier §4.4, §5.4, §6.1, §8 Notifications, §10, §11). Every order status change reaches the reseller live, by push and in the inbox (AUTHORING §1b.3). Apps: all four plus the API. Server module: notifications (fed by the outbox), with support for announcements. The full matrix is in the notifications matrix. NOT-09 to NOT-18 come from HOCO's document 03 Smart Notifications (18 October 2026), a change request whose full catalogue, triggers and copy are on smart notifications.

ID	Requirement	Release	Priority	Source	Apps
NOT-01	In-app notification inbox with read/unread in every app	V1	MUST	§5, §6, §8	API · RA · RW · DA · BO
NOT-02	Push notifications (FCM) with deep links	V1	MUST	§8, §11	API · RA · DA
NOT-03	SMS for OTP and critical messages; email for staff and documents; WhatsApp share links	V1	MUST	§8, §11	API
NOT-04	Event → channel → recipient matrix and localised templates	V1	MUST	§8	API · BO
NOT-05	Automatic notifications on order changes, assignments, follow-ups and promotions	V1	MUST	§4.4, §5.4, §6	API
NOT-06	Notification preferences (marketing opt-out)	V1	SHOULD	§10	RA · RW · DA · API
NOT-07	Announcements from the back-office to delegates or resellers by target ('Messages')	V1	SHOULD	§6.1	BO · DA · RA · API
NOT-08	WhatsApp Business API automated messages	V2	COULD	§11, §14.2	API
NOT-09	Notification groups and the Notification Centre on the reseller home (Urgent, Promotions, Nouveautés, Points et niveaux, Academy, Suggestions)	V1	MUST	Client doc 03 (18 Oct 2026)	API · RA · RW
NOT-10	An action button (label and deep link) on every reseller notification	V1	MUST	Client doc 03 (18 Oct 2026)	API · RA · RW
NOT-11	Catalogue notifications: new arrival, new catalogue, trending product of the week	V1	SHOULD	Client doc 03 (18 Oct 2026)	API · BO · RA · RW
NOT-12	Targeted stock notifications: back in stock to past buyers and favorites, limited quantity without any number	V1	SHOULD	Client doc 03 (18 Oct 2026)	API · RA · RW
NOT-13	Offer notifications: promotion, flash sale, price drop alert	V1	SHOULD	Client doc 03 (18 Oct 2026)	API · RA · RW
NOT-14	Behaviour reminders: abandoned cart after 2 h, reorder reminder from purchase cadence	V1	SHOULD	Client doc 03 (18 Oct 2026)	API · RA · RW
NOT-15	Complementary product suggestions from pairs configured on the product	V1	COULD	Client doc 03 (18 Oct 2026)	API · BO · RA · RW
NOT-16	Commercial push: HOCO picks a product and an audience	V1	SHOULD	Client doc 03 (18 Oct 2026)	API · BO · RA · RW
NOT-17	Anti-fatigue rules: promotional push caps, priority, merge, quiet hours, opt-out per group	V1	MUST	Client doc 03 (18 Oct 2026)	API · RA · RW
NOT-18	Loyalty-driven notifications: double points, new level, missions, gifts, anniversary, objective almost reached, challenge of the month	V2	SHOULD	Client doc 03 (18 Oct 2026)	API · RA · RW

NOT-01 — In-app inboxCopy Anchor Link

Statement — Every app shall have a notification inbox with read and unread state and an unread badge.

Rules

1. A Notification belongs to one user: title, body, NotificationCategory, deep link, related entity, created time, read time. Every pushed notification is also in the inbox.
2. Lists use cursor pagination (20 per page, unread filter); the badge comes from notifications.unreadCount; opening a notification marks it read and follows its deep link; « Tout marquer comme lu ».
3. New notifications reach open apps live through notification.created on events.stream (RA, RW, DA); the back-office bell refreshes on its stream and every 60 seconds.
4. Notifications are kept 180 days (assumption, retention table D-11).

Acceptance criteria

• An order confirmation creates an inbox entry; the badge shows 1 and drops to 0 after opening it, which opens the order detail.
• A user never sees another user's notifications (404 NOT_FOUND on notifications.markRead with a foreign id).

Data — Notification.

Interfaces

• Screens: RA-09 Home · RA-26 Notifications · DA-23 Messages & notifications · BO-03 App shell · RW-11 Notifications
• Endpoints: notifications.list · notifications.unreadCount · notifications.markRead · notifications.markAllRead · events.stream

NOT-02 — Push notifications with deep linksCopy Anchor Link

Statement — The system shall send push notifications through FCM to the mobile apps, each opening the right screen.

Rules

1. Devices register their FCM token, app and version with me.devices.register at sign-in and on token refresh; sign-out unregisters; tokens reported invalid by FCM are deleted.
2. Payload: title, body, notificationId, deep link (e.g. order detail, visit, invitation); tapping marks the notification read and opens the screen, or the inbox if the target no longer exists.
3. Data-only sync hints ({"type":"sync","scope":"tours"}) accompany a visible notification and trigger sync.delta in the delegate app (SYN-01).
4. Promotional pushes respect notifications.quietHours (21:00–08:00); transactional and field pushes are sent at once with high priority.
5. Target: push handed to FCM within 60 seconds of the event (p95). The reseller web uses the inbox and live stream, no web push in V1.

Acceptance criteria

• When the back-office ships an order, the reseller's closed app receives a push that opens the order detail.
• A promotional notification triggered at 22:30 is delivered at 08:00.

Data — Device, Notification, NotificationDelivery.

Interfaces

• Screens: RA-26 Notifications
• Endpoints: me.devices.register

NOT-03 — SMS, email and WhatsApp linksCopy Anchor Link

Statement — The system shall send SMS for one-time codes and critical messages, email for staff and documents, and use WhatsApp share links (no WhatsApp API in V1).

Rules

1. SMS: OTP (always); reseller account approved or rejected; assisted order awaiting confirmation when the reseller has no registered device; staff and delegate temporary passwords. Sender id HOCO (registration delay, D-13).
2. Email: staff account invitations and password resets, export ready, ticket assignment; resellers with an email receive invoice links. SPF, DKIM and DMARC on the sending domain (INT-04).
3. WhatsApp: wa.me links only (invitation sharing, regional support button — SUP-05).
4. Every send is a NotificationDelivery (channel, provider id, status sent / delivered / failed); transient failures retried 3 times with backoff; dev and staging use simulators.

Acceptance criteria

• An OTP request sends one SMS and logs a delivery; a provider failure is retried then marked failed in the delivery log.

Data — NotificationDelivery, NotificationTemplate.

Interfaces — none (internal adapters; delivery log in NOT-04).

NOT-04 — Event → channel → recipient matrix and templatesCopy Anchor Link

Statement — The system shall decide channels and recipients per event from a configurable matrix and render localised templates.

Rules

1. NotificationRule: event key → recipients (reseller, assigned delegate, roles, assignee) → channels (IN_APP, PUSH, SMS, EMAIL); edited in BO-58 with communication.administer; the seeded matrix is the notifications matrix.
2. NotificationTemplate per event × channel × locale (fr required, ar and en optional with fr fallback), variables such as {{orderNumber}}; unknown variables are refused (400 VALIDATION_FAILED, TEMPLATE_VARIABLE_UNKNOWN); SMS templates limited to 2 segments.
3. Dispatch is idempotent per (event, recipient, channel); the delivery log (admin.notifications.log) shows each send and failure.
4. Rules for TRANSACTIONAL events always keep IN_APP.

Acceptance criteria

• Disabling SMS for an event in BO-58 stops SMS for the next occurrence; the change is audited.
• A template with {{foo}} is refused.

Data — NotificationRule, NotificationTemplate, NotificationDelivery, AuditLog.

Interfaces

• Screens: BO-58 Notification templates & rules
• Endpoints: admin.notifications.log · admin.notifications.templates · admin.notifications.rules

NOT-05 — Automatic notificationsCopy Anchor Link

Statement — The system shall notify automatically on order changes, assignments, follow-ups and promotions, according to the matrix.

Rules

1. Events written to the outbox in the same transaction as the change, then dispatched: order submitted (back-office), confirmed, refused, modified, preparing, shipped, delivered, cancelled, returned; assisted order awaiting confirmation, confirmed, rejected, expired; account pending, approved, rejected; point of sale assigned to a delegate; tour planned, changed, cancelled, reopened; follow-up due and overdue; ticket replied, assigned, resolved; return status changed; payment declaration confirmed or rejected; promotion launched for its audience; invitation steps; stock alert; export ready.
2. Every reseller order status change: live event + push + inbox (§5.4 « daté et notifié »).
3. A rolled-back change emits nothing; a dispatched event is never sent twice to the same recipient and channel.

Acceptance criteria

• Confirming an order sends one push and one inbox entry to the reseller and a live event to the open app; replaying the dispatcher does not duplicate them.

Data — OutboxEvent, Notification, NotificationDelivery.

Interfaces — see NOT-01, NOT-02.

Notes / open points — No task of the plan lists NOT-05 in its srs array; it is delivered by SRV-08 and the modules emitting the events.

NOT-06 — Notification preferencesCopy Anchor Link

Statement — Users shall choose their channels per category, except for transactional and security messages.

Rules

1. Toggles per NotificationCategory × channel (PUSH, SMS, EMAIL); TRANSACTIONAL and SECURITY cannot be disabled (422 PREFERENCE_NOT_EDITABLE); the inbox always receives everything.
2. Defaults: PROMOTIONAL push on, PROMOTIONAL SMS off; FIELD and ANNOUNCEMENT on.
3. Resellers can also mute push per NotificationGroup (Promotions, Nouveautés, Suggestions; V2 Points et niveaux); URGENT is locked (NOT-17).

Acceptance criteria

• Turning off promotional push stops promotion pushes but they remain in the inbox; trying to turn off transactional push → 422 PREFERENCE_NOT_EDITABLE.

Data — NotificationPreference.

Interfaces

• Screens: RA-35 Settings · DA-26 Settings · RW-12 Profile & settings
• Endpoints: notifications.preferences.get · notifications.preferences.update

NOT-07 — Announcements ("Messages")Copy Anchor Link

Statement — The back-office shall publish announcements to delegates or resellers by target, and the apps shall show them with read tracking.

Rules

1. An Announcement has title (≤ 120), body (≤ 2 000), optional image and link, audience (delegates or resellers), filters (zones, wilayas, segments, customer types, named users), publish time and optional expiry.
2. Publishing (communication.validate) creates inbox entries and a push (ANNOUNCEMENT); a published announcement cannot be edited, only withdrawn or expired.
3. Reads are recorded (AnnouncementRead); the back-office sees sent / read counts.
4. Delegate Messages is one-way in V1 (D-27).

Acceptance criteria

• An announcement to the delegates of zone Oran reaches only them; the read rate updates as they open it.

Data — Announcement, AnnouncementRead, Notification.

Interfaces

• Screens: RA-26 Notifications · DA-23 Messages · BO-57 Announcements
• Endpoints: announcements.list · announcements.markRead · admin.announcements.crud · admin.announcements.send

NOT-08 — WhatsApp Business API (V2)Copy Anchor Link

Statement — The system could send automated WhatsApp messages through the WhatsApp Business Platform.

Rules

1. Meta-approved templates (order confirmed, shipped, assisted order to confirm, payment reminder); recipient opt-in recorded; SMS fallback when undelivered; per-conversation costs validated by HOCO (INT-07).

Acceptance criteria

• An opted-in reseller receives the order shipped template; a non-opted-in one receives the push only.

Data — NotificationTemplate, NotificationDelivery.

Interfaces — none in V1.

Smart notifications (client document 03)Copy Anchor Link

HOCO's document 03 asks that every notification has a commercial goal and an action button. The requirements below are the V1 part (NOT-09 to NOT-17) and the V2 part (NOT-18). The catalogue SN-01 to SN-28 with exact triggers, audiences and copy is on smart notifications; the event rows are in the matrix.

NOT-09 — Notification groups and the Notification CentreCopy Anchor Link

Statement — Every reseller notification shall belong to one NotificationGroup, and the reseller home shall show a Notification Centre organised by group.

Rules

1. Groups: URGENT Urgent, PROMOTIONS Promotions, NEW_PRODUCTS Nouveautés, LOYALTY Points et niveaux (V2), ACADEMY Academy (later), SUGGESTIONS Suggestions. The template fixes the group; transactional and security notifications are URGENT.
2. Home (RA-09, RW-02): a « Centre de notifications » card with one chip per group with content (unread count from notifications.unreadCount.byGroup) and the 3 latest unread items with their action buttons; an empty group is hidden.
3. Inbox (RA-26, RW-11): tabs « Toutes » plus the groups, notifications.list?group=; « Non lues » remains.
4. Smart notifications never open a modal; in the foreground only URGENT items show the in-app banner.

Acceptance criteria

• A back-in-stock notification appears under Nouveautés on home with its unread count, and an order confirmation under Urgent.
• With no Academy content the Academy chip and tab are not shown.

Data — Notification.group, NotificationTemplate.group, enum NotificationGroup.

Interfaces

• Screens: RA-09 · RA-26 · RW-02 · RW-11
• Endpoints: notifications.list · notifications.unreadCount

NOT-10 — An action button on every notificationCopy Anchor Link

Statement — Every reseller notification shall carry an action — a French label and a deep link — shown as a button in the inbox and the Notification Centre and as a push action on Android.

Rules

1. action: { label, deepLink } on notifications.list items; the label comes from NotificationTemplate.actionLabel (per locale, fr required), the link from the template route with the event's identifiers.
2. Defaults for the existing events are listed on smart notifications (« Voir la commande », « Confirmer la commande », « Répondre »…); BO-58 can override a label.
3. The button and a tap on the row do the same thing: mark read, then open the link; an unknown route opens the inbox (payload rules).

Acceptance criteria

• An order-shipped notification shows « Voir la commande », which opens the order; a back-in-stock one shows « Commander maintenant », which opens the product.
• A template without an action label cannot be saved for a reseller event.

Data — Notification.actionLabel, Notification.actionRoute, NotificationTemplate.actionLabel.

Interfaces — as NOT-09; BO-58.

NOT-11 — Catalogue notificationsCopy Anchor Link

Statement — The system should tell resellers about new arrivals, a new catalogue edition and the trending product of the week.

Rules

1. New arrival (SN-01): first publication of a product with « Annoncer comme nouveauté » ticked; job smart.newArrivalsDigest at 10:00 and 16:00 groups the products published since the last run (2 or more → one notification to /catalog?tab=new).
2. New catalogue (SN-19): an announcement of kind NEW_CATALOGUE with its PDF, published in BO-57.
3. Trending (SN-17): job smart.trendingWeekly (Sunday 09:00) picks the product with the most units on confirmed orders over 7 days, IN_STOCK, at least 5 distinct buyers; sent to resellers who did not order it in 30 days.

Acceptance criteria

• Publishing three products on the same morning produces one « 3 nouveautés chez HOCO » notification per reseller at 10:00.
• A reseller who ordered the trending product last week does not receive SN-17.

Data — Product.publishedAt, Product.announceAsNew, Announcement.kind, OrderItem.

Interfaces — BO-28, BO-57; deep links RA-14, RA-12.

NOT-12 — Targeted stock notificationsCopy Anchor Link

Statement — The system should notify a variant's return to stock only to the resellers interested in it, and signal limited quantities without ever giving a number.

Rules

1. Back in stock (SN-02): availability OUT_OF_STOCK → IN_STOCK after at least smart.restockMinOutHours (24) out of stock; recipients: resellers who ordered the variant in the last smart.restockLookbackDays (90, D-43), have the product in favorites, or hold it in their cart.
2. Limited quantity (SN-03): available stock crosses the variant's alert threshold downwards while IN_STOCK; recipients: favorites, carts, and resellers who ordered it twice in 90 days; fires once until the stock goes back above the threshold.
3. No quantity, no threshold and no « Plus que N » in any reseller payload or copy (STK-07).

Acceptance criteria

• A variant that comes back after 3 days out of stock notifies its 12 buyers of the last 90 days and the 4 resellers who favorited it — and nobody else.
• A correction that puts a variant at 0 then back within an hour sends nothing.
• No SN-03 payload contains a number of units.

Data — StockLevel, OrderItem, Favorite, CartItem.

Interfaces — deep link RA-14 / RW-04 /products/{productId}?variantId=.

NOT-13 — Offer notificationsCopy Anchor Link

Statement — The system should notify promotions, flash sales and price drops to the resellers they concern.

Rules

1. Promotion (SN-04): promotion.started as today, with the action « Voir l'offre ».
2. Flash sale (SN-18): flash_sale.started when an isFlashSale promotion becomes ACTIVE (PRM-07); push TTL = time left; never delivered after the end.
3. Price drop (SN-21): a PriceChange lowering a customer-type price by at least smart.priceDropMinPercent (5 %) notifies the resellers of that type who favorited the product, hold it in their cart or ordered it in 90 days; increases are never notified.

Acceptance criteria

• A 6-hour flash sale starting at 10:00 is pushed at 10:00 to its audience; a reseller in quiet hours never receives it after 16:00.
• Lowering the Demi-gros price of a cable by 10 % notifies interested Demi-gros resellers only.

Data — Promotion.isFlashSale, PriceChange, Favorite, CartItem, OrderItem.

Interfaces — deep links RA-24, RA-25, RA-14.

NOT-14 — Behaviour remindersCopy Anchor Link

Statement — The system should remind a reseller of a cart left without checkout and of a purchase they usually make at this time.

Rules

1. Abandoned cart (SN-20): cart with lines unchanged for smart.abandonedCartDelayHours (2, D-44) and no checkout since; once per cart version, at most once per 24 h; job smart.abandonedCarts every 15 minutes; cancelled by a checkout.
2. Reorder reminder (SN-12): rule-based on cadence — median interval of the reseller's orders containing a leaf sub-category (at least 3 orders in 180 days); sent when the time since the last such order reaches the cadence + smart.reorderGraceDays (1); never when the cart already holds that sub-category; job smart.reorderReminders 09:30.

Acceptance criteria

• A cart left at 15:00 produces one reminder after 17:00; adding a line at 16:30 moves it to 18:30; checking out at 16:45 cancels it.
• A reseller who orders cables every 7 days and has not ordered for 8 days receives « Besoin de réassort ? » once.

Data — Cart, CartItem, Order, OrderItem, Category.

Interfaces — deep links RA-17 / RW-06 /cart, RA-22 /orders/{orderId}?reorder=1.

NOT-15 — Complementary product suggestionsCopy Anchor Link

Statement — The system could suggest, after an order, a complementary product configured by HOCO for a product of that order.

Rules

1. Up to 5 complementary products per product, ordered, edited in BO-28 (ProductComplement).
2. Job smart.complementSuggestions (10:30) the day after an order is VALIDATED: the first complement IN_STOCK, visible to the reseller and not ordered by them in 60 days; at most one per order.
3. AI « bought together » suggestions are not V1 (D-41).

Acceptance criteria

• An order with a phone case configured with tempered glass produces the next morning « Avec Coque iPhone 15, avez-vous aussi besoin de Verre trempé ? », unless the reseller ordered tempered glass in the last 60 days.

Data — ProductComplement, OrderItem.

Interfaces — BO-28; deep link RA-14.

NOT-16 — Commercial push chosen by HOCOCopy Anchor Link

Statement — The back-office should push a product, promotion, category or brand chosen by HOCO to a chosen audience.

Rules

1. An announcement of kind COMMERCIAL_PUSH (BO-57, communication.validate): target, audience (wilayas, segments, customer types, named resellers, buyers of a category in the last N days), title ≤ 40, body ≤ 120, action label (default « Commander maintenant »), send time.
2. Before sending, the editor shows the recipient count and how many get a push versus the inbox only because of the caps (NOT-17).
3. Category PROMOTIONAL, group PROMOTIONS; counted in the caps; audited.

Acceptance criteria

• A push of the Power Bank J101 to wilaya 31 Détail resellers reaches only them; those already at their daily cap get the inbox entry only, and the split shown before sending matches the delivery log.

Data — Announcement (kind, target, actionLabel), Notification, NotificationDelivery.

Interfaces — BO-57; admin.announcements.crud · admin.announcements.send.

NOT-17 — Anti-fatigue rulesCopy Anchor Link

Statement — The system shall limit promotional pushes so that smart notifications do not tire the reseller.

Rules (proposal defaulted in D-39; detail on smart notifications)

1. At most 1 PROMOTIONAL push per reseller per day and 3 per rolling 7 days (notifications.promotionalDailyCap, notifications.promotionalWeeklyCap); transactional and security are never capped.
2. Over the cap → inbox only; the slot goes to the highest-priority candidate (flash sale first).
3. Quiet hours unchanged (matrix); a deferred push past its TTL is dropped.
4. Similar events within 24 h are merged; the same product never notifies the same reseller twice in 7 days.
5. Push opt-out per group (Promotions, Nouveautés, Suggestions; V2 Points et niveaux); URGENT locked (422 PREFERENCE_NOT_EDITABLE).

Acceptance criteria

• A reseller eligible for a flash sale, a back-in-stock and a new arrival on the same day receives one push (the flash sale) and three inbox entries.
• A fourth promotional push within 7 days is not sent; its inbox row exists.
• Muting Suggestions stops abandoned-cart pushes but not order pushes.

Data — NotificationPreference.group, NotificationRule.priority, NotificationDelivery, Setting.

Interfaces — RA-35, RW-12; notifications.preferences.update.

NOT-18 — Loyalty-driven notifications (V2)Copy Anchor Link

Statement — With the V2 loyalty engine, the system should notify double-points days, a new level, missions available and completed, gifts, the registration anniversary, an objective almost reached and the challenge of the month.

Rules

1. Types SN-05, SN-06, SN-07, SN-08, SN-09, SN-15, SN-16, SN-22, SN-24 and the Top 3 (SN-27), group LOYALTY; triggers on smart notifications.
2. They use the V1 groups, actions, caps and preferences unchanged; missions and the Top 3 are LOY-06 and LOY-07.

Acceptance criteria

• A reseller who reaches Gold receives « Félicitations ! Vous êtes maintenant Gold. » with « Découvrir mes avantages ».

Data — V2 LoyaltyAccount, LoyaltyTransaction, Reward.

Interfaces — V2 RA-38, RA-39.