baiyue-firstleg/firstleg/AGENTS.md

Firstleg Service 模块指引

数据库访问与中文注释约束

• 强制继承 ../AGENTS.md 的“数据库访问与中文代码注释”全部规则；该节为分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处。根规则已在上下文时不重复读取，本服务不另设例外。

职责与边界

• Mapper 统一显式使用 @Mapper，仅由 BaiyueFirstlegApplication.java 对 com.baiyue.firstleg 根包按 annotationClass = Mapper.class 扫描；禁止恢复业务子域 Mapper 包白名单。静态门禁见根 scripts/mapper-scan-contract.mjs，模块内编译门禁见 MapperRegistrationArchitectureTest.java、BaiyueFirstlegApplicationContractTest.java。
• 负责履约任务/分配、入库单、测量/OCR、审核后初始计价、FBA 计费、客户在途柜量统计、国内出仓履约链路，以及海外仓业务国内出仓后的船节点查询任务和节点事实。
• 订单主数据归 order/，托盘/库位归 warehouse/，文件对象归 file/，OCR 供应商归 integration-service/；通过客户端 DTO 和内部令牌协作。
• 入库、分柜、装柜、PDA 和出仓能力均在本模块按对应服务端契约协作；WAIT_SPLIT + APPROVED + CONFIRMED 是入库链路状态节点，不是全量验收的范围终点。财务状态仍归 finance，本模块只生产不可变费用来源和柜次成本快照。

快速定位与读取边界

• 先按下表定位目标类，已知文件则直接进入；数据库分层与中文注释遵循后端根规则，已提供的指引不重复加载。
• 代码包路径相对 src/main/java/com/baiyue/firstleg/；src/、docs/、scripts/、../ 和 ../../ 路径相对本服务目录。裸类名在所属包用 rg --files 定位。
• 业务详细索引 是本服务业务细则的维护处；用 rg -n -F '任务词或类名' firstleg/docs/business-index.md 从后端根读取命中段。代码定位、纯文案或不改变业务语义的局部重构不默认加载全文。
• 涉及状态、字段、金额、权限、库存资源或事件时，修改前必须核对该索引对应入口及相关“修改约束”“国内货柜履约装柜与 PDA 资源结算”条款；只找到了类名不能替代业务规则核对。
• 主表只维护关键词、首个代码入口和细则检索词，不复制 DTO、状态机、算法或验收进度；业务规则只在详细索引或其指定正式契约修改。

模块入口

