tech
bc119ff2ae
- Add [backup] retain_days to config (default 1); --days becomes optional - Add scripts/docker-compose.yml (azurite) for local integration testing - Integration tests now use assets/local.toml and localhost endpoints - Update .gitignore and CLAUDE.md accordingly Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# 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.
|