edr-platform/docs/hr-finance-ui-e2e-matrix.md

# HR + Finance Playwright e2e — Phase 0 map and plan

> Phase 0 deliverable for `docs/prompts/hr-finance-e2e-prompt.md`. **Approved by the owner
> 2026-08-24.**
>
> Reconstructed after the 2026-08-24 data-destruction incident
> (`SECURITY-INCIDENT-2026-08-24.md`); the original was lost with the working tree. Content is
> unchanged from the approved version.

---

## 1. The database decision

**Recommendation: use `smart_office_e2e`.** It already exists on this machine — a schema clone of
`smart_office_prod` (verified):

| | `smart_office_prod` | `smart_office_e2e` |
|---|---|---|
| Size | 1483 MB | 1484 MB |
| `iam.users` | 34,637 | 34,639 |
| `iam.employees` | 2,431 | 2,433 |
| `iam.positions` | 1,043 | 1,043 |
| Schemas | `iam`, `freight`, `passenger`, `edr_payment`, `audit`, `hr`, `finance` | same six |
| `hr` tables | 38 | 38 |
| `finance` tables | 22 | 22 |

This answers the prompt's own suggested option ("clone `smart_office_prod` into a
`smart_office_e2e` database and run migrations + HR/Finance seeds there"). Its origin was traced to
an earlier session at 2026-08-24 01:22, which also left a hand-made `e2e_hr_employee` role behind
(since retired — see §1.1).

### 1.1 Seed HR and Finance into it — with the scoped seeder, not the vendor one

Neither module's IAM rows existed in either database (`iam.application` had no `hr` or `finance`
row; 0 of 9 roles). **Do not** run `pnpm run seed:hr`: it re-seeds IAM's entire baseline and aborts
the whole transaction on an id conflict with a pre-existing row —

```
"people_operation" is id 9f9c0c2e-… in the database but the seed assigns it id 7bbf4e76-…
```

— which reproduces identically on any database restored from a dump taken at a different
`@tria-plc/iamapi-common` version. That refusal is correct (it protects rows another product owns),
but it means HR's and Finance's own rows can never be written that way.

Use `scripts/seed-module-permissions.cjs` instead, which writes only the module's own rows by the
stable ids its registry declares:

```bash
DB_NAME=smart_office_e2e DB_PASSWORD=… node scripts/seed-module-permissions.cjs hr
DB_NAME=smart_office_e2e DB_PASSWORD=… node scripts/seed-module-permissions.cjs finance
```

It carries a guard that has already fired for real: a key that exists under a *different* id stops
the write rather than silently diverging. That caught five HR permission keys duplicated by the
earlier session's hand-made `e2e_hr_employee` role. Those five rows and that role were retired in
favour of the product's own `employee_self_service`, which is a strict superset (10 self-service
keys vs 5).

### 1.2 Create every fixture inside the Active railway org

13 of 15 `iam.organizations` rows are `status='Debarred'`, and IAM's login SQL joins `o.status = $2`
when building the session's `employee` array — so an employee in a Debarred org gets an **empty
employee array and no organization context**, and every HR/Finance write plus most reads then 403
with "no organization context".

**This is correct data, not a bug** — the counts make that clear:

| org | status | employees | positions |
|---|---|---|---|
| Ethio Djibouti Standard Gauge Railway Share Company | Active | 2,416 | 1,004 |
| TRIA | Active | 1 | 0 |
| EDR | Debarred | 7 | 8 |
| Nifas Silk-Lafto Sub City | Debarred | 2 | 0 |
| EDR Freight | Debarred | 1 | 10 |
| 10 further Addis Ababa sub-cities + "Endode EDR" | Debarred | 0 | 0 |

**2,417 of 2,433 employees are in Active orgs.** The Debarred rows are Addis Ababa sub-cities
inherited from the Smart Office lineage (this database is a `smart_office` replica — those were
never EDR tenants) plus rows named after **applications** rather than legal entities. Note
`iam.application` separately and correctly holds `edr_freight_app` / `edr_passenger_app` — "EDR
Freight" and "EDR" as *organization* rows are artifacts, and near-empty ones.

