From 3b8934fc60a0ca4f7a911a2a62ddb3f2d2b3239c Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Wed, 19 Aug 2026 16:45:44 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- firstleg/AGENTS.md | 6 ++++-- integration-service/AGENTS.md | 6 ++++-- warehouse/AGENTS.md | 4 +++- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/firstleg/AGENTS.md b/firstleg/AGENTS.md index bb1b71671..6a6e0ec51 100644 --- a/firstleg/AGENTS.md +++ b/firstleg/AGENTS.md @@ -2,7 +2,7 @@ ## 职责与边界 -- 负责履约任务/分配、入库单、测量/OCR、审核后初始计价、FBA 计费、客户在途柜量统计及国内出仓履约链路。 +- 负责履约任务/分配、入库单、测量/OCR、审核后初始计价、FBA 计费、客户在途柜量统计、国内出仓履约链路，以及四期国内出仓后的船节点查询任务和节点事实。 - 订单主数据归 `order/`，托盘/库位归 `warehouse/`，文件对象归 `file/`，OCR 供应商归 `integration-service/`；通过客户端 DTO 和内部令牌协作。 - 入库、分柜、装柜、PDA 和出仓能力均在本模块按对应服务端契约协作；`WAIT_SPLIT + APPROVED + CONFIRMED` 是入库链路状态节点，不是全量验收的范围终点。财务状态仍归 `finance`，本模块只生产不可变费用来源和柜次成本快照。 @@ -28,7 +28,8 @@ | 货柜与智能排柜 | `controller/PlatformContainerController.java`、`PlatformSmartLoadingController.java`、`loading/` | | PDA 拣货与装柜 | `controller/PlatformLoadingPdaController.java`、`loading/controller/PlatformLoadingDeliveryController.java` | | 装柜完成跨区事件 | `service/LoadingCompletedOutboxService.java`、`LoadingCompletedOutboxRelay.java`、`repository/LoadingCompletedOutboxRepository.java`、`client/EventBridgeClient.java`；事件模型见 `../common-event-contract/AGENTS.md` | -| 海运订舱与船期 | `oceanbooking/controller/PlatformOceanBookingController.java`、`oceanbooking/service/OceanBookingService.java`、`portschedule/controller/PlatformCarrierScheduleQueryController.java`、`PlatformPortScheduleController.java`；订舱契约见 `src/main/resources/openapi/ocean-bookings-v1.yaml`，表结构见 `src/main/resources/db/phase3-ocean-booking-schema.sql` | +| 三期海运订舱与出仓前船期资料 | `oceanbooking/controller/PlatformOceanBookingController.java`、`oceanbooking/service/OceanBookingService.java`、`portschedule/controller/PlatformPortScheduleController.java`；订舱契约见 `src/main/resources/openapi/ocean-bookings-v1.yaml`，表结构见 `src/main/resources/db/phase3-ocean-booking-schema.sql` | +| 四期国内出仓后船节点定时查询 | 现有 `portschedule/controller/PlatformCarrierScheduleQueryController.java`、`service/CarrierScheduleQueryService.java` 及查询任务、尝试、历史整体归四期；新增定时编排、节点事实或到港衔接继续归该子域，外部船司/轨迹调用经 `integration-service/`；范围见 `../../docs/四期/README.md` | | Firstleg 业务单据编号 | `service/FirstlegDocumentNumberGenerator.java`；当前支持 `OB`、`TA`、`CB`、`CAB`、`LP` 前缀，按北京时间每日独立编号；具体业务归属以各调用服务为准 | | 拖车与出仓调度 | `controller/PlatformTruckAppointmentController.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java` | | 报关协同 | `customs/controller/PlatformCustomsController.java`、`MerchantCustomsController.java` | @@ -48,6 +49,7 @@ - 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合，放舱后永久只读。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。 - 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。 - 订舱号统一使用 `OB-yyMMdd-####`，按北京时间创建日每日独立递增且单日最多 9999；不得以实体 ID 拼接生成。放舱不要求真实柜号，也不得为满足放舱校验伪造柜号。 +- 四期船节点任务从确认柜子离开国内仓库后启用，必须绑定真实订舱和柜次，保存来源、节点观测时间、最近成功结果、失败尝试及完整历史，并以幂等方式把确认到港/可提柜结果衔接给海外区域。现有 `CarrierScheduleQuery` 及“每 3 天一次、窗口最多 3 次”约束属于四期；外部失败不得推进业务节点，不得在三期另建查询任务。 - Firstleg 只拥有业务费用及履约事实；Finance 拥有费用入池、账期、账单、收款、成本分摊结果和财务状态。修改费用来源版本、发布条件、柜次归属或体积快照时同步检查 `../finance/src/main/java/com/baiyue/finance/client/FirstlegFeeSourceClient.java`、同目录 `FirstlegCostSnapshotClient.java` 及双方契约测试，不在 Firstleg 复制财务状态机。 ## 三期装柜与 PDA 资源结算 diff --git a/integration-service/AGENTS.md b/integration-service/AGENTS.md index b7e48949b..72926fad5 100644 --- a/integration-service/AGENTS.md +++ b/integration-service/AGENTS.md @@ -2,7 +2,7 @@ ## 职责与边界 -- 负责百度 OCR、Amazon Logistics/SP-API 等第三方适配和能力开关；不保存业务主数据。 +- 负责百度 OCR、Amazon Logistics/SP-API、四期船司/船舶轨迹查询等第三方适配和能力开关；不保存业务主数据。 - 二期重量 OCR 由 `file/` 调用；本服务只返回识别结果，不保存 `file_object`、入库单或重量确认记录。 ## 模块入口与验证 @@ -11,11 +11,13 @@ - 内部接口：`controller/IntegrationProviderController.java`、`WeightOcrController.java` - OCR 编排：`service/ocr/WeightOcrBatchService.java`、`ImageCropper.java`、`WeightCandidateSelector.java` - 供应商适配：`provider/IntegrationProviderAdapter.java`、`BaiduOcrAdapter.java`、`AmazonLogisticsAdapter.java` +- 四期船节点外部适配：继续进入 `provider/` 和内部接口层；轮询任务、订舱/柜次关联、最新节点和节点历史归 `firstleg/portschedule/`，范围见 `../../docs/四期/README.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/三期/`。 +- 全量验收按业务链路核对通用适配、File 重量 OCR 及已确认的报关协作契约；柜子确认国内出仓后的船司/船节点外部查询整体归四期，不再列作三期能力。外部调用必须保留来源、频率、限流、超时、最近有效结果和过期标识，凭证缺失按既定人工修正降级，不把未确认的自动化能力当作已实现契约。相关依据：`../../docs/一期/`、`../../docs/二期/`、`../../docs/三期/`、`../../docs/四期/`。 diff --git a/warehouse/AGENTS.md b/warehouse/AGENTS.md index d20a1b119..c888270b4 100644 --- a/warehouse/AGENTS.md +++ b/warehouse/AGENTS.md @@ -2,8 +2,9 @@ ## 职责与边界 -- 负责国内收货仓、地址/能力、往来单位、快递公司、平台公共供应商、国内整柜库存/出入库，以及托盘主数据、库位预占和占用。 +- 负责国内收货仓及现有平台仓库主数据、地址/能力、往来单位、快递公司、平台公共供应商、国内整柜库存/出入库，以及托盘主数据、库位预占和占用。四期只在本模块扩展“海外仓合作仓”仓库类型及其公共主数据契约。 - 入库单、测量和入库状态归 `firstleg/`；订单只通过内部接口校验并保存快照。 +- 四期海外接柜、卸货、海外入库、换标、产品、箱号、库存和库内作业属于海外区域服务，不得落入本国内 Warehouse Service；范围先读 `../../docs/四期/README.md`。 - 公共资源统一 `tenant_id=0`，不得绑定客户或要求客户筛选。 ## 模块入口 @@ -11,6 +12,7 @@ | 目标 | 入口 | |---|---| | 仓库/地址/能力 | `controller/PlatformWarehouseController.java`、`MerchantWarehouseController.java`、`service/WarehouseApplicationService.java` | +| 四期海外仓合作仓类型 | 沿用仓库/地址/能力入口；同步核对仓库 DTO、OpenAPI、`src/main/resources/db/`、统一 SQL 及 Admin `modules/warehouses/`，并与普通海外仓语义明确区分 | | 往来单位/快递 | `controller/PlatformPartnerController.java`、`PlatformExpressCompanyController.java`、`service/PlatformPartnerQueryService.java`、`PartnerImportService.java` | | 托盘 | `controller/PlatformPalletController.java`、`service/PalletApplicationService.java` | | 库位与分配 | `controller/PlatformLocationController.java`、`InternalPalletLocationController.java`、`service/PalletLocationAllocationService.java` |