ouyangxq
19745e46c1
18 个服务与公共模块重复复制的 314 字符数据库访问约束改为指向后端根唯一定义，并给索引门禁增加防退化校验。 - 18 处重复段落合并为一句指针，规则正文只在后端根 AGENTS.md 维护 - 门禁新增路由表行宽上限（根/Admin/Client/后端根/海外 PDA），防止业务规则重新回流表格 - 同步包含此前未提交的链接与锚点、表格存在性校验 - 仅索引文档与门禁脚本，未改动业务代码
4.6 KiB
4.6 KiB
Integration Service 模块指引
数据库访问与中文注释约束
- 强制继承
../AGENTS.md的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。
职责与边界
- 负责百度 OCR、Amazon Logistics/SP-API、海外仓业务船司/船舶轨迹查询等第三方适配和能力开关；不保存业务主数据。
- 入库测量与计费重量 OCR 由
file/调用；本服务只返回识别结果，不保存file_object、入库单或重量确认记录。
模块入口与验证
- 应用/配置：
IntegrationServiceApplication.java、config/IntegrationProperties.java - 内部接口：
controller/IntegrationProviderController.java、WeightOcrController.java - 领星 WMS 自研系统出库只读查询：
controller/LingxingInternalController.java、provider/lingxing/、dto/lingxing/、config/LingxingWmsProperties.java；内部契约openapi/lingxing-wms-v1.yaml位于src/main/resources/。内部提供出库单页摘要、独立按单定位、出库详情、仓库目录及单仓产品库存单页查询；统一账号节流、有限退避和严格分页校验，保留未知数量与源时间原值。不编排定时采集、多页库存同步或业务持久化；本地隔离启动与环境变量入口见README.md，真实调用默认关闭。 - OCR 编排：
service/ocr/WeightOcrBatchService.java、ImageCropper.java、WeightCandidateSelector.java - 供应商适配：
provider/IntegrationProviderAdapter.java、BaiduOcrAdapter.java、AmazonLogisticsAdapter.java - 海外仓业务船节点外部适配：内部契约
controller/IntegrationProviderController.java的/internal/integrations/carrier-schedules/query，统一十节点与四类异常 DTOdto/CarrierScheduleDtos.java，provider SPIprovider/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/test/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/海外仓业务/。