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…, chassisCLAUDETEST…, emails atexample.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 legacycontroller.cfc. Replies are{CODE, MESSAGE, DATA};'000'(or0for grids) is success. Errors are thrown asApiError.- 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 plusfiltersOrderfor reports. Dates areyyyymmdd, rangesyyyymmdd-yyyymmdd. - Row actions arrive as
commonGridAction('NAME','ID')anchors in theACTION_ICONScell; top-of-grid buttons come from AUTHORITY rows whoseSUPPORTED_ACTION_LOCATIONcontainsMAIN; record-page actions come fromgetViewENTITY_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.htmlsetslang="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,
touchthe 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 readElement … is undefined in APPLICATION. - Driver-Owner creation saves the record but answers
SMS.NOT_SENTwhen 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_URLsetting 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.