# 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. |
```