{ "meta": { "title": "Neuro Frontend — Feature Inventory", "application": "neuro-frontend (Ember Octane back office for shopping-centre operators)", "version": "4.0.0-dev", "generated": "2026-10-12", "gitCommit": "276788ca6", "sources": [ "app/router.js — 9 top-level product areas, ~140 routes", "app/routes/**, app/controllers/** — behaviour, actions and error handling", "app/models/** — 130 models; `get validations()` blocks are the authoritative source for failure paths", "app/abilities/** — 55 ember-can classes; the authoritative source for role and module gating", "app/enums/** — statuses, types and filter palettes", "translations.json — 3,214 keys; feature names come from `menu.navbar.*` / `title.header.*` and failure messages from `error.*` and the per-feature namespaces" ], "schema": { "id": "stable slug", "name": "feature name as an operator would say it", "area": "product area", "label": "the translation key(s) the UI labels this feature with", "routes": "Ember route names", "code": "primary implementation files", "models": "Ember Data models touched", "modules": "centre modules that must be enabled", "roles": "staff levels allowed", "description": "what the feature does", "comments": "how it actually works, including quirks and weak spots found in the code", "useCases": "why an operator reaches for it", "happyPaths": "named end-to-end success flows, as ordered steps", "failurePaths": "named failure modes with cause and observed handling", "i18nKeys": "translation keys that evidence the above", "i18nMissing": "translation keys this feature uses that do not exist in translations.json (rendered as raw keys)" }, "notes": [ "Permissions in this product are three-dimensional: staff level x centre module x record state. A feature can be invisible for any of the three reasons, and the UI rarely says which.", "Failure paths are taken from the code, not inferred: model `validations` blocks, `.catch()` handlers and `throw` guards. Where a failure is swallowed or leaves a stuck spinner, that is recorded as the handling, because it is what an operator will actually experience.", "Several translation namespaces have no remaining code references and look like dead or not-yet-built surface: `bonusRequest` (22 keys), `dmr-weekly`, `marketing-analytics` (16 keys), `commerce-stay-alert` (4 keys, though an ability and a menu key still exist), plus partial remnants of `leasing`, `lineitem` and `supplier`. They are deliberately not listed as features.", "Two CSV-import implementations coexist (`nf-import` and the older `import-csv`) with different robustness; `import-csv.errors.load.required-selections` is still in Portuguese while its siblings are English." ], "counts": { "areas": 10, "features": 92, "useCases": 331, "happyPaths": 136, "failurePaths": 436 }, "review": { "method": [ "Every route in app/router.js is referenced by at least one feature.", "100 of 101 controllers and all feature-bearing route files are referenced; the remaining route files are pageHeader-only parents.", "The side menu (utils/get-side-nav-menu.js) was walked entry by entry, including commented-out and module-disabled entries.", "Unreferenced models, serializers and components were traced to their templates to find hidden features (mobile-app config, login methods, integrations, social wifi, Froged, analytics, the dormant action log).", "All 2,598 translation keys used literally in code were checked against translations.json." ], "addedInReview": [ "platform-runtime-config", "platform-ui-language", "platform-support-widget", "xc-product-analytics", "config-mobile-app", "config-customer-login", "config-integrations", "config-social-wifi-location", "crm-customer-action-log" ], "i18nMissingKeys": { "access-to-account-types.client": [ "app/enums/access-to-account-types.js" ], "access-to-account-types.employee-shop": [ "app/enums/access-to-account-types.js" ], "access-to-account-types.employee-outsource": [ "app/enums/access-to-account-types.js" ], "error.server-incident.required": [ "app/models/server-incident.js" ], "error.communication.store.required": [ "app/models/intranet-communication.js" ], "reference-campaign": [ "app/models/campaign.js" ], "reference-date": [ "app/models/campaign.js" ], "error.month.required": [ "app/models/anonymazed-saft.js" ], "cms.multicentre-proposal.general-data": [ "app/controllers/cms/multicentre-proposals/new.js" ], "server-incident": [ "app/templates/configuration/server-incidents/index.hbs" ], "crm.commercy-types": [ "app/templates/crm/commerce-types/index.hbs" ], "email-campaign.insert-variable.placeholder": [ "app/templates/components/email-variable-selector.hbs" ], "intranet.communications.terms-and-conditions": [ "app/templates/components/eula-communications-modal.hbs" ], "actions.edit": [ "app/templates/components/form-user/row-actions.hbs" ], "multicentreProposal": [ "app/templates/cms/multicentre-proposals/index.hbs" ], "cms.proposals.new.image-generation.gif": [ "app/templates/cms/proposals/new.hbs" ], "want_reject_publish": [ "app/templates/cms/proposals/index.hbs" ], "activityCampaign": [ "app/templates/marketing/activity-campaigns/index.hbs" ], "sovosFile": [ "app/templates/intranet/safte/import/index.hbs" ] }, "deadSurface": { "commerce-stay-alert": "model, ability and menu translation exist; no route, template or menu item", "bonusRequest": "22 translation keys and an env comment; no code", "marketing-analytics": "16 keys; only used as a disabledByModule flag", "dmr-weekly": "keys only", "customer action log": "component and model built, not mounted in any template", "supplier / lineitem / service models": "only referenced by enums and the campaign report" } } }, "productAreas": [ { "id": "Platform & Access", "description": "Authentication, session lifecycle, centre scoping and the landing desktop — the shell every other feature runs inside." }, { "id": "CRM", "description": "Customer, segment, store and receipt management: the customer database and everything that reads or writes it." }, { "id": "Marketing", "description": "Activities (campaigns with loyalty mechanics), email campaigns and the embedded loyalty/gift/booking platforms." }, { "id": "CMS", "description": "Content published to the mobile app and web: proposals, push notifications, categories and the app button layout." }, { "id": "Intranet", "description": "Centre-to-tenant operations: sales declaration and closing, annual statements, communications, documents, footfall, SAFT-E and utilities." }, { "id": "Analytics", "description": "Dashboards and the prebuilt CRM / data-quality panels." }, { "id": "Play Center", "description": "Supervised play-area stays: child check-in and check-out against capacity." }, { "id": "Configuration", "description": "Tenant and platform administration: centres and their modules, staff accounts, reference data, dashboards and operational tooling." }, { "id": "Smart Assistant", "description": "The embedded conversational assistant (CandelarIA)." }, { "id": "Cross-cutting", "description": "Shared engines and layers reused by many features: imports, exports, filters, files, i18n, realtime, permissions and error handling." } ], "features": [ { "id": "platform-login", "name": "Staff login", "area": "Platform & Access", "label": "menu.navbar.logout / form-login", "routes": [ "user.login" ], "code": [ "app/routes/user/login.js", "app/components/form/form-login.js", "app/authenticators/", "app/services/auth.js" ], "models": [ "staff-member" ], "modules": [], "roles": [ "any staff level" ], "description": "Email + password authentication for back-office staff. On success a bearer token is stored in the ember-simple-auth session and the current user, their centers and their dashboards are loaded.", "comments": "Auth state lives in the `auth` service: the token is aliased from `session.data.authenticated.token`, while the active centre is persisted as a `cid` cookie (max-age 86400) rather than in the session. `auth.load()` hydrates user + centers + dashboards and is re-run in `routes/index.js#beforeModel` because right after login those relationships are not yet in the store. The user is also pushed to Sentry (`sentrySetUser`).", "useCases": [ "A centre manager signs in at the start of a shift to work on sales, proposals or customers.", "An admin with several centres signs in and then picks which centre to operate on.", "An external/API-level account authenticates to obtain a token." ], "happyPaths": [ { "name": "Successful sign-in", "steps": [ "Staff member opens /user/login and enters email + password.", "Credentials are posted to the API authenticator; a bearer token comes back.", "`auth.load()` resolves the user, the list of accessible centres and the dashboards.", "The `cid` cookie is set to the default centre and the app transitions to the desktop (`index`).", "The side menu is rebuilt from the user's role and the centre's enabled modules." ] } ], "failurePaths": [ { "name": "Wrong credentials", "cause": "API rejects the email/password pair.", "handling": "The login form stays on screen and surfaces the authenticator's error; no token is stored." }, { "name": "Centre cookie unavailable", "cause": "Cookies blocked or `cid` missing — `auth.getCookie` throws `NoCookieError`.", "handling": "`centerId`/`centerGid` getters swallow the error and return an empty string, so centre-scoped queries silently run without a centre filter. Worth treating as a known weak spot: the UI does not warn the user." }, { "name": "Role not recognised", "cause": "`auth.user.role` is not one of the values in `enums/staff-levels`.", "handling": "`nf-navbar#menu` returns `[]`, so the user lands on an app with an empty navigation menu instead of an explicit error." }, { "name": "Session invalidated mid-use", "cause": "Token expired or rejected by the API.", "handling": "`routes/application.js` catches the failure and calls `session.invalidate()`, returning the user to login." } ], "i18nKeys": [ "menu.navbar.logout", "pass-required", "match-pass" ], "i18nMissing": [] }, { "id": "platform-reset-password", "name": "Password reset request", "area": "Platform & Access", "label": "change-password.titles", "routes": [ "user.reset-password" ], "code": [ "app/routes/user/reset-password.js", "app/components/form/reset-password.js" ], "models": [ "staff-member" ], "modules": [], "roles": [ "unauthenticated" ], "description": "Public form where a staff member asks for a password-reset email by entering their address.", "comments": "Deliberately unauthenticated and paired with `update_password/:token`. The route itself is a thin shell (9 lines); the work is in the `reset-password` component.", "useCases": [ "Staff member forgot their password and needs a reset link.", "An admin tells a user to self-service a reset instead of re-issuing credentials." ], "happyPaths": [ { "name": "Reset email requested", "steps": [ "User opens /user/reset-password and submits their email.", "API queues a reset email containing a tokenised link.", "A confirmation message is shown; the user leaves the app and opens the email." ] } ], "failurePaths": [ { "name": "Unknown email", "cause": "Address does not belong to a staff member.", "handling": "Handled by the API response; the form reports the error. Note the flow does not distinguish 'unknown address' from 'sent' in the UI copy, which is the usual anti-enumeration behaviour." }, { "name": "Mail delivery fails", "cause": "Email provider error downstream.", "handling": "No frontend feedback loop exists — the user simply never receives the link and must retry." } ], "i18nKeys": [ "change-password.titles" ], "i18nMissing": [] }, { "id": "platform-update-password", "name": "Password update from reset link", "area": "Platform & Access", "label": "change-password.success-message", "routes": [ "update_password/:token" ], "code": [ "app/routes/update-password.js", "app/controllers/update-password.js" ], "models": [ "staff-member" ], "modules": [], "roles": [ "unauthenticated (token-bearing)" ], "description": "Token-gated screen where a staff member sets a new password and confirmation.", "comments": "The route pre-flights the token (`isValidToken: 200 === checkToken.status`) before rendering, so an expired link is detected on entry rather than on submit. The controller runs its own `validate()` that requires a password and checks the confirmation match before calling the API.", "useCases": [ "Completing a self-service password reset.", "A newly created staff member setting their first password after the 'send password email' action." ], "happyPaths": [ { "name": "Password changed", "steps": [ "User opens the tokenised URL; the route validates the token against the API (HTTP 200).", "User types the new password twice.", "Local validation passes (non-empty, both fields match, format rules from the staff-member model).", "API accepts the change and `change-password.success-message` is shown." ] } ], "failurePaths": [ { "name": "Expired or tampered token", "cause": "Token check returns a non-200 status.", "handling": "`isValidToken` is false and the form is not usable; the user must request a new reset email." }, { "name": "Empty password", "cause": "Field left blank.", "handling": "Local validation sets `errors.password` to `pass-required`; no request is sent." }, { "name": "Confirmation mismatch", "cause": "The two fields differ.", "handling": "`match-pass` is shown inline (also enforced by the staff-member model's `passConfirmation.match` rule)." }, { "name": "Weak password", "cause": "Fails `/^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).{10,}$/` — needs lower + upper + digit and 10+ characters.", "handling": "`pass-format` message from the staff-member validations." } ], "i18nKeys": [ "change-password.success-message", "pass-required", "match-pass", "pass-format" ], "i18nMissing": [] }, { "id": "platform-change-own-password", "name": "Change own password", "area": "Platform & Access", "label": "menu.navbar.configuration.password", "routes": [ "configuration.password", "configuration.password.index" ], "code": [ "app/routes/configuration/password.js", "app/components/form-password.js" ], "models": [ "staff-member" ], "modules": [], "roles": [ "any authenticated staff level" ], "description": "Authenticated self-service password change requiring the current password plus a new one and its confirmation.", "comments": "Extends the generic `routes/form.js` save pipeline, so model validation runs before `save()` and the route redirects to `returnRoute` on success. It overrides the super call with a `.catch()` so an API rejection keeps the user on the form instead of transitioning away. The menu entry excludes `content_creator`, `calibrator` and `external`, so those levels have no self-service password change from the menu.", "useCases": [ "Routine credential rotation.", "A user who suspects their password was shared changing it immediately." ], "happyPaths": [ { "name": "Password rotated", "steps": [ "User opens Configuration → Change password.", "Enters current password, new password and confirmation.", "Model validations pass (`passOld` present, `pass` matches the format rule, `passConfirmation` matches `pass`).", "`informative-message.change-password.success.message` is shown and the user is returned to the previous route." ] } ], "failurePaths": [ { "name": "Current password missing or wrong", "cause": "`passOld` blank (local) or rejected by the API.", "handling": "`current-pass-required` locally; API errors are caught by the overridden `_super(...).catch()` so the form is kept open." }, { "name": "New password too weak", "cause": "Fails the 10-character mixed-case + digit format rule.", "handling": "`pass-format` inline error, no request sent." }, { "name": "Confirmation mismatch", "cause": "`passConfirmation` ≠ `pass`.", "handling": "`match-pass` inline error." } ], "i18nKeys": [ "menu.navbar.configuration.password", "informative-message.change-password.success.message", "current-pass-required", "pass-format", "match-pass" ], "i18nMissing": [] }, { "id": "platform-auto-logout", "name": "Idle auto-logout", "area": "Platform & Access", "label": "modal.logout.description", "routes": [ "(application-wide)" ], "code": [ "app/services/idle-monitor.js", "app/controllers/application.js", "app/models/module-auto-logout.js" ], "models": [ "module-auto-logout" ], "modules": [ "auto_logout" ], "roles": [ "all" ], "description": "Per-centre inactivity timer that warns the user and then ends the session. The timeout in minutes is configured on the centre's `auto_logout` module.", "comments": "The monitor listens to `mousemove`, `mousedown`, `keypress` and `touchmove` on `window` and restarts an Ember `later()` timer on each event. It is a no-op when the module is disabled or `minutes` is unset. The application controller exposes `keepSessionActive` and `logoutNow`, plus `minutesBeforeLogout` for the warning copy. Note `willDestroy` removes listeners using fresh `.bind(this)` references, so those `removeEventListener` calls do not actually detach the original handlers — a real leak if the service is ever torn down.", "useCases": [ "A shopping-centre back office on a shared desktop where unattended sessions must not stay open.", "Centres with stricter data-protection requirements enabling a short window while others leave it off." ], "happyPaths": [ { "name": "Session kept alive", "steps": [ "Centre has `auto_logout.enabled` with e.g. 15 minutes.", "User is idle; the timer fires and the warning modal appears with the remaining minutes.", "User clicks 'keep session active'; the timer resets and work continues." ] }, { "name": "Idle session closed", "steps": [ "User walks away; no input events arrive before the timeout.", "`logout` is triggered, the session is invalidated and the app returns to the login screen." ] } ], "failurePaths": [ { "name": "Module enabled but minutes unset", "cause": "`auto_logout.minutes` is undefined.", "handling": "`logout()` returns early and `msBeforeLogout` is 0 — the feature silently does nothing, so a half-configured centre believes it is protected when it is not." }, { "name": "Centre not loaded yet", "cause": "`auth.center` is still null during boot.", "handling": "`resetTimer`/`msBeforeLogout` guard on the missing centre and skip scheduling until it is available." }, { "name": "Unsaved work lost", "cause": "Logout fires while a long multi-step form (campaign, proposal, centre) is half-filled.", "handling": "No draft persistence — the in-memory records are discarded with the session. A known UX risk on long wizards." } ], "i18nKeys": [ "modal.logout.description", "modules-auto-logout" ], "i18nMissing": [] }, { "id": "platform-center-switching", "name": "Centre switching & multi-centre scoping", "area": "Platform & Access", "label": "menu.navbar.configuration.my-center", "routes": [ "(application-wide)" ], "code": [ "app/services/auth.js", "app/components/nf-navbar.js", "app/utils/get-side-nav-menu.js" ], "models": [ "center", "modules" ], "modules": [], "roles": [ "all; `admin` sees every centre, others only `user.centers`" ], "description": "The navbar centre picker sets the active centre, which scopes virtually every list query (`filter.center_id`), drives which modules are enabled and therefore which menu entries and features exist at all.", "comments": "This is the single most load-bearing cross-cutting concern in the app. `nf-navbar#centers` returns all centres for `admin` and only `auth.centersAvailable` otherwise. `nf-navbar#menu` filters each section by role (`section.levels`), by module (`has`), by `disabledByModule`, or by an ember-can ability when `section.ability` is set. Dashboards are injected into the menu dynamically from `auth.dashboards`. Centre selection is a cookie, not session state, so it survives reloads but is also shared across tabs.", "useCases": [ "A group-level admin comparing or administering several shopping centres from one login.", "Enabling a feature for one centre only — e.g. Yardi, Fideliza or the lottery module — without a code change.", "A store-level user restricted to a single centre and its stores." ], "happyPaths": [ { "name": "Switch active centre", "steps": [ "Admin opens the centre dropdown in the navbar.", "Picks another centre; `auth.center` setter writes the new `cid` cookie.", "Menu recomputes from the new centre's modules and the user's role.", "Subsequent list queries carry the new `center_id` as a fixed filter." ] } ], "failurePaths": [ { "name": "Module disabled", "cause": "Centre does not have the module that guards a section.", "handling": "The menu entry is filtered out and the corresponding route's ability check (`canAccess`) blocks direct URL entry." }, { "name": "Role lacks the level", "cause": "`section.levels` does not include the user's role.", "handling": "Entry hidden; route-level `can` checks reject manual navigation." }, { "name": "Stale cookie pointing at a lost centre", "cause": "`cid` references a centre the user no longer has access to.", "handling": "`auth.center` resolves to `undefined` via `findBy`, and downstream `get(center, 'has…')` checks fall back to false, producing an app with almost no menu rather than a clear 'no access' message." } ], "i18nKeys": [ "menu.navbar.configuration.my-center", "menu.navbar.configuration.centers" ], "i18nMissing": [] }, { "id": "platform-incident-alert", "name": "Server-incident banner", "area": "Platform & Access", "label": "menu.navbar.server-incidents", "routes": [ "(application-wide)" ], "code": [ "app/controllers/application.js", "app/components/nf-incident-alert.js" ], "models": [ "server-incident" ], "modules": [], "roles": [ "all" ], "description": "In-app banner that surfaces an open server incident (title, description, last update) to every user, dismissible per session.", "comments": "Consumer side of the Server incidents admin feature. The application controller exposes `incidentTitle`, `incidentDescription`, `incidentUpdatedAt` and `incidentAlertIsClosed` plus a `closeIncident` action. Dismissal is per user per session, so a re-login re-shows the alert.", "useCases": [ "Telling all back-office users that receipt validation is degraded before they open support tickets.", "Announcing a maintenance window from inside the product." ], "happyPaths": [ { "name": "Incident announced and acknowledged", "steps": [ "An admin creates a server incident under Configuration.", "Every signed-in user sees the banner with title, description and update time.", "A user clicks close; `incidentAlertIsClosed` hides it for the rest of the session." ] } ], "failurePaths": [ { "name": "No open incident", "cause": "Nothing unresolved to display.", "handling": "Banner is simply not rendered." }, { "name": "Incident resolved but banner cached", "cause": "The alert is resolved after the page was loaded.", "handling": "No live push — the banner clears on the next load/refresh." } ], "i18nKeys": [ "menu.navbar.server-incidents", "title.header.configuration.server-incidents" ], "i18nMissing": [] }, { "id": "platform-desktop", "name": "Desktop (home dashboard)", "area": "Platform & Access", "label": "title.header.desktop", "routes": [ "index" ], "code": [ "app/routes/index.js", "app/controllers/index.js" ], "models": [ "dashboard", "receipt" ], "modules": [], "roles": [ "all; pending-receipts nudge only for admin, manager, crmmanager" ], "description": "The landing screen after login. It renders whichever dashboard is configured with `category: 'home'` — a custom panel, the data-quality panel or an embedded external URL — and nudges moderators when receipts are waiting.", "comments": "`beforeModel` re-runs `auth.load()` because dashboards and the centre are often not in the store yet right after login. The panel value is validated against `enums/dashboard-panels` into `isValidDashboard`, and the controller branches on `isCustomDashboard` / `isExternalUrlDashboard`. For external-URL dashboards the page header is hidden (`pageHeader.isHidden`) and restored in `deactivate`. The pending-receipts modal is gated on a `canShowReceiptsModal` sessionStorage flag and shown once, 3 seconds after load, only if the query returns at least one pending receipt.", "useCases": [ "A CRM manager landing on registration-quality KPIs each morning.", "A centre embedding an external BI dashboard as the default home screen.", "Reminding moderators that receipts are queued for verification." ], "happyPaths": [ { "name": "Custom home dashboard", "steps": [ "User logs in and lands on `index`.", "A dashboard with `category: 'home'` and `panel: 'custom'` is found.", "Its configured filters are pushed into the controller models and `ctrl.settle()` runs.", "Charts and KPI tiles render with the current month's date range as the default." ] }, { "name": "Receipts nudge", "steps": [ "An admin/manager/crmmanager logs in with `canShowReceiptsModal` still true.", "A query finds pending receipts for the centre.", "After 3 seconds the modal opens and the flag is set to false so it does not reappear this session." ] } ], "failurePaths": [ { "name": "No home dashboard configured", "cause": "No dashboard has `category: 'home'`.", "handling": "`hasDashboard` is false and the desktop renders empty — the page header falls back to `title.header.dashboards.show`." }, { "name": "Unknown panel type", "cause": "`dashboard.panel` is not one of data-quality / custom / url.", "handling": "`isValidDashboard` is false, so the controller refuses to render the panel." }, { "name": "External dashboard URL unreachable", "cause": "Embedded URL is wrong or the provider is down.", "handling": "`dashboard.error.not-found-external-dashboard`; in older browsers the iframe fallback copy `error_browser_iframe` applies." }, { "name": "Receipt query fails", "cause": "API error while counting pending receipts.", "handling": "`showModalReceipts` is fired without awaiting and has no catch, so the rejection is unhandled — the modal just never appears." } ], "i18nKeys": [ "title.header.desktop", "title.header.dashboards.show", "dashboard.error.not-found-external-dashboard", "error_browser_iframe" ], "i18nMissing": [] }, { "id": "crm-customer-list", "name": "Customer list & filtering", "area": "CRM", "label": "title.header.crm.users / menu.navbar.customer.show", "routes": [ "crm.users", "crm.users.index" ], "code": [ "app/controllers/crm/users/index.js", "app/routes/crm/users/index.js", "app/enums/user-filters.js", "app/enums/user-group-filters.js", "app/mixins/list-mixin.js", "app/mixins/segment-filter-mixin.js" ], "models": [ "user", "segment", "building", "channel" ], "modules": [ "crm" ], "roles": [ "root", "admin", "manager", "crmmanager", "crmoperator", "weboperator", "content_creator" ], "description": "Paginated, sortable, filterable list of the centre's registered customers showing code, name, surname, email, VAT number and phone, with row actions for children, edit and delete.", "comments": "Built on `ListMixin` + `SegmentFilterMixin`. The centre is pinned as a fixed filter (`fixedFilters.center_id`) in `init`, default sort is `-updated-at`, and the query forwards a `meta.page.token` when the API returns one — a cursor-style pagination for large datasets. The available filters come from `enums/user-filters` run through `beautifyFilters(center)` and `groupFilterByModule`, so the filter palette itself changes with the centre's enabled modules. A side panel can list the segments a filtered set belongs to (`fetchSegments`, independently paginated at 16 per page). `resetFilters` clears the pagination token as well as the filters.", "useCases": [ "Finding one customer by email or VAT number to resolve a support query.", "Building an ad-hoc audience (e.g. women 25-34 in a postal code with marketing consent) before saving it as a segment.", "Checking which segments a given filtered population already belongs to.", "Jumping from a customer to their registered children for the play centre." ], "happyPaths": [ { "name": "Filter and page through customers", "steps": [ "User opens CRM → Customer list; the first page loads scoped to the active centre, newest first.", "User adds one or more filters from the grouped filter palette and applies them.", "The query is rebuilt with `filter`, `page` and `sort`; results refresh.", "User pages forward; the API's `page.token` is forwarded so deep pages stay consistent." ] }, { "name": "Inspect segments of a filtered set", "steps": [ "With filters applied, the user opens the segments panel.", "`fetchSegments` queries segments with the same fixed filters and fills a separate paginated table." ] } ], "failurePaths": [ { "name": "Filter left with an empty value", "cause": "A filter row is added but no value is chosen.", "handling": "`segment-filters#applyFilters` detects the void value, sets `showFilterWarning` and refuses to apply — no request is sent." }, { "name": "Required filter missing", "cause": "The filter palette marks some options `required` and none of them is present.", "handling": "`hasValidFilters` is false, blocking apply/save." }, { "name": "Row action invoked without a record", "cause": "`showChildren`/`delete` called with a missing model or id.", "handling": "Throws `TypeError('\\`model\\` is not a valid user')` — a programming guard rather than user-facing copy." }, { "name": "Deep pagination drift", "cause": "Records change between page requests while a token is in use.", "handling": "The token is passed through unchanged; stale tokens surface as an API error with no dedicated message." } ], "i18nKeys": [ "title.header.crm.users", "menu.navbar.customer.show", "crm.users.code", "crm.users.name", "crm.users.last_name", "crm.users.email", "crm.users.vat-number", "crm.users.phone", "show-children" ], "i18nMissing": [] }, { "id": "crm-customer-form", "name": "Customer create & edit", "area": "CRM", "label": "crm.new-user / users.general_data", "routes": [ "crm.users.new", "crm.users.edit" ], "code": [ "app/controllers/crm/users/new.js", "app/routes/crm/users/new.js", "app/routes/crm/users/edit.js", "app/components/form-user.js", "app/models/user.js" ], "models": [ "user", "campaign", "channel", "user-type", "extra" ], "modules": [ "crm" ], "roles": [ "root", "admin", "manager", "crmmanager", "crmoperator", "weboperator" ], "description": "Tabbed customer record: general data (identity, contact, address, consents, tags, manual campaigns) plus receipts and loyalty tabs once the customer exists.", "comments": "Tabs are computed in `form-user.js`: 'general' always, then 'receipts' and 'loyalty' only when `model.id` exists AND the centre has the tickets or loyalty-cards module. Required fields are partly centre-driven — `auth.center.userRequired` injects extra presence validations at runtime, so the same form has different mandatory fields per centre. `name` and `cp` are only required on create (`if: _this.isNew`); for existing records the controller instead shows a soft warning listing the missing recommended fields. Saving is two-stage: `saveUser` validates, then `_hasAcceptedAllNotifications()` opens a consent modal when any of mail / partner-mail / app notification consents is unchecked, and only `patchUser` actually persists. Email is also validated live on change via `emailRegexValidator`. A Pusher channel keyed on the user id streams in a captured signature URL, and `willDestroyElement` disconnects it. Existing customers show an identity QR code encoding `user_id:` (download button hidden) next to the captured signature, so a desk device can scan a customer straight into their record.", "useCases": [ "Registering a walk-in customer at the information desk, including GDPR consent.", "Updating contact details or consents on request.", "Attaching user tags or manual (non-segmented) campaigns to a specific customer.", "Recording single-parent / large-family status for benefit schemes.", "Capturing a handwritten signature from a tablet and seeing it appear live on the record." ], "happyPaths": [ { "name": "New customer saved with full consent", "steps": [ "Operator opens CRM → new customer and fills registration date, email, name, postal code and the centre's extra required fields.", "GDPR (`eula`) and the notification consents are ticked.", "`saveUser` validates the model successfully and `_hasAcceptedAllNotifications()` returns true.", "`patchUser` saves, tracks `CRM_USER_SAVED`, shows `crm.users.user-saved` and scrolls to the top." ] }, { "name": "Existing customer edited with partial consent", "steps": [ "Operator edits a record and leaves third-party notifications unchecked.", "The consent modal lists the unchecked statements.", "Operator confirms; `patchUser` runs and the record is saved as-is." ] }, { "name": "Signature captured remotely", "steps": [ "Operator opens an existing customer; `pusher.connectToChannel(user.id)` subscribes.", "The customer signs on a paired device.", "The pushed URL is written to `model.signatureUrl` and the signature renders without a reload." ] } ], "failurePaths": [ { "name": "Missing mandatory fields", "cause": "Email, registration date or channels blank; name/postal code blank on create.", "handling": "`user.validate()` fails, `parseErrors` maps the messages to fields (`error.user.email.required`, `error.user.registration-date.required`, `error.user.name.required`, `error.user.cp.required`, `error.channels.required`) and the page scrolls to the top." }, { "name": "Invalid email format", "cause": "Address fails the email validator.", "handling": "`form-user.not-valid.email` is set on change and again by the model's `email` rule on submit." }, { "name": "GDPR not accepted", "cause": "`eula` false.", "handling": "Custom validation fails with `error.user.gdpr`." }, { "name": "Centre-specific required field left blank", "cause": "A field listed in `center.userRequired` (e.g. `commerce`) is empty.", "handling": "A presence rule is generated at runtime with the generic `required` message; note only `commerce` has a translated attribute label, so other dynamic fields show an untranslated attribute name." }, { "name": "Consent modal declined", "cause": "User closes the notifications modal instead of confirming.", "handling": "`onCloseNotificationsModal` only closes it — the record stays unsaved, which can read as a silent no-op." }, { "name": "API rejection on save", "cause": "Server-side conflict (e.g. duplicate email) or validation.", "handling": "The catch block populates `infoErrors` from `parsedErrors.data` or `errors.errors[].detail`, sets `crm.users.user-save-errors` as the banner and scrolls up." }, { "name": "External sync failure", "cause": "Downstream integration (Juguettos Fusion) rejects the create/update.", "handling": "`user.fusion-error` / `user.fusion-error-update` are surfaced; the local record may already be saved, so the two systems can diverge." }, { "name": "Registration email resend fails", "cause": "API error on resending the registration email.", "handling": "`user.registration-email-error`." }, { "name": "Raw translation key on screen", "cause": "The code references `access-to-account-types.client`, `access-to-account-types.employee-outsource`, `access-to-account-types.employee-shop` but the key does not exist in translations.json.", "handling": "ember-intl renders the missing key (or its missing-message placeholder) instead of text — visible to every user of this screen until the key is added." } ], "i18nKeys": [ "crm.new-user", "users.general_data", "crm.users.user-saved", "crm.users.user-save-errors", "error.user.email.required", "error.user.name.required", "error.user.cp.required", "error.user.gdpr", "error.user.registration-date.required", "error.channels.required", "form-user.not-valid.email", "user.fusion-error", "user.fusion-error-update", "user.registration-email-error", "error.signature.not_exist" ], "i18nMissing": [ "access-to-account-types.client", "access-to-account-types.employee-outsource", "access-to-account-types.employee-shop" ] }, { "id": "crm-customer-delete", "name": "Customer deletion with unsubscribe notice", "area": "CRM", "label": "delete", "routes": [ "crm.users.index" ], "code": [ "app/controllers/crm/users/index.js", "app/routes/crm/users/index.js" ], "models": [ "user" ], "modules": [ "crm" ], "roles": [ "root", "admin", "manager (per `user` ability `canDelete`)" ], "description": "Deletes a customer record and, unless the operator opts out, posts to `users_unsubscribe_send` so the person receives an unsubscribe/erasure notification.", "comments": "`sendRemoveEmail` defaults to true and is reset to true in `finally`, so the opt-out is per-deletion rather than sticky. The notification is a raw `fetch` to `/api/v4/users_unsubscribe_send` with the bearer token — fire-and-forget, with no `.then`/`.catch`, so its outcome is invisible to the operator. Deletion itself goes through `destroyRecord()`.", "useCases": [ "Honouring a GDPR erasure request and confirming it to the customer by email.", "Removing a duplicate or test registration without emailing anyone (opt-out ticked)." ], "happyPaths": [ { "name": "Delete and notify", "steps": [ "Operator clicks delete on a row and confirms in the deletion modal.", "`destroyRecord()` removes the customer.", "Because `sendRemoveEmail` is true, an unsubscribe notification is posted for that user id.", "The flag resets to true for the next deletion." ] } ], "failurePaths": [ { "name": "Invalid model", "cause": "`delete` called without a model or id.", "handling": "Throws `TypeError('model' is not a valid user)`." }, { "name": "Delete rejected by the API", "cause": "Referential constraints or permissions.", "handling": "`destroyRecord()` rejects; the `.then` that sends the email is skipped, but the `finally` still resets the flag. There is no explicit user-facing error for this branch." }, { "name": "Unsubscribe email never sent", "cause": "The fire-and-forget fetch fails (network, 4xx/5xx).", "handling": "Unhandled and unreported — the customer is deleted but never notified. A compliance-relevant blind spot." } ], "i18nKeys": [ "delete" ], "i18nMissing": [] }, { "id": "crm-customer-export", "name": "Customer CSV export with column picker", "area": "CRM", "label": "informative-message.export-crm-csv.success.message", "routes": [ "crm.users.index" ], "code": [ "app/controllers/crm/users/index.js", "app/services/load.js", "app/mixins/export-csv.js" ], "models": [ "user" ], "modules": [ "crm" ], "roles": [ "root", "admin", "manager (`user` ability `canExport`)" ], "description": "Exports the currently filtered customer set as CSV, letting the operator choose from ~30 columns. The file is produced server-side and delivered by email.", "comments": "The default column set is computed in `userExportColumns` and grows with the centre's modules: `account_type` when `hasEmployeesSegments`, `calculated_income` + `calculated_postal_code` when `hasForegroundLocation`. `toggleUserExportColumns` flips individual columns. `load.export()` POSTs to `/api/v4/exports` with the model name, the active filters (minus `type`, which is sent separately as `filter-type`), the chosen `csv-fields` and the centre id (used as the email 'from'), and tracks a `DATA_EXPORTED` analytics event.", "useCases": [ "Handing a filtered audience to an external mailing tool.", "Pulling a data-quality extract to see how many records lack a phone or postal code.", "Exporting employee-segment populations where account type matters." ], "happyPaths": [ { "name": "Filtered export emailed", "steps": [ "Operator filters the list, then opens the export modal (`openUserExportModal`).", "Columns are pre-ticked from the module-aware default set; operator adjusts them.", "`exportUserCsv` closes the modal, sets the loading flag and calls `load.export('user', filters, columns)`.", "On resolve the success banner `informative-message.export-crm-csv.success.message` appears and the file arrives by email." ] } ], "failurePaths": [ { "name": "Export request fails", "cause": "API error on `/api/v4/exports`.", "handling": "`exportUserCsv` has no `.catch()`, so `isExportLoading` stays true and the spinner never clears — the operator is left waiting with no error message." }, { "name": "Email never arrives", "cause": "Export job fails asynchronously or the mail is filtered.", "handling": "The UI already reported success; there is no job-status surface in the frontend." }, { "name": "No columns selected", "cause": "Operator unticks every column.", "handling": "Not validated client-side — an empty `csv-fields` array is sent and the outcome depends entirely on the API." } ], "i18nKeys": [ "informative-message.export-crm-csv.success.message" ], "i18nMissing": [] }, { "id": "crm-customer-import", "name": "Customer CSV import", "area": "CRM", "label": "import-csv.column-database", "routes": [ "crm.users.import" ], "code": [ "app/controllers/crm/users/import.js", "app/routes/crm/users/import.js", "app/components/nf-import.js", "app/components/import-csv.js", "app/models/load.js", "app/enums/csv-examples.js" ], "models": [ "load", "user", "channel", "campaign", "user-account-type" ], "modules": [ "crm" ], "roles": [ "root", "admin (`user` ability `canImport`)" ], "description": "Bulk customer create/update from a CSV: the operator uploads the file, maps each CSV column to one of ~40 user attributes, picks the match key (id / email / VAT number), separator, date format, consent defaults and channels, then runs the import.", "comments": "The mapping table auto-matches CSV headers whose text equals an attribute value, so a template-shaped file needs no manual mapping. `modelExample` serves a different downloadable template when the centre has employee segments (`baseContentCreatorCSV(userTypeCodes)` instead of `baseCSV`). Validation lives on the `load` model: no duplicate column mappings, a date format when `register_date`/`bdate` are mapped, and at least one channel when importing users. `nf-import` adds a pre-flight (`_validateSelectionsAndShowErrors`) that collects the same issues into a summary banner before the model validation runs, and `update: true` controls insert-only vs update-and-insert.", "useCases": [ "Onboarding a centre by loading its historical customer database.", "Periodic sync from a POS or legacy CRM keyed on email or VAT number.", "Bulk-assigning user tags or account types to an existing population." ], "happyPaths": [ { "name": "Template-shaped import", "steps": [ "Operator downloads the example CSV, fills it and uploads it.", "The file is parsed (`csv.parseCSV`, `;` delimiter) and simultaneously uploaded to storage (`apiFiles.uploadFile`).", "Columns auto-map; operator picks the match key, date format and channels.", "`load.validate()` passes, `load.save()` queues the job and the success state is reported." ] } ], "failurePaths": [ { "name": "Same attribute mapped twice", "cause": "Two CSV columns point at one database field.", "handling": "`csvFields` custom validation fails with `error.load.repeated-fields`; the modal scrolls to the top to show it." }, { "name": "Date columns without a format", "cause": "`register_date` or `bdate` mapped but no date format chosen.", "handling": "`error.load.format-date.required` / `import-csv.errors.load.format-date.required`." }, { "name": "No channel selected", "cause": "Importing users without `commons.channels`.", "handling": "`error.load.channels.required` / `import-csv.errors.load.channels.required`." }, { "name": "Required selections incomplete", "cause": "Pre-flight finds any of the above.", "handling": "`import-csv.errors.load.required-selections` is shown as the banner — note this key's value is in Portuguese while the rest of the file is English, a localisation inconsistency." }, { "name": "Server-side row errors", "cause": "Rows rejected during processing.", "handling": "`informative-message.import-csv.error.title` + `informative-message.import-csv.error` list the errors returned by the API." }, { "name": "Malformed CSV / wrong separator", "cause": "File does not parse into a header row.", "handling": "`parseCSV` throws inside an `async` action; `nf-import` wraps its import in try/catch and reads `error.errors[0].status`, but a parse failure in `import-csv.js` is unguarded and leaves `isLoading` true." }, { "name": "Upload rejected", "cause": "File type or size refused by storage.", "handling": "`error.file.type.not_allowed`, `error.file.oversize`, `error.file.not_allowed`." } ], "i18nKeys": [ "import-csv.column-csv", "import-csv.column-database", "error.load.repeated-fields", "error.load.format-date.required", "error.load.channels.required", "import-csv.errors.load.required-selections", "informative-message.import-csv.error", "import-csv.update-options.only-insert", "import-csv.update-options.update-insert" ], "i18nMissing": [] }, { "id": "crm-children-import", "name": "Children CSV import", "area": "CRM", "label": "user.relationship", "routes": [ "crm.users.import-children" ], "code": [ "app/controllers/crm/users/import-children.js", "app/routes/crm/users/import-children.js", "app/components/nf-import.js" ], "models": [ "load", "child" ], "modules": [ "crm", "playcenter" ], "roles": [ "root", "admin" ], "description": "Bulk import of customers' children (dependants) keyed on the parent's id or email, carrying name, surname, birth date, gender, relationship and notes.", "comments": "A narrower variant of the customer import: `modelName` is `child`, the match options are only id and email (no VAT number), and the template is `baseChildrenCSV`. Reached from the customer list via the `navigateToImportChildren` action, and gated by `canImportChildren` in `nf-import`.", "useCases": [ "Loading existing play-centre registrations when a centre adopts the module.", "Keeping dependants in sync with an external kids-club system." ], "happyPaths": [ { "name": "Children loaded against existing parents", "steps": [ "Operator opens the children import from the customer list.", "Uploads a CSV whose rows carry the parent's email plus the child's details.", "Columns map, match key set to email, date format chosen for `bdate`.", "Import runs and the children appear under each customer." ] } ], "failurePaths": [ { "name": "Parent not found", "cause": "The id/email in a row matches no customer.", "handling": "Rejected server-side and reported in the import error list; the frontend does not pre-check." }, { "name": "Missing birth date format", "cause": "`bdate` mapped without a date format.", "handling": "`error.load.format-date.required`." }, { "name": "Duplicate column mapping", "cause": "Two columns mapped to the same attribute.", "handling": "`error.load.repeated-fields`." } ], "i18nKeys": [ "user.relationship", "user.match-options.id", "user.match-options.email" ], "i18nMissing": [] }, { "id": "crm-ai-filter", "name": "AI natural-language customer filter", "area": "CRM", "label": "ai.error", "routes": [ "crm.users.index", "crm.segments.new" ], "code": [ "app/components/nf-ai-filter.js", "app/models/module-ai.js", "app/utils/filter.js" ], "models": [ "user" ], "modules": [ "ai" ], "roles": [ "as per customer list / segment builder" ], "description": "A prompt box that turns a plain-language audience description into structured customer filters, which are then prepended to whatever filters are already applied.", "comments": "Only available when `auth.center.hasAIUserFilter`. The prompt is sent as a query parameter to `/api/v4/client_filter`, and the JSON returned is reshaped into `Filter` objects, each resolved to a group filter through `userFilters` → `groupFilterCode` → `groupFilters`. If any filter cannot be matched to a group, the code throws and reports to Sentry. Privacy-conscious by design: the analytics events (`AI_FILTER_REQUESTED`, `AI_FILTER_SUCCEEDED`, `AI_FILTER_FAILED`) deliberately send only the prompt *length*, filter count and filter types — never the prompt text, because it may contain customer data. Note the prompt is interpolated into the URL without `encodeURIComponent`, so prompts containing `&` or `#` will be truncated.", "useCases": [ "A marketer describing an audience in words instead of assembling six filter rows by hand.", "Quickly exploring a population before saving the result as a segment." ], "happyPaths": [ { "name": "Prompt converted to filters", "steps": [ "User types e.g. 'women between 25 and 34 with a valid email in Madrid'.", "`_fetchClientFilter` calls the API and parses the returned filter JSON.", "Each entry is mapped to a `Filter` with its group, operation and values.", "`onApplyFilter` prepends them to the existing filters and `AI_FILTER_SUCCEEDED` is tracked." ] } ], "failurePaths": [ { "name": "Empty prompt", "cause": "Nothing typed.", "handling": "`isDisabled` keeps the apply button inactive." }, { "name": "No usable filter returned", "cause": "API responds non-OK.", "handling": "`error` is set and `{}` returned; the UI shows `ai.error` ('No valid filter found')." }, { "name": "Unmappable filter key", "cause": "A returned filter key has no matching entry in `enums/user-filters`, so its group filter is undefined.", "handling": "`getFilters` throws, reports `GPT filter error` to Sentry with the prompt and filter payload, sets `error` and returns `[]`. Note this Sentry capture *does* include the prompt text, which is at odds with the deliberate no-prompt policy in the analytics calls." }, { "name": "Network failure", "cause": "Fetch rejects.", "handling": "`AI_FILTER_FAILED` is tracked with `reason: 'network'` and the error is re-thrown, so `isLoading` is left true and the spinner sticks." }, { "name": "Prompt containing URL-special characters", "cause": "Prompt is concatenated into the query string unescaped.", "handling": "Not handled — the prompt is silently truncated at `&`/`#`, producing a confusingly wrong filter." } ], "i18nKeys": [ "ai.error", "modules-ai" ], "i18nMissing": [] }, { "id": "crm-save-filters-as-segment", "name": "Save current filters as a segment", "area": "CRM", "label": "crm.new-segment", "routes": [ "crm.users.index", "crm.segments.new" ], "code": [ "app/controllers/crm/users/index.js", "app/mixins/segment-filter-mixin.js", "app/components/segment-filters.js" ], "models": [ "segment" ], "modules": [ "crm" ], "roles": [ "root", "admin", "manager, crmmanager (`segment` ability `canCreate`)" ], "description": "Turns the ad-hoc filter set from the customer list into a reusable, named segment by handing the serialised filters to the segment builder.", "comments": "`saveSegment(filters)` transitions to `crm.segments.new` with `filtersJSON` and `filterType` as query params — so the segment builder opens pre-populated. `filterType` carries the and/or combinator from `enums/segment-filters-types`.", "useCases": [ "Promoting an exploratory audience into a segment used by email campaigns, push notifications and proposals.", "Standardising a recurring audience definition so colleagues reuse it instead of re-filtering." ], "happyPaths": [ { "name": "Filters promoted to a segment", "steps": [ "User applies filters on the customer list and clicks save as segment.", "Filters are JSON-serialised into the query params and the segment builder opens.", "User names the segment and submits; the segment is created with the same filter definition." ] } ], "failurePaths": [ { "name": "Void filter values", "cause": "A filter row with no value.", "handling": "`applyFilters`/`saveChanges` set `showFilterWarning` first; the transition is only offered from an applied state." }, { "name": "Segment name missing", "cause": "`segmentName` blank on submit.", "handling": "The segment model's presence rule fails with the generic `required` message and `_scrollTop()` brings the error into view." } ], "i18nKeys": [ "crm.new-segment", "all", "any-of" ], "i18nMissing": [] }, { "id": "crm-segment-list", "name": "Segment list, refresh & export", "area": "CRM", "label": "title.header.crm.segments / menu.navbar.segment.show", "routes": [ "crm.segments", "crm.segments.index" ], "code": [ "app/controllers/crm/segments/index.js", "app/routes/crm/segments/index.js" ], "models": [ "segment" ], "modules": [ "crm" ], "roles": [ "root", "admin", "manager", "crmmanager", "crmoperator", "weboperator", "content_creator" ], "description": "Lists segments with their category, account types, consent flags, automatic tags and member count, and offers per-row recalculation and CSV export of the members.", "comments": "`refreshSegment` forces a server-side recount — the UI shows `segment.calculating-user-info` while it runs. `exportSegment` reuses the shared `load.export` pipeline with the segment's own column set. `hasEmployeeSegments` toggles the account-types column. Some segments are flagged non-editable (`crm.segment.current-segment-is-not-editable`) and segments bound to a user tag warn with `crm.segment.tag-associated` before deletion.", "useCases": [ "Checking how many customers a segment currently reaches before launching a campaign.", "Recomputing a segment after a large import so campaign audiences are accurate.", "Exporting a segment's members for an external channel." ], "happyPaths": [ { "name": "Recalculate a segment", "steps": [ "User clicks refresh on a segment row.", "The recalculation request is sent and the row shows the calculating state.", "On completion the member count updates in place." ] }, { "name": "Export segment members", "steps": [ "User clicks export on a row.", "`load.export` is called with the segment's filters and columns and the CSV is emailed." ] } ], "failurePaths": [ { "name": "Refresh fails", "cause": "API error during recalculation.", "handling": "A bare `.catch(() => {})` swallows it — the row leaves the calculating state with the old count and no error message." }, { "name": "Segment is locked", "cause": "The segment is one of the non-editable system segments.", "handling": "`crm.segment.current-segment-is-not-editable` is shown and edit is blocked." }, { "name": "Deleting a tag-linked segment", "cause": "The segment is associated with a user tag.", "handling": "`crm.segment.tag-associated` warns the operator, since deletion would affect the tag's automatic assignment." }, { "name": "Export error", "cause": "Export request rejects.", "handling": "Caught in a `try/catch` with no user-facing message." } ], "i18nKeys": [ "title.header.crm.segments", "segment.refresh-segment", "segment.export-segment", "segment.users-in-segment", "segment.calculating-user-info", "crm.segment.current-segment-is-not-editable", "crm.segment.tag-associated" ], "i18nMissing": [] }, { "id": "crm-segment-builder", "name": "Segment builder with automatic tag actions", "area": "CRM", "label": "crm.new-segment", "routes": [ "crm.segments.new", "crm.segments.edit" ], "code": [ "app/controllers/crm/segments/new.js", "app/routes/crm/segments/new.js", "app/models/segment.js", "app/models/usertype-linked-segment.js", "app/components/segment-filters.js", "app/enums/automatic-action-types.js" ], "models": [ "segment", "user", "user-type", "usertype-linked-segment", "building", "user-account-type" ], "modules": [ "crm", "employees_segments (optional)", "ai (optional)" ], "roles": [ "root", "admin", "manager", "crmmanager (`segment` ability `canCreate`/`canEdit`)" ], "description": "Two-tab editor for a segment: general data (name, category, account types) plus a live filter builder that previews the matching customers, with optional rules that automatically add or remove user tags as people enter or leave the segment.", "comments": "The preview table reuses the customer columns, and the same AI filter and export affordances as the customer list are available here. `addNewAutomaticActionType` / `removeAutomaticAction` manage `usertypeLinkedSegments` fragments, each needing both a `usertype` and a `dynamic` flag — the model validates this with a single combined message. `isLifeCycleSegment` flags segments driven by lifecycle rules. When the centre has employee segments, at least one account type is mandatory (`userAccountTypes.length.minimum 1`). New user tags can be created inline (`addNewUserType`), which validates the tag model separately into `userTypeErrors`.", "useCases": [ "Defining 'families with children under 12 who shopped in the last 90 days' once and reusing it everywhere.", "Auto-tagging customers as VIP when they enter a segment and untagging them when they leave.", "Restricting a segment to employee account types in centres with employee segmentation." ], "happyPaths": [ { "name": "Segment created with an automatic tag rule", "steps": [ "User names the segment, picks a category and (if required) account types.", "Filters are assembled in the builder; the preview refreshes with matching customers.", "An automatic action is added: tag X, dynamic on.", "`submit` validates the segment and the linked-segment fragments and saves it." ] } ], "failurePaths": [ { "name": "Name missing", "cause": "`segmentName` blank.", "handling": "Presence rule fails; `_scrollTop()` scrolls the error into view." }, { "name": "Account types missing", "cause": "Employee-segments centre with no account type selected.", "handling": "Minimum-length rule fails with `required` + `user.account-type`." }, { "name": "Incomplete automatic action", "cause": "A `usertypeLinkedSegments` row lacks `usertype` or `dynamic`.", "handling": "`error.user.automatic-action-type` ('Remember that you have to fill in all the fields') — one message for the whole collection, so the operator is not told which row is wrong." }, { "name": "Inline user-tag creation invalid", "cause": "The new tag fails its own validations.", "handling": "`userTypeErrors` is populated via `parseErrors` and shown on the inline form." }, { "name": "Filters not applicable", "cause": "`isDisableApplyFilters` is true (incomplete filter rows).", "handling": "Apply is disabled; the preview is not refreshed." }, { "name": "Save rejected", "cause": "API error.", "handling": "A bare `.catch(() => {})` in the submit chain hides the reason." } ], "i18nKeys": [ "crm.new-segment", "general_data", "segment.segment-category", "segment.account-types", "segment.automatic-tags", "error.user.automatic-action-type", "segment.app-notifications", "segment.email-notifications" ], "i18nMissing": [] }, { "id": "crm-segment-categories", "name": "Segment categories", "area": "CRM", "label": "title.header.crm.segment-categories / menu.navbar.segment-categories.show", "routes": [ "crm.segment-categories", "crm.segment-categories.index", "crm.segment-categories.new", "crm.segment-categories.edit" ], "code": [ "app/controllers/crm/segment-categories/index.js", "app/routes/crm/segment-categories/*.js", "app/models/segment-category.js" ], "models": [ "segment-category" ], "modules": [ "crm" ], "roles": [ "root", "admin", "manager", "crmmanager" ], "description": "Simple CRUD for the taxonomy used to group segments, so long segment lists stay navigable.", "comments": "A minimal list (name + edit/delete) built on the standard `nf-crud` + `routes/form.js` pattern; deletion goes through the shared confirm-deletion service.", "useCases": [ "Separating lifecycle segments from campaign segments and employee segments.", "Keeping a centre's segment list organised as it grows." ], "happyPaths": [ { "name": "Category created and assigned", "steps": [ "User creates a category with a name.", "`routes/form.js#saveModel` validates and saves, then returns to the list.", "The category becomes selectable in the segment builder." ] } ], "failurePaths": [ { "name": "Name missing", "cause": "Blank name on save.", "handling": "Model validation rejects and `saveModel` surfaces the field error." }, { "name": "Deleting a category still in use", "cause": "Segments still reference it.", "handling": "Rejected by the API; `routes/form.js` sets `errorMessage` from `response.errors[0].detail`." } ], "i18nKeys": [ "title.header.crm.segment-categories", "segment-categories.new" ], "i18nMissing": [] }, { "id": "crm-user-types", "name": "User tags (user types)", "area": "CRM", "label": "menu.navbar.tag.show / crm.tags", "routes": [ "crm.user-types.index", "crm.user-types.new", "crm.user-types.edit" ], "code": [ "app/controllers/crm/user-types/index.js", "app/routes/crm/user-types/*.js", "app/components/form-user-type.js", "app/models/user-type.js", "app/abilities/user-type.js" ], "models": [ "user-type" ], "modules": [ "crm" ], "roles": [ "root", "admin", "manager", "crmmanager", "weboperator" ], "description": "Manages the labels that can be attached to customers, with flags controlling whether a tag is an interest, whether it is visible in the back office and whether it is visible in the mobile app.", "comments": "The list surfaces code, name and three visibility flags (`is-interest`, `is-visible`, `is-visible-on-app`, plus an `is-not-visible` state). Tags are assignable manually on the customer form and automatically through segment rules (`usertype-linked-segment`), so deleting one has reach beyond the tag list. Deletion uses the `delete` / `cancelRemove` / `onShowDeleteModal` trio common to the simpler CRUD controllers.", "useCases": [ "Marking interests (e.g. 'cinema', 'kids') that the app exposes as preference chips.", "Flagging internal-only attributes that should never show in the app.", "Driving automatic tagging from segment membership." ], "happyPaths": [ { "name": "App-visible interest tag created", "steps": [ "User creates a tag with code and name and ticks interest + visible on app.", "The tag saves and appears in the customer form and in the app's interest picker.", "A segment rule can now add it automatically." ] } ], "failurePaths": [ { "name": "Invalid model on delete", "cause": "`delete` invoked without a valid record.", "handling": "Throws `TypeError('model' is not a valid user-type)`." }, { "name": "Deleting a tag bound to a segment", "cause": "The tag is referenced by an automatic segment action.", "handling": "The segment list warns with `crm.segment.tag-associated`; the API is the final arbiter." }, { "name": "Duplicate code", "cause": "Code already used in the centre.", "handling": "Server-side rejection surfaced through the generic form error path." } ], "i18nKeys": [ "menu.navbar.tag.show", "crm.tags", "crm.tag.new", "crm.tags.code", "crm.tags.is-interest", "crm.tags.is-visible", "crm.tags.is-visible-on-app", "crm.tags.is-not-visible" ], "i18nMissing": [] }, { "id": "crm-customer-receipts-tab", "name": "Customer receipts tab & ticket/stamp generation", "area": "CRM", "label": "users.receipts", "routes": [ "crm.users.edit" ], "code": [ "app/components/form-user/receipts.js", "app/models/receipt.js", "app/models/ticket.js" ], "models": [ "receipt", "ticket", "campaign", "commerce" ], "modules": [ "tickets", "loyalty-cards" ], "roles": [ "root", "admin", "manager", "crmmanager", "crmoperator", "weboperator" ], "description": "Inside an existing customer record: register purchase receipts (date, code, amount, store, campaign) and generate the raffle tickets or loyalty stamps they earn, with a preview of what will be created before confirming.", "comments": "Only present when the centre has the tickets or loyalty-cards module and the customer already exists. `activeCampaigns` restricts which campaigns a receipt can be attributed to. The preview tables (`ticketsPreviewColumns`, `stampsPreviewColumns`) show the computed entitlement — including accumulated and pending balance — before `generateTickets` commits. Receipt validation errors are bubbled up to the parent form through `onReceiptErrors`, so the receipts tab shows an error badge. Submission wraps `receipt.validate()` in an explicit promise that rejects with the model errors.", "useCases": [ "Desk staff entering a paper receipt a customer brings in so they get their raffle entries.", "Awarding loyalty-card stamps for a qualifying purchase.", "Correcting or cancelling a wrongly entered receipt." ], "happyPaths": [ { "name": "Receipt registered and tickets generated", "steps": [ "Operator opens the receipts tab on a customer and adds a receipt with date, code, amount and store.", "A campaign is selected from the active list; the accumulated/pending balance updates.", "`submitReceipt` validates and saves the receipt.", "Operator opens the generate-tickets modal, reviews the preview and confirms.", "`ticket.generate-success-message` is shown and the tickets appear under the loyalty tab." ] } ], "failurePaths": [ { "name": "Receipt fields missing", "cause": "Date, amount, store or code blank.", "handling": "`error.tickets.date.required`, `error.tickets.amount.required`, `error.tickets.commerce.required`, `error.tickets.code.required`; the promise rejects with the model errors and the tab badge turns red." }, { "name": "Ticket generation fails", "cause": "API error while creating tickets.", "handling": "`ticket.generate-error-message` — explicitly tells the operator nothing was created and to contact support." }, { "name": "Invalid record on cancel", "cause": "`cancelReceipt` called with a bad model.", "handling": "Throws `TypeError('model' is not a valid receipt)`." }, { "name": "No active campaign", "cause": "No campaign is currently open for attribution.", "handling": "The campaign picker is empty, so no entitlement can be generated — the receipt can still be stored." } ], "i18nKeys": [ "users.receipts", "receipt.save-message", "receipt.campaign.accumulated-balance", "receipt.campaign.accumulative-amount", "receipt.pending-balance", "receipt.stamps-number", "ticket.generate-success-message", "ticket.generate-error-message", "error.tickets.date.required", "error.tickets.amount.required", "error.tickets.commerce.required", "error.tickets.code.required" ], "i18nMissing": [] }, { "id": "crm-customer-loyalty-raffles", "name": "Customer loyalty — raffle tickets", "area": "CRM", "label": "ticket.raffle", "routes": [ "crm.users.edit" ], "code": [ "app/components/form-user/loyalty.js", "app/components/form-user/loyalty/raffles.js" ], "models": [ "ticket", "campaign" ], "modules": [ "tickets" ], "roles": [ "root", "admin", "manager", "crmmanager", "crmoperator", "weboperator" ], "description": "Read-oriented view of a customer's raffle entries per campaign: ticket code, originating receipt, store, rule, creation date, plus a per-rule resume with pending balance.", "comments": "One of four steps inside the loyalty tab (`loyalty.js` computes `raffleStepId`, `loyaltyCardStepId`, `rewardStepId`, `couponStepId` and shows only the ones the centre's modules allow). Campaign selection (`changeCampaign`) re-queries the tickets. The resume columns expose `ticket.pending-balance`, i.e. purchase value not yet converted into an entry.", "useCases": [ "Answering 'how many entries do I have?' at the information desk.", "Auditing which receipt and rule produced a given ticket when a customer disputes a draw." ], "happyPaths": [ { "name": "Review a customer's entries", "steps": [ "Operator opens the loyalty tab and the raffle step.", "Picks a campaign; the ticket list and the per-rule resume load.", "Pending balance explains any purchase amount not yet converted." ] } ], "failurePaths": [ { "name": "Module disabled", "cause": "Centre has no tickets module.", "handling": "The raffle step is not offered at all." }, { "name": "Ticket list fails to load", "cause": "API error on the campaign-scoped query.", "handling": "No dedicated message in this component — the table stays empty." } ], "i18nKeys": [ "ticket.raffle", "ticket.code", "ticket.receipt-code", "ticket.rule", "ticket.tickets-number", "ticket.pending-balance", "ticket.commerce-name" ], "i18nMissing": [] }, { "id": "crm-customer-loyalty-cards", "name": "Customer loyalty — cards & stamps", "area": "CRM", "label": "ticket.loyalty-card", "routes": [ "crm.users.edit" ], "code": [ "app/components/form-user/loyalty/loyalty-cards.js" ], "models": [ "campaign", "ticket", "loyalty-card" ], "modules": [ "loyalty-cards" ], "roles": [ "root", "admin", "manager", "crmmanager", "crmoperator", "weboperator" ], "description": "Shows the customer's loyalty cards per campaign with their stamp counts, and lets staff manually add stamps or exchange a completed card.", "comments": "`createStamps` is guarded by `validateStampNumber(amount, campaign)`, which refuses an amount larger than the campaign's stamp quota. `createStampsModalCampaigns` narrows the picker to campaigns that can still take stamps. `exchangeStamps` consumes a completed card. Unredeemed stamps are surfaced separately (`loyalty-cards.unredeemed-stamps`).", "useCases": [ "Compensating a customer whose stamp was not registered at the till.", "Redeeming a completed card for its reward at the desk.", "Explaining to a customer how many stamps they still need." ], "happyPaths": [ { "name": "Stamps granted manually", "steps": [ "Operator opens the loyalty-cards step and selects a campaign.", "Opens the create-stamps modal and enters an amount within the campaign's quota.", "`validateStampNumber` passes and the stamps are created.", "`loyalty-cards.generate-success-message` confirms and the card's count updates." ] }, { "name": "Completed card exchanged", "steps": [ "Operator opens the exchange-stamps modal for a full card.", "Confirms; the stamps are consumed and the card moves to its exchanged state." ] } ], "failurePaths": [ { "name": "Too many stamps requested", "cause": "Amount exceeds the campaign's stamp quantity.", "handling": "`loyalty-cards.error-stamp-number` ('Number of stamps is greater than the quantity of stamps in the campaign'); nothing is created." }, { "name": "Card generation fails", "cause": "API error while creating cards/stamps.", "handling": "`loyalty-cards.generate-error-message` states explicitly that nothing was created and to contact support." }, { "name": "Exchange fails", "cause": "API error or already-exchanged card.", "handling": "Caught in `try/catch`; the modal closes without a specific message." } ], "i18nKeys": [ "ticket.loyalty-card", "loyalty-cards", "loyalty-card.campaign", "loyalty-card.stamps.value", "loyalty-cards.unredeemed-stamps", "loyalty-cards.generate-success-message", "loyalty-cards.generate-error-message", "loyalty-cards.error-stamp-number" ], "i18nMissing": [] }, { "id": "crm-customer-loyalty-rewards", "name": "Customer loyalty — rewards", "area": "CRM", "label": "ticket.rewards", "routes": [ "crm.users.edit" ], "code": [ "app/components/form-user/loyalty/rewards.js", "app/models/reward.js", "app/abilities/reward.js" ], "models": [ "reward", "campaign" ], "modules": [ "rewards" ], "roles": [ "root", "admin", "manager", "crmmanager", "crmoperator", "weboperator" ], "description": "Issue a reward to a customer against a campaign and then redeem, un-redeem or resend it, with code, validity window and exchange date on show.", "comments": "Four distinct mutations, each with its own success and error message: `redeem`, `unredeem`, `resend` and `cancelReward`. `submitReward` wraps `reward.validate()` in an explicit promise so a missing campaign or expiry date rejects before the request. `activeCampaigns` limits issuance to currently running campaigns. The presence of an `unredeem` action means redemption is reversible — important for till mistakes.", "useCases": [ "Handing a customer their prize at the desk and marking it redeemed.", "Reversing a redemption that was registered by mistake.", "Resending a reward code the customer never received.", "Issuing a goodwill reward outside the normal earning rules." ], "happyPaths": [ { "name": "Reward issued and redeemed", "steps": [ "Operator picks an active campaign and an expiry (`validUntil`) and submits the reward.", "Validation passes and the reward is created with a code.", "Later the operator opens the redeem modal and confirms.", "`reward.redeem-success` is shown and the exchange date is recorded." ] }, { "name": "Redemption reversed", "steps": [ "Operator opens the un-redeem modal on a redeemed reward and confirms.", "`reward.unredeem-success` is shown and the reward becomes redeemable again." ] } ], "failurePaths": [ { "name": "Campaign or expiry missing", "cause": "`campaign` or `validUntil` blank.", "handling": "`error.reward.campaign.required` / `error.reward.validUntil.required`; the promise rejects with the model errors." }, { "name": "Redeem fails", "cause": "API error or reward already redeemed/expired.", "handling": "`reward.redeem-error` ('please retry later')." }, { "name": "Un-redeem fails", "cause": "API refuses the reversal.", "handling": "`reward.unredeem-error`." }, { "name": "Resend fails", "cause": "Mail dispatch error.", "handling": "`reward.resend-error`." }, { "name": "Cancel fails", "cause": "API error on delete.", "handling": "Bare `.catch(() => {})` — silent." } ], "i18nKeys": [ "ticket.rewards", "reward.campaign", "reward.code", "reward.valid-from", "reward.valid-until", "reward.exchanged-at", "reward.redeem-success", "reward.redeem-error", "reward.unredeem-success", "reward.unredeem-error", "reward.resend-success", "reward.resend-error", "error.reward.campaign.required", "error.reward.validUntil.required" ], "i18nMissing": [] }, { "id": "crm-customer-coupon-exchanges", "name": "Customer loyalty — coupon exchanges", "area": "CRM", "label": "ticket.coupon-exchanges", "routes": [ "crm.users.edit" ], "code": [ "app/components/form-user/loyalty/coupon-exchanges.js", "app/models/coupon-exchange.js", "app/abilities/coupon.js" ], "models": [ "coupon-exchange", "coupon", "commerce" ], "modules": [ "cms (coupons on proposals)", "crm" ], "roles": [ "root", "admin", "manager", "crmmanager, crmoperator, weboperator (`coupon` ability `canRedeem`)" ], "description": "Lists the proposal coupons a customer has taken and lets staff redeem one by recording the store and the exchange date.", "comments": "Redemption has its own client-side form validation (`validateRedeemForm` → `_validateCommerce` + `_validateDate`), including a rule that the date cannot be in the future. The API error detail is preferred over the generic copy when present (`json?.errors?.[0]?.detail ? … : intl.t('coupon-exchanges.redeem.error')`), which is better error plumbing than most of the surrounding code.", "useCases": [ "A store assistant redeeming a promotional coupon the customer shows on their phone.", "Back-office correction of a coupon redeemed against the wrong store." ], "happyPaths": [ { "name": "Coupon redeemed", "steps": [ "Operator opens the coupon-exchanges step and the redeem modal on a coupon.", "Selects the store and a date that is not in the future.", "`validateRedeemForm` passes and the redemption is posted.", "`coupon-exchanges.redeem.success` is shown and the coupon's status changes." ] } ], "failurePaths": [ { "name": "Store not selected", "cause": "`couponSelectedCommerce` empty.", "handling": "`coupon-exchanges.redeem.validation.commerce`." }, { "name": "Date missing", "cause": "No exchange date chosen.", "handling": "`coupon-exchanges.redeem.validation.date`." }, { "name": "Future date", "cause": "Exchange date after today.", "handling": "`coupon-exchanges.redeem.validation.future.date`." }, { "name": "API rejects the redemption", "cause": "Usage limit reached, coupon expired, or exchange limit per user exceeded.", "handling": "The API's `errors[0].detail` is shown if provided, otherwise `coupon-exchanges.redeem.error` under the `coupon-exchanges.error.title` heading." } ], "i18nKeys": [ "ticket.coupon-exchanges", "coupon-exchanges.coupon", "coupon-exchanges.shop", "coupon-exchanges.date-coupon-has-exchanged", "coupon-exchanges.redeem", "coupon-exchanges.redeem.success", "coupon-exchanges.redeem.error", "coupon-exchanges.error.title", "coupon-exchanges.redeem.validation.commerce", "coupon-exchanges.redeem.validation.date", "coupon-exchanges.redeem.validation.future.date" ], "i18nMissing": [] }, { "id": "crm-children", "name": "Customer children (dependants)", "area": "CRM", "label": "children / crm.children.add", "routes": [ "crm.children", "crm.children.index", "crm.children.new", "crm.children.edit" ], "code": [ "app/controllers/crm/children/index.js", "app/routes/crm/children/*.js", "app/models/child.js", "app/abilities/child.js" ], "models": [ "child", "user", "child-stay" ], "modules": [ "playcenter" ], "roles": [ "root", "admin", "manager", "crmmanager", "crmoperator", "weboperator" ], "description": "Per-customer list of registered children with name, birth date and relationship, plus play-centre check-in and check-out directly from the row.", "comments": "Nested under a customer (`users/:user_id/children`). Check-in/check-out are the same operations as the play-centre screen but reached from the parent's record; both map API errors through `mapErrors(e, intl.t)` into `errorDetails`, which is the better error-surfacing pattern in this codebase. The `child` ability makes the gating explicit: `canCheckIn` needs `hasVatNumber && !isInPlayCenter`, `canCheckOut` needs `hasVatNumber && isInPlayCenter`.", "useCases": [ "Registering a customer's children once so play-centre entry is a single click later.", "Checking a child in when the parent arrives at the play area.", "Checking a child out when collected." ], "happyPaths": [ { "name": "Child registered and checked in", "steps": [ "Operator opens a customer's children list and adds a child with name, birth date, gender and relationship.", "Later, with the parent's VAT number on file, the check-in modal is opened.", "Entry time and expected exit time are entered and confirmed.", "`child.checkin-success-message` is shown and the child appears as in the play centre." ] }, { "name": "Child checked out", "steps": [ "Operator opens the check-out modal for a child currently inside.", "Confirms; `child.checkout-success-message` is shown." ] } ], "failurePaths": [ { "name": "Parent has no VAT number", "cause": "`hasVatNumber` false.", "handling": "`canCheckIn`/`canCheckOut` are false and the UI explains with `child.not-dni-error-message`, telling the operator to set the VAT number on the customer profile first." }, { "name": "Child data incomplete", "cause": "Name, relationship, gender or birth date missing.", "handling": "`error.child.name.required`, `error.child.relationship.required`, `error.child.sex.required`, `error.child.bdate.required`." }, { "name": "Check-in times missing", "cause": "Entry or expected exit time blank.", "handling": "`error.crm.children.entryTime.required` / `error.crm.children.expectedExitTime.required`." }, { "name": "Check-in/out rejected by the API", "cause": "Capacity reached, already inside, or server error.", "handling": "`response.errors` are mapped through `mapErrors` into `errorDetails` and listed to the operator." }, { "name": "Invalid record", "cause": "Action called without a valid child.", "handling": "Throws `TypeError('model' is not a valid child)`." } ], "i18nKeys": [ "children", "crm.children.add", "crm.children.name", "crm.children.bdate", "child.checkin-success-message", "child.checkout-success-message", "child.not-dni-error-message", "error.child.name.required", "error.child.relationship.required", "error.child.sex.required", "error.child.bdate.required", "error.crm.children.entryTime.required", "error.crm.children.expectedExitTime.required" ], "i18nMissing": [] }, { "id": "crm-receipt-moderation", "name": "Receipt verification queue", "area": "CRM", "label": "title.header.crm.receipts / menu.navbar.receipt.show", "routes": [ "crm.receipts", "crm.receipts.index" ], "code": [ "app/controllers/crm/receipts/index.js", "app/routes/crm/receipts/index.js", "app/enums/receipt-status.js", "app/enums/reject-reasons-receipts.js", "app/enums/pending-reasons-receipts.js", "app/abilities/receipt.js" ], "models": [ "receipt", "campaign", "commerce" ], "modules": [ "tickets" ], "roles": [ "root", "admin", "manager", "crmmanager", "crmoperator", "weboperator" ], "description": "Moderation workspace for customer-uploaded purchase receipts: review the image and OCR'd data, validate (which also redeems the entitlement), reject with a reason, un-reject, and navigate the queue with previous/next.", "comments": "The richest state machine in the app. Seven receipt states (`draft`, `pending`, `not-redeemable`, `redeemable`, `not-yet-redeemable`, `redeemed`, `rejected`) each with a colour and a tooltip; eight reject reasons (duplicated, illegible, modified, other centre, out of period, out of store, over max amount, other) and seven automatic pending reasons explaining why the system could not decide (no code, no store, over 250 amount, not this centre, out of date, no amount, invalid date). `isValidating`/`isSavingReject`/`isUnrejecting` guard concurrent mutations, and `previousReceipt`/`nextReceipt` with `isFirstSelectedReceipt`/`isLastSelectedReceipt` make high-volume moderation keyboard-fast. `canSeeModerator` reveals who moderated a receipt. `reprocessPendingReceipts` re-runs automatic processing over the pending backlog.", "useCases": [ "A moderator working through the overnight backlog of uploaded receipts.", "Rejecting a duplicate receipt with an auditable reason the customer can be told.", "Reversing a wrong rejection (`unreject` re-runs validation).", "Re-processing the pending queue after fixing a store's configuration or campaign dates.", "Finding out which moderator handled a disputed receipt." ], "happyPaths": [ { "name": "Receipt validated", "steps": [ "Moderator opens the queue filtered to pending and selects a receipt.", "Reviews the image against the parsed amount, date, code and store.", "Clicks validate; `isValidating` blocks double submission.", "The state moves to a validated state, `validatedAt` is stamped and the entitlement is redeemed." ] }, { "name": "Receipt rejected with a reason", "steps": [ "Moderator picks a reject reason (required) and saves.", "State becomes `rejected`, `validatedAt` is stamped and the reason is stored for the customer-facing explanation." ] }, { "name": "Rejection reversed", "steps": [ "Moderator opens a rejected receipt and clicks un-reject.", "`unreject()` delegates straight to `validate()`, so the receipt is re-validated in one step." ] }, { "name": "Pending backlog reprocessed", "steps": [ "Moderator triggers reprocess on the pending set.", "`crm.receipts.reprocess-receipts-success` confirms the job was accepted." ] } ], "failurePaths": [ { "name": "Validated but not redeemable", "cause": "The receipt validates but the entitlement cannot be redeemed (campaign closed, limits reached).", "handling": "`receipt.validate.error-message-unable-to-redeem` — explicitly states the receipt was validated but not redeemed, so the operator knows the two outcomes diverged." }, { "name": "Validation request fails", "cause": "API error.", "handling": "`catch` resets `selectedReceipt.validatedAt` to null and clears `isValidating`, rolling the optimistic update back." }, { "name": "Reject without a reason", "cause": "`rejectReason` not set.", "handling": "`reject()` only proceeds when a reason exists; the field is marked `required`." }, { "name": "Unknown reject reason", "cause": "A stored `rejectReason` is not in the enum.", "handling": "`rejectReasons` getter does `.find(...).label` without a guard, so this throws a TypeError and breaks the panel." }, { "name": "Reject save fails", "cause": "API error.", "handling": "`catch` resets `validatedAt` and leaves the previous state." }, { "name": "Embedded API errors", "cause": "A 200 response that still carries `data.errors`.", "handling": "`throw data.errors.firstObject` surfaces it into the catch chain." }, { "name": "Reprocess not permitted", "cause": "`canReprocessReceipts` false for the role.", "handling": "The action is hidden." } ], "i18nKeys": [ "title.header.crm.receipts", "menu.navbar.receipt.show", "receipt.status.draft", "receipt.status.pending", "receipt.status.redeemable", "receipt.status.not-redeemable", "receipt.status.not-yet-redeemable", "receipt.status.redeemed", "receipt.status.rejected", "receipt.validate.error-message-unable-to-redeem", "crm.receipts.reprocess-receipts-success", "receipts.reject-reason", "receipts.index.moderator-name", "receipt.state.duplicated", "receipt.state.illegible", "receipt.state.modified", "receipt.state.other-center", "receipt.state.out-of-period", "receipt.state.out-of-commerce", "receipt.state.over-max-amount", "receipt.pending.not_code", "receipt.pending.not_store", "receipt.pending.over_250_amount", "receipt.pending.not_center", "receipt.pending.out_of_date", "receipt.pending.not_amount", "receipt.pending.invalid_date" ], "i18nMissing": [] }, { "id": "crm-commerce-list", "name": "Store list, filters & exports", "area": "CRM", "label": "title.header.crm.commerces / menu.navbar.shop.show", "routes": [ "crm.commerces", "crm.commerces.index" ], "code": [ "app/controllers/crm/commerces/index.js", "app/routes/crm/commerces/index.js", "app/enums/commerces-filters.js", "app/abilities/commerce.js" ], "models": [ "commerce", "user" ], "modules": [ "crm" ], "roles": [ "root", "admin", "manager", "scmanager", "storeManager", "weboperator" ], "description": "The centre's store directory with module-aware filters, a CSV export of the full store dataset, and a bulk QR export for store-level loyalty QR codes.", "comments": "`modelFilters` filters each filter option by the modules it declares, so e.g. Yardi- or Fideliza-specific filters only appear where those modules are on. `exportQr` downloads QR assets and `exportCsv` uses the shared export pipeline; `canExport` is limited to root/admin/manager and `canImport` to root/admin only — tighter than `canEdit`. `checkUsersRelationship` is a safety check before deletion: it looks for customers attached to the store.", "useCases": [ "Maintaining the store directory that feeds the app's store list and map.", "Exporting all store QR codes to print in-store loyalty signage.", "Finding stores missing a Yardi tenant code before a sales export.", "Sending a store its back-office access information." ], "happyPaths": [ { "name": "Store QR codes exported", "steps": [ "User filters the store list as needed and triggers the QR export.", "`exportQr` fetches the QR assets and the download starts." ] }, { "name": "Access information emailed to a store", "steps": [ "User triggers the access-information action for a store.", "`crm.commerce-access-information.sent-success` confirms the email was queued." ] } ], "failurePaths": [ { "name": "Deleting a store with customers attached", "cause": "`checkUsersRelationship` finds customers linked to the store.", "handling": "`crm.commerce-access-information.users-related-error` ('you are trying to remove a store with customers associated') and the delete is not confirmed." }, { "name": "QR export fails", "cause": "API/download error.", "handling": "`crm.commerces.qr-error` asks the user to retry later." }, { "name": "Access-information email fails", "cause": "API error.", "handling": "`.catch(() => setUpResponse('error'))` → `crm.commerce-access-information.sent-error` (a generic 'An error has occurred')." } ], "i18nKeys": [ "title.header.crm.commerces", "menu.navbar.shop.show", "commerces.new", "crm.commerces.qr-error", "crm.commerce-access-information.sent-success", "crm.commerce-access-information.sent-error", "crm.commerce-access-information.users-related-error" ], "i18nMissing": [] }, { "id": "crm-commerce-form", "name": "Store create & edit", "area": "CRM", "label": "crm.commerce.general-data", "routes": [ "crm.commerces.new", "crm.commerces.edit" ], "code": [ "app/controllers/crm/commerces/new.js", "app/routes/crm/commerces/new.js", "app/models/commerce.js", "app/models/commerce-extra.js" ], "models": [ "commerce", "extra", "commerce-extra", "zone", "language", "campaign", "commerce-type" ], "modules": [ "crm", "yardi (optional)", "fideliza (optional)", "intranet-sovos (optional)" ], "roles": [ "root", "admin", "manager", "scmanager", "weboperator" ], "description": "Multi-step store editor covering general data, physical-store attributes, the store QR code and centre-defined extra attributes, including social links, opening data, categories, zone, gift-card administrators and integration codes.", "comments": "Steps and tabs are computed, and several are module-conditional: `hasYardi` adds the tenant-code field (with a centre-specific label via `yardiCodeLabel`), `hasFideliza` brings in gift-card administrators, and `canSeeIntelISales` exposes IntelliSales. Extra attributes are handled separately from the model: `requiredExtras` is assembled per label and `isValidCommerceExtra` sets a bespoke `extraError` of the form `` `${label} is required` `` — note this message is built in code, not translated. `saveCommerce` validates the commerce, then saves extras, and special-cases HTTP 422 from the adapter. A loyalty-QR flow (`downloadQr`, `searchCampaign`, `loadSelectedCampaign`) ties a store QR to a campaign. Category selection supports select-all.", "useCases": [ "Onboarding a new tenant: address, categories, contact, social links and images.", "Setting the Yardi tenant code so the store's sales can be exported.", "Nominating gift-card administrators for a Fideliza-enabled centre.", "Printing a store's loyalty QR code tied to a specific campaign." ], "happyPaths": [ { "name": "Store created with extras", "steps": [ "User fills general data: name, categories, zone, address, locality, province, image.", "Yardi centres also require the tenant code.", "Extra attributes required by the centre are completed.", "`saveCommerce` validates the model, saves it, then persists the commerce-extras.", "The store appears in the directory and in the app." ] }, { "name": "Loyalty QR downloaded", "steps": [ "User searches and selects a campaign for the store QR.", "`downloadQr` renders and downloads the QR image with the store name as alt text." ] } ], "failurePaths": [ { "name": "Mandatory store fields missing", "cause": "Name, categories, zone, image, address, direction, locality or province blank.", "handling": "`error.commerce.name.required`, `error.commerce.categories.required`, `error.commerce.zone.required`, `error.commerce.imageUrl.required`, `error.commerce.address.required`, `error.commerce.direction.required`, `error.commerce.locality.required`, `error.commerce.province.required`." }, { "name": "Yardi code missing", "cause": "Centre has Yardi but `tenantCode` is blank.", "handling": "`error.commerce.tenantCode.required` ('Yardi code is required')." }, { "name": "Malformed URL", "cause": "`webUrl` or `bookTableUrl` does not match the http(s) regex.", "handling": "`error.commerce.web.format` ('The text must be a url')." }, { "name": "WhatsApp number without country code", "cause": "Phone not in `+346xxxxxxxx` shape.", "handling": "`error.commerce.whatsapp-phone.format` spells out the expected format; a WhatsApp message is also required (`error.commerce.whatsapp-message.required`)." }, { "name": "Invalid gift-card administrator emails", "cause": "One or more addresses malformed, or the field left empty when required.", "handling": "`error.commerce.gift-card-admins.invalid-email` / `error.commerce.gift-card-admins.required`." }, { "name": "Required extra attribute empty", "cause": "A centre-defined required extra has no value.", "handling": "`extraError` is set to an untranslated `\"