Payroll Calculation and Lifecycle Operations
Summary
This page records confirmed payroll calculation and lifecycle operations behavior and marks incomplete boundaries explicitly.
Audience
Payroll users, developers, QA and support engineers, architects, and implementation reviewers.
Pre-operation checks
Confirm tenant, period, workforce projection, required Attendance projection, optional Leave/Expense inputs, advance balances, and current run state using approved interfaces.
| Check | Proceed when | Stop condition |
|---|---|---|
| Route family | Native or compatibility ownership is known | Ownership is ambiguous during a transition |
| Tenant and period | Both match the intended processing scope | Missing tenant, invalid month/year, or future-period restriction |
| Workforce | Eligible Payroll profiles are present | No eligible workforce or incomplete required profile data |
| Attendance | A current snapshot exists for each native calculation target | Required snapshot is missing or stale |
| Leave and expense | Available snapshots are understood as optional inputs | Operators are assuming missing optional input is zero without evidence |
| Lifecycle | Run is eligible for the requested operation | Frozen calculation, invalid freeze state, or non-Frozen unfreeze |
| Advance recovery | Balance and prior recovery/reversal evidence agree | Duplicate unreversed recovery or insufficient balance |
Calculation
Native calculation writes run/detail/calculation, evidence, and outbox intent together. Compatibility save/freeze uses its own contract and status behavior.
After a native calculation, verify the tenant/period run is Calculated, expected employee details exist, and audit/outbox intent was created in the same persistence boundary. After a compatibility save, validate the compatibility read model instead; do not infer a native aggregate merely from a successful browser save.
Freeze and unfreeze
Freeze requires an eligible run with details and validates recoveries. Unfreeze requires Frozen state and creates recovery reversals where needed. Both native operations save lifecycle evidence and event intent.
Native unfreeze moves the run to Unfrozen; compatibility unfreeze returns the run/details to Draft. Record the route family with support evidence so the resulting status is not misclassified. Freeze remains reversible and must never be used as evidence of payment, accounting posting, workflow approval, or irreversible finalization.
Safe response
On failure, do not edit persistence manually. Preserve correlation/time/tenant/run context without sensitive values, classify validation versus dependency failure, and escalate with source-backed evidence.
Retry only when the prior transaction outcome is known. If the client timed out after submission, read the current run, detail, audit, and outbox state before resubmitting. When partial advance recovery is reported, reconcile the supported recovery/reversal evidence through application reads and escalate; do not compensate with a direct balance change.
Source References
microservices/src/payroll-service/Application/PayrollCalculationService.csmicroservices/src/payroll-service/Application/PayrollCompatService.csmicroservices/src/payroll-service/Infrastructure/PayrollDbContext.cs
Related Articles
See Also
Keywords
- Payroll operations
- Payroll Calculation and Lifecycle Operations
Revision Information
- Status: Draft
- Last reviewed: 2026-07-15
- Review cycle: Quarterly