75 lines
8.2 KiB
Markdown
75 lines
8.2 KiB
Markdown
# 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).
|
|
4. 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).
|
|
6. Open questions for the owner.
|