refactor: move Python implementation to legacy/, make Go primary

Go (go/) becomes the primary implementation. The original Python
version moves to legacy/ and is kept runnable; new features are still
built in both (see the Dual implementation rule in CLAUDE.md).

- git mv app.py, scripts/, templates/, tests/, pyproject.toml, uv.lock
  and build/ into legacy/
- Makefile: Python targets point at legacy/, venv in legacy/.venv,
  CREDENTIALS_PATH exported for the root .secret/ file
- CI and make image build the Python image with legacy/ as context;
  the Makefile is no longer copied into the image
- legacy/.dockerignore moved to the context root so it takes effect
- CLAUDE.md, docs/README.md, Go comments, fixture README, capture
  script and VS Code launch config updated to the new layout

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CLAUDE.md

@@ -4,28 +4,62 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Status
 
-Flask-based financial management system for FUJ (Frisbee Ultimate Jablonec). Handles attendance-based fee calculation, Fio bank transaction sync, payment reconciliation, and a web dashboard.
+Financial management system for FUJ (Frisbee Ultimate Jablonec). Handles attendance-based fee calculation, Fio bank transaction sync, payment reconciliation, and a web dashboard.
+
+- **Go is the primary implementation** (`go/`). It is the version that is built, deployed and developed first.
+- **Python is legacy** (`legacy/`). The project was originally developed in Python (Flask); that version is kept runnable and in sync, but is considered legacy from now on.
+
+## Dual implementation rule
+
+Until the Python version is retired, **every new feature and every behaviour change must be implemented in both Go and Python**:
+
+1. Implement and test in Go first (`go/`).
+2. Mirror the change in the legacy Python code (`legacy/`), including its tests.
+3. Keep the two in parity: shared constants (fee rates, merged months, bank accounts, sheet IDs) must match on both sides, and the JSON API contract (`/api/adults`, `/api/juniors`, `/api/payments`) must stay identical. The HTML frontends are allowed to diverge.
+4. If a pure function's behaviour changes, add or update seeds in `legacy/scripts/_fixture_seeds.py`, run `make capture-fixtures`, and make sure `make go-test-all` passes. With both servers running, `make parity` diffs the live JSON APIs.
+
+Go-only or Python-only changes are fine for things that exist on one side only (build, tooling, HTML/CSS/JS, refactors with no behaviour change).
 
 ## Key Constraints
 
 - **PII separation**: Member data (names, emails, payment info) must never be committed to git. Enforce config/data separation from day one.
-- **Configuration**: External service IDs, credentials, and tunable parameters are centralized in `scripts/config.py`. Domain-specific constants (fees, merged months) stay in their respective modules.
+- **Configuration**: External service IDs, credentials, and tunable parameters are centralized in `go/internal/config/config.go` (mirrored in `legacy/scripts/config.py`). Domain-specific constants (fees, merged months) stay in their respective modules.
 
 ## Development Setup
 
-This project uses `uv` for dependency management.
+Go (primary): a recent Go toolchain (see `go/go.mod`) and `golangci-lint`.
 
 ```bash
-uv venv && uv sync
-source .venv/bin/activate
+make go-build     # builds bin/fuj
 ```
 
-Set `PYTHONPATH=scripts:.` when running scripts directly (the Makefile does this automatically).
+Python (legacy) uses `uv`; the project file and virtualenv live in `legacy/`.
+
+```bash
+make venv         # uv sync --project legacy  →  legacy/.venv
+```
+
+The Makefile sets `PYTHONPATH` (`legacy/scripts:legacy`) and `CREDENTIALS_PATH` (`.secret/fuj-management-bot-credentials.json` at the repo root) for the Python targets. Set both yourself when running Python scripts directly.
 
 ## Commands
 
+Go (primary):
+
 ```bash
-make web          # Start dashboard at http://localhost:5001
+make web-go         # Build and start dashboard at http://localhost:8080
+make go-build       # Build bin/fuj
+make go-test        # Unit tests (go test -race ./...)
+make go-parity      # Parity tests against the captured Python fixtures
+make go-test-all    # Both of the above
+make go-lint        # golangci-lint
+make go-run ARGS="fees"        # Run a subcommand: server, fees, reconcile, sync, infer, version
+make go-sync-debug [DAYS=N]    # Dry-run bank sync with debug logs
+```
+
+Python (legacy):
+
+```bash
+make web-py       # Start dashboard at http://localhost:5001 (make web is an alias)
 make web-debug    # Same with FLASK_DEBUG=1
 make test         # Run all tests (unittest discover)
 make test-v       # Tests with verbose output
@@ -33,12 +67,20 @@ make fees         # Print fee report from attendance sheet
 make sync-2026    # Sync Fio bank transactions for 2026 to Google Sheets
 make infer        # Auto-fill Person/Purpose/Amount columns in payments sheet
 make reconcile    # Print balance report from Google Sheets data
-make image        # Build Docker image
+make image        # Build the legacy Python Docker image
+```
+
+Cross-implementation:
+
+```bash
+make capture-fixtures   # Regenerate go/tests/fixtures from the Python implementation
+make parity             # Diff /api/* between web-py (:5001) and web-go (:8080); both must be running
 ```
 
 Run a single test:
 ```bash
-PYTHONPATH=scripts:. python -m unittest tests.test_app.TestWebApp.test_adults_route
+cd go && go test ./internal/domain/reconcile -run TestName
+cd legacy && PYTHONPATH=scripts:. .venv/bin/python -m unittest tests.test_app.TestWebApp.test_adults_route
 ```
 
 ## Architecture
