Requirements
How HOCO's requirements are written, prioritised and traced, and the 25 requirement areas with their V1/V2 counts.
This section is the normative core of the SRS: 194 requirements in 25 areas, each traced to the client's Cahier des charges (cahier) and down to the screens, API operations and plan tasks that deliver it. The canonical list — id, title, release, priority, source and apps — lives in content/spec/requirements.json; every area page renders it with <RequirementTable> and then specifies each requirement in full. Behaviour that spans many areas is gathered on dedicated pages: lifecycles and statuses, business rules, the permissions matrix, the notifications matrix, the acceptance scenarios of cahier §12 and the cross-cutting requirements.
How a requirement is written
Every requirement on an area page has the same parts, in the same order.
| Part | What it contains | Who relies on it |
|---|---|---|
| Heading | ORD-08 — Assisted orders, with the explicit anchor #ord-08. Ids are AREA-NN, stable, never renumbered and never reused. | Links from tasks, screens, API pages, PRs |
| Header table | Release (V1/V2) · Priority (MUST/SHOULD/COULD) · Source (cahier section, reference screen or team decision) · Apps (BO, RA, RW, DA, API, OPS) · Owner tasks (every task of the plan whose srs list contains the id) | Planning, scope discussions |
| Statement | One sentence, "The system shall …": the obligation itself. | Everyone |
| Rules | Numbered, normative details: limits, defaults and the setting that holds them, the order in which checks run, who may do what, what is recorded and who is notified. | Developers, testers |
| Acceptance criteria | Testable bullets, often Given/When/Then, including the negative cases with their HTTP status and stable error code (409 ORDER_TRANSITION_NOT_ALLOWED). | QA scripts (QA-03), API integration tests, the client's acceptance |
| Data | The canonical Prisma models involved (names from the database design). | Server, database |
| Interfaces | The screens and API operations that list the requirement in screens.json / endpoints.json, linked to their specification. | Design, mobile, web |
| Notes / open points | Assumptions and links to the decision register when a rule depends on a decision HOCO has not taken yet. | Anis, client |
Wording. Shall / must is mandatory; should is the expected behaviour unless a recorded reason says otherwise; may is permitted, not required. "Default 72 h (setting orders.assistedConfirmationHours)" means the value is a business parameter an authorised user changes in the back-office (ADM-03) without a release; a value written without a setting key is a platform constant that changes only with a release.
Citing a rule. Tickets, tests and pull requests cite rules as ORD-02 R3 (requirement id, then rule number). Test names start with the citation: it("ORD-02 R3 — rejects a quantity that is off the step"). A rule is never renumbered once the requirement has shipped; new rules are appended.
Error codes. Codes quoted in acceptance criteria are the stable error.code values of the API envelope, with the HTTP status that carries them. Validation problems on a single field are reported inside 400 VALIDATION_FAILED as a field code (details.fields[].code, e.g. INVALID_PHONE). The full registry is on API › Errors.
Priority
| Priority | Meaning | Consequence |
|---|---|---|
| MUST (155) | Required for the release to be accepted. Most map directly to a priority scenario of cahier §12. | A failing MUST acceptance criterion is a blocking defect: the acceptance report (PV de recette) is not signed while it is open. No workaround counts as done. |
| SHOULD (33) | Expected in the release and planned with effort and an owner. | If a blocker threatens the date, a SHOULD may move to the next patch release with HOCO's written agreement; it is then a major defect, not a blocking one. |
| COULD (6) | Valuable but optional. | Built when capacity allows; otherwise moved to a later release without a change request. |
Release
| Release | Scope | When |
|---|---|---|
| V1 (177) | The cahier's recommended first version (§14.1): back-office CRM, catalog, stock, orders, delegates, tours, notifications and essential reports; reseller account, catalog, cart, order, tracking, simple promotions and support; delegate tour, GPS, visit, prospect, invitation, first order, report and closing. The reseller web app (team decision) is V1 scope too: it is built in P1 and deployed with the rest, before acceptance and the pilot. | Designed, built and deployed within the three-month V1 frame: built in P1 (reseller web included), accepted, put in production and piloted in P2; generalisation (P3) follows the three months — see the timeline. |
| V2 (17) | The cahier's evolutions (§14.2): advanced loyalty, profitable packs, detailed credit, returns/after-sales, carrier API, WhatsApp Business API, accounting/ERP integration, stock-system API sync, tour optimisation and advanced analytics. | Phase P4. Designs are produced during P1 (DES-30) and the contract is extended first (SRV-29). |
Release is about product scope; phases P0–P4 are about the plan. A V1 requirement may leave room for its V2 successor (for example CreditNote exists in the data model but is only written in V2), and a V2 requirement never weakens a V1 rule.
Traceability
- Upstream. The Source column cites the cahier section (
§4.4), a client reference screen, or a dated team decision. The source traceability page maps every cahier section to its requirements, so nothing in the cahier is left without a requirement. - Downstream.
tasks.jsonlists the requirements each task delivers (srs),screens.jsonandendpoints.jsonlist the requirements each screen and operation serves (reqs). The header table and the Interfaces list of every requirement are built from those files, so a requirement with no owner task or no interface is visible at a glance. - Done. A requirement is done when its operations exist in the contract and are implemented, every acceptance criterion has an automated test or a QA script that passes on staging, its screens match the design QA, and the notifications and audit entries it specifies are produced.
- Change. Requirements change only through the change-request process: the id is kept, the change is dated in the PR, and the plan is re-estimated when effort moves.
Conventions every page assumes
These are defined once in the API reference and apply to every requirement:
- Money is an integer number of centimes of DZD (
249000= 2 490,00 DA); rates and percentages are basis points (1900= 19 %). Rounding is half-up to the centime, at the steps stated in PRC-02 and PRC-04. - Time is stored in UTC; "today", business days, due dates and daily jobs use
Africa/Algiers(UTC+1, no daylight saving). - Phones are stored and returned in E.164 (
+213555123456) — normalisation rules in CRM-03. - Permissions are
<module>.<action>keys checked on every operation; resellers are limited to their own data (self) and delegates to their zones and assigned resellers (delegate) — see ACL-05. - Idempotency. Mutations accept
Idempotency-Key; it is required on checkout, offline sync and every delegate mutation, so a retried request never creates a second order, prospect or visit. - French first. UI labels quoted in requirements (« Valider la commande ») and status labels come from the enums; Arabic and English are prepared.
Areas
| Code | Area | V1 | V2 | Total | of which MUST |
|---|---|---|---|---|---|
AUTH | Authentication & accounts | 11 | 0 | 11 | 11 |
ACL | Roles, permissions & data scope | 5 | 0 | 5 | 5 |
AUD | Audit trail & history | 3 | 0 | 3 | 2 |
GEO | Geography, zones & GPS | 4 | 0 | 4 | 3 |
CRM | Resellers & prospects (CRM) | 12 | 1 | 13 | 11 |
CAT | Catalog | 13 | 0 | 13 | 10 |
PRC | Pricing | 4 | 1 | 5 | 4 |
STK | Stock | 8 | 1 | 9 | 7 |
ORD | Cart & orders | 15 | 0 | 15 | 14 |
DLV | Preparation & delivery | 5 | 1 | 6 | 3 |
FIN | Invoicing, payments & credit | 7 | 3 | 10 | 5 |
PRM | Promotions & packs | 5 | 1 | 6 | 3 |
LOY | Loyalty programme | 0 | 5 | 5 | 0 |
FLD | Field operations (delegates, tours, visits) | 18 | 1 | 19 | 16 |
IVT | Invitations & activation | 4 | 0 | 4 | 4 |
SUP | Support & claims | 5 | 0 | 5 | 4 |
NOT | Notifications & messaging | 7 | 1 | 8 | 5 |
ANA | Dashboards, KPIs & reports | 5 | 1 | 6 | 4 |
ADM | Administration & settings | 8 | 0 | 8 | 7 |
SYN | Synchronisation & offline | 7 | 0 | 7 | 7 |
INT | External integrations | 6 | 1 | 7 | 6 |
RWA | Reseller web app | 2 | 0 | 2 | 1 |
NFR | Non-functional requirements | 9 | 0 | 9 | 9 |
SEC | Security, privacy & compliance | 8 | 0 | 8 | 8 |
OPS | Deployment, training & maintenance | 6 | 0 | 6 | 6 |
| Total | 25 areas | 177 | 17 | 194 | 155 |
AUTH — Authentication & accounts
ACL — Roles, permissions & data scope
AUD — Audit trail & history
GEO — Geography, zones & GPS
CRM — Resellers & prospects (CRM)
CAT — Catalog
PRC — Pricing
STK — Stock
ORD — Cart & orders
DLV — Preparation & delivery
FIN — Invoicing, payments & credit
PRM — Promotions & packs
LOY — Loyalty programme
FLD — Field operations (delegates, tours, visits)
IVT — Invitations & activation
SUP — Support & claims
NOT — Notifications & messaging
ANA — Dashboards, KPIs & reports
ADM — Administration & settings
SYN — Synchronisation & offline
INT — External integrations
RWA — Reseller web app
NFR — Non-functional requirements
SEC — Security, privacy & compliance
OPS — Deployment, training & maintenance
End-to-end test plan
QA-01 on staging: the fifteen priority scenarios and the 17 October decision scenarios run on the seeded data, step by step per app with the API operations, the cross-app and returns / after-sales runs, the device matrix, the defect scale and daily triage, the hardening checks and the test-data reset.
Authentication & accounts
Sign-in for staff, delegates and resellers, guest browsing, reseller sign-up with a declared customer type, account claim, one-time codes, sessions, account statuses, devices and app versions.