order-bak/CLAUDE.md

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

# 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.