@@ -46,25 +88,45 @@ PYTHONPATH=scripts:. python -m unittest tests.test_app.TestWebApp.test_adults_ro
 ### Data flow
 
 ```
-Google Sheets (attendance) ──► attendance.py ──► reconcile() ──► Flask routes ──► templates/
-Google Sheets (payments)   ──► match_payments.py ──┘
-Fio Bank API               ──► sync_fio_to_sheets.py ──► Google Sheets (payments)
+Google Sheets (attendance) ──► attendance loader ──► reconcile ──► HTTP handlers ──► templates
+Google Sheets (payments)   ──► payments loader   ──┘
+Fio Bank API               ──► bank sync ──► Google Sheets (payments)
 ```
 
-### Key modules
+### Repository layout
 
-- `app.py` — Flask app; routes for `/adults`, `/juniors`, `/payments`, `/sync-bank`, `/qr`, `/flush-cache`
-- `scripts/attendance.py` — Fetches attendance CSV from Google Sheets, computes per-member per-month fees. Contains fee rate constants (`ADULT_FEE_DEFAULT`, `JUNIOR_FEE_DEFAULT`) and `ADULT_MERGED_MONTHS` / `JUNIOR_MERGED_MONTHS` dicts.
-- `scripts/match_payments.py` — `reconcile()` matches transactions to members/months. `fetch_sheet_data()` reads the payments sheet. `fetch_exceptions()` reads the `exceptions` tab.
-- `scripts/cache_utils.py` — Invalidation via Google Drive API `modifiedTime`; falls back to 5-minute TTL buckets when Drive API is unavailable. Cache files live in `tmp/`.
-- `scripts/sync_fio_to_sheets.py` — Pulls Fio bank transactions and appends them to the payments Google Sheet.
-- `scripts/infer_payments.py` — Fills in Person/Purpose/Inferred Amount columns using name-matching heuristics.
-- `scripts/config.py` — All external IDs, paths, and tunable TTLs. Override via env vars (`CREDENTIALS_PATH`, `BANK_ACCOUNT`, `CACHE_TTL_SECONDS`).
+- `go/` — primary implementation (single binary `fuj`, templates and static assets embedded).
+- `legacy/` — legacy Python implementation (`app.py`, `scripts/`, `templates/`, `tests/`, `pyproject.toml`, `build/Dockerfile`).
+- `docs/` — documentation; `docs/plans/` holds plans and task lists.
+- `.gitea/workflows/` — CI: image builds on tag push, gitops image-update PR.
+
+### Key modules — Go (primary)
+
+- `go/cmd/fuj` — CLI entry point; subcommands `server`, `fees`, `reconcile`, `sync`, `infer`, `version`.
+- `go/cmd/parity` — diffs the JSON API of the Go and Python servers.
+- `go/internal/config` — sheet IDs, bank accounts, env-driven settings (`CREDENTIALS_PATH`, `CACHE_DIR`, `CACHE_TTL_SECONDS`, `CACHE_API_CHECK_TTL_SECONDS`, `MONTHS_TO_SHOW`, `SERVER_ADDR`, `LOG_LEVEL`, `FIO_API_TOKEN_NEW` / `FIO_API_TOKEN_OLD`).
+- `go/internal/domain` — pure logic: `fees` (rates, `CalculateFee`, `CalculateJuniorFee`), `reconcile`, `matching` (name matching, inference), `czech` (normalize, month parsing), `money`, `synch` (sync IDs).
+- `go/internal/io` — external systems: `attendance` (CSV export), `sheets`, `drive`, `fio` (API + transparent-page scraper), `cache` (file cache). Each has a fake for tests.
+- `go/internal/services` — `membership` (loading, merged months, fee and reconcile reports) and `banksync` (Fio sync + inference).
+- `go/internal/web` — routes for `/adults`, `/juniors`, `/payments`, `/sync-bank`, `/flush-cache`, `/qr`, `/version`, `/api/*`; `templates/` and `static/` are embedded.
+- `go/tests` — parity tests and the scrubbed fixture corpus captured from Python.
+
+### Key modules — Python (legacy)
+
+- `legacy/app.py` — Flask app; routes for `/adults`, `/juniors`, `/payments`, `/sync-bank`, `/qr`, `/flush-cache`, `/api/*`
+- `legacy/scripts/attendance.py` — Fetches attendance CSV from Google Sheets, computes per-member per-month fees. Contains fee rate constants (`ADULT_FEE_DEFAULT`, `JUNIOR_FEE_DEFAULT`) and `ADULT_MERGED_MONTHS` / `JUNIOR_MERGED_MONTHS` dicts.
+- `legacy/scripts/match_payments.py` — `reconcile()` matches transactions to members/months. `fetch_sheet_data()` reads the payments sheet. `fetch_exceptions()` reads the `exceptions` tab.
+- `legacy/scripts/cache_utils.py` — Invalidation via Google Drive API `modifiedTime`; falls back to 5-minute TTL buckets when Drive API is unavailable. Cache files live in `legacy/tmp/`.
+- `legacy/scripts/sync_fio_to_sheets.py` — Pulls Fio bank transactions and appends them to the payments Google Sheet.
+- `legacy/scripts/infer_payments.py` — Fills in Person/Purpose/Inferred Amount columns using name-matching heuristics.
+- `legacy/scripts/views.py` — View models shared by the HTML routes and the JSON API.
+- `legacy/scripts/config.py` — All external IDs, paths, and tunable TTLs. Override via env vars (`CREDENTIALS_PATH`, `CACHE_TTL_SECONDS`, `MONTHS_TO_SHOW`).
+- `legacy/scripts/capture_fixtures.py`, `scrub_fixtures.py`, `_fixture_seeds.py` — produce the scrubbed parity fixtures for Go.
 
 ### Member tiers
 
 Tiers are set in column B of the attendance sheet:
