Reseller app

The reseller app (application revendeur) is the Flutter app through which a point of sale orders HOCO, ACEFAST and BOROFONE accessories, follows its orders live, handles invoices, payments, returns and after-sales claims, and talks to HOCO (cahier §5, §14.1). Imad builds it in hoco-mobile/apps/reseller (application id dz.hoco.reseller); Akram designs it on days 6 to 10 of the design plan, the V2 screens in DES-30. The reseller web is its responsive twin on the same API.

This page holds what every screen shares. The section pages hold one specification per screen.

Who uses it and howCopy Anchor Link

Users.

• Resellers (revendeurs): the owner or counter staff of a phone-accessory shop anywhere in Algeria's 58 wilayas (provinces). Today they order by phone or WhatsApp from their délégué commercial (field sales delegate) or HOCO's office. One account per shop; the shop's main mobile number is the login (cahier §4.2). Each reseller has a customer type — Super-gros, Demi-gros or Détail — that selects their price for every product (PRC-02, AUTH-11).
• Guests: shop owners who installed the app from a store listing, a flyer or a delegate's QR code and have no account yet. They browse the catalog, products and promotions without prices and can write to HOCO on WhatsApp (AUTH-10).

Context of use.

• In the shop, between customers. Sessions are short and interrupted. The cart lives on the server and forms keep drafts, so nothing is lost when the reseller switches app or the phone locks.
• Mid-range Android on mobile data (cahier §9, NFR-04). The app opens and returns search results in under 3 seconds on a normal connection (NFR-01). Lists show skeletons, never a blank screen.
• B2B quantities. Lines of 10, 50 or 100 pieces are normal. Quantities can be typed, not only tapped with +/−.
• Onboarding often happens with a delegate standing next to the reseller. The delegate shows an invitation QR code; the reseller installs, signs up, and the delegate may prepare a first order that the reseller confirms (cahier §6.6, §6.7). Sign-up must take less than three minutes.
• Trust. Prices are always the reseller's own, totals always come from the server, every order waits for HOCO's explicit confirmation (ORD-14), and every status change shows up live and as a notification (ORD-15).

Scope. V1: guest browsing, account, catalog with advanced filters, cart, ordering, live order tracking, returns and after-sales claims, simple promotions, finance view, notifications, support and regional WhatsApp (cahier §14.1 and the team decisions of 17 Oct 2026 recorded in the decision register). V2: loyalty points and levels, rewards, profitable packs (cahier §14.2) — RA-37 to RA-39.

How to read a screen specCopy Anchor Link

Every screen on the section pages follows the same template:

Component names come from the mobile component library (DES-03): AppBar, TabRootHeader (store greeting + bell), SearchField, BottomNav, Button (primary, secondary, text, destructive), IconButton, TextField, PhoneField, PasswordField, OtpField, Select, QuantityStepper, Chip, FilterChip, RangeSlider, StatusBadge, StockBadge, PriceTag, PriceLock, ProductCard, CartLine, OrderCard, ProgressTracker, Timeline, KpiTile, ListRow, SectionHeader (title + « Voir tout »), Tabs, Carousel, Countdown, RadioCard, AddressCard, SummaryCard, StickyFooter, WhatsAppButton, Banner (info, warning, error, success), BottomSheet, Dialog, Snackbar, Skeleton, EmptyState, ErrorState, Uploader, ImageGallery. If Akram names a component differently in Claude Design, Claude Design wins.

Formatting rulesCopy Anchor Link

These rules apply to every screen; the specs do not repeat them.

Prices and customer type. A signed-in reseller sees, for every variant, the price of their customer type (Super-gros (SUPER_GROS), Demi-gros (DEMI_GROS) or Détail (DETAIL)), with active promotions applied on top (PRC-01, PRC-02). The type is never chosen per order and only the back-office changes it after sign-up. When it changes, the server pushes account.customer_type_changed; the app refreshes Me, the catalog and the cart (lines show « Prix mis à jour »).

