contract.py 4.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137
  1. """数据处理工具的对外契约(**替换点**)。
  2. 平台其余部分只依赖本文件里的数据类型与 ``CustomsProcessor`` 协议,
  3. 不 import ``engine`` 下的任何实现。要整体替换数据处理工具,只需:
  4. 1. 实现 ``CustomsProcessor.process(request, progress) -> CustomsProcessResult``;
  5. 2. 在 ``toolsvc.customs.factory.load_processor()`` 里换掉默认实现,或设置环境变量
  6. ``CUSTOMS_PROCESSOR`` 指向你的新类(``模块路径:类名``)。
  7. 前端直接调用的 ``POST /api/process`` 与 Agent 的 ``customs_process`` 工具
  8. 都走同一个协议,因此替换后两端同时生效,不需改前端。
  9. """
  10. from __future__ import annotations
  11. from dataclasses import dataclass, field
  12. from typing import Any, Callable, Protocol
  13. #: 进度回调:(阶段说明, 0~1 的完成度)
  14. ProgressCallback = Callable[[str, float], None]
  15. #: 支持的 operation
  16. OPERATIONS = ("full_pipeline", "custom_aggregate")
  17. @dataclass
  18. class CustomsOptions:
  19. """处理参数。默认值即《0909 需求问题整理与回复》的推荐口径。"""
  20. start_year: int = 2025
  21. end_year: int = 2026
  22. cutoff_date: str | None = None
  23. directions: list[str] = field(default_factory=lambda: ["I"])
  24. encoding: str = "auto"
  25. delimiter: str = "auto"
  26. country_code_system: str = "ISO"
  27. confirmed_complete_years: list[int] = field(default_factory=list)
  28. allow_partial_year_basket: bool = True
  29. demo: bool = False
  30. #: operation=custom_aggregate 时生效
  31. group_by: list[str] = field(default_factory=list)
  32. filters: dict[str, str] = field(default_factory=dict)
  33. def validate(self) -> None:
  34. if not (1900 <= int(self.start_year) <= int(self.end_year) <= 9998):
  35. raise ValueError("无效年份范围")
  36. if self.country_code_system not in ("ISO", "GEC"):
  37. raise ValueError("country_code_system 只支持 ISO/GEC")
  38. if not self.directions or set(self.directions) - {"I", "E"}:
  39. raise ValueError("directions 只支持 I / E")
  40. if self.delimiter not in ("auto", ",", "\t", ";", "|"):
  41. raise ValueError("只支持 , \\t ; | 四种分隔符")
  42. def to_dict(self) -> dict[str, Any]:
  43. return {
  44. "start_year": self.start_year,
  45. "end_year": self.end_year,
  46. "cutoff_date": self.cutoff_date,
  47. "directions": list(self.directions),
  48. "encoding": self.encoding,
  49. "delimiter": self.delimiter,
  50. "country_code_system": self.country_code_system,
  51. "confirmed_complete_years": list(self.confirmed_complete_years),
  52. "allow_partial_year_basket": self.allow_partial_year_basket,
  53. "demo": self.demo,
  54. "group_by": list(self.group_by),
  55. "filters": dict(self.filters),
  56. }
  57. @dataclass
  58. class CustomsProcessRequest:
  59. """一次处理请求。"""
  60. input_path: str
  61. output_dir: str
  62. operation: str = "full_pipeline"
  63. options: CustomsOptions = field(default_factory=CustomsOptions)
  64. #: 名称 → 绝对路径;允许调用方覆盖规则文件(默认用包内 rules/)
  65. rules_dir: str | None = None
  66. def validate(self) -> None:
  67. if self.operation not in OPERATIONS:
  68. raise ValueError(f"operation 只支持 {OPERATIONS}")
  69. self.options.validate()
  70. @dataclass
  71. class SheetInfo:
  72. sheet: str
  73. kind: str
  74. rows: int
  75. columns: list[str]
  76. table: str
  77. @dataclass
  78. class CustomsProcessResult:
  79. """处理结果。所有对外字段都是可序列化的基础类型。"""
  80. output_dir: str
  81. xlsx_path: str
  82. sqlite_path: str
  83. sheets: list[SheetInfo] = field(default_factory=list)
  84. stats: dict[str, Any] = field(default_factory=dict)
  85. lineage: dict[str, Any] = field(default_factory=dict)
  86. warnings: list[str] = field(default_factory=list)
  87. def to_dict(self) -> dict[str, Any]:
  88. return {
  89. "output_dir": self.output_dir,
  90. "xlsx_path": self.xlsx_path,
  91. "sqlite_path": self.sqlite_path,
  92. "sheets": [sheet.__dict__ for sheet in self.sheets],
  93. "stats": self.stats,
  94. "lineage": self.lineage,
  95. "warnings": self.warnings,
  96. }
  97. class CustomsProcessor(Protocol):
  98. """数据处理工具必须实现的协议。"""
  99. name: str
  100. version: str
  101. def process(self, request: CustomsProcessRequest, progress: ProgressCallback | None = None) -> CustomsProcessResult:
  102. ...
  103. class ProcessorError(RuntimeError):
  104. """处理失败时抛出,service 层转成结构化错误返回给前端/Agent。"""
  105. def __init__(self, message: str, *, code: str = "PROCESS_FAILED", detail: dict | None = None) -> None:
  106. super().__init__(message)
  107. self.code = code
  108. self.detail = detail or {}