feat(appointments): unify pre-inbound planning and confirmed FBA bookings

lastleg-service/src/main/resources/openapi/appointment-planning-v1.yaml

@@ -6,6 +6,134 @@ info:
 security:
   - bearerAuth: []
 paths:
+  /api/platform/v1/last-leg/appointment-planning/appointments:
+    post:
+      operationId: createAppointmentFromSources
+      summary: 在入仓前按稳定货源保存跨客户预约安排
+      description: >-
+        仅平台；同时需要platform:appointment:list、platform:overseas-warehouse:last-mile-order:list及platform:overseas-warehouse:inbound-order:fba-appointment。
+        与入仓明细入口共用同一FBA预约聚合；系统生成AP单号，不创建入仓计划、库存或车次。
+        PENDING允许日期、时段、外部约号及箱数暂缺。SUCCESS必须有权威目的仓时区、真实货件材料、确定箱数及外部约号和确认时段。
+        实际客户、起运仓、目的仓及原BOOKING由服务端核对；活动来源与已形成订单均唯一占用，取消后释放并保留历史。
+        命令与主单、明细同事务；同键同操作人同内容重试返回原快照，不受后来编辑影响。异内容或来源占用冲突拒绝。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [sources, originWarehouseId, fbaWarehouseCode, details, idempotencyKey]
+              properties:
+                originWarehouseId: {type: string, minLength: 1, description: 选择货源时的接仓点，保存时重新核对}
+                fbaWarehouseCode: {type: string, minLength: 1, maxLength: 64, description: 选择货源时的目的仓编码，变化则拒绝保存}
+                sources:
+                  type: array
+                  minItems: 1
+                  maxItems: 100
+                  items:
+                    type: object
+                    required: [sourceKey, customerId]
+                    properties:
+                      sourceKey: {type: string, maxLength: 160}
+                      customerId: {type: string, maxLength: 128}
+                      destinationKey: {type: string}
+                details: {$ref: './fba-appointment-calendar-v1.yaml#/components/schemas/AppointmentDetails'}
+                idempotencyKey: {type: string, minLength: 1, maxLength: 64}
+      responses:
+        '200': {$ref: './fba-appointment-calendar-v1.yaml#/components/responses/AppointmentResult'}
+        '400': {description: 来源、时段或正式确认材料无效}
+        '403': {description: 权限不足或非平台身份}
+        '404': {description: 来源不存在或客户不匹配}
+        '409': {description: 同键异内容、版本或活动货物占用冲突}
+        '503': {description: 权威仓库目录或时区暂不可用}
+  /api/platform/v1/last-leg/appointment-planning/appointments/unscheduled:
+    get:
+      operationId: listUnscheduledAppointments
+      summary: 分页读取没有日期或时段的预约安排
+      description: 仅平台，权限platform:appointment:list；排除取消/失败，不用09点或零点占位。
+      parameters:
+        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
+        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
+      responses:
+        '200':
+          description: code=200时data为分页
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    type: object
+                    properties:
+                      records: {type: array, items: {$ref: './fba-appointment-calendar-v1.yaml#/components/schemas/Appointment'}}
+                      total: {type: integer}
+                      page: {type: integer}
+                      size: {type: integer}
+                      pages: {type: integer}
+        '403': {description: 无列表权限或非平台身份}
+  /api/platform/v1/last-leg/appointment-planning/batches/preview:
+    post:
+      operationId: previewAppointmentBatch
+      summary: 核对跨客户同仓货源合批资格
+      description: >-
+        只读核对，不保存预约安排、不占货、不确认预约。仅平台，同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
+        最多100票，批量查询货源、实际开船节点和美国仓目录，支持ORDER与已确认承运BOOKING混合；同一订单重复别名拒绝。
+        必须同美国起运仓及同美国FBA目的仓；暂扣、多目的地、已有有效预约或已取消完成货源拒绝；未知箱数保留待核实，不填0。
+        未建入仓计划及尚未来货的已确认BOOKING不伪造计划、库存或入仓码；正式确认前必须核实箱数。
+        未接入权威备妥窗口时返回readinessIncomplete及READY_WINDOW_UNVERIFIED，不拿到港/到仓预测代替。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [sources]
+              properties:
+                sources:
+                  type: array
+                  minItems: 1
+                  maxItems: 100
+                  items:
+                    type: object
+                    required: [sourceKey, customerId]
+                    properties:
+                      sourceKey: {type: string, maxLength: 160}
+                      customerId: {type: string, maxLength: 128}
+                      destinationKey: {type: string, description: 可选预期目的地；存在时必须与来源一致}
+      responses:
+        '200':
+          description: code=200时data为本次核对结果，不是已保存单据
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data:
+                    type: object
+                    properties:
+                      originWarehouseName: {type: string}
+                      destinationWarehouseCode: {type: string}
+                      sources: {type: array, items: {$ref: '#/components/schemas/PlanningSource'}}
+                      missingFields: {type: array, items: {type: string}}
+                      group:
+                        type: object
+                        properties:
+                          originWarehouseId: {type: string}
+                          destinationKey: {type: string}
+                          packages: {type: integer, nullable: true}
+                          unknownQuantitySources: {type: integer}
+                          sourceCount: {type: integer}
+                          customerCount: {type: integer}
+                          readyFrom: {type: string, format: date-time, nullable: true}
+                          readyTo: {type: string, format: date-time, nullable: true}
+                          readinessIncomplete: {type: boolean}
+        '400': {description: 来源重复、跨仓、数量不明或不满足合批资格}
+        '403': {description: 权限不足或非平台身份}
+        '404': {description: 来源与客户不匹配}
+        '503': {description: 美国仓目录不可用}
   /api/platform/v1/last-leg/appointment-planning/containers:
     get:
       operationId: appointmentPlanningContainers
