ite 32.6.5 — Journey Bonus Compensation - RodrigoMattosoSilveira/EnterpriseRemoteSystems GitHub Wiki

Bite 32.6.5 — Journey Bonus Compensation

Manual Promotion Test Suite

Promotion Candidate

Bite:   32.6.5 — Journey Bonus Compensation
Branch: 917-bite-3265-journey-bonus-compensation
SHA:    5b51c6880b108ba93e30d427881385afe3b7897c

The supplied HEAD ZIP was verified to contain the exact committed SHA above.

All LOCAL and CI tests pass. Perform the following targeted manual tests before promotion.

This suite is intentionally UI-driven. No SQL or direct API calls are required.

Scope Being Proven Manually

The manual suite verifies the customer-facing behavior that is hardest to establish from automated tests alone:

a Tenant Administrator can request a BRL bonus during an open Journey;
requesting the bonus does not credit the Current Account;
the requesting Tenant Administrator cannot approve their own bonus;
a different Tenant Administrator can approve it;
approval creates the Current Account credit;
the same Journey can receive additional bonuses after an earlier bonus was posted;
a later bonus can be denominated in grams of gold;
the Collaborator can see the resulting bonus evidence but cannot request or approve bonuses;
the workflow is usable in Brazilian Portuguese.

Shared Test Environment

Use the deterministic Brazilian demo dataset.

Important

The reset command deletes and recreates only:

backend/data/brazilian-demo.db

Do not point these commands at another database.

Reset and verify the demo database

From the repository root:

make brazilian-demo-local-reset
make brazilian-demo-local-verify

Start the application using the Brazilian demo database:

ERS_DATABASE_PATH=data/brazilian-demo.db make local-backend

In another terminal:

make local-frontend

Entity

Mineração Serra Dourada — DEMO

Tenant Administrator A — requester

Name:     Mariana Alves
Nickname: Mari Admin
Role:     Tenant Administrator
Login:    [email protected]
Password: Demo-31.4-Brasil!

Collaborator used for all bonus tests

Name:     Rafael Lima
Nickname: Rafa
Login:    [email protected]
Password: Demo-31.4-Person!

Rafael has one closed historical Journey and one current active Journey.

Use the current active Journey for every bonus-creation and bonus-approval test.

At the demo baseline Rafael's active BRL balance is R$ 0.00. Record the displayed BRL and gold balances before beginning Test 01.

One-Time Preparation — Create the Second Tenant Administrator Through the UI

The approval rule requires a different Tenant Administrator. The demo fixture contains only Mariana initially, so configure the existing synthetic Person Beatriz Nascimento (Bia) as Tenant Administrator B.

This setup is itself useful manual confirmation that the normal ERS identity and delegation paths support the approval workflow.

Part A — Enable authentication for Beatriz

Sign-In Identity

Mariana Alves
[email protected]
Demo-31.4-Brasil!

Context

Confirm the selected Entity is:

Mineração Serra Dourada — DEMO

Steps

Navigate to People.
Find and open:
```
Beatriz Nascimento
Nickname: Bia
```
Scroll to the Authentication section.
Confirm authentication is not yet enabled.
Record the displayed Account Login.

The deterministic demo value should be:
```
[email protected]
```
In Initial temporary password, enter:
```
Demo-32.6.5-Bia!
```
In Confirm temporary password, enter exactly the same value:
```
Demo-32.6.5-Bia!
```
Click the button that enables authentication.
Confirm the UI reports authentication enabled for Beatriz.

Part B — Grant Beatriz the second TENANT_ADMIN Role

While still signed in as Mariana, navigate to:
```
Administration
→ Authorization
```
In Filter actors by Actor Key or display name, enter:
```
Bia
```
Locate the Actor corresponding to Beatriz Nascimento.
Confirm the Actor is active and is eligible for Tenant Role Grants.
In that Actor card, open the Role selector.
Select:
```
TENANT_ADMIN
```
Confirm Grant tenant is:
```
demo-br-serra-dourada
```
Click:
```
Grant Role
```
Confirm the Actor card now lists an active:
```
TENANT_ADMIN
```
grant for demo-br-serra-dourada.

Part C — Complete Beatriz's first sign-in

Sign out from Mariana.

Login:    [email protected]
Password: Demo-32.6.5-Bia!

If ERS requires the temporary password to be changed, complete the password-change screen.
Use this permanent password for the remainder of the suite:
```
Demo-32.6.5-Bia-Ready!
```
After authentication completes, confirm the selected Entity is:
```
Mineração Serra Dourada — DEMO
```
Confirm Beatriz can access the normal Tenant Administrator workspaces, including Collaborators.
Sign out.