The practical rule: **seed fixtures exclusively inside the Active railway org**, which has all the
real structure (2,416 employees, 1,004 positions, 7-level position hierarchy) a test could need. No
org status needs changing, in prod or in the e2e clone. `seed-personas.cjs` asserts the org is
Active and refuses to run otherwise.

### 1.3 Running the suite against it

Point both APIs at `smart_office_e2e` **for the test run only**, via environment rather than by
editing `.env` — verified working: `DB_NAME`, `PORT` and `CORS_ORIGINS` all override the `.env`
file, and Vite picks up `PORT` and `VITE_*` from the process environment too.

Use separate ports so a run never collides with the dev stack a human is using (the same isolation
the freight/passenger suites get from their own databases):

| | dev | e2e |
|---|---|---|
| hr-api | 3005 | **3105** |
| finance-api | 3004 | **3104** |
| hr-web | 5185 | **5285** |
| finance-web | 5186 | **5286** |

`CORS_ORIGINS` must be set on each API to its e2e web origin, or login dies at the preflight with a
"Network Error" that says nothing about CORS.

**Never point the running dev instances at the e2e database by accident** — a stray `nest start
--watch` found bound to `smart_office_e2e` cost an hour of misdiagnosis, because every write
appeared to succeed and then could not be found.

### 1.4 Teardown and hermeticity

Journals, payroll runs and posted ledger entries are deliberately append-only by product design, so
"run twice, DB unchanged" cannot mean "delete what got posted". The realistic story:

- Fixtures live under the Active org, never touching the 2,415 real employees' data.
- Each spec drives its fixture to a terminal, assertable state, or leaves a **named, findable
  row** (`E2E-` prefix) rather than deleting — matching the passenger suite's convention of
  asserting against real rows, not a wiped table.
- The reset mechanism is periodically re-cloning `smart_office_e2e` from `smart_office_prod`, not a
  per-run DELETE. Cadence to be decided.

---

## 2. Route × permission × audience inventory

Read from `App.tsx` in both apps, cross-referenced against each app's permission-role matrix
(`hr-permissions.registry.ts`, 5 roles; `finance-permissions.registry.ts`, 4 roles). `viewOwn`-gated
rows are additionally reachable by everyone via `SELF_SERVICE_KEYS` (HR) / `READ_ONLY_KEYS`
(Finance).

### edr-hr-web (26 routes)

| Path | Gate | Reachable by |
|---|---|---|
| `/`, `/me` | none | any authenticated employee |
| `/employees` | `view:employee_profile` | hr_manager, hr_officer, payroll_admin, recruitment_officer |
| `/employees/new` | `create:employee_profile` | hr_manager, hr_officer |
| `/employees/:id` | `view:employee_profile` | as `/employees` |
| `/employees/:id/edit` | `update:employee_profile` | hr_manager, hr_officer |
| `/organisation`, `/departments`, `/job-titles`, `/job-positions` | `view:hr_org_structure` | hr_manager, hr_officer, payroll_admin, recruitment_officer |
| `/reports` | `view:hr_report` | hr_manager, hr_officer, payroll_admin |
| `/appraisals` | `submit_self:appraisal` | everyone (self-service) |
| `/appraisals/reviews` | `submit_manager:appraisal` | hr_manager |
| `/appraisals/cycles` | `manage:appraisal_cycle` | hr_manager |
| `/recruitment`, `/recruitment/:id` | `view:application` | hr_manager, recruitment_officer |
| `/payroll` | `view_all:payslip` | hr_manager, payroll_admin |
| `/payroll/settings` | `manage:salary_rule` | hr_manager, payroll_admin |
| `/payslips` | `view_own:payslip` | everyone |
| `/attendance` | `view_own:attendance` | everyone |
| `/attendance/approvals` | `approve:regularization` — confirmed NOT the same trap as leave; both roles hold this key | hr_manager, hr_officer |
| `/attendance/register` | `view_all:attendance` | hr_manager, hr_officer |
| `/attendance/settings` | `view_own:attendance` (read; write gated in-page on `manage:work_schedule`) | everyone (read) |
| `/leave` | `view_own:leave_request` | everyone |
| `/leave/approvals` | **fixed 2026-08-24** — was `approve_l1` solo (ungrantable), now `[approve_l1, approve_l2]` | any line manager (dynamic) + hr_manager (static L2) |
| `/leave/register` | `view_all:leave_request` | hr_manager, hr_officer |
| `/leave/settings`, `/leave/types`, `/leave/holidays` | `view_own:leave_request` (read) | everyone (read) |
| `/forbidden` | none | anyone denied elsewhere |

