Merge remote-tracking branch 'origin/test' into dev

# Conflicts:
#	order/AGENTS.md
#	scripts/agents-index-contract.ps1

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -181,6 +181,37 @@ paths:
             schema: {$ref: '#/components/schemas/OrderApprovedInboundCommand'}
       responses:
         '200': {description: 成功或业务失败；相同客户和订单重放返回已有入库单 ID}
+  /internal/firstleg/v1/inbounds/order-channel-changes/validate:
+    post:
+      summary: Order 审核后变更渠道的 Firstleg 履约只读门禁
+      description: >-
+        严格按客户和订单校验同柜组渠道兼容性、分柜、预装、PDA及装柜事实。
+        已存在不可逆履约事实时返回 A0409；不会拆组、删除计划或修改任何作业事实。
+      security:
+        - internalServiceToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/OrderChannelChangeValidationRequest'}
+      responses:
+        '200': {description: 成功时 data 返回订单版本、新渠道和当前统一履约状态；冲突时响应体 code=A0409}
+  /internal/firstleg/v1/inbounds/order-declaration-updated:
+    post:
+      summary: 按 eventId 幂等、按订单 version 单调消费客户申报快照
+      description: >-
+        只更新客户备注、预计到仓时间、渠道镜像和独立货物申报 JSON 快照；入仓码和唛头保持不变，
+        不覆盖箱码、实测重量体积、托盘、库位、PDA、装柜或已确认计费事实。
+        相同 eventId 同负载安全重放，旧版本不覆盖新版本，同版本异事件返回 A0409。
+      security:
+        - internalServiceToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/OrderDeclarationUpdatedEvent'}
+      responses:
+        '200': {description: 成功、幂等重放或旧版本已忽略；冲突时响应体 code=A0409}
   /internal/firstleg/v1/inbounds/unified-orders/query:
     post:
       summary: 按统一订单条件分页查询履约摘要（Order 内部）
@@ -1042,6 +1073,36 @@ components:
       required: true
       schema: {type: string, pattern: '^[1-9][0-9]*$'}
   schemas:
+    OrderChannelChangeValidationRequest:
+      type: object
+      additionalProperties: false
+      required: [tenantId, orderId, orderVersion, channelCode]
+      properties:
+        tenantId: {type: integer, format: int64, minimum: 1}
+        orderId: {type: integer, format: int64, minimum: 1}
+        orderVersion: {type: integer, format: int64, minimum: 0}
+        channelCode: {type: string, minLength: 1, maxLength: 64}
+    OrderDeclarationUpdatedEvent:
+      type: object
+      additionalProperties: false
+      required: [schemaVersion, eventId, tenantId, orderId, orderNo, inboundCode, version, operatorId, occurredAt, channelCode, channelName, channelChanged, cargoes, changes]
+      properties:
+        schemaVersion: {type: integer, enum: [1]}
+        eventId: {type: string, minLength: 1, maxLength: 128}
+        tenantId: {type: integer, format: int64, minimum: 1}
+        orderId: {type: integer, format: int64, minimum: 1}
+        orderNo: {type: string, minLength: 1}
+        inboundCode: {type: string, minLength: 1, maxLength: 40, description: 仅作一致性校验，绝不修改 Firstleg 入仓码或唛头}
+        version: {type: integer, minimum: 0}
+        operatorId: {type: integer, format: int64, minimum: 1}
+        occurredAt: {type: string, format: date-time}
+        customerRemark: {type: string, nullable: true, maxLength: 1000}
+        expectedArrivalAt: {type: string, format: date-time, nullable: true}
+        channelCode: {type: string, minLength: 1, maxLength: 64}
+        channelName: {type: string, minLength: 1, maxLength: 128}
+        channelChanged: {type: boolean}
+        cargoes: {type: array, minItems: 1, maxItems: 500, items: {type: object, description: 与 OrderDeclarationDtos.Cargo 字段完全一致}}
+        changes: {type: array, items: {type: object, description: 与 OrderDeclarationDtos.FieldChange 字段完全一致}}
     OrderChannelChangePricingRequest:
       type: object
       additionalProperties: false