User Manual - RodrigoMattosoSilveira/EnterpriseRemoteSystems GitHub Wiki

Enterprise Remote Systems — User Manual

1. Purpose of the System

Enterprise Remote Systems, or ERS, helps administrators manage people, collaborators, journeys, work periods, expenses, current accounts, receipts, payouts, and end-of-journey settlement workflows.

The system is designed for tenant-scoped operations. This means that each tenant manages its own people, collaborators, financial records, reference data, and settings.

ERS is especially strict around financial operations. Any operation that affects a collaborator’s current account must be traceable, auditable, and supported by receipts where required.

2. Main User Roles

ERS may be used by several types of users.

Application Administrator

The Application Administrator can manage system-wide or multi-tenant operations. This role is normally reserved for trusted technical or business administrators.

Typical responsibilities:

Configure tenants.
Help diagnose authorization or data issues.
Support go-live and production administration.
Perform high-level administrative actions when permitted.

Tenant Administrator

The Tenant Administrator manages one tenant’s business operations.

Typical responsibilities:

Manage people and collaborators.
Manage reference data.
Configure tenant-level settings.
Review sensitive financial controls.
Supervise end-of-journey processes.

Earnings Operator

The Earnings Operator manages work-period planning and earnings-related activity.

Typical responsibilities:

View collaborator records.
Plan work periods.
Enter or review earning data.
Support future/current earnings views.

Expenses Operator

The Expenses Operator manages expense preparation and current-account deductions.

Typical responsibilities:

View collaborators.
Prepare expenses.
Review current-account summaries.
Create required receipts.
Support PIX or payout-related workflows when authorized.

3. System Navigation Overview

The ERS user interface is organized around the main business areas:

People
Collaborators
Work Periods
Expenses
Current Accounts
Receipts
Reference Data
Administration / Settings

Illustration suggestion: Insert a screenshot of the main navigation menu with each major section labeled.

Part I — Onboarding Workflow

4. Onboarding Overview

Onboarding is the process of preparing a person to become an active collaborator in the system.

The normal onboarding flow is:

Create Person
→ Complete required profile fields
→ Confirm eligibility
→ Create Collaborator Journey
→ Assign or plan work periods
→ Begin expense/current-account activity

Illustration suggestion: Insert a simple flow diagram showing Person → Eligible Person → Collaborator Journey → Active Collaborator.

5. Creating a Person

A Person record stores personal and administrative information about an individual.

To create a Person:

Open the People section.
Select Create Person.
Enter the required personal information.
Save the record.
Confirm that the person appears in the People list.

Required profile fields usually include:

First name
Last name
Nickname
CPF
RG
Cellular
Email
Status

ERS validates Brazilian cellular numbers and identification fields. Duplicate checks are tenant-scoped, meaning the same CPF, RG, email, cellular number, or PIX key cannot be duplicated within the same tenant unless the system rules are changed later.

Illustration suggestion: Insert a screenshot of the Create Person form with the required fields highlighted.

6. Person Profile Completion

A person must have a complete and valid profile before they can become a collaborator.

The system tracks whether the person can be used to create a collaborator journey.

A person is not eligible if required information is missing, invalid, duplicated, or inactive.

To review profile completion:

Open People.
Select the person.
Review the profile details.
Correct any missing or invalid fields.
Save the updated profile.

Illustration suggestion: Insert a screenshot of the Person detail page showing profile completion or eligibility status.

7. Creating a Collaborator

A Collaborator represents a person who is participating in a journey.

To create a Collaborator:

Open the Collaborators section.
Select Create Collaborator.
Choose an eligible person from the eligible-person list.
Enter journey details, including the journey start date.
Confirm payment-related settings as required.
Save the collaborator journey.

The system prevents:

Creating a collaborator from an incomplete person.
Creating a duplicate active journey for the same person.
Using inactive reference data where active data is required.

Illustration suggestion: Insert a screenshot of the Create Collaborator screen, especially the eligible-person dropdown.

8. Journey Duration and Days Remaining

A collaborator journey is calculated using:

Journey end date = start date + 90 days + extension days

ERS displays a days-remaining indicator in collaborator-related screens.

Indicator rules:

More than 30 days remaining: green
8 through 30 days remaining: yellow
7 days or fewer remaining, including overdue journeys: red

