diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9ba8acb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,96 @@ +# 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.