Price lock. When ProductCard.price is null and priceLocked is true — guests, and pending resellers when settings.catalog.pricesVisibleBeforeValidation is false — every PriceTag is replaced by the PriceLock component: a lock icon and « Créez un compte pour voir les prix » (guest) or « Prix visibles après validation de votre compte » (pending). Tapping it opens the sign-up prompt of RA-41 for guests. No price, discount amount, margin or price filter may appear anywhere in a locked state; a promotion keeps its label and percentage badge.

Stock is availability only. Resellers and guests see exactly two states, never a quantity (STK-07): StockBadge En stock (IN_STOCK) (success tone) or En rupture (OUT_OF_STOCK) (danger tone). No screen, helper or error message says « Plus que N pièces » or reveals a quantity; stock problems read « Stock insuffisant pour cette quantité ».

Quantity stepper. Every QuantityStepper (product detail, cart, scanner sheet, return and claim forms) obeys the variant's limits from the API: valid quantities are minQty, minQty + qtyStep, minQty + 2 × qtyStep… up to maxQtyPerOrder (ORD-02). Available stock is not known by the app; the server checks it.

• − is replaced by a trash icon when the quantity equals minQty (cart only; on product detail it is disabled).
• + is disabled at the maximum, with the helper « Maximum 20 pièces par commande ».
• Tapping the number opens a numeric keypad. A typed value is snapped down to the nearest valid quantity with an explanation (« Par multiples de 5 — quantité ajustée à 45 »).
• Long-press on +/− repeats every 150 ms.

Navigation modelCopy Anchor Link

Five bottom tabs, as on the reference screens:

• Each tab keeps its own navigation stack (go_router StatefulShellRoute). Re-tapping the active tab pops to its root, or scrolls the root to the top when already there.
• Tab roots Accueil, Catalogue and Commandes use the TabRootHeader: store logo, « Bonjour, » and the store name, and the notification bell with the unread badge (notifications.unreadCount → count, « 9+ » above 9). Guests see the HOCO logo, « Bienvenue sur HOCO » and a « Se connecter » text button instead of the bell. Panier and Compte use an AppBar with a title.
• Android back pops the current stack; on a tab root other than Accueil it goes to Accueil; on Accueil it exits the app.
• Full-screen flows hide the bottom navigation: onboarding (RA-02 to RA-08), the scanner (RA-11), checkout to confirmation (RA-18 to RA-20), the image viewer, and the forms of RA-19, RA-31, RA-33 and RA-40.
• Badges refresh after every cart mutation (from its response), on live events, when the app returns to the foreground, when a push arrives, and on pull-to-refresh.

WhatsApp support button (SUP-05). A fixed WhatsAppButton (56 dp round button, WhatsApp green, glyph and the accessible label « Contacter HOCO sur WhatsApp ») floats bottom-right, 16 dp above the bottom navigation, on Accueil, Catalogue, Commandes and Compte roots, on RA-24, RA-25, RA-32, RA-02 and every guest screen. It is hidden where it would cover a sticky footer or a form (cart, checkout, scanner, forms, image viewer); RA-14 and RA-22 carry a WhatsApp icon in their AppBar instead, with a prefilled message naming the product or the order. One tap opens WhatsApp on the number of the user's support region:

1. Signed in: Me.supportRegion.whatsappNumber (region of the wilaya declared in the account) — no call needed.
2. Signed in without a region (supportRegion: null): settings.support.whatsapp from appConfig.get.
3. Guest: support.whatsapp with the device position when the location permission is granted (nearest commune → wilaya → region); without permission, the first tap opens a BottomSheet « Votre wilaya » (searchable list, plus « Utiliser ma position »), the choice is stored on the device and sent as wilayaCode; failing that, the default number.

