# OrderSentry

OrderSentry 是一个 Python 3.11+ 的企业订单 CSV 校验与标准化工具。运行时逐行读取，不修改输入文件；默认禁止覆盖；写出使用临时文件与原子替换。

## 安装

Windows PowerShell：

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
```

开发与质量工具：

```powershell
python -m pip install -e ".[dev]"
ruff check .
mypy src
python -m unittest discover -s tests -v
```

## 运行

先执行不写文件的预检：

```powershell
order-sentry --input samples\orders_mixed.csv --output outputs\orders_clean.csv --config config.example.json --dry-run
```

正式写出：

```powershell
order-sentry --input samples\orders_mixed.csv --output outputs\orders_clean.csv --config config.example.json
```

如确认允许替换既有输出，额外使用 `--overwrite`。脚本不会默认覆盖。

## 输出

- `orders_clean.csv`：标准化业务结果
- `JOB-*-report.json`：总量、成功、跳过、失败、耗时与状态
- `JOB-*-failures.jsonl`：逐行失败分类与说明
- `logs/JOB-*.log`：带时间、级别和任务编号的日志

正常完成退出码为 `0`；部分行失败为 `2`；参数或未预期错误为 `3`；输入、配置或权限问题为 `4`；用户中断为 `130`。

## 恢复与幂等

中断时临时文件会清理，输入不会改变。重新运行同一输入会产生相同业务结果；任务编号和日志时间会不同。若输出已经存在，先核对原报告，再决定更换输出路径或显式使用 `--overwrite`。

## 安全修改项

客户可以修改 `config.example.json` 中的编码、分隔符、允许状态、分块大小、失败上限和日志级别。新增字段、修改金额公式、改变时间语义或接入生产 API 属于业务逻辑变更，需要同时更新契约和测试。

## 已知限制

- 当前输入为本地 CSV，不包含数据库或远程 API。
- 无时区时间只能按 UTC 补齐；其他默认时区需要引入标准时区数据库映射。
- 去重集合保存在内存中。超大规模唯一键应改用 SQLite 或外部去重存储。
- 权限不足测试依赖操作系统文件权限，CI 中应使用平台适配的集成测试。