# 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//…`, `backend/entities//…`) and match it. ## Commands ```bash 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.