Administration & settings

This area covers what super administrators and managers configure in the back-office (cahier §3, §3.1, §8, §9, §10, §13.2, §13.4, plus the support regions decided on 17 Oct 2026 — AUTHORING §1b.8). Apps: back-office, API, and the mobile apps for the version policy. Server modules: identity and access (users, roles), settings (settings, reference lists, app versions, numbering), jobs (imports), support (support regions). The full settings table is the settings catalogue.

ID	Requirement	Release	Priority	Source	Apps
ADM-01	Staff and delegate user management: create, assign roles, deactivate, reset password	V1	MUST	§3, §10	BO · API
ADM-02	Roles and permissions editor	V1	MUST	§3.1	BO · API
ADM-03	Business parameters: order minimums, reservation status, GPS tolerance and frequency, credit policy, stacking, payment methods, delivery fees, return and after-sales windows	V1	MUST	§8	BO · API
ADM-04	Unique human-readable numbers for resellers, orders, invoices, tours, visits, tickets and returns	V1	MUST	§8	API
ADM-05	Reference lists: business types, potentials, visit types, not-done reasons, issue tags, ticket types, carriers	V1	MUST	§6.5, §6.8	BO · API
ADM-06	Initial imports: products, resellers, user accounts, stock	V1	MUST	§13.2	BO · API
ADM-07	Mobile app versions: minimum and latest version, forced update, maintenance mode	V1	SHOULD	§9, §13.4	BO · API · RA · DA
ADM-08	Support regions: wilayas grouped into regions, each with its WhatsApp support number and hours	V1	MUST	Team decision (17 Oct 2026)	BO · API

ADM-01 — Staff and delegate user managementCopy Anchor Link

Statement — Authorised users shall create staff and delegate accounts, assign roles, reset passwords and deactivate accounts without losing history.

Rules

1. Create (users.create): first and last name, phone (E.164) and/or email (staff need one of them, delegates a phone), one or more roles; unique phone and email among users (409 USER_PHONE_TAKEN, 409 USER_EMAIL_TAKEN). A temporary password is sent by SMS or email; first sign-in forces a change. Delegates also get a profile (FLD-01). Reseller accounts are not created here (CRM).
2. Edit roles (users.update): the last active SUPER_ADMIN cannot be demoted or deactivated (409 LAST_SUPER_ADMIN); DELEGATE and RESELLER cannot be combined with staff roles.
3. Status (admin.users.setStatus): SUSPENDED (temporary) or DISABLED (permanent) revokes all sessions at once; reactivation possible for SUSPENDED; nothing is deleted (SEC-06).
4. Reset password sends a reset code or temporary password and revokes sessions.
5. Every action is audited with actor, target and changes; changing roles needs a recent re-authentication on the back-office.

Acceptance criteria

• Creating a finance manager sends an email with a temporary password; the first sign-in requires a new password.
• Disabling a user revokes their sessions (next call 401) and keeps their orders, visits and audit entries.
• Demoting the only super admin → 409 LAST_SUPER_ADMIN.

Data — User, UserRole, Role, Session, DelegateProfile, AuditLog.

Interfaces

• Screens: BO-18 Delegate create / edit · BO-61 Users
• Endpoints: admin.users.list · admin.users.create · admin.users.update · admin.users.setStatus · admin.users.resetPassword

ADM-02 — Roles and permissions editorCopy Anchor Link

Statement — A super administrator shall edit, per role, the permissions per module and action in a matrix.

Rules

1. Matrix: modules (dashboard, crm, catalog, pricing, stock, orders, delivery, finance, promotions, loyalty, field, support, communication, reports, users, roles, audit, settings) × actions (view, create, update, delete, validate, export, administer).
2. Guard rails: SUPER_ADMIN keeps every permission (409 ROLE_PROTECTED); DELEGATE and RESELLER are scope roles whose back-office permissions cannot be granted (422 PERMISSION_NOT_GRANTABLE). Rules of ACL-02 apply.
3. Saving replaces the role's permission set (roles.administer), is audited as PERMISSION_CHANGE with the diff, and applies to the next request of every user of the role (permission cache at most 60 seconds).

Acceptance criteria

• Removing orders.validate from COMMERCIAL_ADMIN hides the Valider button and the API refuses validation (403 PERMISSION_DENIED) within 60 seconds.

Data — Role, Permission, RolePermission, AuditLog.

Interfaces

• Screens: BO-62 Roles & permissions matrix
• Endpoints: admin.roles.list · admin.roles.updatePermissions

ADM-03 — Business parametersCopy Anchor Link

Statement — The system shall expose the configurable business rules of §8 as typed, validated and audited settings.

Rules

1. Settings are grouped by domain in BO-64: orders (minimum amount, quantities, cancellable statuses, assisted-order delay), stock (reservation and deduction statuses), pricing (TTC/HT display, VAT), credit (over-limit policy, default limit), payments (enabled methods and instructions), promotions (stacking), delivery (fee mode and amounts), field (GPS tolerance and accuracy, sampling frequency and distance, retention, closing and unlock rules), invitations, support, notifications (quiet hours), exports, numbering. Keys, types, defaults and ranges: settings catalogue.
2. There is no stock display setting: resellers and delegates only ever see availability (AUTHORING §1b.1).
3. Each key has a schema; an invalid value → 400 VALIDATION_FAILED with the allowed range. Changes need settings.administer, are audited with old and new values, and take effect within 60 seconds.
4. Settings needed by apps are published by appConfig.get (public subset, no sensitive value) and, for the delegate app, by sync.delta.

Acceptance criteria

• Setting field.gpsToleranceMeters to 5 → 400 VALIDATION_FAILED (range 20–1000); setting 200 is audited and applied by delegate apps at their next refresh.

