# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

SaleShow is a monolithic Flask web application for analyzing sales data from Excel files. It supports manual Excel uploads and automated daily downloads from secsion.com via Playwright browser automation. There is no database — all data lives as Excel files on disk in `uploads/`.

## Commands

```bash
# Install dependencies
pip install -r requirements.txt

# Run development server (Flask on port 5000, debug via FLASK_DEBUG env var)
python app.py

# Run with Docker (builds image, installs Playwright Chromium, port 5000)
docker-compose up -d

# Production
gunicorn -w 4 -b 0.0.0.0:8000 app:app

# CLI automation — download reports from secsion.com
python -m automation.secsion --start 2026-04-28 --end 2026-04-28
python -m automation.secsion --start 2026-05-15 --end 2026-05-17 --username 15682076681 --password yourpassword
```

No test framework or linter is configured in this project.

## Architecture

**Backend (Flask, single `app.py`):**
- Routes handle file upload (`/upload`), file listing (`/files`), data loading/processing (`/load/<filename>`), deletion, and cleanup.
- `process_sales_data()` (~lines 371-575) is the core logic. It uses a state-machine approach to handle two Excel formats: "flat tables" (each row has code + product) and "hierarchical tables" (code row is a header, product rows are children). Outputs daily summaries with per-product breakdowns.
- `find_header_row()` dynamically detects the header row by scanning first 20 rows for keyword matches.
- Auto-download routes use a global `download_status` dict and run Playwright in daemon threads via `threading.Thread`.

**Automation module (`automation/`):**
- `secsion.py` — `SecsionDownloader` uses Playwright headless Chromium to log into secsion.com, navigate to reports, set date range via TDesign date picker (requires click → select day → Enter confirm → Escape close sequence), optionally inject `shop_id` via route interception on `**/api/bill/export`, and download exports. Has 3-retry logic with exponential backoff.
- `uploader.py` — copies downloaded files into `uploads/` with `YYYYMMDD_HHMMSS_` prefix naming (same convention as manual uploads).
- `scheduler.py` — APScheduler `BackgroundScheduler` with `CronTrigger` runs daily auto-download (default 01:00). Uses `misfire_grace_time=3600`.

**Configuration (`config.py`):**
- Three-tier priority: Web UI settings (`data/config.json`) > environment variables (`.env` / system env) > defaults.
- `Config` class provides static methods for reading/writing secsion credentials, shop ID, and scheduler settings.
- Passwords are masked (`******`) when returned via the API.

**Frontend (vanilla JS/CSS, no build step):**
- `main.js` — all client-side interactivity: file upload (drag-and-drop), AJAX to API, data rendering (card/table view), client-side filtering, sorting, pagination (50 items/page), export.
- `style.css` — Glassmorphism design with CSS custom properties.
- `settings.html` — self-contained settings page with inline `<script>` (no separate JS file).

## Key Design Decisions

- No database — Excel files on disk are the data store.
- No frontend build step — vanilla JS/CSS served directly via Flask static files.
- Playwright automation runs in daemon threads; status tracked via module-level `download_status` dict in `app.py`.
- The secsion.com date picker uses TDesign's `needconfirm="true"` mode — simply calling `.fill()` won't work; must click cell then press Enter.