### finance-web (14 routes)

| Path | Gate | Reachable by |
|---|---|---|
| `/`, `/forbidden` | none | any authenticated staff |
| `/accounts` | `view:gl_account` | all 4 roles |
| `/journals`, `/journals/:id` | `view:journal_entry` | all 4 roles |
| `/journals/new` | `create:journal_entry` | finance_manager, accountant |
| `/periods` | `view:fiscal_period` | all 4 roles |
| `/receivables`, `/revenue-mappings` | `view:receivable` | all 4 roles |
| `/payables`, `/payroll` | `view:payable` | all 4 roles |
| `/budgets`, `/cost-centers` | `view:budget` | finance_manager, accountant, finance_auditor (**not** cashier) |
| `/assets` | `view:fixed_asset` | all 4 roles |
| `/reports` | `view:finance_report` | all 4 roles |
| `/cutover` | `view:fiscal_period` (reuses `period.view`, not a new key) | all 4 read; only finance_manager can act |

Every write action is gated **in-page**, not at the route level — `finance_auditor` and `cashier`
can open most screens but most buttons on them should be disabled or absent. That belongs in the
scenario matrix (§5) and needs its own `data-testid`s (§4).

### Verified persona boundaries

Driven against the running services rather than inferred from the matrix:

| persona | own-leave | approvals | employees | payroll | recruitment |
|---|---|---|---|---|---|
| hr-employee | 200 | 403 | 403 | 403 | 403 |
| hr-manager | 200 | 200 | 200 | 200 | 200 |
| hr-payroll-admin | 200 | 403 | 200 | 200 | 403 |
| hr-recruitment-officer | 200 | 403 | 200 | 403 | 200 |

| persona | accounts | journals | create-journal | budgets | cutover |
|---|---|---|---|---|---|
| finance-manager | 200 | 200 | past guard | 200 | 200 |
| finance-accountant | 200 | 200 | past guard | 200 | 200 |
| finance-cashier | 200 | 200 | **403** | **403** | 200 |
| finance-auditor | 200 | 200 | **403** | 200 | 200 |

("past guard" = 400 from DTO validation on a deliberately empty body, i.e. the permission check
was passed.)

---

## 3. Network contract per flow

Paths come from the controllers (`@Controller()` base + verb literals). `(verify)` means the path is
confirmed but the guard should be re-read at test-writing time.

### HR

