67 lines
2.5 KiB
Markdown
67 lines
2.5 KiB
Markdown
# 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. |
|
|
```
|