目标	首个代码入口与细则检索词
履约分配、入库查询、客户工作台	controller/PlatformFulfillmentAssignmentController.java、service/InboundOrderQueryService.java、service/MerchantWorkbenchFilterService.java；查“履约任务/分配”“客户工作台筛选范围”
入库单扣货、履约门禁与凭证	service/InboundHoldService.java、service/InboundHoldGuard.java；查“入库单扣货”
Order 申报同步与渠道变更履约门禁	service/OrderDeclarationSyncService.java、controller/InternalInboundOrderController.java；查“Order 申报同步”
测量/OCR、墨家设备	service/InboundMeasurementService.java、service/MojiaMeasurementOpenApiService.java；查“平台测量/OCR”“墨家设备测量上传”
箱唛箱码生成、打印与测量绑定	service/InboundCartonLabelService.java、service/InboundCartonLabelPrintService.java；查“稳定箱码”“箱唛箱码”
一件代发清点组托	service/DropshipPalletizationService.java；查“一件代发测量后 PDA 清点组托”“fl_inbound_carton_label_sku”
称重确认、整票库位块、部分拣货结算	service/MeasurementLocationOccupationService.java、service/MeasurementSubmissionService.java；查“首张称重图片”“删除称重图片”“PDA 部分拣货”
审核与初始计价	service/MeasurementReviewService.java、service/InitialInboundPricingService.java；查“测量审核通过”
客户四档箱规与默认算法	service/CustomerDimensionConfigService.java、service/CustomerDimensionWeightingService.java；查“客户箱规配置”
FBA 计价、客户专属价格簿、柜级阶梯运费	service/FbaPricingService.java、service/PlatformPriceBookService.java、pricing/ContainerTierAmountAllocator.java；查“客户专属价格簿、柜级阶梯运费与调价边界”
费用项目、价格簿查询内部切片	controller/PlatformFeeItemController.java、pricebookquery/application/PriceBookQueryService.java；查“价格簿查询内部切片”
入库费用、客户确认、直接已付	service/InboundFeeDetailService.java、service/MerchantInboundBillingService.java、service/FeePaymentSnapshotValidator.java；查“客户入库费用”“DIRECT_PAID”
柜次费用、跨客户分摊与财务快照	service/ContainerFeeDetailService.java、controller/InternalFinanceFeeSourceController.java、loading/service/FinanceCostSnapshotService.java；查“柜次费用明细与跨客户分摊组”
分柜、预装、正式装柜清单生命周期	service/LoadingListService.java、split/controller/PlatformSplitPreloadController.java；查“分柜、预装”“预装进入”
同柜不可拆组	loading/coload/service/ColoadGroupService.java；查“同柜不可拆组”及资源结算中的整组原子规则
货柜、全局智能排柜与候选	service/SmartLoadingService.java、controller/PlatformSmartLoadingController.java；查“货柜与全局智能排柜”“新增模拟柜”
PDA 拣货装柜、证据上传	controller/PlatformLoadingPdaController.java、loading/service/CabinetLoadingEvidenceService.java；查“PDA 拣货与装柜”“PDA 普通散箱拣货”
货柜资料、散货托盘码、业务单据编号	service/LoadingPalletLabelService.java、service/FirstlegDocumentNumberGenerator.java、mapper/ContainerOverviewMapper.java；查“柜次号与散货托盘码”“Firstleg 业务单据编号”
装柜完成、船节点直投及海外回写	service/LoadingCompletedOutboxRelay.java、portschedule/service/CarrierScheduleNodeOutboxService.java、controller/InternalOverseasContainerEventController.java；查“装柜完成直连事件”“海外派送完成回写”
订舱资料、订舱级拖车与整柜出仓	oceanbooking/service/OceanBookingService.java、service/TruckAppointmentService.java、outbound/dispatch/service/OutboundDispatchService.java；查“订舱级拖车”“供应商必须通过”
船节点查询、到港日历与预约来源	portschedule/service/CarrierScheduleQueryService.java、portschedule/service/AppointmentWorkSourceService.java、portschedule/controller/PlatformPortScheduleController.java；查“船节点定时查询”“已开船预约事项完整来源”“预约日历到港只读”
直送目的仓实际卸货、码头拖车与还空	terminaldrayage/service/DirectDeliveryService.java、terminaldrayage/service/TerminalDrayageService.java；查“直送目的仓实际卸货”“目的港码头拖车与还空预警”
整柜出口报关、买单明细导出	customs/container/service/ContainerCustomsService.java、customs/container/controller/LoadingListBuyDeclarationExportController.java；查“整柜出口报关”“买单订单明细导出 Provider”
首页指标、客户统计与在途柜量	dashboard/PlatformDashboardMetricsController.java、customerstatistics/application/CustomerTransitStatisticsService.java；查“首页实时指标”
跨模型桥接、供应商快照与服务客户端	loading/bridge/controller/PlatformLoadingModelBridgeController.java、service/WarehouseSupplierSnapshotService.java、client/；查“跨模型桥接”“仓库公共供应商快照”
事件人工重试	controller/EventOperationsController.java；查“事件人工重试”，仅内部运维身份操作
SQL、OpenAPI、模块化基线	src/main/resources/db/、src/main/resources/openapi/、docs/firstleg-internal-modularization-baseline.md；查“SQL/OpenAPI”“内部模块化基线与依赖分析”

修改边界与最低验证

• 平台接口核对目标客户、权限、版本、幂等、历史与审计；客户查询只使用认证客户。不得跨服务读库或在本模块复制 Order、Warehouse、Finance、File 的权威事实。
• Mapper 显式 @Mapper，只用启动类根包扫描；新增/移动 Mapper 或扫描配置变化时，从后端根执行 node scripts/mapper-scan-contract.mjs。
• Java 签名与行为变更分别遵循后端根的测试编译及直接受影响测试门禁；本模块测试从后端根执行 mvn -pl firstleg -am test。
• 移包或跨切片依赖变化时，从后端根执行 node --test firstleg/scripts/analyze-firstleg-dependencies.test.mjs 并核对内部模块化基线；禁止用基线更新掩盖临时循环依赖。
• 对外 API、数据库、公共签名、事件或权限变化按后端根对应门禁核对直接消费者，不为文档整理启动 Java、数据库、HTTP 或部署。
• 本文件或详细索引变更后，统一执行一次 ./scripts/agents-index-contract.ps1；详细条款迁移不得丢失业务语义，不提高读取预算掩盖增长。

全量验收导航

本服务覆盖测量计费、订单编排、装柜出仓及直接事件链。验收按受影响链路进入详细索引和正式业务域文档；PDA 设备证据与服务端合同分别核对，不以历史规划终点限制联调。仅作索引调整时运行离线门禁。