97 lines
6.0 KiB
Markdown
97 lines
6.0 KiB
Markdown
# 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
|
|
|
|
```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.
|