Preparation PASS Criteria

Preparation passes only if:

Beatriz can sign in through her own Authentication Account;
Beatriz has her own Tenant-scoped Actor;
Beatriz has an active TENANT_ADMIN Role Grant for the demo Entity;
Mariana remains the other active Tenant Administrator;
the two administrators are distinct Persons and distinct Actors.

If any of these conditions fail, stop the manual suite.

Test 01 — Mariana Requests a BRL Bonus and No Credit Is Posted Yet

Purpose

Verify that a bonus request is durable pending evidence and does not credit the Current Account until a different Tenant Administrator approves it.

Sign-In Identity

Mariana Alves
Role: Tenant Administrator A

Required Context

Entity:  Mineração Serra Dourada — DEMO
Person:  Rafael Lima / Rafa
Journey: current active Journey
Locale:  en-US

Steps

Sign in as Mariana.
Navigate to Collaborators.
Open Rafael Lima's current active Journey.
Open Rafael's Current Account in another tab or record the currently displayed balances.

Record:

BRL balance before request:
Gold balance before request:

Return to Rafael's Journey.
Locate the Journey Bonus section.
Confirm the help text explains that:
- multiple bonus awards are allowed;
- the bonus may be BRL or grams of gold;
- another Tenant Administrator must approve before Current Account credit.
In Value unit, select:
```
Brazilian Real (BRL)
```
In Bonus amount, enter:
```
500.00
```
In Bonus effective date, enter:
```
2026-09-18
```

In Bonus description, enter:

Retention bonus for critical maintenance coverage

Click:
```
Request Bonus Award
```
Wait for the request to appear in the Journey Bonus history.
Record its Bonus receipt number.

Confirm the request shows:

Amount:      R$ 500.00
Status:      Pending approval
Description: Retention bonus for critical maintenance coverage

Confirm the request displays the message:

A different Tenant Administrator must approve this bonus.

Confirm Mariana does not see an Approve Bonus button on her own pending award.
Open Rafael's Current Account.
Confirm the BRL balance is unchanged from step 5.
Confirm there is no posted JOURNEY_BONUS credit for the new receipt/award yet.
Navigate away and reopen Rafael's current Journey.
Confirm the pending award is still present.

Values to Record

BRL balance before request:
Gold balance before request:
BRL bonus receipt number:
Status after request:
BRL balance after request:

Expected Results

The request is preserved as Pending approval.
No financial credit is posted yet.
Mariana cannot approve her own request.
Navigation does not lose the pending award.

PASS Criteria

PASS only if all Expected Results are satisfied.

Promotion-Blocking Conditions

Block promotion if:

requesting the award immediately credits the Current Account;
Mariana can approve her own award;
the request disappears after navigation;
the amount/unit/description is not preserved correctly.

Test 02 — Beatriz Approves the BRL Bonus and the Credit Is Posted Exactly Once

Purpose

Verify that a different Tenant Administrator can approve the award and that approval creates the actual BRL Current Account credit.

Sign-In Identity

Beatriz Nascimento
Role: Tenant Administrator B
Login: [email protected]
Password: Demo-32.6.5-Bia-Ready!

If the first-sign-in flow did not require password replacement, use the password that remained valid after Preparation.

Prerequisite

Test 01 passed and the R$ 500.00 award remains pending.

Steps

Sign out from Mariana.
Sign in as Beatriz.
Confirm the selected Entity is Mineração Serra Dourada — DEMO.
Navigate to Collaborators.
Open Rafael Lima's current active Journey.
Locate the exact BRL bonus receipt recorded in Test 01.
Confirm it still shows:
```
Pending approval
```
Confirm Beatriz sees:
```
Approve Bonus
```
Click:
```
Approve Bonus
```
Wait for the award card to refresh.
Confirm status becomes:
```
Posted
```
Confirm an Approved at timestamp is displayed.
Confirm Approve Bonus is no longer available for that posted award.
Open Rafael's Current Account.
Confirm the BRL balance increased by exactly:
```
R$ 500.00
```
Locate the corresponding earning credit.
Confirm the credit is identifiable as Journey Bonus provenance / source.
Navigate away and reopen Rafael's Journey and Current Account.
Confirm:
- the award remains Posted;
- the credit remains present;
- the BRL balance has not increased a second time.

Values to Record

