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:

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-testids (§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.