| Flow | Method + path | Key fields | Notes |
|---|---|---|---|
| Leave — quote | `GET /leave-requests/quote` | day count, balance after | drives the request-modal preview |
| Leave — submit | `POST /leave-requests` | `id`, `status: SUBMITTED`, `chargedDays` | day count frozen at submission |
| Leave — awaiting-me | `GET /leave-requests/awaiting-me` | `{items, total}` | **gate fixed**: `[approve_l1, approve_l2]` |
| Leave — approve/reject | `PATCH /leave-requests/:id/approve`, `/:id/reject` | `status`, `decidedByEmployeeId` | deducts in the same transaction — assert response AND `hr.leave_ledger_entries` |
| Leave — cancel | `PATCH /leave-requests/:id/cancel` | reversal entry | REVERSAL row, capped at one per entry by a unique index |
| Leave balance | via `/leave-balances` | balance = `SUM(days)` | **never stored** — the DB assertion must SUM the ledger |
| Attendance — clock | `POST /attendance/check-in`, `/check-out` | `work_date` (DATE) | night shift stays on the day it began |
| Attendance — regularize | `POST /attendance-regularizations` → `PATCH /:id/approve` | prior values preserved | applies **on approval** |
| Overtime | `GET /overtime/rates` + request/approve `(verify)` | category, multiplier | category derived, multiplier **frozen on the claim** |
| Payroll — lifecycle | `POST /payroll-runs` → `/:id/calculate` → `PATCH /:id/approve` → `/:id/mark-paid` | `status` | recalculation refused after APPROVED; one run per period |
| Payroll — payslips | `GET /payroll-runs/my-payslips`, `/payslips/:id` | own + approved only | |
| Appraisal — cycle open | `POST /appraisal/cycles/:id/open` | criteria copied | copy independent of later template edits |
| Appraisal — score | `POST /appraisal/:id/manager` | `finalScore` | manager's score only, never averaged |
| Recruitment — hire | `POST /recruitment/offers/:id/hire` | IAM user + employee + profile + salary | re-hiring the same offer → 409 |
| Reports — leave liability | `GET /reports/leave-liability` | valued days | only types with `max_carry_over_days > 0` |
| Org — hire | `POST /org/positions/:id/hire` | employee, `status='pending'` | `pending` is normal (2,424 of 2,433 real employees are) — only **org** status gates login |
| Job positions | `GET /job-positions` | `{items, total}` | **fixed**: 500'd for any non-super-admin (`hr.job_positions` has no org column; must join `iam.positions`) |

### Finance

| Flow | Method + path | Notes |
|---|---|---|
| GL — post | `POST /journals` → `POST /journals/:id/post` | balances or refused; refused outside a fiscal period; enforced in service **and** a DB constraint |
| GL — reverse | `POST /journals/:id/reverse` | links both ways, requires a reason |
| AR — ingest | broker consumer (`payment.#`), not HTTP | idempotent under redelivery; needs `PAYMENT_RABBITMQ_URL` (off by default) |
| AP — bills | `POST /payables/bills` → `/:id/approve` → `/:id/payments` | approve = `approve:supplier_bill` (finance_manager only); pay = `record:supplier_payment` (accountant + cashier) |
| AP — payroll→GL | `POST /payables/payroll/runs/:id/post` | depends on an HR payroll run existing first |
| Budgeting | `POST /budgeting/budgets/:id/approve` | budget vs actual vs committed |
| Assets — depreciation | `POST /assets/depreciation/run` | counts from `depreciation_entries` **plus** `opening_periods_charged`, in both the run and the schedule |
| Assets — dispose | `POST /assets/:id/dispose` | opening figures may not combine with `fundingAccountId` |
| Reports | `GET /reports/trial-balance`, `/balance-sheet` | debits = credits; assets = liabilities + equity + unclosed result |
| Cutover — readiness | `GET /cutover/readiness` | 5 checks; **suspense check counts posted lines only** |
| Cutover — import | `POST /cutover/opening-balances` | DRAFT entry; 3900 plug **computed, never accepted from the caller** |
| Cutover — set date | `PUT /cutover` | a payment dated before cutover must be **SKIPPED**, recorded in `inbound_events` |

---

## 4. `data-testid` prerequisite checklist

**Current state:** only nav-level testids exist (`nav-item-*`, `nav-group-*` from the redesign).
**Zero on any feature page.** This is the blocker that stalled the passenger effort; treat it as a
blocker, not a footnote. Note `SpotlightSearchProps` rejects `data-testid` — address the palette
input by placeholder.

**HR (`apps/edr-hr-web/src/features/**`)**
- `leave/RequestModal.tsx`: `leave-request-type`, `leave-request-dates`, `leave-request-submit`
- `leave/LeaveApprovalsPage.tsx`: `leave-approval-row-<id>`, `leave-approve-btn-<id>`, `leave-reject-btn-<id>`
- `attendance/*`: `attendance-clock-in`, `attendance-clock-out`, `attendance-regularization-row-<id>`
- `payroll/PayrollRunsPage.tsx`: `payroll-run-row-<id>`, `payroll-calculate-btn`, `payroll-approve-btn`, `payroll-mark-paid-btn`
- `appraisal/*`: `appraisal-criterion-<key>`, `appraisal-weight-total`, `appraisal-submit-self`, `appraisal-submit-manager`
- `recruitment/ApplicationDrawer.tsx`: `recruitment-stage-select`, `recruitment-hire-btn`
- `reports/ReportsPage.tsx`: `report-row-<key>`, `report-export-btn`

