Skip to main content

Advance and Recovery Storage

Summary​

Persistence of advance balances, recovery transactions, and reversal references.

Audience​

Payroll developers, QA and support engineers, solution and security architects, and implementation partners.

Reference Content​

The sections below describe the confirmed logical storage contract and its implementation boundaries.

Purpose​

Describe AdvanceSummary and AdvanceTransaction persistence used by Payroll recovery processing.

Ownership​

Payroll Service owns the local summary and transaction records.

Lifecycle​

Compatibility operations and backfill create/update summaries and transactions. Native freeze can record recovery transactions; unfreeze can record compensating transactions linked by a reversal identifier.

Persisted fields​

Summaries contain tenant/employee identity, aggregate and remaining amounts, planned deduction, and update time. Transactions contain tenant/employee identity, optional run and reversal references, amount, type, transaction date, note, and creation time.

Relationships​

Run, employee, and reversal identifiers are logical only. No self-referencing or run foreign key is configured.

Constraints​

One summary per tenant/legacy employee is enforced. Transaction uniqueness is not database enforced.

Indexes​

Summary identity is unique. Transactions have tenant/employee/date and tenant/run/type search indexes.

Tenant behavior​

Both objects have global filters. Service and backfill code use explicit tenant conditions when bypassing them.

Audit behavior​

Native lifecycle and compatibility operations have differing audit coverage. Backfill completion is audited separately.

Integration usage​

Recovery changes staged during native freeze/unfreeze participate in the same context save as run lifecycle, audit, timeline, and outbox intent.

Known limitations​

No foreign key guarantees reversal or run references. Summary/transaction reconciliation is application-owned.

Requires confirmation​

  • Formal correction and reconciliation policy.
  • Whether database uniqueness is required for recovery transactions and reversals.

Source References​

  • microservices/src/payroll-service/Infrastructure/PayrollDbContext.cs
  • microservices/src/payroll-service/Domain/PayrollEntities.cs
  • microservices/src/payroll-service/Infrastructure/Migrations/PayrollDbContextModelSnapshot.cs
  • microservices/src/payroll-service/Application/PayrollCalculationService.cs
  • microservices/src/payroll-service/Application/PayrollCompatService.cs
  • microservices/src/payroll-service/Backfill/AdvanceBackfill.cs

See Also​

Keywords​

  • Payroll database
  • Advance and Recovery Storage
  • Payroll persistence

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-15
  • Review cycle: Quarterly