The indicator helps administrators prioritize collaborators who are approaching the end of their journey.

Illustration suggestion: Insert a screenshot of the Collaborator list showing green, yellow, and red journey indicators.

Part II — Daily and Operational Workflows

9. Work Period Planning

ERS assumes that a collaborator works at most one work period per day.

Work-period planning supports earnings projections through the journey end date.

To plan a work period:

Open Work Periods.
Select the relevant date.
Choose the collaborator.
Confirm the planned assignment.
Save the work period or assignment.

When projecting future earnings, the system uses one remaining potential work period per remaining calendar day.

Illustration suggestion: Insert a calendar-style screenshot or diagram showing one collaborator assigned to one work period on a given day.

10. Expense Preparation

Expenses represent deductions or charges associated with a collaborator.

Typical expense categories include:

Canteen
Flight
Cargo
Other

PIX is not treated as a normal expense category. PIX is part of the collaborator current-account and remittance flow.

To prepare an expense:

Open Expenses.
Select Create Expense.
Choose the collaborator.
Choose the active expense category.
Enter the amount and currency/unit.
Save the expense.
Follow any receipt workflow required by the system.

Expenses may be represented in Brazilian Real or grams of gold, depending on the business rule and the collaborator’s current-account state.

Illustration suggestion: Insert a screenshot of the Create Expense screen showing collaborator, category, amount, and currency/unit fields.

11. Current Account Overview

The Collaborator Current Account shows the collaborator’s financial position.

It reflects:

Earnings
Expenses
PIX remittances
Payouts
Gold-to-BRL conversions where applicable
Corrections
Settlement activity

The current account should provide a clear picture of what the collaborator has earned, what has been deducted, and what remains payable or unsettled.

Illustration suggestion: Insert a screenshot of a collaborator current-account summary with key balances labeled.

12. PIX and BRL Remittance

PIX remittance applies to Brazilian Real.

If a collaborator has gold-gram credits and needs a PIX remittance, the gold amount must first be converted to BRL using the tenant’s recorded gold-to-BRL conversion rate.

Gold-to-BRL conversion is separate from PIX remittance.

Normal flow:

Gold credit exists
→ Tenant records or confirms gold-to-BRL conversion rate
→ Gold amount is converted to BRL
→ PIX remittance uses BRL amount
→ Current account is updated
→ Receipt/audit rules apply

Illustration suggestion: Insert a diagram showing Gold Balance → Conversion Rate → BRL Balance → PIX Remittance.

13. Receipts

ERS has a key business rule:

Every debit from a collaborator current account must generate a receipt signed and returned.

Receipts protect both the collaborator and the tenant by documenting deductions, payouts, corrections, and settlements.

Common receipt statuses include:

Issued
Printed
Signed
Returned
Cancelled

The system enforces required metadata for receipt statuses. For example, returned receipts require signed and returned information, including a signed document reference.

A receipt that is returned or cancelled is terminal and cannot be returned again.

Illustration suggestion: Insert a receipt lifecycle diagram: Issued → Printed → Signed → Returned, with Cancelled as a terminal branch.

Part III — Sensitive Financial Workflows

14. Sensitive Operations

Some operations are considered sensitive because they affect financial records or audit-critical history.

Examples include:

Ledger reversal
Ledger replacement
Manual correction
Journey settlement adjustment
Receipt backfill or status override
Gold zeroing correction
Payout correction
Journey close settlement

Sensitive operations require stronger controls.

Depending on tenant policy and operation type, the system may require:

Actor authorization
Correction reason code
Correction reason text
Recent reauthentication
Second-person approval
Audit metadata
Receipt compliance

Illustration suggestion: Insert a checklist graphic showing the controls required before a sensitive operation can proceed.

15. Correction Reasons

Sensitive correction operations require a structured reason.

A correction reason includes:

Reason code
Reason text

Example:

{
  "reasonCode": "DUPLICATE_POSTING",
  "reasonText": "Correcting duplicate expense posting after review."
}

The system rejects missing or blank correction reasons.

Correction reasons are stored with the correction, ledger metadata, and audit metadata where applicable.

Illustration suggestion: Insert a screenshot of a sensitive correction form with reason code and reason text highlighted.

16. Recent Reauthentication

Sensitive operations require recent reauthentication.