The link is https://wa.me/<number without +>?text=<message>. Prefilled messages: signed in « Bonjour HOCO, je suis {storeName} ({resellerNumber}). »; guest « Bonjour HOCO, je souhaite des informations sur vos produits. »; from a product « … Ma question concerne {productName} (réf. {sku}). »; from an order « … Ma question concerne la commande {orderNumber}. ». Region name and hours are shown on RA-32.

Navigation mapCopy Anchor Link

Launch, guest browsing and onboarding:

Main navigation (tabs and the screens they lead to):

Global behavioursCopy Anchor Link

Launch and session restoreCopy Anchor Link

1. RA-01 reads the session token from secure storage and calls appConfig.get and, when a token exists, me.get in parallel.
2. The version policy is applied first (see below). Then the route: no token and first launch → RA-02; no token and the user already chose to browse as a guest → RA-09 in guest mode; token valid → RA-09 or the pending deep link (a pending account lands on RA-06 once, right after sign-up); 401 UNAUTHENTICATED → token cleared, guest mode with the banner « Votre session a expiré. Reconnectez-vous. »
3. Me.mustChangePassword true → the change-password form of RA-35 opens first; every other call answers 403 PASSWORD_CHANGE_REQUIRED until it is done.
4. Me.consents.termsVersion differs from settings.legal.termsVersion → a blocking Dialog asks to accept the new terms (link to the text), saved with me.update.
5. Sessions last 30 days and slide with activity (AUTH-06): a reseller who opens the app at least once a month never signs in again. Signing out (auth.logout) clears the token and the cached Me, keeps the catalog cache and returns to guest browsing.
6. Offline at launch with a stored token: the app opens on cached data with the offline banner and checks the session when the network returns. Offline at the very first launch: RA-36 offline state.
7. On the first launch only, the Play install referrer is read and sent with invitations.attribute so that an installation from an invitation link is attributed to the delegate (IVT-03, IVT-04).

What each kind of user can doCopy Anchor Link

The server enforces these rules (403 ACCOUNT_PENDING_VALIDATION, 403 ACCOUNT_SUSPENDED, 403 RESELLER_SUSPENDED); the app never offers an action the server will refuse (ACL-05). The state comes from Me.status and Me.reseller.validationStatus (AUTH-08).

• A pending reseller has the full shell; the Compte tab shows the RA-06 status card at the top and checkout shows the validation banner.
• SUSPENDED and DISABLED accounts lose their sessions server-side; the next call answers 403 ACCOUNT_SUSPENDED and the app signs out locally.
• Ordering blocks on an active account. Reseller lifecycle status Suspendu (SUSPENDED) (unpaid, fraud, closure): blocking issue RESELLER_SUSPENDED in cart.get → issues, banner on Accueil and Panier « Les commandes sont suspendues sur votre compte. Contactez HOCO. », checkout disabled — everything else, including invoices and payments, stays available. A credit account blocked by finance only disables the Crédit payment method. An order below settings.orders.minAmount disables checkout until the minimum is reached.

Version policy, forced update and maintenanceCopy Anchor Link

appConfig.get (called with app=RESELLER_APP, platform=android and version) returns minVersion, latestVersion, forceUpdate, updateAvailable, storeUrl, releaseNotes, maintenance and serverTime (ADM-07).

• forceUpdate true, or any call answering 426 UPGRADE_REQUIRED: blocking RA-36 « Mise à jour requise »; the only action opens storeUrl.
• updateAvailable true: a dismissible dialog once per new version with releaseNotes.
• maintenance.enabled, or any call answering 503 MAINTENANCE: blocking maintenance state with maintenance.message and « Retour prévu vers 14:30 » when maintenance.until is set; « Réessayer » calls appConfig.get again.
• appConfig.get is called at launch, when the app returns to the foreground after more than one hour, and after any 426 or 503 MAINTENANCE.

Live updatesCopy Anchor Link

Order screens are live (ORD-15, SYN-07). While the app is in the foreground and signed in, it keeps one Server-Sent Events connection to events.stream (GET /v1/events, heartbeat every 25 s).

