update CLAUDE.md

CLAUDE.md

@@ -9,9 +9,67 @@ Order backup CLI tool — backs up order data by time range to CSV, then deletes
 ## Tech Stack
 
 - **Language**: Python
-- **Package management**: `uv` (install via `uv tool`)
-- **Storage**: Azure Table (Python SDK)
+- **Package management**: `uv`
+- **Storage**: Azure Table (`azure-data-tables` SDK)
+- **CLI framework**: Click
 
 ## Reference Implementation
 
 Order data model and format: `/Users/tech/workspace/n3-world/N3-Server/n3backend/n3order`
+
+## Commands
+
+```bash
+# Install dependencies for development
+uv sync --group dev
+
+# Run unit tests only (no Azure emulator required)
+uv run pytest tests/ -v -m "not integration"
+
+# Run a single test file
+uv run pytest tests/test_backup.py -v
+
+# Run integration tests (requires Azure Storage emulator at 192.168.9.101)
+uv run pytest tests/test_integration.py -v
+
+# Seed test data into the emulator
+uv run python scripts/seed_test_data.py
+
+# Install as a CLI tool
+uv tool install .
+```
+
+## Architecture
+
+The tool implements a three-phase pipeline: **scan → backup → delete**.
+
+### Three-Phase Pipeline
+
+1. **`scan`** (`scan.py`): Full table scan of the `order` Azure Table, writing all entities to `scan/scan-<date>.csv`. Uses pagination with configurable page size and inter-page delay to limit production load.
+
+2. **`backup`** (`backup.py`): Reads the scan CSV offline (no Azure calls), filters to `state == 1` (`Recived`) orders with `OrderTime < cutoff`, and writes per-day CSVs to `backups/<YYYY-MM-DD>.csv`. The `--days` flag sets cutoff as `today_utc - N days`.
+
+3. **`delete`** (`delete.py`): Reads a backup CSV and deletes those records from Azure Table using batched transactions grouped by `PartitionKey`. Requires interactive confirmation before executing.
+
+### Data Flow
+
+- Azure Table `order` → scan CSV → backup CSVs → Azure Table deletion
+- Scan and backup are read-only with respect to Azure; only `delete` writes to production.
+- The `state` field is stored as an integer in Azure but legacy scan files may contain string values (`"Payed"` → 0, `"Recived"` → 1). `csv_utils.parse_row` handles both forms.
+
+### Key Modules
+
+- `cli.py`: Click command definitions; loads config and delegates to module functions
+- `config.py`: Reads `~/.config/order-bak/config.toml` (TOML via `tomllib`); only `[azure].connection_string` is required
+- `csv_utils.py`: Canonical column list (`CSV_COLUMNS`), `entity_to_row` / `parse_row` for serialization with type coercion
+- `scan.py`, `backup.py`, `delete.py`: One function each, thin and focused
+
+### Configuration
+
+Config file: `~/.config/order-bak/config.toml`. Template in `assets/config.toml`. For local development against the emulator, copy `assets/local.toml`.
+
+Override config path with `order-bak --config /path/to/config.toml <command>`.
+
+### Integration Tests
+
+The integration test (`tests/test_integration.py`) hits a real Azure Storage emulator at `192.168.9.101:10002`. Override the endpoint via `ORDER_BAK_TEST_CONNECTION_STRING` env var. Tests are gated by the `integration` pytest marker.