BRL bonus receipt:
Approved-at timestamp:
BRL balance before approval:
BRL balance after approval:
Displayed Current Account source/provenance:

Expected Results

Beatriz can approve Mariana's request.
Approval posts exactly one BRL earning credit.
The posted award becomes terminal evidence.
Reopening the page does not post the award again.

PASS Criteria

PASS only if the Current Account increases exactly once by R$ 500.00.

Promotion-Blocking Conditions

Block promotion if:

Beatriz cannot approve;
approval posts more than once;
the resulting credit has the wrong amount or value unit;
the award remains pending after the credit is posted;
a posted award can be approved again.

Test 03 — The Same Journey Receives a Second Bonus in Grams of Gold

Purpose

Verify the prospective client's central refined requirement:

A Collaborator may receive another bonus even after an earlier bonus has already been awarded, and the later bonus may be denominated in grams of gold.

Phase A — Mariana requests the second bonus

Sign out from Beatriz.
Sign in as Mariana.
Open Rafael's current active Journey.
Confirm the previously approved R$ 500.00 award remains visible as Posted.
Confirm the Journey Bonus request controls remain available even though Rafael has already received a bonus.
Select:
```
Value unit: Grams of gold
```
Enter:
```
Bonus amount: 1.25
```
Enter effective date:
```
2026-09-18
```
Enter description:
```
Safety milestone bonus
```
Click:
```
Request Bonus Award
```
Record the new bonus receipt number.

Confirm the new award shows:

1.25 g
Pending approval
Safety milestone bonus

Confirm the earlier BRL award remains separately visible as Posted.
Confirm Mariana does not see Approve Bonus for the new gold award.
Open Rafael's Current Account and confirm the gold balance has not yet increased.

Phase B — Beatriz approves the second bonus

Sign out from Mariana.
Sign in as Beatriz.
Open Rafael's current active Journey.
Locate the exact 1.25 g pending bonus receipt.
Click:
```
Approve Bonus
```
Confirm the award becomes:
```
Posted
```
Open Rafael's Current Account.
Confirm the gold balance increased by exactly:
```
1.25 g
```
Confirm the BRL balance from Test 02 remains unchanged.
Confirm both independent bonus awards remain visible in Journey Bonus history:
- one posted BRL award;
- one posted gold award.

PASS Criteria

PASS only if:

an already-bonused Journey accepts another bonus request;
the second bonus can use GOLD_GRAM;
the pending gold award does not affect the Current Account;
approval by the second administrator posts exactly 1.25 g;
the earlier BRL award remains intact.

Promotion-Blocking Conditions

Block promotion if:

the UI prevents a second award because one already exists;
requesting the second bonus overwrites the first;
gold is converted into BRL;
BRL and gold balances interfere with one another;
the second award can be self-approved.

Test 04 — Collaborator Self-Service Can Read Bonus Evidence but Cannot Manage It

Purpose

Verify that bonus evidence is visible to the affected Collaborator without granting bonus-administration authority.

Sign-In Identity

Rafael Lima
Role: intrinsic Person + current Collaborator self-service
Login: [email protected]
Password: Demo-31.4-Person!

Prerequisites

Tests 01–03 passed.

Steps

Sign out from Beatriz.
Sign in as Rafael.
Confirm the selected Entity is Mineração Serra Dourada — DEMO.
Navigate through Rafael's normal self-service UI to his current Journey.
Locate Journey Bonus.
Confirm both posted awards are visible:
- the R$ 500.00 retention bonus;
- the 1.25 g safety milestone bonus.
Confirm the receipt numbers and descriptions are readable.
Confirm Rafael does not see:
- Request Bonus Award;
- Approve Bonus;
- editable bonus amount;
- editable effective date;
- editable bonus description.
Open Rafael's Current Account.
Confirm the BRL bonus credit and gold bonus credit are visible in the financial record.
Confirm their source/provenance identifies them as Journey Bonus entries.

PASS Criteria

PASS only if Rafael can inspect his own bonus evidence and resulting credits but has no ability to request or approve a bonus.

Promotion-Blocking Conditions

Block promotion immediately if self-service exposes bonus mutation controls.

Test 05 — Brazilian Portuguese Bonus Workflow

Purpose

Verify the new workflow is fully usable in pt-BR.

Sign-In Identity

Sign out from Rafael and sign in as Mariana.

Context

Entity: Mineração Serra Dourada — DEMO
Locale: Português (Brasil)

Steps