• The connection opens after sign-in and when the app comes to the foreground, and closes when it goes to the background (push takes over). Mobile has no browser EventSource: the client sends the bearer token and, on reconnection, Last-Event-ID itself, with backoff from 1 s to 30 s; silence for 60 s (the server pings every 25 s) means reconnect. Event ids already processed are ignored (at-least-once delivery).
• On return to the foreground the app reloads the screen it shows — events that happened in the background are not replayed, the inbox holds them.
• Every event that matters is also a notification (push + inbox), so nothing depends on the stream (notifications matrix).

Online-first, cached catalog, offline bannerCopy Anchor Link

The reseller app is online-first. Unlike the delegate app it has no outbox: an order, a confirmation, a payment declaration, a return or a claim is never queued offline, because prices, stock and credit must be re-validated when it is submitted (PRC-05).

• Cached on the device for offline reading (kept 7 days; the account data is cleared at sign-out, the public catalog is kept): the last home aggregate, categories, brands and facets, catalog pages and product details viewed in the last 24 hours, favorites, the last cart snapshot, the first page of orders and every order detail viewed, invoices list, the first page of notifications, the store profile. Product images use the image cache (200 MB cap).
• Offline banner. After 3 seconds without connectivity a Banner appears under the header: « Hors connexion — données du 14 nov. à 10:32 ». Cached screens stay readable; every action that writes is disabled with « Connexion requise pour cette action ». When the network returns the banner turns into the snackbar « Connexion rétablie », the visible screen refreshes and the live connection reopens.
• Prices shown offline may be stale; the cart and checkout always re-validate them.

Errors and retriesCopy Anchor Link

When a screen has no specific copy for an error code, it shows the server's error.message, which is localised and safe to display. Codes are listed in the error registry.

Push notificationsCopy Anchor Link

• The device registers its FCM token with me.devices.register after sign-in, when FCM rotates the token and after an app update; auth.logout unregisters it (AUTH-09, NOT-02). Guests receive no push.
• Android 13+ notification permission is requested with a pre-prompt at the moments it makes sense — on RA-06 (« Soyez prévenu dès la validation de votre compte ») and on RA-20 (« Suivez la confirmation de votre commande ») — never at first launch.
• A push received in the foreground shows an in-app banner with « Voir » (unless the live stream already showed it) and refreshes the badges. A tap on a push opens its route (table below) and marks it read with notifications.markRead. Signed out, the route is kept and opened after sign-in; if the target is gone or out of scope, the parent list opens with « Ce contenu n'est plus disponible ».

Data freshnessCopy Anchor Link

Accessibility and localisationCopy Anchor Link

• Touch targets at least 48 × 48 dp; text contrast WCAG AA (4.5:1); statuses always carry text, never colour alone; every icon button has a semantic label (NFR-07).
• Layouts survive a 130 % system text scale without truncating prices, totals or statuses (they wrap to two lines).
• French only in V1, Arabic (RTL) and English prepared (NFR-06): no text inside images, directional icons mirror, all strings in ARB files (MOB-07). Banner images carry no text that matters — titles and calls to action are separate fields.

AnalyticsCopy Anchor Link

Events are snake_case, logged through one analytics wrapper (provider to confirm; Firebase Analytics is the natural choice as Firebase already serves push). Every event carries screenId, appVersion, platform, userKind (guest, pending, active) and, when signed in, customerType; the reseller is identified by its UUID only — no name, phone or address (Law 18-07). Screen views are logged by the router observer with the screen id (RA-18). Per-screen events are listed in each spec.

Deep linksCopy Anchor Link

The app, its push notifications and the reseller web share one URL space under https://app.hoco.dz (domain to confirm). Android App Links open the app when it is installed, else the same path on the web. Push payloads carry notificationId, category, event and route. Event keys are those of the notifications matrix; the ones below are the reseller-facing events.

Screen listCopy Anchor Link

Section pagesCopy Anchor Link