NTP_V2/docs/HANDOVER.md

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