# Integration Service 模块指引

## 职责与边界

- 负责百度 OCR、Amazon Logistics/SP-API、四期船司/船舶轨迹查询等第三方适配和能力开关；不保存业务主数据。
- 二期重量 OCR 由 `file/` 调用；本服务只返回识别结果，不保存 `file_object`、入库单或重量确认记录。

## 模块入口与验证

- 应用/配置：`IntegrationServiceApplication.java`、`config/IntegrationProperties.java`
- 内部接口：`controller/IntegrationProviderController.java`、`WeightOcrController.java`
- OCR 编排：`service/ocr/WeightOcrBatchService.java`、`ImageCropper.java`、`WeightCandidateSelector.java`
- 供应商适配：`provider/IntegrationProviderAdapter.java`、`BaiduOcrAdapter.java`、`AmazonLogisticsAdapter.java`
- 四期船节点外部适配：内部契约 `controller/IntegrationProviderController.java` 的 `/internal/integrations/carrier-schedules/query`，统一十节点与四类异常 DTO `dto/CarrierScheduleDtos.java`，provider SPI `provider/CarrierScheduleProviderAdapter.java`，标准枚举 `domain/CarrierScheduleStandardNode.java`、`CarrierScheduleExceptionCode.java`；美森网页会话、动态 `ttr` 与公开查询代理适配见 `provider/MatsonTrackingClient.java`、`MatsonCarrierScheduleProviderAdapter.java`，由 `MATSON_TRACKING_ENABLED` 显式启用；SML 的 122→125→124→126 JSON 调用链与 A/E 时间解析见 `provider/SmlTrackingClient.java`、`SmlCarrierScheduleProviderAdapter.java`，由 `SML_TRACKING_ENABLED` 显式启用；ZIM 正式 Tracing API 的 OAuth2 token 缓存、401 单次刷新及柜号活动解析见 `provider/ZimTrackingClient.java`、`ZimCarrierScheduleProviderAdapter.java`，凭据只从外部 secret 注入并由 `ZIM_TRACKING_ENABLED` 显式启用；长荣柜号→关联提单两段 UTF-8 HTML 查询、表头定位与日粒度事实解析见 `provider/EvergreenTrackingClient.java`、`EvergreenCarrierScheduleProviderAdapter.java`，由 `EMC_TRACKING_ENABLED` 显式启用且不输出完整提单号；合德 UTF-8 HTML 主表解析见 `provider/HedeTrackingClient.java`、`HedeCarrierScheduleProviderAdapter.java`，由 `HEDE_TRACKING_ENABLED` 显式启用且当前只自动解析柜号；轮询任务、租约、订舱/柜次关联、最新实际节点、节点/异常事实和历史归 `firstleg/portschedule/`，标准见 `../../docs/四期/船节点标准化契约.md`
- 安全：`security/InternalServiceTokenGuard.java`；配置 `application.yml`、`../config/nacos/{local,cn}/integration-service.yml`
- 测试：`src/test/java/com/baiyue/integration/`；`mvn -pl integration-service -am test`

## 修改约束与分期

- 密钥、原始响应和客户敏感数据不得写入日志；真实调用默认关闭，适配器负责超时、重试、限流、错误归一化。
- 船节点适配器不得自行维护业务轮询任务或到港状态；必须返回可审计的来源、观测时间、标准化节点和错误结果，由 Firstleg 负责幂等落库与停止条件。查询周期和供应商额度通过配置表达，不硬编码复用三期人工查询限制。
- OCR 只能访问受控输入/输出目录，接口仅接受内部服务令牌；契约变更同步检查 File 的 `WeightOcrClient` 和测试。
- 全量验收按业务链路核对通用适配、File 重量 OCR 及已确认的报关协作契约；柜子确认国内出仓后的船司/船节点外部查询整体归四期，不再列作三期能力。外部调用必须保留来源、频率、限流、超时、最近有效结果和过期标识，凭证缺失按既定人工修正降级，不把未确认的自动化能力当作已实现契约。相关依据：`../../docs/一期/`、`../../docs/二期/`、`../../docs/三期/`、`../../docs/四期/`。