Back-office

The back-office (@hoco/dashboard, Next.js) is where HOCO staff run the business: CRM, field operations, catalog and stock, orders and delivery, finance, promotions, support, reports and administration (cahier §4). Anis builds it: DSH-01 to DSH-13 for V1, with returns and after-sales in DSH-13; V2 pages in DSH-20 and DSH-21. Akram designs it on days 15 to 19 (DES-15 to DES-19), and the V2 surfaces later in DES-30.

Most of the 71 pages are built from five page templates that Akram defines on day 4 (DES-04). Only 21 pages are bespoke: maps, boards, planners, the 360° sheet, editors with a live preview, and the permissions matrix. This page holds what all pages share. Each section page then specifies its screens one by one: layout, data, actions, rules, real-time behaviour, states and acceptance criteria.

Who uses the back-officeCopy Anchor Link

Six internal roles use it (cahier §3, ACL-01). Delegates and resellers have no back-office access. Sign-in (BO-01) refuses them and points them to their app. A staff user can hold several roles, and their effective permissions are the union of those roles.

Information architectureCopy Anchor Link

SidebarCopy Anchor Link

Navigation comes from permissions, not from roles (ACL-05). An item appears when the user holds the permission of its main read operation. A group appears when at least one of its items does. If HOCO edits the matrix (BO-62), the navigation follows without any code change. V2 items stay hidden until their release flag is on (they are never shown greyed out). Routes are shown without the locale segment.

The remaining pages have no sidebar item. They are reached from a list or a record: sign-in and reset (BO-01, BO-02), the reseller 360° and its form (BO-11, BO-12), delegate detail and form (BO-17, BO-18), the tour editor and live detail (BO-22, BO-23), the visit detail (BO-25), the product editor and import wizard (BO-28, BO-32), the order detail and order on behalf (BO-39, BO-40), the promotion editor (BO-50), the ticket detail (BO-56) and each report (BO-59 runner).

Badges read the total of the matching list call with pageSize=1. The Commandes à confirmer badge reads admin.orders.toConfirm. Badges refresh on page load, on window focus, every 60 s, and after the live events that concern them. The to-confirm badge updates within seconds of order.created and order.status_changed. Counts above 99 show 99+.

Sections visible by roleCopy Anchor Link

These visibilities follow from the default permission seed below. The seed is derived from cahier §3 and the role descriptions in RoleKey. The authoritative matrix is SRS › Permissions matrix, and HOCO can change it in BO-62.

Navigation mapCopy Anchor Link

Page templatesCopy Anchor Link

The remaining bespoke screens (BO-01, BO-03, BO-10, BO-19, BO-21, BO-42) have their own layouts but reuse the shared header, filter bar and states.

Shared page anatomyCopy Anchor Link

• Breadcrumb (Commandes › CMD-2026-000158) above the page title. Next to the title: the record count for lists, status pills for records.
• One primary action on the right of the header (« Nouveau produit », « Valider la commande »). Secondary actions sit in a « Plus » menu. Destructive actions always sit in the menu, never next to the primary button.
• Content width: lists and dashboards are fluid up to 1 680 px. Forms are capped at 960 px. Detail pages use a 1 fr / 360 px split with a side rail on desktop.
• Each page sets the browser title to <page> · HOCO and has a stable data-page="bo-38" attribute for end-to-end tests (QA-01).

ListCopy Anchor Link

1. Header: title and total (« 312 commandes »), the primary action, and « Exporter » / « Importer » when the module allows them.
2. Status tabs (saved views) when the record has a lifecycle. Each tab is a preset filter with a counter, for example « En préparation » = status=PREPARING. The active tab is ?view=<key>.
3. Filter bar:
   • A search input (q, debounced 300 ms, at least 2 characters) and up to four inline filters (select, multi-select, date range).
   • « Plus de filtres » opens a side sheet with the rest. Active filters show as removable chips, plus « Réinitialiser ».
   • Every filter lives in the URL under the API filter name (status, wilaya, commune, delegate, from, to, q; repeated parameters for multi-values). The view is shareable, back/forward works and a reload restores it. Each list's last URL is kept in session storage, so the sidebar link brings the user back to the same view.
   • A filter change resets page to 1.
4. Table (TanStack Table):
   • Sorting is server-side and on a single column (sort and order parameters), with an arrow on the sorted header.
   • « Colonnes » toggles column visibility. The choice is stored per user and per table in local storage (bo.table.<tableId>.columns). Each spec lists the default-visible columns.
   • The identifier column is pinned. Numbers are right-aligned in tabular figures. Statuses render as pills.
   • A row click opens the record (Ctrl/Cmd-click opens a new tab). A kebab menu at the end of the row holds row actions.
   • A density toggle (« Confortable » / « Compacte ») is stored like the column choice.
