baiyue-firstleg/integration-service/AGENTS.md

Integration Service 模块指引

职责边界

• 集中承载百度 OCR、Amazon Logistics/SP-API 等第三方适配器和能力启停状态。
• 不保存业务主数据，不把第三方 DTO 泄漏为内部领域模型；真实外部调用默认关闭，密钥仅从安全配置注入。
• 二期入库重量 OCR 由 file/ 调用本服务；Firstleg 只消费 File 返回的识别结果，不直接依赖供应商协议。

快速索引

功能	入口
应用与配置扫描	src/main/java/com/baiyue/integration/IntegrationServiceApplication.java
baiyue.integration 配置	config/IntegrationProperties.java
内部供应商状态 API	controller/IntegrationProviderController.java
重量 OCR 内部 API	controller/WeightOcrController.java；目录批处理 POST /internal/integrations/weight-ocr/batches，单图识别 POST /internal/integrations/weight-ocr/single
能力状态模型与服务	dto/ProviderStatus.java、service/ProviderStatusService.java
适配器抽象	provider/IntegrationProviderAdapter.java
百度 OCR 状态与客户端	provider/BaiduOcrAdapter.java、provider/ocr/BaiduMeterClient.java
重量 OCR 协议模型	dto/ocr/
重量 OCR 批处理	service/ocr/WeightOcrBatchService.java
图片裁剪与重量筛选	service/ocr/ImageCropper.java、service/ocr/WeightCandidateSelector.java
OCR 文件访问边界	service/ocr/WeightOcrStoragePolicy.java
二期调用方	../file/src/main/java/com/baiyue/file/client/WeightOcrClient.java、../file/src/main/java/com/baiyue/file/service/MeasurementImageService.java；File 负责图片持久化和业务归属，本服务只返回识别结果
Amazon	provider/AmazonLogisticsAdapter.java
内部服务令牌	security/InternalServiceTokenGuard.java
配置与 OCR 测试	src/test/java/com/baiyue/integration/config/IntegrationPropertiesTest.java、src/test/java/com/baiyue/integration/service/ocr/
本地/Nacos 配置	src/main/resources/application.yml、../config/nacos/{local,cn}/integration-service.yml

修改与验证

• 第三方密钥、Token、请求原文和客户敏感数据不得写入源码或日志；配置应支持按供应商独立关闭。
• 适配器负责外部协议转换、超时、错误归一化和安全降级；业务编排留在调用方服务。
• 启用真实调用前补齐超时、重试边界、限流、幂等和可观测性，并避免在测试中访问真实供应商。
• OCR 目录批处理只能访问 WEIGHT_OCR_INPUT_ROOT 和 WEIGHT_OCR_OUTPUT_ROOT 内的路径，不得恢复任意服务器路径读取。
• OCR 接口只允许内部服务令牌调用；图片大小、解码像素数、单批数量和并发批次限制不得绕过。
• OCR 原始响应和第三方密钥不得写入应用日志，真实供应商调用必须保持默认关闭。
• 单图接口只接收 File 传入的受控图片内容，不负责保存 file_object、入库单或重量确认记录；响应 DTO 或错误语义变化时同步检查 File 的 WeightOcrClient、MeasurementImageService 和契约测试。
• 从父目录运行 mvn -pl integration-service -am test。

分期快速索引

• 一期：不承载一期订单主流程；仅提供可复用的第三方适配基础，不得把供应商 DTO 直接变成订单或客户领域模型。范围依据先读 ../../docs/一期/README.md。
• 二期：当前主要消费者是 file/ 的重量 OCR 链路；先读 ../../docs/二期/README.md、主流程和第三方测量联调说明。真实 OCR 凭证未配置时只能验证失败后人工修正的降级链路，不能伪造识别成功。
• 三期：当前 NO-GO；不提前接入自动报关、船期、港务或其他外部业务接口。待 ../../docs/三期/三期需求确认表.md 解除相关阻断项后，再为每个供应商单独确认契约、开关、超时、重试、幂等和审计边界。