This means the actor must have recently confirmed their identity before performing the operation.

In the current transitional implementation, the backend receives reauthentication metadata through request headers. In the final production model, this should be integrated with the real authentication/session provider.

If recent reauthentication is missing, invalid, or stale, the system rejects the sensitive operation.

Typical user-facing behavior should be:

User starts sensitive operation
→ System asks user to reauthenticate
→ User confirms identity
→ System allows operation to continue

Illustration suggestion: Insert a mockup of a reauthentication modal or confirmation screen.

17. Second-Person Approval

ERS supports optional and configurable second-person approval.

When enabled for the tenant, sensitive operations require approval by a second person.

The second approver must not be the same person as the primary actor.

Example approval metadata:

{
  "secondApproval": {
    "approvedBy": "[email protected]",
    "notes": "Reviewed supporting documents and approved correction."
  }
}

When the tenant setting requires second-person approval:

Missing approval is rejected.
Blank approver is rejected.
Same approver as primary actor is rejected.
A valid different approver is accepted and audited.

Illustration suggestion: Insert a screenshot of the second-person approval section on a sensitive operation form.

18. Audit Trail

ERS records sensitive authorization and financial decisions in audit logs.

Audit logs capture information such as:

Tenant
Actor
Operation
Resource
Decision
Reason metadata
Reauthentication metadata
Second approval metadata
Timestamp

Audit records are immutable. They are append-only and cannot be normally updated or deleted.

The audit trail helps support:

Operational review
Internal controls
Compliance
Debugging
Production incident investigation

Illustration suggestion: Insert a screenshot or mockup of a future Audit Log Viewer showing event type, actor, resource, and timestamp.

Part IV — End-of-Journey Workflow

19. End-of-Journey Overview

At the end of a collaborator journey, the tenant must review and settle the collaborator’s account.

The end-of-journey process should ensure that:

All work periods are accounted for.
All earnings are recorded.
All expenses are recorded.
PIX remittances are reflected.
Gold balances are resolved.
Receipts are complete.
Corrections have reasons and approvals where required.
Final settlement is recorded and audited.

Illustration suggestion: Insert a flow diagram: Journey Near End → Review Account → Resolve Balances → Generate Receipts → Close Journey.

20. Reviewing the Collaborator Before Closing

Before closing a journey:

Open the collaborator record.
Review the journey start date, end date, and extension days.
Review days remaining or overdue status.
Open the current account.
Review all earnings, expenses, remittances, corrections, and receipts.
Confirm whether any pending receipt or unresolved balance remains.

Do not close a journey if required receipts or account records are incomplete.

Illustration suggestion: Insert a checklist screenshot or annotated collaborator detail page showing journey status and current-account access.

21. Gold Balance Resolution

If a collaborator has a gold balance, the tenant must decide how to resolve it according to business policy.

Possible flows include:

Keep the gold balance recorded.
Convert gold to BRL.
Pay out the converted BRL.
Zero gold balance as part of a correction or settlement.

Gold zeroing and payout corrections are sensitive operations. They require correction reasons, recent reauthentication, audit logging, and second-person approval if configured.

Illustration suggestion: Insert a diagram showing remaining gold balance and possible resolution paths.

22. Final Settlement

Final settlement closes the financial journey state for the collaborator.

Before final settlement:

Confirm all debits have receipts.
Confirm all required returned receipts are complete.
Confirm no duplicate or unresolved corrections remain.
Confirm all sensitive operations have audit metadata.
Confirm second-person approval requirements have been satisfied if enabled.

After settlement, the journey should be treated as closed for normal operational purposes.

Illustration suggestion: Insert a settlement confirmation screen showing final balances and required acknowledgements.

Part V — Reference Data Handling

23. Reference Data Overview

Reference data contains controlled lists used throughout ERS.

Examples include:

Person statuses
Payment methods
Expense categories
Other tenant-specific operational categories

Reference data helps keep the system consistent. Users should select from reference data instead of typing arbitrary values.

Illustration suggestion: Insert a screenshot of the Reference Data administration page with grouped categories.

24. Managing Reference Data

To manage reference data:

Open Admin or Reference Data.
Select the reference data type.
Review existing active and inactive values.
Create a new value if needed.
Edit an existing value if allowed.
Deactivate values that should no longer be used.
Reactivate values if needed.