5. Selection and bulk actions: a checkbox column. Once rows are selected, a sticky bar appears (« 12 sélectionnés » plus actions).
   • Selection is limited to the current page.
   • When no bulk operation exists, the action runs item by item with an Idempotency-Key each. A progress dialog ends with a per-item report (done / failed with the error message). A partial result is never silent.
6. Pagination: page and pageSize (25 by default; 25, 50 or 100), « 1–25 sur 312 », plus first, previous, next and last.
7. Export: « Exporter » offers XLSX, CSV and PDF. It exports the current filters and visible columns as an async job (BO-60), with the toast « Export en préparation — il apparaîtra dans le centre d'exports ». The button only shows with the module's export permission (ANA-05).
8. States: see States.

Drawer or page?

• A drawer (right sheet, 560 px; full width on tablet portrait) edits small records without sub-collections (about 12 fields or fewer): brands, categories, attribute definitions, warehouses, carriers, segments, tasks, users, reference items, support regions, banners, announcements, payment recording, credit-limit changes. The drawer is addressable (?drawer=new or ?drawer=<id>), so links and the back button work, and it guards unsaved changes on close.
• A page edits records with sub-collections, tabs, maps or long forms: reseller, delegate, product, tour, promotion, order on behalf, stock operation.
• A read-only quick view drawer previews a record without leaving the list (stock movements of a variant, an invoice, a delivery card).

Detail with tabsCopy Anchor Link

• Header summary:
  • The business number in monospace (copy on click), the name, and one status pill per lifecycle (for example the order status plus the assisted-confirmation status).
  • A row of five to seven key facts.
  • Primary actions computed by the server: detail responses carry allowedActions, and the UI renders exactly those, never re-deriving transitions.
  • On scroll, the header condenses and stays sticky.
• Tabs: addressable with ?tab=<key>. Each tab loads lazily, has its own loading, empty and error states, and shows a counter when the detail response provides one.
• Side rail (desktop at 1 280 px and wider): summary cards. Below that width they move under the main content.
• History tab: who, when, what (before → after), reason. System actions read « Système ».
• Concurrency: records carry a version that mutations send back. A 409 VERSION_CONFLICT opens « Cette fiche a été modifiée par Karim B. à 10:42 » with « Recharger », and the user's unsaved input stays in the form.

Form / editorCopy Anchor Link

• Sections with a title and a two-column field grid on desktop (one column on tablet). Labels sit above fields; a required field is marked with « * ». Help text sits under the field, and the error replaces it in the danger tone.
• Validation:
  • The client validates with the same Zod schemas as the contract (packages/contracts), on blur and on submit.
  • Server VALIDATION_FAILED errors map onto fields through details.fields[].path.
  • The first error gets focus and is scrolled into view. With more than three errors, a summary banner lists them.
• Save bar: a sticky bottom bar appears as soon as the form is dirty (« Modifications non enregistrées » · « Annuler » · « Enregistrer »). Ctrl/Cmd+S saves.
  • Leaving a dirty form asks « Quitter sans enregistrer ? ».
  • While a save is pending, the button shows a spinner and is disabled. Form saves are never optimistic.
• Inputs:
  • Money is typed in DA with two decimals (1 250,00) and sent as integer centimes.
  • Percentages are typed in % and sent as basis points.
  • Phones accept the national format (0555 12 34 56) and are sent in E.164.
  • Dates are entered and shown in Africa/Algiers.
• Files:
  • Drag-and-drop zones check type and size per FilePurpose before upload.
  • Upload runs files.createUpload, then PUT, then files.completeUpload, with per-file progress and retry.
• Permission-gated fields:
  • Without the view permission, the field is not rendered.
  • With view but not update, it is read-only, with a lock icon and the tooltip « Modification réservée aux profils autorisés ».

SettingsCopy Anchor Link

• An anchor navigation on the left lists the groups. Each group is a card with its own « Enregistrer », so saves are independent and a mistake stays contained. Each card shows « Modifié par … le … ».
• Every change is validated by the server and audited (UPDATE on Setting with before/after).
• A change with operational impact (disabling a payment method, raising a minimum app version, changing the GPS tolerance) asks for confirmation. The dialog states the impact in one sentence.
• A user with only the view permission sees the same page, read-only.

DashboardCopy Anchor Link

• Filter bar at the top (period plus dimensions), synced to the URL. « Mis à jour à 09:42 » sits next to a refresh button.
• KPI cards on a 12-column grid: four per row on desktop, two on tablet, six on large screens.
  • A card shows a label, the value, its unit, a comparison (Δ % with an arrow, toned by meaning: up is good for revenue, bad for unpaid amounts), an optional sparkline, and an ⓘ tooltip with the exact definition.
  • A click opens the matching list with the same filters.