Change the application language to:
```
Português (Brasil)
```
Open Rafael's current active Journey.
Locate:
```
Bônus da Jornada
```
Confirm the help text communicates that:
- multiple bonuses may be requested;
- BRL and grams of gold are supported;
- another Administrador da Entidade must approve before credit.

Confirm the request form contains Portuguese labels equivalent to:

Unidade de valor
Real brasileiro (BRL)
Gramas de ouro
Valor do bônus
Data efetiva do bônus
Descrição do bônus
Solicitar bônus

Confirm the two existing posted awards remain visible.
Confirm posted status is displayed as:
```
Lançado
```
Confirm no raw translation keys such as the following are visible:
```
bonus.*
financial.source.JOURNEY_BONUS
```
Confirm surrounding Tenant terminology uses:
```
Entidade
Administrador da Entidade
```
and not Locatário.
Switch back to English (United States).
Confirm the same bonus evidence remains present and unchanged.

PASS Criteria

PASS only if the complete visible Journey Bonus workflow is correctly localized and switching locale does not alter bonus state.

Promotion-Blocking Conditions

Block promotion if:

raw i18n keys appear;
the workflow mixes English action labels into the Portuguese surface;
Locatário reappears;
changing locale changes or loses financial evidence.

Test 06 — Distinct-Administrator Rule Remains Enforced Across Repeated Awards

Purpose

Perform one final UI-level control check that the four-eyes rule is associated with each individual award, not merely with the Journey.

Sign-In Identity

Steps

Open Rafael's current active Journey.

In Journey Bonus, create a new small BRL award:

Value unit: BRL
Amount: 25.00
Effective date: 2026-09-18
Description: Manual control verification

Click:
```
Request Bonus Award
```
Confirm the new award is Pending approval.
Confirm Beatriz, as the requester of this third award, does not see Approve Bonus on that award.
Confirm the two earlier awards requested by Mariana remain Posted.
Sign out from Beatriz.
Sign in as Mariana.
Open Rafael's current Journey.
Locate the R$ 25.00 Manual control verification award.
Confirm Mariana sees Approve Bonus for it.
You may approve it to complete the lifecycle.
If approved, confirm it becomes Posted and creates exactly one additional R$ 25.00 Current Account credit.

PASS Criteria

PASS only if the required second administrator is evaluated separately for every award.

Promotion-Blocking Conditions

Block promotion if an administrator can approve an award they personally requested merely because another award on the Journey was approved previously.

Final Promotion Checklist

Promote Bite 32.6.5 only when every applicable box is checked:

[ ] Preparation PASS — Beatriz is the distinct second Tenant Administrator
[ ] Test 01 PASS — BRL request stays pending and does not credit Current Account
[ ] Test 02 PASS — second administrator approves BRL bonus exactly once
[ ] Test 03 PASS — additional GOLD_GRAM bonus works after previous bonus
[ ] Test 04 PASS — Collaborator has read-only bonus evidence
[ ] Test 05 PASS — pt-BR workflow is complete and correct
[ ] Test 06 PASS — four-eyes rule is enforced independently per award

Immediate promotion blockers:

- requesting administrator can approve their own award
- pending award credits the Current Account
- one prior bonus prevents another award
- BRL and GOLD_GRAM are not independently preserved
- approval creates more than one credit
- posted award can be approved again
- Collaborator self-service can request or approve bonuses
- bonus evidence disappears after navigation or locale change

Glossary Impact

For Bite 32.6.5, the architecture glossary should contain the refined definition below in:

docs/02-Architecture/29. Authorization.md

under:

### 4.6.2 Journey Bonus Award

Expected definition:

### 4.6.2 Journey Bonus Award

A **Journey Bonus Award** is independent discretionary compensation that a Tenant Administrator may request at any time while a Collaborator Journey is open. A Journey may have 0..N Bonus Awards. Each award specifies exactly one value unit (`BRL` or `GOLD_GRAM`), a positive amount, an effective date on or after the Journey start date, optional descriptive evidence, and the requesting Tenant Administrator. A new award begins in `PENDING_APPROVAL` and does not affect the Collaborator's Current Account. A different Tenant Administrator must approve the award. Approval atomically changes the award to `POSTED` and creates exactly one `EARNING_CREDIT` in the Person-owned Current Account with `JOURNEY_BONUS` provenance. The requesting Tenant Administrator cannot approve the same award. Posted awards are immutable evidence, multiple posted awards may coexist for one Journey, and a Journey cannot close while a Bonus Award remains pending approval.