aiolabs/payroll
9
0
Fork 0
Code Issues 6 Pull requests Projects Releases Packages Wiki Activity Actions

feat: schedule preview and off-cycle payouts

Browse source 
Two things an operator needs that the scheduler alone does not give them.

Preview draws a contract's calendar from loose terms — start date,
frequency, period count — with no employee or wallet required, because the
schedule is what an operator wants to sanity-check first and a mistyped
start date is cheapest to fix before anything is saved. The same shape is
available for a live contract, from its current position. Both return
`ends_on`: "12 monthly payments from 15 Jan" is far easier to verify
against "ends 15 Dec" than against a list of twelve dates.

pay-now settles the next period immediately and consumes it. Deliberately
one endpoint rather than two: "run it now, don't wait for the tick" and
"pay it early" are the same operation and differ only in whether today
happens to be the payday. It bypasses the back-dated skip — that guard
exists to stop a new contract firing surprise back-pay, and an operator
explicitly asking to pay is not a surprise — and it takes the same
per-contract lock as the scheduler, which is what that lock was added for.
The ledger row is returned even on failure, since a manual payout that did
not land is exactly when you want the reason.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018jy52j9GRZ6XKa1Zt21LLj
This commit is contained in:
Padreug 2026-08-31 13:51:20 +02:00
commit ee10b2e04d
6 changed files with 313 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

29
docs/operations.md
View file

@ -105,3 +105,32 @@ lock exists for the off-cycle paths that can land mid-tick.
This is per-process. Two LNbits processes sharing one database would not
be serialised by it — payroll assumes the single-writer deployment LNbits
itself assumes.
## Previewing a schedule
`POST /payroll/api/v1/schedule/preview` draws a calendar from loose terms
(`start_date`, `frequency`, `total_periods`) — no employee or wallet
required, because the schedule is usually the thing worth sanity-checking
first, and a mistyped start date is cheapest to fix before anything is
saved. `GET /payroll/api/v1/contracts/{id}/schedule` does the same for a
live contract, from its current position.
Both return `ends_on`, the contract's last payday. "12 monthly payments
from 15 Jan" is much easier to check against "ends 15 Dec" than against a
list of twelve dates.
## Paying off-cycle
`POST /payroll/api/v1/contracts/{id}/pay-now` settles the contract's next
period immediately, whatever the calendar says, and consumes it.
One endpoint covers both "run it now" (don't wait for the tick) and "pay it
early", because they are the same operation — they differ only in whether
today happens to be the payday. It bypasses the back-dated skip: that guard
exists to stop a *new* contract firing surprise back-pay, and an operator
explicitly asking to pay a period is not a surprise.
It is recorded in the ledger like any other payout, with the early payment
noted in `detail`, and the ledger row is returned even when the payout
failed — a manual payout that did not land is exactly when you want to know
why.