• Charts: line, bar or donut, with legend and tooltips. A « Voir les données » toggle swaps the chart for a table (accessibility, NFR-07).
• Card states:
  • Loading: a skeleton.
  • Empty: « Aucune donnée sur la période ».
  • Error: the card alone shows the error; the page keeps working.
  • Not permitted: the card is not rendered.
• Layout comes from admin.dashboard.layout.get (DashboardLayout, per role). Holders of settings.administer can edit it.
• Refresh: on relevant live events (debounced 10 s), every 5 minutes and on window focus (ANA-02).

StatesCopy Anchor Link

Global elementsCopy Anchor Link

App shell and top barCopy Anchor Link

The shell (BO-03) has:

• A sidebar: 256 px wide, collapsible to a 72 px icon rail, with the HOCO logo, groups, items and badges.
• A 56 px top bar with:
  • the global search field (Ctrl K);
  • the live-status dot;
  • the notifications bell with its unread badge;
  • the user menu.

Global searchCopy Anchor Link

• One field, « Rechercher un revendeur, une commande, un produit, une facture… », opened with Ctrl K (⌘K on macOS), calling admin.search.
• Results are grouped (Revendeurs, Commandes, Produits, Factures), with at most five per group, and filtered by permission on the server: a user without finance.view never gets the Factures group. « Voir tous les résultats » opens the group's list with q=.
• Matching:
  • An exact business number (CMD-2026-000158, REV-000123, FAC-2026-000123) is the first result, and Enter opens it.
  • Phones are normalised (0555123456 finds +213555123456).
  • Products match by name, reference or barcode.
• Mechanics: at least 2 characters, debounced 250 ms. Keyboard: ↑ ↓ Enter Esc. The last five searches are stored locally.

Notifications drawerCopy Anchor Link

• The bell opens a 400 px right drawer (NOT-01), fed by notifications.list with cursor pagination.
• Items: tabs « Toutes » / « Non lues ». Each item has an icon for its NotificationCategory, a title, two lines of body, a relative time and an unread dot.
  • Clicking an item marks it read (notifications.markRead, optimistic) and opens its deep link in the back-office.
  • « Tout marquer comme lu » calls notifications.markAllRead.
• Badge (notifications.unreadCount) refreshes on focus, every 60 s, and after each live event.
• Staff typically receive assigned tasks and tickets, accounts to validate, declarations to verify and stock alerts. The notifications matrix is authoritative.

Live events and toastsCopy Anchor Link

• Connection: the shell opens one Server-Sent Events connection per tab, after sign-in, to admin.events.stream (SYN-07). It closes on sign-out.
• Reconnection: exponential backoff (1 s up to 30 s) with Last-Event-ID. When the server can no longer replay the gap, every visible query is invalidated.
• Filtering: the server filters events by permission and scope. The client maps each event to TanStack Query invalidations in one central handler table.

Retours et SAV (BO-69) is live: it listens to return.requested and return.status_changed (contract 1.1.0). The ticket conversation (BO-56) still polls every 60 s while visible: the stream has ticket.created but no reply event. On the reseller side, every status change the back-office makes reaches the reseller live through events.stream and as a push and in-app notification (ORD-15).

Toast rules:

• At most three toasts stack. They dismiss after 6 s (error toasts stay until closed) and announce through aria-live="polite".
• Bursts are grouped: « 5 nouvelles commandes ».
• No toast for the user's own actions (actor = me).
• Each event category can be muted from the user menu (« Alertes en direct »). The choice is stored in the browser.

User menuCopy Anchor Link

• Header: name, email and role labels.
• « Mon profil et sessions » (BO-68).
• « Alertes en direct » (per-category toggles).
• « Langue »: Français. العربية and English appear once enabled (NFR-06).
• « Se déconnecter » (auth.logout): it closes the event stream and returns to BO-01.

Confirmations, reasons and auditCopy Anchor Link

Dialog anatomy:

• The title is a question naming the record: « Refuser la commande CMD-2026-000158 ? ».
• The body states the consequences (stock, notification, irreversibility).
• Required inputs follow (reason, comment).
• The primary button repeats the verb (« Refuser la commande », never « OK »), in the danger tone when destructive. The secondary button is « Annuler ».
• Enter never confirms a destructive dialog.

Re-authentication. Sensitive actions ask for the password again when the last authentication is more than 15 minutes old. They are: role permissions, user status, credit limits, business settings, app-version policy. Assumption — the list and the delay are a decision to confirm (open decisions).

Reasons come from the reference lists (ReferenceItem.listKey) when one exists. Otherwise they are free text of at least 10 characters. An item whose label is « Autre » requires a comment.

Visit not-done reasons (VISIT_NOT_DONE_REASON) and tour suspension reasons (TOUR_SUSPEND_REASON) are entered in the delegate app. The back-office only displays them and filters on them.

BreakpointsCopy Anchor Link