Reference data is tenant-scoped.

The system prevents duplicate active names for the same type within the same tenant.

Illustration suggestion: Insert a screenshot showing create, edit, deactivate, and reactivate controls.

25. Active and Inactive Reference Data

ERS distinguishes between active and inactive reference data.

Active values may be used in new business records.

Inactive values are preserved for historical records but should not normally be used in new operations.

For example:

An old payment method may remain visible in past records.
A deactivated expense category should not be selectable for a new expense.

This protects historical accuracy while preventing future use of outdated values.

Illustration suggestion: Insert a screenshot showing active and inactive reference data rows with visual labels.

26. Expense Categories

Expense categories are reference data.

Initial categories include:

Canteen
Flight
Cargo
Other

PIX should not be configured as a normal expense category. PIX is a current-account remittance workflow, not a standard expense.

Illustration suggestion: Insert a reference data screenshot showing expense categories and a note that PIX is excluded.

27. Payment Methods

Payment methods are also reference data.

Only active payment methods should be used when creating collaborator journeys or financial operations.

If a payment method is no longer valid, deactivate it instead of deleting it. This preserves historical records.

Part VI — Administrative Settings

28. Second-Person Approval Policy

Tenant administrators can configure whether sensitive operations require second-person approval.

When disabled:

Sensitive operation may proceed without second approval if all other requirements are met.

When enabled:

Sensitive operation must include approval by a different person.

This setting should be enabled when the tenant wants stricter dual-control procedures for corrections, payouts, settlements, or receipt overrides.

Illustration suggestion: Insert a screenshot of the second-person approval settings page, including the enable/disable control and explanatory warning.

29. Authorization Helper During Development

ERS currently includes an authorization helper in the UI, sometimes referred to as the Authz button.

This is a development/testing aid. It helps simulate an authorized actor while ERS is still transitioning to a full authentication and session model.

The Authz helper may set values such as:

Actor
Tenant
Permissions

This is not the final production security model.

In production, the backend should derive actor identity and permissions from a trusted authentication provider or session mechanism.

Illustration suggestion: Insert a screenshot of the Authz helper, with a warning label: “Development authorization helper — not final production login.”

Part VII — Common User Scenarios

30. Scenario: Onboard a New Collaborator

Create a Person.
Complete all required profile fields.
Confirm that the person is eligible.
Create a Collaborator journey from the eligible person.
Confirm journey start date.
Review days remaining.
Begin normal work-period and financial workflows.

Expected result:

The collaborator appears as active and can be used in work periods, expenses, current-account workflows, and journey tracking.

31. Scenario: Prepare an Expense

Open Expenses.
Select Create Expense.
Choose an active collaborator.
Choose an active expense category.
Enter amount and unit/currency.
Save.
Follow receipt workflow if the expense debits the collaborator current account.

Expected result:

The expense is recorded, the current account is updated where applicable, and the required receipt workflow is triggered or available.

32. Scenario: Correct a Ledger Entry

Open the relevant current account or ledger view.
Choose the correction operation.
Enter reason code.
Enter reason text.
Reauthenticate if prompted.
Add second-person approval if required.
Confirm the correction.
Verify audit and receipt outcomes.

Expected result:

The correction is recorded with reason metadata, authorization metadata, and audit history.

33. Scenario: Close a Collaborator Journey

Open the collaborator detail page.
Review journey status and days remaining.
Open current account.
Confirm all earnings, expenses, remittances, and corrections.
Resolve remaining BRL or gold balances.
Confirm receipt completeness.
Perform final settlement.
Close the journey.

Expected result:

The journey is closed with complete financial and audit records.

34. Scenario: Update Reference Data

Open Reference Data.
Select the type of reference data.
Add, update, deactivate, or reactivate values.
Confirm the change appears correctly.
Verify inactive values are not available for new records.

Expected result:

Reference data is updated for future use while historical records remain preserved.

Part VIII — Best Practices

35. Operational Best Practices

Users should follow these practices:

Keep person profiles complete and accurate.
Do not create duplicate people.
Review collaborator journey dates regularly.
Use reference data instead of free-text workarounds.
Do not use PIX as an expense category.
Review current accounts before payouts or settlements.
Never perform sensitive corrections without a clear business reason.
Ensure receipts are signed and returned.
Use second-person approval for high-risk operations.
Review audit history during disputes or production incidents.