Data — Setting, AuditLog.

Interfaces

• Screens: BO-64 Business settings
• Endpoints: appConfig.get · admin.settings.get · admin.settings.update

ADM-04 — Human-readable business numbersCopy Anchor Link

Statement — The system shall give resellers, orders, invoices, delivery notes, payments, tours, visits, tickets and returns a unique, sequential, human-readable number.

Rules

1. Formats: REV-000123, CMD-2026-000158, FAC-2026-000123, BL-2026-000123, PAY-2026-000077, TRN-2026-000045, VIS-2026-001234, TKT-2026-000045, RET-2026-000012; yearly sequences restart on 1 January (Africa/Algiers).
2. Numbers are allocated from NumberSequence inside the creating transaction (row lock), so they are unique under concurrency and gap-free (required for invoices); never reused or changed.
3. Records created offline receive their number when they reach the server; the app shows « Numéro attribué à la synchronisation » until then.

Acceptance criteria

• 100 concurrent checkouts produce 100 distinct consecutive CMD- numbers; the first order of 2027 is CMD-2027-000001.

Data — NumberSequence.

Interfaces — none (internal).

ADM-05 — Reference listsCopy Anchor Link

Statement — Administrators shall maintain the reference lists used in forms.

Rules

1. Editable lists (ReferenceItem.listKey): BUSINESS_TYPE, PERSON_ROLE, VISIT_NOT_DONE_REASON, VISIT_ISSUE_TAG, TOUR_SUSPEND_REASON, ORDER_REFUSAL_REASON, ORDER_CANCEL_REASON, PAYMENT_REJECT_REASON. Visit types are configured in FLD-16, carriers in DLV-04; potentials and ticket types are fixed enums.
2. Item: immutable code, labels fr (required), ar and en, order, active flag, options (e.g. comment required).
3. Items in use are deactivated, never deleted (409 REFERENCE_ITEM_IN_USE); clients cache lists with ETag; the delegate app receives changes through sync.delta.

Acceptance criteria

• Adding Travaux devant le magasin to VISIT_NOT_DONE_REASON makes it selectable in the delegate app after its next sync; deleting a used reason is refused.

Data — ReferenceItem.

Interfaces

• Screens: BO-65 Reference lists
• Endpoints: reference.lists · admin.referenceLists.crud

ADM-06 — Initial importsCopy Anchor Link

Statement — The system shall import products, resellers, user accounts and stock from Excel/CSV files with a validation report before applying.

Rules

1. Downloadable templates per type; upload (≤ 10 MB, ≤ 10 000 rows) creates an ImportJob; a dry run returns a row-level report (OK, warning, error with column and message).
2. Apply only after a dry run; by default all-or-nothing, or « Ignorer les lignes en erreur »; idempotent by natural key (product reference, variant SKU, reseller phone, user phone or email, SKU + warehouse) so a re-import updates instead of duplicating.
3. Resellers get source IMPORT; delegates are matched by code; users are created without passwords and receive an invitation; stock rows post INVENTORY movements with reason « Import initial ».
4. Permission settings.administer; each import audited (IMPORT). Source formats: D-31.

Acceptance criteria

• A reseller file with one duplicate phone reports that row as an error in the dry run; applying with Ignorer imports the others; re-importing the same file creates no duplicates.

Data — ImportJob, File, Product, ProductVariant, Reseller, User, StockMovement, AuditLog.

Interfaces

• Screens: BO-67 Data imports
• Endpoints: admin.imports.create · admin.imports.get

ADM-07 — Mobile app versions and maintenanceCopy Anchor Link

Statement — Administrators shall set, per app and platform, the minimum and latest version and a maintenance mode, which the apps enforce.

Rules

1. AppVersionPolicy per app (reseller, delegate) × platform (android, ios): minimum version, latest version, store URL, update message, maintenance flag with message and expected end.
2. Apps check appConfig.get at start and at foreground (at most every 15 minutes): below minimum → blocking update screen (the API also answers 426 UPGRADE_REQUIRED); below latest → dismissible prompt once a day; maintenance → blocking screen (API 503 MAINTENANCE).
3. During maintenance or a forced update the delegate app keeps working offline and keeps its queue; it syncs once allowed.

Acceptance criteria

• Raising the delegate Android minimum to 1.2.0 blocks version 1.1.0 with the update screen; its queued items sync after the update.

Data — AppVersionPolicy.

Interfaces

• Screens: RA-01 Splash · RA-36 System states · DA-01 Splash · DA-28 System states · BO-66 Mobile app versions
• Endpoints: appConfig.get · admin.appVersions.crud

ADM-08 — Support regionsCopy Anchor Link

Statement — Administrators shall group wilayas into support regions, each with a WhatsApp support number and hours.

Rules

1. SupportRegion: name, WhatsApp number (E.164, Algerian), opening hours (days and times), active flag; SupportRegionWilaya: each wilaya belongs to at most one region (409 WILAYA_ALREADY_IN_REGION).
2. A wilaya without region falls back to support.defaultWhatsappNumber; BO-70 lists uncovered wilayas.
3. Permission settings.administer; changes audited and effective at the next support.whatsapp call (SUP-05).

Acceptance criteria

• Creating region Ouest with Oran, Tlemcen and Mostaganem returns its number to resellers of those wilayas; adding Oran to another region → 409 WILAYA_ALREADY_IN_REGION.

Data — SupportRegion, SupportRegionWilaya, Wilaya, Setting, AuditLog.

Interfaces

• Screens: BO-70 Support regions & WhatsApp numbers
• Endpoints: admin.supportRegions.crud

Notes / open points — Region list and numbers: D-36.