NTP_V2/docs/HANDOVER.md

64 lines
11 KiB
Markdown

# Hand-over notes (written 2026-11-17)
How to start: open the repository folder in Claude Code (it reads `CLAUDE.md` by itself), then say
"Read docs/HANDOVER.md and CLAUDE.md, summarise the state and the open items". Claude's per-machine memory does **not** travel with the
repository: everything a new person needs is in these two files, `docs/ENVIRONMENTS.md` and `docs/MIGRATION.md`. Keep them updated.
## 1. State of the work
- **Look and feel** ported from the `mams` project (theme tokens, Cairo font, grids, framed form sections, view page with Details / Attachments tabs, grouped home page, collapsible menu, Arabic only, breadcrumbs in the header).
- **Billing (المطالبات المالية)** ported from the new legacy `Invoice.cfc` (wages / fines lookup, invoice creation, serial / invoice number mapping).
- **Registry (trucks, trailers, drivers):** attachments are stored under `Grains:Registry:UploadedFilesPath` (production `/mnt/NTPFiles`, sub-folders `ntp_trucks_files` / `ntp_trailers_files` / `ntp_drivers_files`; legacy names like `0.723.pdf` are read).
- **Reports:** the two GTO reports (ارسالية عطاء التموين, ملخص التوزيع) and turn reports (translated values, centred counters).
- **Permits / distribution:** distribution reviewed twice against legacy and fixed (BlCategory bind, General Cargo exclusion, OPEN guards, queue cursor reset at sign-in, per-category confirmation, process-with-destination dropdowns + server check); voice call (الاتصال الصوتي) uses the legacy SOAP call; dialer callback hardened.
- **Security pass:** accept / reject / cancel-confirmation staff-only, submit needs REQST, company-access null check, seed / check-trucks SU-only, attachment download scoped to the company.
- **Scheduled jobs:** SU screen `/jobs` ("المهام المجدولة") starts / stops the three legacy jobs (`activateGrainsDestination`, `GRAINS_Close_Old_Permits` - ported new, `parseGrainsPermits`) and sets their running time: every N minutes / hours, or at fixed times of the day (database server time). Code: `src/NTP.Application/Jobs` (catalog, schedule rules, service), `src/NTP.Infrastructure/Jobs` (20-second scheduler loop, runner), `JobsController`, `web/src/features/jobs`. Needs `db/grains-jobs.sql` first. The lock is a database row, so two API instances never run one job twice. Add a job = one entry in `JobCatalog`. The old config-driven `GrainsPermitJobsWorker` is not registered and superseded by this.
- **Operations:** unexpected 5xx errors go to `SYSTEM_ERRORS`; containers run with `TZ=Asia/Amman`.
- **Roles:** `CO` was given the same code-level rights as `GTO` (see 3.1).
- Last local commit at hand-over: `bf1c04b`. **It may not be pushed** (Claude sessions cannot authenticate to Gitea): run `git log origin/main..HEAD` and push it.
## 2. Deploy / configuration checklist (nothing below was verified on the production server)
1. Jenkins builds `deploy/qa/Dockerfile` (`WEB_MODE=build:prod`), pushes the image, copies `deploy/prod/docker-compose.yml` to the server and runs `docker compose pull && up -d --no-build` (see `Jenkinsfile`). The compose file must reach the server for new volumes / env to apply.
2. Server `.env` (never committed): `ConnectionStrings__NAFITHTCS`, `ConnectionStrings__NtpSchema`, `Jwt__Key`, `Cors__AllowedOrigins__0`; optional `Grains__Permits__AutoCall__ApiKey` (the dialer's callback key, empty = callback disabled).
3. Host folder `/mnt/NTPFiles` must exist, be writable by the container, and hold the legacy files in `ntp_*_files`. Check `docker inspect ntpv2-prod --format '{{json .Mounts}}'`.
4. `Grains:Registry:UploadedFilesPath` must be a plain path (`/mnt/NTPFiles`), never a `host:container` mapping.
5. `appsettings.Production.json` sets: attachment paths, `Grains:Permits:AutoCall` (enabled, IVR WSDL address), ownership code lists (`BadiyaOwnershipCodes 3,2`, `OtherOwnershipCodes 1,2` - confirm against production `SYSTEM_VARIABLES`).
6. The provider of the dialer must call `/api/v1/grains/permit-autocall/callback` with header `X-Api-Key`; nothing in the repo repoints it.
7. Mobile notifications are ported (see 3.5): production pushes through the legacy web service `http://aqtcs.nafith.net/backend/common/MobileNotification.cfc` and sends the SMS for owners without the app (`SEND_SMS_GN_DIST` = 1). Put the SMS account in the server `.env`: `Grains__Permits__Notifications__Sms__UserName` and `__Password` (until then the SMS is skipped with a warning). Provider `JORMALL` is a guess (the AqabaTCS app uses it): confirm which provider NTP used (`application.SMS_PROVIDER`).
8. The NTP database user needs INSERT on `SYSTEM_ERRORS` and SELECT on `SEQ_SYSTEM_ERRORS`, otherwise error logging only writes a warning to the API log.
9. After deploy: `docker exec ntpv2-prod date` (Amman time), `/health/ready`, sign in, open a truck attachment, click الاتصال الصوتي once (it really dials every requested truck: do not test casually).
10. Database scripts: see docs/ENVIRONMENTS.md ("Database objects"). They are applied by hand; which ones ran on which environment is not recorded: check the tables before re-running (all are safe to re-run).
## 3. Open decisions and known gaps
### 3.0 Scheduled jobs: untested parts
The schedule rules are unit-tested and the close-old-permits SQL was run read-only on QA, but the job tables did not exist when this was written: run `db/grains-jobs.sql`, then try the screen (save a time, start, run now, history) on QA. Close-old-permits differs from legacy in two safe ways: a permit found by two of its four groups is closed once, and it is closed only while it still has the status it was found with.
### 3.1 Role CO
`CO` already existed in the database ("مدير العمليات وخدمة الجمهور", own group id 149, stakeholder 61, 29 mostly oil-related actions, 1 user) and the legacy menu uses it in many places. The code now treats CO like GTO, and `GRAINS_SCREEN_PERMISSIONS` already has the same 27 rows for both. **Decide** whether that user should really get GTO's grains authority or whether a new role code is wanted. Also unresolved: CO's legacy group has none of the registry actions 66-71 / 107, so accept / revoke of trucks, trailers, drivers and destinations are off for CO; `db/role-co.sql` does not create `GROUPS` / `GROUP_ACTIONS` rows.
### 3.2 Role lists in code differ from the legacy action holders
Legacy holders (from the database): phone confirm 93 = GNSU, GOO, GTO, MOT, SU; cancel order 106 = GNSU, GOO, GPO, MOT, SU; cancel permit 167 = GTO, MOT; voice call 96 = GNAC, GNSU, GTO, MOT, SU; accept / reject / cancel-confirmation 74 / 85 / 88 = GNSU, GOO, GPO, GTO, MOT, SU. V2 uses the single list `GrainsRoles.Operators` (SU, GPO, GNSU, GNCO, GTO, CO), so GOO cannot confirm by phone or cancel an order, and the "staff" gate for accept / reject is "any non-company user" (includes GGO). Proposed: one explicit role list per action.
### 3.3 Review findings: owner decisions (2026-11-17)
Decided **to match legacy** (done): blacklist expiry uses shift 1 for a typed permit number and for NO_ANSWER (the real order shift only when a permit id is sent); the dialer callback accepts numbers or strings, any key case and any content type, and answers with the legacy keys `CODE` / `MSG`; trailer edit needs one document (stored or new); revoking a trailer resets its truck to REGREQST only when the revoke is made from the truck's page (trailer opened with `?truckId=`), and never a revoked truck.
Decided **to keep V2** (not open): `acceptDriver` accepts (legacy never did), upload rules (fixed extension list, 10 MB), `TO_CHAR(pn/tn)` comparisons, manual weighbridge entry+exit without an outer transaction, manual-input date list, done-by shown to company users, used-orders count summed.
Settled: time zone (container `TZ=Asia/Amman`, verified by the owner). No rate limit on the dialer callback; replays duplicate blacklist rows, as in legacy.
Still open / not ported: company destinations save (Orders slice) only deletes the locations the screen offers (PCKD / BULK / BULK_GALLAB) where legacy deleted every row of the company, and it writes only ID / SCAC / LOCATIONID where legacy also wrote date and user (check the production table's columns and NOT NULL flags: `select column_name, nullable from user_tab_columns where table_name='GRAINS_COMPANIES_LOCATION'`); company users' "registered count share/open" on the truck / trailer grids; head-type change log; Firebase push; QUED/TCS permit flow (tables missing on QA); the approvals-file import is a second copy of the phone logic and likely broken (SU-only, legacy button commented out).
### 3.4 Never tested against real data
Distribution runs, the IVR call, dialer callbacks, `SYSTEM_ERRORS` insert, the attachment folder in the container, the Amman time zone. Everything was verified only by build, unit tests, type check and read-only queries.
## 4. Security housekeeping for the owner
- Database passwords from `appsettings.Local.json` were once shown in a Claude session's output: **rotate them**.
- Make sure the new developer has Gitea access (push) and their own `appsettings.Local.json`; they need network access to the Oracle servers.
- The repository holds no secrets by design (`.env` and `appsettings.Local.json` are git-ignored).
## 5. Useful read-only database checks
Role and groups: `select * from roles where code='GTO'`, `select id,name,stakeholderid,status from groups where name in ('GTO','CO')`.
Who holds a legacy action: `select ga.actionid, listagg(g.name,',') within group (order by g.name) from group_actions ga join groups g on g.id=ga.groupid and g.status=1 where ga.actionid in (73,74,93,94) group by ga.actionid`.
Screen rights per role: `select rolecode, count(*) from grains_screen_permissions group by rolecode`.
Ownership lists: `select name, value from system_variables where upper(name) like '%OWNERSHIP%'`.
### 3.5 Mobile notifications (ported from components/MobileNotifications.cfc)
Flow per template (CONFIRM_PN, PHONE_REJECT, DELAY_PN, DISTRIBUTE_PACKED_BULK_OWNERS / _OWNERS_COMPANIES / _COMP): find the app users (driver DRVR and owner TRKOWNER by the truck phone, dispatchers DISP by company login), read their ACTIVE devices (USERDEVICEINFO), fill the NOTIFICATIONMESSAGETEMPLATE text (VAR1..VARn, first occurrence only, as ColdFusion Replace), call SendFromCF9 of the legacy push web service (it sends the OneSignal push and writes MOBILENOTIFICATIONSLOG). It runs in the background in its own scope (legacy used a thread); a failure only goes to the API log and SYSTEM_ERRORS. Owners distribution: an account with no active device gets an SMS with the app link when SendSmsToOwnersWithoutApp (legacy SEND_SMS_GN_DIST) is on, logged in USER_SMS_LOGS. Same legacy quirk: no account for the phone = no SMS.
The SQL was checked read-only on the QA database (all 7 templates exist). **Not tested end to end**: no real push or SMS was sent, and the SOAP envelope for SendFromCF9 was built from its WSDL, not captured from legacy. Difference: the SMS log status is the real HTTP result (legacy always wrote SUCCESS). Still not ported: the push of addPhoneAcceptEvent (phone approval import) and the tender-order publishMobile switch. The legacy files hold the old Firebase and SMS provider keys in clear text (MobileNotifications.cfc, SMS.cfc): rotate them.