**Finance (`apps/finance-web/src/features/**`)**
- `journals/NewJournalPage.tsx`: `journal-line-row-<n>`, `journal-balance-indicator`, `journal-post-btn`
- `payables/PayablesPage.tsx`: `bill-row-<id>`, `bill-approve-btn-<id>`, `bill-record-payment-btn-<id>`
- `budgeting/BudgetsPage.tsx`: `budget-row-<id>`, `budget-approve-btn`
- `assets/AssetsPage.tsx`: `asset-row-<id>`, `run-depreciation-btn`, `dispose-btn-<id>`
- `cutover/CutoverPage.tsx`: `cutover-readiness-check-<key>`, `cutover-set-date-btn`, `cutover-import-paste`, `cutover-import-preview`
- `reports/ReportsPage.tsx`: `report-trial-balance-row-<code>`, `report-balance-sheet-total`

A starting inventory from reading route components, not exhaustive — whoever writes each spec adds
what their scenario needs in the same pass.

---

## 5. Scenario matrix

**DOM** = UI assertion, **NET** = network, **DB** = database.

| id | module | audience | proves | DOM | NET | DB | fixture |
|---|---|---|---|---|---|---|---|
| HR-01 | leave | employee | submitting freezes the day count | request in "My leave" | `POST /leave-requests` 201, `chargedDays` matches quote | `charged_days` unchanged after a later holiday-calendar edit | employee with an entitlement |
| HR-02 | leave | line manager | L1 approval deducts atomically | balance updates | `PATCH /:id/approve` 200 | one DEDUCTION row in the same statement window as the status flip | the real manager/report position pair |
| HR-03 | leave | hr_manager | **L2 reaches the page and can decide** (regression pin) | `/leave/approvals` renders, not `/forbidden` | `GET /awaiting-me` 200 not 403 | — | hr-manager persona |
| HR-04 | leave | employee | cancel reverses, not deletes | both entries in ledger drawer | `PATCH /:id/cancel` 200 | REVERSAL row added; original untouched; unique index holds | an approved request |
| HR-05 | attendance | employee | night shift stays on its start date | one day marked | check-in 22:00, check-out after midnight | `work_date` = check-in date | — |
| HR-06 | payroll | payroll_admin | recalculation refused after approval | error on retry | `POST /:id/calculate` → non-2xx | status unchanged | an APPROVED run |
| HR-07 | payroll | employee | self-service is scoped | own, approved-only | `GET /my-payslips` | — | two employees, one run |
| HR-08 | appraisal | hr_manager | manager score is final | shown = manager's, not an average | `POST /:id/manager` | `final_score` = manager's raw score | template weights = 100 |
| HR-09 | recruitment | recruitment_officer | re-hiring an offer is refused | error on 2nd click | 2nd `POST /offers/:id/hire` → 409 | FILLED count unchanged | one vacancy, one offer |
| HR-10 | job-positions | hr_manager | **org-filtered list no longer 500s** (regression pin) | table renders | `GET /job-positions` 200 | — | any non-super-admin |
| HR-11 | reports | hr_manager | liability values only carry-over types | excludes sick/bereavement/paternity | `GET /reports/leave-liability` | cross-check filtered `SUM` | both balance kinds |
| HR-12 | gating | **hr-employee** | a gated screen is refused by direct URL | lands on `/forbidden` | 403 if forced | — | ✅ unblocked — persona verified 403 on 4 of 5 endpoints |
| FIN-01 | GL | accountant | unbalanced entry refused | error on submit | `POST /journals` mismatched → non-2xx | no row written | — |
| FIN-02 | GL | finance_manager | posting outside a period refused | error on post | `POST /:id/post` → non-2xx | stays DRAFT | journal outside any open period |
| FIN-03 | AP | finance_manager vs cashier | separation of duties | approve visible only to manager; pay only to accountant/cashier | matching 403s if forced | — | one bill, two personas |
| FIN-04 | assets | accountant | a migrated asset still depreciates | non-zero charge in schedule | `POST /assets/depreciation/run` | entry row added; `periodsCharged` past the opening count | asset with opening figures |
| FIN-05 | cutover | finance_manager | suspense counts posted lines only | panel matches DB state | `GET /cutover/readiness` | DRAFT-only batch reads PENDING, not FAIL | unposted opening import |
| FIN-06 | cutover | finance_manager | pre-cutover payment skipped, not double-posted | — | broker message before cutover → no journal | `inbound_events` SKIPPED; ledger unchanged | needs `PAYMENT_RABBITMQ_URL` |
| FIN-07 | reports | finance_auditor | trial balance balances | totals equal | `GET /reports/trial-balance` | `SUM(debit) = SUM(credit)` | any posted period |
| FIN-08 | gating | **cashier** | a manage-only screen is refused | — | 403 | — | ✅ unblocked — cashier verified 403 on create-journal and budgets |

