README.md 1.9 KB

数据处理模块(可整体替换)

本目录是唯一需要改动就能换掉海关数据处理引擎的地方。

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/ 的任何模块。

替换方式

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