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
mamsproject (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-foldersntp_trucks_files/ntp_trailers_files/ntp_drivers_files; legacy names like0.723.pdfare 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. Needsdb/grains-jobs.sqlfirst. The lock is a database row, so two API instances never run one job twice. Add a job = one entry inJobCatalog. The old config-drivenGrainsPermitJobsWorkeris not registered and superseded by this. - Operations: unexpected 5xx errors go to
SYSTEM_ERRORS; containers run withTZ=Asia/Amman. - Roles:
COwas given the same code-level rights asGTO(see 3.1). - Last local commit at hand-over:
bf1c04b. It may not be pushed (Claude sessions cannot authenticate to Gitea): rungit log origin/main..HEADand push it.
2. Deploy / configuration checklist (nothing below was verified on the production server)
- Jenkins builds
deploy/qa/Dockerfile(WEB_MODE=build:prod), pushes the image, copiesdeploy/prod/docker-compose.ymlto the server and runsdocker compose pull && up -d --no-build(seeJenkinsfile). The compose file must reach the server for new volumes / env to apply. - Server
.env(never committed):ConnectionStrings__NAFITHTCS,ConnectionStrings__NtpSchema,Jwt__Key,Cors__AllowedOrigins__0; optionalGrains__Permits__AutoCall__ApiKey(the dialer's callback key, empty = callback disabled). - Host folder
/mnt/NTPFilesmust exist, be writable by the container, and hold the legacy files inntp_*_files. Checkdocker inspect ntpv2-prod --format '{{json .Mounts}}'. Grains:Registry:UploadedFilesPathmust be a plain path (/mnt/NTPFiles), never ahost:containermapping.appsettings.Production.jsonsets: attachment paths,Grains:Permits:AutoCall(enabled, IVR WSDL address), ownership code lists (BadiyaOwnershipCodes 3,2,OtherOwnershipCodes 1,2- confirm against productionSYSTEM_VARIABLES).- The provider of the dialer must call
/api/v1/grains/permit-autocall/callbackwith headerX-Api-Key; nothing in the repo repoints it. - Mobile push / SMS (legacy Firebase) is not ported:
Grains:Permits:Notificationsonly posts to a URL that does not exist yet (disabled by default). - The NTP database user needs INSERT on
SYSTEM_ERRORSand SELECT onSEQ_SYSTEM_ERRORS, otherwise error logging only writes a warning to the API log. - 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). - 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.jsonwere 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 (
.envandappsettings.Local.jsonare 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%'.