@@ -152,7 +280,7 @@ paths:
       description: >-
         仅平台；同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
         依据真实客户、货源与美国仓目录核对来源，URL参数不能授予预约资格。
-        ORDER仅接受已开船头程FBA货；BOOKING保留原登记身份，确认承运后尚未生成入仓单也能跟进。
+        ORDER接受已开船头程FBA货和没有外接登记的真实仓储转运；有原登记必须使用BOOKING稳定身份，确认承运后尚未生成入仓单也能跟进。
         此查询不建单、不确认预约。当前覆盖读取已有FBA预约，尚未生成货物时返回SOURCE_NOT_MATERIALIZED。
       parameters:
         - {name: sourceKey, in: query, required: true, schema: {type: string, maxLength: 160}, description: 'ORDER:<内部关联ID>或BOOKING:<登记号>，非用户展示编号'}

lastleg-service/src/main/resources/openapi/fba-appointment-calendar-v1.yaml

@@ -1,15 +1,15 @@
 openapi: 3.0.3
 info:
   title: 跨客户 FBA 预约与日历
-  version: 1.0.0
-  description: 按同一目的FBA仓合并多个客户的货物，预约号全局唯一。货物明细保留客户归属，只有平台可读取或维护完整预约；不改变库存与客户订单归属。
+  version: 2.0.0
+  description: 同一美国起运仓和目的FBA仓的跨客户安排。系统单号与外部约号分开；入仓前后共用稳定货源，只有平台可维护完整预约，不推进库存或现场作业。
 security:
   - bearerAuth: []
 paths:
   /api/platform/v1/last-leg/inbound-plans/fba-appointments/batch:
     post:
       summary: 为同一目的仓的跨客户入仓明细创建预约
-      description: '权限：platform:overseas-warehouse:inbound-order:fba-appointment。平台身份限定。客户归属由服务端入仓计划确定，不接受预约主单customerId；同号同内容重放返回原预约，异内容拒绝。已有有效预约的货物不能重复建约。'
+      description: '权限：platform:overseas-warehouse:inbound-order:fba-appointment。平台身份限定。入仓明细仅作选择入口，服务端转成原ORDER/BOOKING整票来源，不另建别名。系统生成appointmentNo，不接受主单客户或外部号冒充系统单号。同键、同操作者、同内容返回原命令快照；异内容拒绝。与入仓前货源入口共用同一主表及唯一占用约束。'
       requestBody:
         required: true
         content:
@@ -18,10 +18,11 @@ paths:
               allOf:
                 - {$ref: '#/components/schemas/AppointmentWrite'}
                 - type: object
-                  required: [lineIds, appointmentNo]
+                  required: [lineIds, originWarehouseId, fbaWarehouseCode]
                   properties:
-                    lineIds: {type: array, minItems: 1, maxItems: 500, items: {type: string}}
-                    appointmentNo: {type: string, maxLength: 64}
+                    originWarehouseId: {type: string, minLength: 1, description: 选择时的接仓点，保存时核对}
+                    fbaWarehouseCode: {type: string, minLength: 1, maxLength: 64, description: 选择时的目的仓，变化则拒绝}
+                    lineIds: {type: array, minItems: 1, maxItems: 100, items: {type: string}}
       responses:
         '200': {$ref: '#/components/responses/AppointmentResult'}
         '403': {description: 非平台身份或无写权限}
@@ -32,8 +33,8 @@ paths:
         required: true
         schema: {type: string}
     delete:
-      summary: 删除未关联有效排车的预约
-      description: '平台专用，权限platform:appointment:delete。校验当前版本后原子删除预约及预约明细，不删除客户货物。已有关联有效排车时拒绝。'
+      summary: 取消未关联有效排车的预约并释放占用
+      description: '平台专用，权限platform:appointment:delete。校验版本后保留主单、确认事实及明细历史，设置CANCELLED并释放货源占用；不删除客户货物或回退库存。已有关联有效排车时拒绝。取消命令按系统单号、版本和操作者幂等。'
       parameters:
         - {name: version, in: query, required: true, schema: {type: integer, minimum: 0}}
       responses:
