Backend: Implement Yield Accrual Audit Ledger & Daily Balance Snapshot

[ONEONUORA]

📌 Target Component

backend/src/yield_calculator.rs

📝 Description

Daily accrued yield is computed dynamically on read without persisting daily historical snapshot records in PostgreSQL.

📋 Implementation Requirements

1. Create database table daily_yield_snapshots.
2. Run daily cron taking balance and yield snapshot for every active inheritance plan.

🎯 Testnet Goal

Accurate historical accounting ledger for testnet users.

[bilhokista]

I have opened #1210 for this issue.

The part I would most like reviewed is the unique constraint on (plan_id, snapshot_date). It is the ledger's integrity guarantee rather than a nicety: a daily worker runs twice more often than one might expect — a restart, a redeploy, or a second replica — and without it each of those silently doubles a plan's history. An audit ledger that double-counts is worse than none. Writes use ON CONFLICT ... DO NOTHING so the first observation of a day stands, and snapshot_all returns the rows actually inserted, which is how a re-run makes itself visible in the logs instead of looking identical to a first run. I chose DO NOTHING over DO UPDATE because first-write-wins is easier to reason about for an audit record, but say the word if you would rather the latest run win.

Two edge cases I handled explicitly. seconds_until_next_run never returns zero — landing exactly on the configured hour returns a full day, because a zero delay would spin the worker in a tight loop re-running the snapshot as fast as the database could answer. And elapsed_since_ping saturates, since last_ping can sit in the future after a clock correction and a plain subtraction cast to u64 would wrap into an enormous number and write an absurd figure into the ledger.

The snapshot also copies principal and yield_rate_bps as they stood on the day rather than referencing the live columns, so a later rate change cannot silently rewrite history.

On verification: I lifted both helpers and all 7 tests into a scratch crate with real chrono and ran cargo test — all pass, including a sweep across all 24 hours asserting the wait is always positive and at most a day. I could not run the crate's own tests, so snapshot_all itself — the SQL, the Decimal conversions and the rows_affected accounting — needs CI with a database.

One thing I want to flag rather than leave buried: principal goes through Decimal → String → f64 to reach the existing calculate_yield, which takes f64. For NUMERIC(78, 0) that is lossy at the extreme end. I kept it because widening calculate_yield's signature affects its other callers and felt like a separate decision, but if you would prefer the whole path in Decimal I am glad to do it here.

Finally, main.rs is also touched by my open PR #1209. This PR deliberately follows the current master pattern for starting workers so it stands alone; if #1209 lands first, this worker should return its JoinHandle too, which is a one-line follow-up I am happy to make.