fuj-management/docs/by-gemini/scripts.md

Support Scripts Reference

The project includes several CLI utilities located in the scripts/ directory. Most are accessible via make targets.

🚀 Primary Scripts

sync_fio_to_sheets.py

Target: make sync | make sync-2026

• Purpose: Downloads transactions from Fio bank via API and appends new ones to the Google Sheet.
• Key Logic: Uses a Sync ID (SHA-256 hash of transaction details) to ensure that even if the sync is run multiple times, no duplicate rows are created.
• Arguments:
  • --days: How many days back to look (default 30).
  • --from/--to: Specific date range.
  • --sort-by-date: Re-sorts the spreadsheet after appending.

infer_payments.py

Target: make infer

• Purpose: Processes the "Transactions" sheet to fill in Person, Purpose, and Inferred Amount.
• Logic:
  • Analyzes the Sender and Message fields.
  • Uses match_payments.py heuristics to find members.
  • If confidence is low, prefixes the name with [?] to flag it for manual review.
  • Won't overwrite cells that already have data (respecting your manual fixes).

match_payments.py

Target: make match | make reconcile

• Purpose: The core "Reconciliation Engine".
• Logic:
  • Fetches attendance fees (from attendance.py).
  • Fetches transaction data.
  • Correlates them based on inferred Person and Purpose.
  • Handles "rollover" balances—extra money from one month is tracked as a credit for the next.

---

🛠 Utility Modules

attendance.py

• Handles the connection to the Google Attendance sheet (exported as CSV).
• Implements the club's fee rules:
  • 0 practices = 0 CZK
  • 1 practice = 200 CZK
  • 2+ practices = 750 CZK
• Note: Fee calculation only applies to members in Tier "A" (Adults).

czech_utils.py

• Normalization: Strips diacritics and lowercases text (e.g., František -> frantisek).
• Month Parsing: Advanced regex to detect month references in Czech (e.g., "leden-brezen", "11+12/25", "na únor").

fio_utils.py

• Low-level wrapper for the Fio Bank API.
• Handles HTTP requests and JSON parsing for transaction lists.

---

⚙️ Makefile Summary

Command	Action
make fees	Preview calculated fees based on attendance.
make sync	Sync last 30 days of bank data.
make infer	Run smart tagging on the sheet.
make reconcile	Run a text-based reconciliation report in terminal.
make web	Start the Flask dashboard.
make test	Run the test suite.