fuj-management/docs/plans/2026-10-08-1216-scheduled-bank-sync.md

Scheduled bank sync in the Go server (Go only)

Context

Bank synchronization only runs when someone opens /sync-bank; the payments sheet is as fresh as the last click. The Go server should run the same sync → infer → flush-cache sequence by itself on a configured schedule, defaulting to once a day.

Decisions already made:

• Go only. Deliberately not implemented in the legacy Python app, which is being phased out (gunicorn's multi-worker model would also need a cross-process lock). This is recorded as an explicit exception to the dual implementation rule.
• Schedule format: one or more times of day. On by default, once a day.

Behaviour

• SYNC_SCHEDULE — comma-separated HH:MM times, default 04:00. off disables the scheduler. An invalid value makes fuj server exit at startup with a clear error.
• SYNC_TZ — IANA zone the times are read in, default Europe/Prague. The binary embeds the zone database (import _ "time/tzdata"), because the Alpine image has none.
• At each scheduled time the server runs exactly what /sync-bank runs (banksync.DefaultWindow, SyncToSheets, InferPayments, cache flush), with a 10-minute timeout, and logs start, result and row counts via slog.
• Nothing runs at startup; a restart only recomputes the next run time.
• A scheduled run and a manual /sync-bank can no longer overlap: both go through one mutex. If a sync is already running, the manual page shows "a sync is already running" and a scheduled run is skipped with a log line. (This also closes today's gap where two overlapping manual runs could append the same rows.)
• The footer of every page shows the last sync since the server started: time, trigger (scheduled / manual), ok or failed, and the next scheduled run. Status is in memory only and resets on restart.

Implementation

Branch feat/scheduled-bank-sync off main; MR via tea.

1. Config — go/internal/config/config.go

   • Add SyncSchedule []TimeOfDay and SyncLocation *time.Location to Config.
   • Add ParseSyncSchedule(s string) ([]TimeOfDay, error) ("off" → empty, sorted, de-duplicated, rejects anything not HH:MM) and a LoadSyncSchedule() (…, error) reading SYNC_SCHEDULE / SYNC_TZ. Load() keeps its signature; serverCmd calls the new loader and exits on error.
   • New config_test.go for the parser (first tests in this package).

2. Scheduler — new package go/internal/scheduler

   • Next(now time.Time, times []TimeOfDay, loc *time.Location) time.Time — pure; builds candidates with time.Date in loc for today and tomorrow and returns the earliest one strictly after now (handles DST days).
   • Run(ctx, times, loc, logger, job func(context.Context)) — loop: compute Next, wait on a timer or ctx.Done(), call job.
   • Tests: Next table test (before/after today's time, multiple times, midnight rollover, the two DST switch days in Europe/Prague); Run with a cancelled context returns.

3. Sync runner with lock and status — new go/internal/services/banksync/runner.go

   • Runner wraps the existing sync+infer function (moved out of the closure in go/cmd/fuj/main.go) with a sync.Mutex (TryLock) and records Status{Started, Finished, Trigger, Err}.
   • Run(ctx, trigger string, out io.Writer) error returns ErrBusy when a run is in progress. Last() (Status, bool) for display.
   • Tests with a fake job: status recorded, error recorded, second concurrent call gets ErrBusy.

4. Wiring — go/cmd/fuj/main.go

   • Add import _ "time/tzdata".
   • Build one Runner; ActionHandlers.BankSync calls runner.Run(ctx, "manual", out) (signature unchanged, so TestServeSync keeps working).
   • If the schedule is non-empty, start go scheduler.Run(...) whose job calls runner.Run(ctx, "scheduled", &buf) with a 10-minute timeout, then sources.FlushCache(), and logs the outcome. Log the schedule and next run at startup, or "scheduled sync disabled".

5. Display — go/internal/web

   • ActionHandlers gains optional SyncInfo func() string (last + next run as one line). PageData gains SyncInfo string; add a small h.page(active) helper in html_handler.go and use it where PageData{Active: …, Build: h.build} is built today.
   • templates/partials/footer.tmpl: append the line when non-empty.
   • templates/sync.tmpl: fix the description, which still says "current year" (stale since the window change).
   • Extend html_handler_test.go: footer shows the info when provided, nothing extra when not.

6. Docs and notes

   • CLAUDE.md: document SYNC_SCHEDULE / SYNC_TZ under the Go config list and the commands/architecture text; under "Dual implementation rule" add a "Deliberately Go-only" list with this feature and the reason.
   • legacy/app.py: one comment above sync_bank() stating that scheduled sync exists only in Go, on purpose.
   • CHANGELOG.md entry; copy this plan to docs/plans/2026-10-08-HHMM-scheduled-bank-sync.md.
   • Add a note to the cleanup task list: T18 (time zone) is addressed for the scheduler only; the "current month" logic still uses the process clock.

No new dependencies. No Dockerfile change. No change to parity fixtures or the JSON API.

Deployment notes (for the MR description)

• On by default at 04:00 Europe/Prague. Set SYNC_SCHEDULE=off to disable.
• A locally running make web-go with real credentials will also sync at that time.
• With more than one replica each pod would run its own schedule; the deployment must stay at one replica (or disable the schedule on extras).
• Without FIO_API_TOKEN_* the sync scrapes the transparent-account pages, as today.

Verification

1. make go-test-all and make go-lint equivalent (go vet, gofmt -l); make test to confirm Python is untouched.
2. Start fuj server with SYNC_SCHEDULE=off → log says disabled, footer shows no schedule.
3. Start with an invalid value (SYNC_SCHEDULE=25:00) → exits with an error.
4. Live check: start with SYNC_SCHEDULE set two minutes ahead and watch the log for the scheduled run and the footer for the status line. This performs one real sync against the payments sheet (currently one pending transaction would be appended) — the same thing a click on /sync-bank does.
5. While that run is in progress, or with a test job, confirm a second trigger reports "already running".
6. Build the Go image and confirm the schedule log line shows the Prague zone inside the container (proves the embedded zone data works).