NTP_V2/docs/HANDOVER.md

8.3 KiB

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.
  • 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 push / SMS (legacy Firebase) is not ported: Grains:Permits:Notifications only posts to a URL that does not exist yet (disabled by default).
  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.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 not yet fixed (from the legacy review of grains.cfc, register.cfc, autoCallResponse.cfc)

  • Time zone of DateTime.Now expiry vs Oracle SYSDATE (container now Amman; verify).
  • NO_ANSWER / blacklist expiry use the order's real shift; legacy always used shift 1 for typed numbers (confirm which is wanted).
  • Dialer callback: strict string fields (400 on numeric JSON), no rate limit, replays duplicate blacklist rows (as in legacy).
  • Company destinations save (Orders slice) deletes only PCKD / BULK / BULK_GALLAB locations; audit columns not written.
  • acceptDriver: legacy never accepts (bug), V2 accepts; accepted drivers then disappear from the GOO grid.
  • Trailer edit needs 2 attachments (stored + new), legacy effectively 1; revoke trailer always resets the truck to REGREQST.
  • Not ported: company users' "registered count share/open" on the truck / trailer grids, head-type change log, Firebase push, QUED/TCS permit flow (its tables are missing on QA), the approvals-file import is a second copy of the phone logic and likely broken (SU-only; legacy button commented out).
  • Production upload rules differ from legacy (legacy allowed xls / xlsx / zip, no size limit; V2 a fixed list, 10 MB).
  • Performance: many queries use TO_CHAR(pn) / TO_CHAR(tn) on indexed number columns; measure a real distribution run (the command timeout is 30 s).
  • Manual weighbridge entry + exit are not in one transaction; manual-input screen date list differs from legacy and assumes GN_MANUAL_ORDER.id = GRAINSTENDERORDER.id (unverified).
  • Done-by column is still shown to company users (legacy hid it) - deliberately skipped so far.
  • Used-orders count: the view GN_USED_ORDER_BY_CATEGORY may return several rows for PCKD; V2 sums them, legacy read the first row. Check the view's rows.

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%'.