docs: add design spec for backup --days parameter

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-04-21 22:16:24 +08:00
parent ef449729d7
commit 34db3dc439

View File

@@ -0,0 +1,48 @@
# Backup Days Parameter Design
## Summary
Replace the `--start` / `--end` date range parameters on the `backup` command with a single `--days N` parameter that backs up all orders older than N days. The minimum value is 1 (today's data is never backed up).
## Current Behavior
```
order-bak backup --start 2025-01-01 --end 2025-02-01
```
Backs up orders where `start <= OrderTime < end` and `state == 1`.
## New Behavior
```
order-bak backup --days 7
```
Backs up all orders where `OrderTime < cutoff` and `state == 1`, where `cutoff = today_utc - timedelta(days=N)`.
Example: `--days 7` on April 21 → cutoff is April 14 00:00 UTC → backs up all orders with OrderTime before April 14.
## Changes
### cli.py
- Remove `--start` and `--end` options
- Add `--days` option: required, int, must be >= 1
- Compute `cutoff = datetime.now(timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0) - timedelta(days=days)`
- Pass `cutoff` to `backup_orders()`
### backup.py
- Change signature from `backup_orders(scan_path, backup_dir, start, end)` to `backup_orders(scan_path, backup_dir, cutoff)`
- Replace filter `if order_time < start or order_time >= end` with `if order_time >= cutoff`
### test_backup.py
- Update all existing tests to pass `cutoff` instead of `start`/`end`
- Add edge cases: cutoff exactly at midnight, N=1 (only today excluded)
## Unchanged
- `scan` command, `delete` command, config, csv_utils
- State filtering (state == 1), OrderTime null check
- Output format (per-date CSV files in backups/)