@@ -47,7 +48,7 @@ paths:
         '403': {description: 无读取权限}
     put:
       summary: 按版本更新预约
-      description: '权限：platform:overseas-warehouse:inbound-order:fba-appointment。平台限定，版本冲突拒绝；取消不删除货物。恢复时重新校验货物是否已被其他有效预约占用。'
+      description: '权限：platform:overseas-warehouse:inbound-order:fba-appointment。平台限定，版本及持久化幂等校验；已有有效排车时先处理运输安排。取消/失败必须写原因并保留原确认时间。恢复时重新核对来源、目的仓和占用；不能直接将SUCCESS退回PENDING。'
       requestBody:
         required: true
         content:
@@ -66,7 +67,7 @@ paths:
     get:
       operationId: fbaAppointmentCalendar
       summary: 按日期范围查询 FBA 预约
-      description: '权限：platform:appointment:list。仅平台身份可读取跨客户预约。固定批量查询预约及关联明细，不逐预约查详情。'
+      description: '权限：platform:appointment:list。按确认当地时间、计划时段或仅计划日期选取，排除取消/失败。仅有日期时不补造零点时段；无日期记录走未定时分页入口。固定批量查询预约及明细，不逐预约查详情。跨时区总览仍需按地点标注，不将当地值当成浏览器时区。'
       parameters:
         - name: from
           in: query
@@ -110,22 +111,40 @@ components:
   schemas:
     AppointmentWrite:
       type: object
-      required: [appointmentAt, expectedLoadingAt, appointmentStatus]
+      required: [details, idempotencyKey]
       properties:
-        appointmentAt: {type: string, description: 预约开始日期时间}
+        details: {$ref: '#/components/schemas/AppointmentDetails'}
+        idempotencyKey: {type: string, minLength: 1, maxLength: 64}
+    AppointmentDetails:
+      type: object
+      required: [appointmentStatus]
+      properties:
+        plannedDate: {type: string, format: date, nullable: true, description: 计划当地日期，允许未定}
+        plannedAt: {type: string, nullable: true, description: 已知的计划开始当地时段，日期必须与plannedDate一致}
+        plannedEndAt: {type: string, nullable: true}
+        confirmationNo: {type: string, maxLength: 128, nullable: true, description: 仅SUCCESS登记收货方的外部约号；同一FBA仓不得重复}
+        appointmentAt: {type: string, nullable: true, description: 对方确认开始当地时间；SUCCESS必填，PENDING不能当作计划填写}
         appointmentEndAt: {type: string, nullable: true, description: 明确结束时间时必须晚于开始时间；未知留空，不推算}
-        expectedLoadingAt: {type: string}
         appointmentStatus: {type: string, enum: [PENDING, SUCCESS, FAILED, CANCELLED]}
         appointmentRemark: {type: string, maxLength: 1000, nullable: true}
+        startOffset: {type: string, maxLength: 6, nullable: true, description: 当地重叠时刻的明确时差；必须符合目的仓IANA时区}
+        endOffset: {type: string, maxLength: 6, nullable: true}
     Appointment:
       type: object
       properties:
         id: {type: string, description: 内部标识，不作为展示编号}
-        appointmentNo: {type: string}
-        appointmentAt: {type: string, description: 业务日期时间，不含时区偏移}
+        appointmentNo: {type: string, description: 系统生成AP业务单号}
+        confirmationNo: {type: string, nullable: true, description: 对方正式外部确认号}
+        plannedDate: {type: string, format: date, nullable: true}
+        plannedAt: {type: string, nullable: true}
+        plannedEndAt: {type: string, nullable: true}
+        appointmentAt: {type: string, nullable: true, description: 对方确认的地点当地时间}
         appointmentEndAt: {type: string, nullable: true}
         version: {type: integer, minimum: 0}
-        expectedLoadingAt: {type: string}
+        appointmentStartUtc: {type: string, format: date-time, nullable: true}
+        appointmentEndUtc: {type: string, format: date-time, nullable: true}
+        timezone: {type: string, nullable: true, description: 来自美国FBA仓主档的IANA时区；缺失不得正式确认}
+        originWarehouseId: {type: string}
         appointmentStatus: {type: string, enum: [PENDING, SUCCESS, FAILED, CANCELLED]}
         appointmentRemark: {type: string, nullable: true}
         fbaWarehouseCode: {type: string}
@@ -140,8 +159,9 @@ components:
             properties:
               id: {type: string}
               customerId: {type: string, description: 本票货物客户归属，不在预约主单指定客户}
-              planId: {type: string}
-              lineId: {type: string}
-              orderId: {type: string}
-              inboundCode: {type: string}
+              sourceKey: {type: string}
+              sourceVersion: {type: string, nullable: true}
+              orderId: {type: string, nullable: true}
+              inboundCode: {type: string, nullable: true}
+              packageCount: {type: integer, nullable: true}
               fbaWarehouseCode: {type: string}