---

## 6. Harness plan

- `e2e-hr-finance/playwright.config.ts` — one project per audience (8 personas + super admin).
- `webServer`: boot-or-reuse both API+web pairs on the e2e ports (§1.3) against `smart_office_e2e`.
- **`storageState` per role**: mint programmatically per role (`POST /api/v1/auth/login`) for
  speed, plus **one persona through the real login UI** — the passenger suite's precedent — so the
  actual `<LoginPage>` form stays covered.
- **Fixtures**: draw on the Active org's existing hierarchy rather than building an IAM tree from
  nothing. This is the advantage `smart_office_e2e` has over the passenger suite's 5544 database,
  and the reason Phase 0 did not recommend a fresh Prisma-seeded DB. New rows get an `E2E-` prefix.
- **Serialization**: serialize specs sharing a payroll run or journal period; parallelize
  independent reads.
- **Run script**: `e2e-hr-finance/run.sh` — infra → build → seed (module permissions + personas) →
  boot → mint storageStates → run → open report.
- **CI**: no pipeline exists for either app (no `Jenkinsfile.HR`/`Jenkinsfile.Finance`). Out of
  scope for Phase 0; flagged rather than invented.

---

## 7. Bugs found while preparing this

The `hr.demo` recreation doubled as the first real non-super-admin browser pass either app has had.
Both were invisible to every prior pass because those ran as super admin, which bypasses the checks
involved.

1. **`/leave/approvals` was unreachable by any role** — gated on `can:approve_l1:leave_request`, a
   key the seed deliberately grants to no role, position, or position-type (zero rows in both
   `iam.position_permissions` and `iam.position_type_permissions`, system-wide). Fixed in the nav
   gate, route gate, badge hook, and the three backend routes to accept `approve_l1` **or**
   `approve_l2` — matching what `LeaveRequestsService.assertCanDecide` already assumed. Verified:
   403 → 200 for an L2-only persona.
2. **`GET /job-positions` 500'd for any non-super-admin** — `findPage` referenced
   `position.organization_id`, a column `hr.job_positions` has never had (it deliberately stores no
   copy of IAM's org/unit). Fixed by joining `iam.positions` the way the file's own
   `headcountTotals` already did correctly. Verified: 500 → 200.

HR-03 and HR-10 exist to pin these.

---

## Open items before Phase 1 writes specs

1. Land the `data-testid` pass (§4), one reviewable commit per app.
2. Decide the re-clone cadence for `smart_office_e2e` (§1.4).
3. **Separately, not an e2e concern**: `iam.organizations` holds rows named after applications
   ("EDR Freight", "EDR") rather than legal entities, alongside 10 Addis Ababa sub-cities from the
   Smart Office lineage. ~10 employees between them, all Debarred. A cleanup decision for whoever
   owns the tenant list — flagged, not acted on.