-- `A` — Adult, pays fees (per-month rate from `ADULT_FEE_MONTHLY_RATE`, fallback 700 CZK for 2+ sessions; 200 CZK for exactly 1)
+- `A` — Adult, pays fees (per-month rate from `AdultFeeMonthlyRate` / `ADULT_FEE_MONTHLY_RATE`, fallback 700 CZK for 2+ sessions; 200 CZK for exactly 1)
 - `J` — Junior attending adult practices; their attendance is merged with the junior sheet
 - `X` — Excluded from junior fee calculation (coaches, etc.)
 
@@ -76,17 +138,17 @@ Tiers are set in column B of the attendance sheet:
 
 ### Merged months
 
-`ADULT_MERGED_MONTHS` / `JUNIOR_MERGED_MONTHS` in `attendance.py` map a source month to a target month (e.g., `"2025-12": "2026-01"` merges December into January billing). The target month accumulates attendance from both months.
+`AdultMergedMonths` / `JuniorMergedMonths` in `go/internal/services/membership/sources.go` (`ADULT_MERGED_MONTHS` / `JUNIOR_MERGED_MONTHS` in `legacy/scripts/attendance.py`) map a source month to a target month (e.g., `"2025-12": "2026-01"` merges December into January billing). The target month accumulates attendance from both months.
 
 ### Caching
 
-`get_cached_data()` in `app.py` checks the Drive API `modifiedTime` before each request and serves a JSON file from `tmp/` when the sheet hasn't changed. Cache is warmed up at startup (`warmup_cache()`). Flush via `/flush-cache` (POST) or `flush_cache()`.
+Both implementations check the Drive API `modifiedTime` and serve a cached JSON file when the sheet hasn't changed, falling back to 5-minute TTL buckets when the Drive API is unavailable. Go: `go/internal/io/cache`, files in `tmp/go/` (`CACHE_DIR`). Python: `get_cached_data()` in `legacy/app.py`, files in `legacy/tmp/`, warmed up at startup (`warmup_cache()`). Flush via `/flush-cache` (POST).
 
 ### Payments sheet columns
 
 `Date | Amount | manual fix | Person | Purpose | Inferred Amount | Sender | VS | Message | Bank ID | Sync ID`
 
-`Person` and `Purpose` are written by `infer_payments.py` and can be manually corrected. `manual fix` column presence disables re-inference for that row. Multiple people or months are comma-separated in Person/Purpose.
+`Person` and `Purpose` are written by the inference step (`fuj infer` / `infer_payments.py`) and can be manually corrected. `manual fix` column presence disables re-inference for that row. Multiple people or months are comma-separated in Person/Purpose.
 
 ### QR codes