The back-office must work on desktop, tablet and large screens (cahier §9, NFR-05). Akram designs at 1 440 px and checks 1 024 px, 768 px and 1 920 px.

Formatting and languageCopy Anchor Link

• Money: 1 250,00 DA (narrow no-break space for thousands, comma for decimals). Show HT / TTC explicitly wherever both exist.
• Dates and times:
  • Shown as 03/11/2026 and 09:12 in Africa/Algiers. A tooltip gives the full timestamp.
  • Times within the last 24 h are relative (« il y a 5 min »).
  • Periods such as « aujourd'hui » and « ce mois » are business days in Algiers.
• Phones: shown in national format (0555 12 34 56), linked as tel: and as WhatsApp (https://wa.me/213555123456).
• Measures: distances 850 m / 12,4 km; percentages 12,5 %.
• Status labels: the label is the enum's fr and the pill colour is its tone.
• Languages: French in V1. Layouts use logical CSS properties (ms-*, pe-*, start / end) so Arabic (RTL) can be switched on later. No text is baked into images (NFR-06).
• Accessibility: WCAG 2.1 AA contrast. Focus stays visible. Every action is reachable by keyboard, including table rows, dialogs and drag-and-drop alternatives. Charts have a data-table view (NFR-07).

Contract and data notes raised by these specsCopy Anchor Link

Writing the page specs turned up gaps in the endpoint catalogue. These go to the API contract in SRV-03 and to the module tasks:

1. Missing list operations:
   • Credit accounts (BO-46) need GET /admin/credit-accounts (finance.view).
   • Import history (BO-32, BO-67) needs GET /admin/imports (job type permission).
2. Import job permission: admin.imports.get is declared with settings.administer, but product imports are started with catalog.administer. The job should be readable with the permission of its type.
3. Option lists for pickers: the CRUD groups for segments, zones, warehouses, carriers and visit types gate GET with *.administer. Pickers on other pages (filters, forms) must be able to read them with the module's view.
4. List exports: admin.exports.create is declared with reports.export. List exports must also check the module's export permission (orders.export, stock.export…).
5. Delivery failure: DeliveryStatus.FAILED has no operation. Proposal: admin.deliveries.update accepts status: FAILED with a reason, plus a retry.
6. Fulfilment rights: admin.orders.transition requires orders.update, the same permission as line modification and cancellation. Proposal: also accept delivery.update for the PREPARING → READY → SHIPPED → DELIVERED / RETURNED transitions, and drop orders.update from the delivery manager.
7. Order list filters: admin.orders.list needs controls (blocking / warning / ok) and firstOrder filters (BO-38). admin.orders.toConfirm needs status, channel, assistedConfirmation and controls filters (BO-41).
8. KPI inputs:
   • Orders need validatedAt, validatedBy and a snapshot of the attributed delegate (the source delegate for assisted orders, else the reseller's assigned delegate at checkout), so that revenue by delegate stays stable after a reassignment (BO-04).
   • The confirmation delay (validatedAt − submittedAt) feeds the Commandes à confirmer card.
9. Staff-facing label: TicketStatus.WAITING_RESELLER is labelled « En attente de votre réponse » (reseller wording). The back-office shows « En attente du revendeur ».
10. Promotion preview: admin.promotions.preview should return the competing promotions and why each one was excluded (BO-50).
11. Pricing operations to retire: admin.variants.tiers and admin.priceLists.crud / admin.priceLists.items are still listed as V1. Under §1b, quantity tiers are dropped and price lists move to V2 (PRC-03).
    • BO-31 in V1 is the three-price grid. It saves through admin.variants.crud.
    • A bulk price operation (PUT /admin/variants/prices, catalog.update) would save a whole grid in one call.
12. Support and returns events: the admin stream has no ticket.created, ticket.replied or return.requested event. Adding them would make the Tickets et SAV and Retours et SAV badges live like the orders queue.
13. After-sales claim items: admin.tickets.get must return the claimed lines (TicketItem: order line, quantity, AfterSalesIssue, photos) and the resulting replacement order, return or credit note (BO-56).
14. Putting an order on hold: BO-39 and BO-41 offer « Mettre en attente » (SUBMITTED → PENDING, with a reason). admin.orders.transition lists only fulfilment targets, so the transition table and the operation must accept PENDING.
15. Refused at the door: moving a failed delivery to RETURNED (BO-42) should create the ReturnRequest server-side (IN_TRANSIT), so that reception in BO-69 restocks like any return.
16. Credit notes and receipts (V1, FIN-08): the admin finance group has no credit-note list or detail. BO-44 needs GET /admin/credit-notes (or a type filter on invoices), and confirmed payments need a receipt PDF URL (BO-45).
17. Import templates: a GET /admin/imports/{type}/template?category= operation would generate templates whose attribute columns match the category (BO-32, BO-67).

Screen indexCopy Anchor Link