36. Sensitive Operation Checklist

Before confirming a sensitive operation, verify:

[ ] Correct collaborator selected
[ ] Correct tenant context
[ ] Current account reviewed
[ ] Supporting documents reviewed
[ ] Reason code provided
[ ] Reason text provided
[ ] Recent reauthentication completed
[ ] Second-person approval included if required
[ ] Receipt requirements understood
[ ] Final result reviewed after save

Illustration suggestion: Insert this checklist as a visual callout box in the manual.

37. End-of-Journey Checklist

Before closing a journey, verify:

[ ] Journey dates reviewed
[ ] Extension days reviewed
[ ] Work periods reviewed
[ ] Earnings reviewed
[ ] Expenses reviewed
[ ] PIX remittances reviewed
[ ] Gold balance reviewed
[ ] BRL balance reviewed
[ ] Corrections reviewed
[ ] Receipts issued where required
[ ] Receipts returned where required
[ ] Final settlement reviewed
[ ] Audit trail complete

Illustration suggestion: Insert this checklist near the journey close screen or settlement section.

Part IX — Troubleshooting

38. Common Messages

Authorization actor is required

The backend requires an actor for the operation.

What to do:

Confirm the user is logged in or the development Authz helper is configured.
Confirm the request includes an actor.
Contact an administrator if the problem continues.

Forbidden

The actor is known but does not have permission.

What to do:

Confirm the actor has the correct role or permissions.
Confirm the tenant context is correct.
Contact a Tenant Administrator or Application Administrator.

Recent reauthentication required

The operation is sensitive and requires recent identity confirmation.

What to do:

Reauthenticate.
Retry the operation shortly after reauthentication.

Correction reason required

The operation requires a reason code and reason text.

What to do:

Provide a structured reason code.
Provide a clear explanation in the reason text.

Second-person approval required

The tenant requires dual approval for the operation.

What to do:

Ask a different authorized person to approve.
Enter the second approver and notes.
Retry the operation.

Receipt metadata incomplete

The receipt status requires additional information.

What to do:

Confirm the signed document reference.
Confirm signed date and returned date.
Confirm received-by information.
Save again.

Part X — Illustration Checklist for Documentation Team

Recommended illustrations to add:

[ ] Main navigation screenshot
[ ] Onboarding flow diagram
[ ] Create Person form screenshot
[ ] Person eligibility/detail screenshot
[ ] Create Collaborator screenshot
[ ] Journey days remaining screenshot
[ ] Work Period calendar screenshot
[ ] Create Expense screenshot
[ ] Current Account summary screenshot
[ ] Gold-to-BRL-to-PIX diagram
[ ] Receipt lifecycle diagram
[ ] Sensitive operation checklist graphic
[ ] Correction reason form screenshot
[ ] Reauthentication modal mockup
[ ] Second-person approval form screenshot
[ ] Audit log viewer mockup
[ ] End-of-journey flow diagram
[ ] Reference Data administration screenshot
[ ] Second-person approval settings screenshot
[ ] Authz development helper screenshot

Appendix A — Glossary

Actor

The user or system identity performing an operation.

Collaborator

A person participating in a work journey.

Current Account

The financial ledger-like view of a collaborator’s earnings, expenses, remittances, corrections, and settlements.

Journey

The collaborator’s active work period in the system, normally calculated as start date plus 90 days plus extension days.

Reference Data

Controlled tenant-specific lists such as statuses, expense categories, and payment methods.

Receipt

A document associated with a current-account debit or other financial operation requiring acknowledgement.

Second-Person Approval

Approval by a different authorized person for a sensitive operation.

Tenant

A separate business context within ERS. Tenant data is scoped and isolated.

Appendix B — Production Notes

ERS currently includes transitional authorization helpers and headers for development and testing.

For production use, the system should move toward a full authentication and session model where the backend derives actor identity and permissions from trusted login/session data.

Regardless of authentication implementation, the backend must continue enforcing:

actor required
tenant scope required
permission required
correction reason required for sensitive corrections
recent reauthentication required for sensitive operations
second-person approval when configured
receipt lifecycle rules
immutable audit logging

The guiding rule is:

The frontend may guide the user, but the backend must enforce the rule.