# 数据处理模块(可整体替换) 本目录是**唯一**需要改动就能换掉海关数据处理引擎的地方。 ``` customs/ ├─ contract.py # 契约:请求/结果/协议(调用方只依赖这里) ├─ factory.py # 装配:默认实现 + CUSTOMS_PROCESSOR 环境变量替换 ├─ pipeline.py # 参考实现的编排 ├─ engine/ # 参考实现:numbers / rules / storage / excel / reports └─ rules/*.xlsx # 海关提供的规则工作簿 ``` ## 调用方 | 调用方 | 入口 | |---|---| | 前端「数据处理」页 | `POST /api/process` → BFF → Python `POST /runs` → `runs.py` → `load_processor()` | | Agent 工具 `customs_process` | BFF → Python `POST /tools/customs_process` → `runs.run_sync()` → `load_processor()` | 两条路径都只经过 `contract.py` 里的类型,不 import `engine/` 的任何模块。 ## 替换方式 ```python # 1) 新建实现 # toolsvc/customs_v2/processor.py class MyProcessor: name = "my-processor" version = "1.0.0" def process(self, request, progress=None) -> CustomsProcessResult: ... # 2) 切换(推荐,零代码改动) # .env 里加: CUSTOMS_PROCESSOR=toolsvc.customs_v2.processor:MyProcessor # 或者改工厂默认值:factory.DEFAULT_SPEC ``` ## 必须满足的输出 * `output_dir/stat.sqlite`:每张结果表一张表,含 `_row_index` / `_row_hash` / 各列 TEXT (数值列建议加 `_num_<列>` REAL 影子列),外加 `sheet_meta(sheet, table_name, headers_json, row_count)`; * `sheets[].sheet`:逻辑表名(前端展示与 Agent 查询都用它),建议与海关 16 张模板表同名; * `sheets[].table`:该表在 `stat.sqlite` 里的真实表名; * `lineage`:`input_sha256 / params_hash / output_hash / engine{name,version}`。 完整验收清单与示例代码见仓库根目录 `docs/04-工具模块替换指南.md`。