mams_frontend/CLAUDE.md

6.0 KiB

MAMS front end

React 18 + Vite + TypeScript + MUI. It replaces only the front end of the legacy ColdFusion 2018 + jQuery system (C:\inetpub\wwwroot\OmanTCS_STG, staging 192.168.6.46). Arabic (RTL) is the default language, English is the second, light theme is the default, dark mode is available.

Rules that always apply

  • Never modify the backend. Every change is in this project. If the backend is wrong, report it.
  • Do not rebuild or deploy unless asked. The user controls builds and releases.
  • Never type passwords, tokens or other credentials into any page or command. The user signs in themselves.
  • Do not submit real transactions when testing: payments, subscriptions, posting, withdrawals, publishing, credit memos, VAT updates, receipts. Read-only checks only. Creating test records (trucks, investors…) on staging is fine when asked; use obvious test values (plate 99…, chassis CLAUDETEST…, emails at example.com) and tell the user what was created.
  • Only change what was asked.
  • When the new screen differs from the old system, read the legacy source first (frontend/entities/<entity>/…, backend/entities/<entity>/…) and match it.

Commands

npm install
npm run dev            # dev server, backend proxied (see .env.*)
npm run dev:staging    # against staging
npx tsc --noEmit       # typecheck: run it after every change, it must print nothing
npm run build          # production build (reads .env.production)
npm run build:staging  # writes dist-staging/

Staging serves the app at /mams/ on the same host as the backend (VITE_API_BASE=/OmanTCS_stg). Production is a static site on mamsv2.nafith.om with /api/ forwarded to the backend (deploy/apache-mamsv2.conf).

How the app talks to the backend

  • src/api/client.ts: rpc(entity, method, args, {post}) calls the legacy controller.cfc. Replies are {CODE, MESSAGE, DATA}; '000' (or 0 for grids) is success. Errors are thrown as ApiError.
  • Record ids are encrypted and bound to the login session: an id from another login fails with a decrypt error.
  • Action arguments: { data: {...} } for most actions, { id, data } for view actions, flat keys plus filtersOrder for reports. Dates are yyyymmdd, ranges yyyymmdd-yyyymmdd.
  • Row actions arrive as commonGridAction('NAME','ID') anchors in the ACTION_ICONS cell; top-of-grid buttons come from AUTHORITY rows whose SUPPORTED_ACTION_LOCATION contains MAIN; record-page actions come from getView ENTITY_ACTIONS.

How screens are built

Forms, record pages and search panels are metadata driven (from getConfig: ROLE_FIELD_STATUS_AUTHORITY_VIEW, ROLE_SEARCH_FIELD_AUTHORITY_VIEW, AUTHORITY, LT_CAPTIONS_VIEW). Layouts are generated from the legacy pages (scripts/gen-layouts.mjs → src/features/forms/generated-layouts.json). Exceptions live in a few files:

What Where
Hidden fields/sections, field order, aliases, titles src/features/forms/layouts.ts
Menu, hidden modules, top-bar modules src/layout/nav.ts, menu.ts
Record page, per-entity headers, plate tags src/features/view/EntityView.tsx, headers.tsx
Grid, status chips, row actions src/components/EntityGrid.tsx, src/api/gridActions.ts
Search panel, dependent drop lists src/features/search/
Special popups (pay, renew, settings, upload) src/features/gridActions/
Screen texts the backend does not have src/i18n/ui.ts
Colors, sizes, popups src/theme.tsx

UI conventions (agreed with the user)

  • Font Cairo. Field text, labels, placeholders, drop list values, menu items and grid cells are 13.5px; popup title 16.8px, popup text 14.4px, buttons 13px.
  • Colors: primary #0b6ea8 (dark mode #5fb4ea), text #0b3a5c, page titles gold-orange #d1a233.
  • Record page header: entity name on top (gold-orange), the record's value under it (16px bold), status chip beside it; vehicle records show the plate as a small tag the same height as the chip.
  • Section headers (SectionTitle): icon + dark blue title + thin line, inside a blue-tinted frame (sectionFrame). Field captions on record pages are 13.5px semi-bold primary blue.
  • "New record" shortcut: plus-in-circle icon, 16px, primary blue (newRecordSx), shown in the menu, Home and top search.
  • Grids: 10 rows per page, alternate rows tinted, the filters button always at the end of its row.
  • Arabic first: index.html sets lang="ar" dir="rtl" and the saved language before React loads.

Testing in the browser

  • Use the dev server on http://localhost:5181/mams/ (port may differ). A login session belongs to one origin.
  • After editing files, the dev server can serve a half-updated module; if a screen breaks for no reason, touch the file and reload before debugging.
  • Slow grids (for example Subscriptions, ~11,000 rows) need a wait; stakeholder name lists (Investors 671, Companies 8,000+) take several seconds to load.

Known problems (not front-end bugs)

  • Backend settings missing on some servers: SECRETKEY/storage keys (attachment saving), ATTACHMENT_PATH1 (VAT update, overdue-charge invoices). Reported errors read Element … is undefined in APPLICATION.
  • Driver-Owner creation saves the record but answers SMS.NOT_SENT when the SMS service is down.
  • One old 2022 credit-card reconciliation record fails to open (SQL conversion error in the backend).
  • Attachment links built from the ATTACHMENT_URL setting 404 on production when the files are not under the proxied host (check which host serves /UploadedFiles/…).
  • Card payment (gateway redirect) is not built; the method is listed disabled.
  • The legacy backend source contains hard-coded storage keys (backend/core/abstract/bean.cfc): they should be moved out and rotated. Do not copy them anywhere.

Not built yet

Card payment gateway, a few legacy top-bar helpers, and any screen not listed in the menu for the roles tested (system admin, operations, finance manager, Nafith side). Check the legacy page before assuming a screen is complete.