# CLAUDE.md

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

## Project Overview

Order backup CLI tool — backs up order data by time range to CSV, then deletes backed-up records from the production Azure Table store. Operates on production tables, so performance impact must be minimized.

## Tech Stack

- **Language**: Python
- **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

# Start Azure Storage emulator (required for integration tests)
docker compose -f scripts/docker-compose.yml up -d

# Run integration tests (requires emulator running via docker compose above)
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

Integration tests (`tests/test_integration.py`) require the Azure Storage emulator running locally via `scripts/docker-compose.yml` (azurite on `localhost:10002`). Start it with `docker compose -f scripts/docker-compose.yml up -d` before running. Tests are gated by the `integration` pytest marker. Override the endpoint via `ORDER_BAK_TEST_CONNECTION_STRING` env var if needed.