257 lines
9.7 KiB
Markdown
257 lines
9.7 KiB
Markdown
# Web Application Documentation
|
||
|
||
## Overview
|
||
|
||
The FUJ Management web application is a Flask-based dashboard that provides real-time visibility into club finances. It renders server-side HTML with embedded CSS and JavaScript — no build tools, no npm, no framework. The UI follows a distinctive **terminal-inspired aesthetic** with monospace fonts, green-on-black colors, and dashed borders.
|
||
|
||
## Routes
|
||
|
||
### `GET /` — Index (Redirect)
|
||
|
||
Redirects to `/fees` via an HTML meta refresh tag. This exists so the root URL always leads somewhere useful.
|
||
|
||
### `GET /fees` — Attendance & Fees Dashboard
|
||
|
||
**Template**: `templates/fees.html`
|
||
|
||
Displays a table of all adult members with their calculated monthly fees based on attendance. Each cell shows the fee amount (in CZK), the number of practices attended, or a dash for months with zero attendance.
|
||
|
||
**Data pipeline**:
|
||
```
|
||
attendance.py::get_members_with_fees() → Filter to tier "A" (adults)
|
||
match_payments.py::fetch_exceptions() → Check for fee overrides
|
||
→ Format cells with override indicators
|
||
→ Render fees.html with totals row
|
||
```
|
||
|
||
**Visual features**:
|
||
- Fee overrides shown in **orange** with the original amount in parentheses
|
||
- Empty months shown in muted gray
|
||
- Monthly totals row at the bottom
|
||
- Performance timing in the footer (click to expand breakdown)
|
||
|
||
**Template variables**:
|
||
|
||
| Variable | Type | Content |
|
||
|----------|------|---------|
|
||
| `months` | `list[str]` | Month labels like "Jan 2026" |
|
||
| `results` | `list[dict]` | `{name, months: [{cell, overridden}]}` |
|
||
| `totals` | `list[str]` | Monthly total strings like "3750 CZK" |
|
||
| `attendance_url` | `str` | Link to the attendance Google Sheet |
|
||
| `payments_url` | `str` | Link to the payments Google Sheet |
|
||
|
||
### `GET /reconcile` — Payment Reconciliation
|
||
|
||
**Template**: `templates/reconcile.html` (802 lines — the most complex template)
|
||
|
||
The centerpiece of the application. Shows a matrix of members × months with payment status, plus summary sections for credits, debts, and unmatched transactions.
|
||
|
||
**Data pipeline**:
|
||
```
|
||
attendance.py::get_members_with_fees() → All members + fees
|
||
match_payments.py::fetch_sheet_data() → All payment transactions
|
||
match_payments.py::fetch_exceptions() → Fee overrides
|
||
match_payments.py::reconcile() → Match payments ↔ fees
|
||
→ Render reconcile.html
|
||
```
|
||
|
||
**Cell statuses**:
|
||
|
||
| Status | CSS Class | Display | Meaning |
|
||
|--------|-----------|---------|---------|
|
||
| `empty` | `cell-empty` | `-` | No fee expected, no payment |
|
||
| `ok` | `cell-ok` | `OK` | Paid in full (green) |
|
||
| `partial` | `cell-unpaid` | `300/750` | Partially paid (red) |
|
||
| `unpaid` | `cell-unpaid` | `UNPAID 750` | Nothing paid (red) |
|
||
| `surplus` | — | `PAID 200` | Payment received but no fee expected |
|
||
|
||
**Interactive features**:
|
||
|
||
1. **Member detail modal** — Click the `[i]` icon next to any member name to see:
|
||
- Status summary table (month, attendance count, expected, paid, status)
|
||
- Fee exceptions (if any, shown in amber)
|
||
- Full payment history with dates, amounts, senders, and messages
|
||
|
||
2. **Keyboard navigation** — When a member modal is open:
|
||
- `↑` / `↓` arrows navigate between members (respecting search filter)
|
||
- `Escape` closes the modal
|
||
|
||
3. **Name search filter** — Type in the search box to filter members. Uses diacritic-insensitive matching (e.g., typing "novak" matches "Novák").
|
||
|
||
4. **QR Payment** — Hover over an unpaid/partial cell to reveal a "Pay" button. Clicking it opens a QR code modal with:
|
||
- A Czech SPD-format QR code (scannable by Czech banking apps)
|
||
- Pre-filled account number, amount, and payment message
|
||
- The QR image is generated server-side via `GET /qr`
|
||
|
||
**Client-side data**:
|
||
|
||
The template receives a full JSON dump of member data (`member_data`) embedded in a `<script>` tag. This powers the modal without additional API calls:
|
||
|
||
```javascript
|
||
const memberData = {{ member_data | safe }};
|
||
const sortedMonths = {{ raw_months | tojson }};
|
||
```
|
||
|
||
**Summary sections** (rendered below the main table):
|
||
|
||
| Section | Shown when | Content |
|
||
|---------|-----------|---------|
|
||
| Credits | Any member has positive balance | Names with surplus amounts |
|
||
| Debts | Any member has negative balance | Names with outstanding amounts (red) |
|
||
| Unmatched Transactions | Any transaction couldn't be matched | Date, amount, sender, message |
|
||
|
||
### `GET /payments` — Payments Ledger
|
||
|
||
**Template**: `templates/payments.html`
|
||
|
||
Displays all bank transactions grouped by member name. Each member section shows their transactions in reverse chronological order.
|
||
|
||
**Data pipeline**:
|
||
```
|
||
match_payments.py::fetch_sheet_data() → All transactions
|
||
→ Group by Person column
|
||
→ Strip [?] markers
|
||
→ Handle comma-separated people
|
||
→ Sort by date descending
|
||
→ Render payments.html
|
||
```
|
||
|
||
**Multi-person handling**: If a transaction's "Person" field contains comma-separated names (e.g., "Alice, Bob"), the transaction appears under both Alice's and Bob's sections.
|
||
|
||
### `GET /qr` — QR Code Generator
|
||
|
||
Returns a PNG image containing a Czech SPD (Short Payment Descriptor) QR code.
|
||
|
||
**Query parameters**:
|
||
|
||
| Parameter | Default | Description |
|
||
|-----------|---------|-------------|
|
||
| `account` | `BANK_ACCOUNT` env var | IBAN or Czech account number |
|
||
| `amount` | `0` | Payment amount |
|
||
| `message` | *(empty)* | Payment message (max 60 chars) |
|
||
|
||
**SPD format**: `SPD*1.0*ACC:{account}*AM:{amount}*CC:CZK*MSG:{message}`
|
||
|
||
This format is recognized by all Czech banking apps and generates a pre-filled payment order when scanned.
|
||
|
||
## UI Design System
|
||
|
||
### Color Palette
|
||
|
||
| Element | Color | Hex |
|
||
|---------|-------|-----|
|
||
| Background | Near-black | `#0c0c0c` |
|
||
| Base text | Medium gray | `#cccccc` |
|
||
| Headings, accents, "OK" | Terminal green | `#00ff00` |
|
||
| Unpaid, debts | Alert red | `#ff3333` |
|
||
| Fee overrides | Amber/orange | `#ffa500` / `#ffaa00` |
|
||
| Empty/muted | Dark gray | `#444444` |
|
||
| Borders | Subtle gray | `#333` (dashed), `#555` (solid) |
|
||
|
||
### Typography
|
||
|
||
All text uses the system monospace font stack:
|
||
```css
|
||
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
|
||
"Liberation Mono", "Courier New", monospace;
|
||
```
|
||
|
||
Base font size is 11px with 1.2 line-height — intentionally dense for a data-heavy dashboard.
|
||
|
||
### Navigation
|
||
|
||
A persistent nav bar appears at the top of every page:
|
||
```
|
||
[Attendance/Fees] [Payment Reconciliation] [Payments Ledger]
|
||
```
|
||
The active page's link is highlighted with inverted colors (black text on green background).
|
||
|
||
### Shared Footer
|
||
|
||
Every page includes a click-to-expand performance timer showing total render time and a per-step breakdown.
|
||
|
||
## Flask Application Architecture
|
||
|
||
### Request Lifecycle
|
||
|
||
```
|
||
Request → @app.before_request (start timer) → Route handler → Template → Response
|
||
│ │
|
||
▼ ▼
|
||
g.start_time record_step("fetch_members")
|
||
g.steps = [] record_step("fetch_payments")
|
||
record_step("process_data")
|
||
│
|
||
▼
|
||
@app.context_processor
|
||
inject_render_time()
|
||
│
|
||
▼
|
||
{{ get_render_time() }}
|
||
in template footer
|
||
```
|
||
|
||
### Module Loading
|
||
|
||
The Flask app adds the `scripts/` directory to `sys.path` at startup, allowing direct imports from scripts:
|
||
|
||
```python
|
||
scripts_dir = Path(__file__).parent / "scripts"
|
||
sys.path.append(str(scripts_dir))
|
||
|
||
from attendance import get_members_with_fees, SHEET_ID
|
||
from match_payments import reconcile, fetch_sheet_data, fetch_exceptions, normalize
|
||
```
|
||
|
||
### Environment Variables
|
||
|
||
| Variable | Default | Purpose |
|
||
|----------|---------|---------|
|
||
| `BANK_ACCOUNT` | `CZ8520100000002800359168` | Bank account for QR code generation |
|
||
| `FIO_API_TOKEN` | *(none)* | Fio API token (used by `fio_utils.py`) |
|
||
|
||
### Error Handling
|
||
|
||
The application has minimal error handling:
|
||
- If Google Sheets returns no data, routes return a simple "No data." text response
|
||
- No custom error pages for 404/500
|
||
- Exceptions propagate to Flask's default error handler (debug mode in development, 500 in production)
|
||
|
||
## Template Architecture
|
||
|
||
All three page templates share a common structure:
|
||
|
||
```html
|
||
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>FUJ [Page Name]</title>
|
||
<style>
|
||
/* ALL CSS is inline — no external stylesheets */
|
||
/* ~150-400 lines of CSS per template */
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div class="nav"><!-- 3-link navigation --></div>
|
||
<h1>Page Title</h1>
|
||
<div class="description"><!-- Source links --></div>
|
||
|
||
<!-- Page-specific content -->
|
||
|
||
<div class="footer"><!-- Render time --></div>
|
||
|
||
<script>
|
||
/* Page-specific JavaScript (only in reconcile.html) */
|
||
</script>
|
||
</body>
|
||
</html>
|
||
```
|
||
|
||
There is no shared base template (no Jinja2 template inheritance). CSS is duplicated across templates with small variations.
|
||
|
||
---
|
||
|
||
*Web application documentation generated from comprehensive code analysis on 2026-03-03.*
|