NTP_V2/docs/refinery-agent-brief.md

8.2 KiB

Refinery migration: shared brief for the porting agents

Port refinery modules of the legacy ColdFusion app AqabaTCS (C:\inetpub\wwwroot\AqabaTCS_LIVE, read-only) into NTP V2 (.NET 10 API + Oracle 11g/Dapper + React/MUI web). Read first: CLAUDE.md, docs/MIGRATION.md, docs/refinery-db-objects.txt (text of the legacy DB views and the diesel / amount functions, already extracted), and docs/schema/NAFITHTCS.md sections REFINERY_*. Reference slices that show the house style: src/NTP.Application/Grains/Registry, .../Orders (BillingService), src/NTP.Infrastructure/Persistence/Repositories/Grains/*, src/NTP.Api/Controllers/V1/Grains/RegistryController.cs, web/src/features/grains-registry (pages, meta, strings, api hooks).

Legacy layout (AqabaTCS)

  • Backend per entity: backend/entities/<entity>/ : *dao.cfc (SQL), *factory.cfc (business rules, validation, transactions, log rows), *factoryweb.cfc (web layer: filter whitelist, role specific branches, row actions), *bean.cfc (fields).
  • Frontend per entity: frontend/entities/<ENTITY>/<ENTITY>GRID, <ENTITY> (form), <ENTITY>Log (history popup): .js + .html.
  • Menu / authority: customtags/Menu.cfm (entries REFINERYTRIP, REFINERY_WAGE_CLAIM, REFINERY_COMMISSION_CLAIM, REFINERY_WALLET, REFINERY_VARIABLES, REFINERY_CARDS). Grids read DB views (REFINERY_*_VIEW, text in docs/refinery-db-objects.txt); common.getGridData builds the filter SQL (look at backend/common/common.cfc when you need to know how a filter field maps to a column).
  • Captions (Arabic UI / message texts) are in the database: select code, ar from ntp.lt_caption where code like 'REFINERY%' (also PUBLIC.%, ERROR.%, MESSAGE.%, MENU.% for the codes you meet). User-facing texts must be the legacy Arabic captions, verbatim.

Read-only database access (NAFITHTCS, real data)

dotnet "C:\Users\samers\AppData\Local\Temp\claude\d72adf472b8502c5\42c5454f-ddae-4fd6-af13-dba201a0f7ce\scratchpad\q\out\q.dll" NAFITHTCS "select ..." (only SELECT / WITH; prints | separated rows, max 400). Use it to check columns, status codes, sample rows, views, user_source, user_tab_columns, ntp.lt_caption. Never print or copy a connection string; never write to the database; do not run SQL scripts. appsettings.Local.json is in the MAIN checkout (C:\inetpub\wwwroot\NTP_V2\src\NTP.Api\), not in your worktree: you cannot run the API.

Rules (see CLAUDE.md too, they apply)

  • Oracle 11.2: no OFFSET/FETCH or identity, page with ROWNUM (OracleSql.Paginate), sequences for ids (SEQ_REFINERY_* exist). Dapper with classes that have settable properties for results. Bind by name; do not add unused DynamicParameters. Bind numbers, no TO_CHAR on indexed columns. Reuse the legacy views where it is simplest (they exist in the database) but prefer explicit SQL when the view is slow or wrong for the screen.
  • Layers: thin controllers (src/NTP.Api/Controllers/V1/Refinery/<Module>Controller.cs, route api/v{version}/refinery/<module>, [RequirePermission(key)]), services + contracts + validators + repository interfaces in src/NTP.Application/Refinery/<Module>/, Dapper repositories in src/NTP.Infrastructure/Persistence/Repositories/Refinery/<Module>/ (class names *Service / *Repository registered by convention against I{Name}). Primary connection IDbSession (NAFITHTCS) holds all REFINERY_* tables; IUnitOfWork.ExecuteInTransactionAsync for multi-statement writes. Errors: BusinessException (422), ForbiddenException, NotFoundException, FluentValidation (400) with the legacy Arabic text.
  • The legacy *_LOG tables (OLD_DATA / NEW_DATA JSON, METHOD_NAME, USER_ID, USER_IP) are written on every legacy action: keep doing it (same method names, same JSON content as far as you can see in the factory) and port the log popup (history list + old/new view). Find out what legacy puts in USER_ID / CREATED_BY (numeric NTPUSERS id vs login) and use the matching ICurrentUser member.
  • Authority: ONLY SU (always allowed by the code) and role PTADM get access. Do not port the legacy role-specific branches (REFINERY_MGR, REFINERY_OP, EXCHANGE_OP, REFINERY_AC, OPOFF, hard-coded user ids ...). Instead: one screen key per module (already defined in PermissionKeys.Refinery.cs) and one action key per legacy action (e.g. refinery.trips.firstAdvance), declared in YOUR OWN partial file src/NTP.Application/Access/PermissionKeys.Refinery.<Module>.cs (public static partial class PermissionKeys). Every endpoint carries [RequirePermission(...)] with the right key; the web hides buttons with useAuth().can(key). Do NOT add them to PermissionDefaults (rows in GRAINS_SCREEN_PERMISSIONS are the source; the lead writes db/refinery-permissions.sql from the key list you report). Where a legacy rule depended on the role only to narrow what a user sees, drop it and say so in your report.
  • No secrets, no real side effects: legacy code contains hard-coded credentials (e.g. the Jopetrol SOAP password). Never copy them. External calls go behind IDinarakGateway / IJopetrolGateway (src/NTP.Application/Refinery/Integrations/RefineryGateways.cs, already written; do not change the signatures) with options from configuration and Enabled=false by default; add the non-secret defaults to src/NTP.Api/appsettings.json (section Refinery:...) and say in your report which env vars hold the secrets. Never call a real endpoint.
  • Web (React 19, MUI 9): Arabic (RTL), logical CSS properties, metadata-driven DataGrid / MetaForm from web/src/components, strings { en, ar } in the module's strings.ts, API hooks with React Query like grains-registry/api.ts. Put everything of a module under web/src/features/refinery/<module>/ and export from web/src/features/refinery/<module>/index.ts: export const routes: RouteObject[] (absolute paths /refinery/<module>...) and export const menuItems: MenuItem[] (leaf entries only: key = the screen key, title, icon, path; the lead composes the group and features/refinery/routes.tsx). Do NOT create features/refinery/routes.tsx.
  • Port behaviour, not markup: same filters, same grid columns, same row actions, same validations and messages, same status flow. Do not port dead code (check callers / Menu.cfm). Cite legacy file:line in code comments where a rule is non-obvious.
  • Tests: xUnit in tests/NTP.Tests/Refinery/ for pure logic (calculations, status rules, validators). dotnet test tests/NTP.Tests.

Working environment

  • You work in your own git worktree. Do not touch the main checkout. Do NOT start the API or the dev server (ports are used by the lead).
  • First copy these uncommitted foundation files from the main checkout into the same relative paths in your worktree (they are identical for all agents): src/NTP.Application/Access/PermissionDefaults.cs (class made partial), src/NTP.Application/Access/PermissionKeys.Refinery.cs, src/NTP.Application/Refinery/Integrations/RefineryGateways.cs (all under C:\inetpub\wwwroot\NTP_V2\). Commit them with your work.
  • Web checks need node_modules: in your worktree web/ create a junction to the main one: cmd /c mklink /J node_modules C:\inetpub\wwwroot\NTP_V2\web\node_modules (do not commit it; check git status). Then cd web && npx tsc -b --noEmit.
  • Build with dotnet build src/NTP.Api and test with dotnet test tests/NTP.Tests in your worktree. Everything must build and pass before you finish.
  • Shared files you may have to touch (re-read right before editing, make a minimal Edit, never rewrite): src/NTP.Infrastructure/DependencyInjection.cs (gateway registration), src/NTP.Api/appsettings.json. Touch nothing else outside your module folders.
  • Commit your work in the worktree branch (one commit, clear message, end it with the line Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>). Do not push.

Report back (your final message, plain text, concise)

  1. Branch name and commit hash. 2. Files added / changed outside your module folders. 3. Exact list of permission keys you declared (screen + action keys).
  2. What you did NOT port or changed on purpose (and why). 5. Anything you could not verify (nothing was run against real data except read-only SELECTs).
  3. Open questions for the owner.