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.getGridDatabuilds the filter SQL (look atbackend/common/common.cfcwhen 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%'(alsoPUBLIC.%,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, noTO_CHARon 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, routeapi/v{version}/refinery/<module>,[RequirePermission(key)]), services + contracts + validators + repository interfaces insrc/NTP.Application/Refinery/<Module>/, Dapper repositories insrc/NTP.Infrastructure/Persistence/Repositories/Refinery/<Module>/(class names*Service/*Repositoryregistered by convention againstI{Name}). Primary connectionIDbSession(NAFITHTCS) holds all REFINERY_* tables;IUnitOfWork.ExecuteInTransactionAsyncfor multi-statement writes. Errors:BusinessException(422),ForbiddenException,NotFoundException, FluentValidation (400) with the legacy Arabic text. - The legacy
*_LOGtables (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 matchingICurrentUsermember. - Authority: ONLY
SU(always allowed by the code) and roleREFINERY_MGRget 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 inPermissionKeys.Refinery.cs) and one action key per legacy action (e.g.refinery.trips.firstAdvance), declared in YOUR OWN partial filesrc/NTP.Application/Access/PermissionKeys.Refinery.<Module>.cs(public static partial class PermissionKeys). Every endpoint carries[RequirePermission(...)]with the right key; the web hides buttons withuseAuth().can(key). Do NOT add them toPermissionDefaults(rows in GRAINS_SCREEN_PERMISSIONS are the source; the lead writesdb/refinery-permissions.sqlfrom 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 andEnabled=falseby default; add the non-secret defaults tosrc/NTP.Api/appsettings.json(sectionRefinery:...) 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/MetaFormfromweb/src/components, strings{ en, ar }in the module'sstrings.ts, API hooks with React Query likegrains-registry/api.ts. Put everything of a module underweb/src/features/refinery/<module>/and export fromweb/src/features/refinery/<module>/index.ts:export const routes: RouteObject[](absolute paths/refinery/<module>...) andexport const menuItems: MenuItem[](leaf entries only: key = the screen key, title, icon, path; the lead composes the group andfeatures/refinery/routes.tsx). Do NOT createfeatures/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:linein 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 madepartial),src/NTP.Application/Access/PermissionKeys.Refinery.cs,src/NTP.Application/Refinery/Integrations/RefineryGateways.cs(all underC:\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; checkgit status). Thencd web && npx tsc -b --noEmit. - Build with
dotnet build src/NTP.Apiand test withdotnet test tests/NTP.Testsin 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)
- Branch name and commit hash. 2. Files added / changed outside your module folders. 3. Exact list of permission keys you declared (screen + action keys).
- 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).
- Open questions for the owner.