优化

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

@@ -153,8 +153,8 @@ paths:
       responses: {'200': {description: 成功或业务失败}, '403': {description: 无权限}}
   /api/platform/v1/inbounds/{inboundId}/fees/published:
     put:
-      summary: 调整已发布费用
-      description: 需要 firstleg:fba-pricing:adjust 权限；生成新 SENT 版本并将旧版本标记 SUPERSEDED，不回退 WAIT_SPLIT 状态。
+      summary: 调整初算或已发布费用
+      description: 需要 firstleg:fba-pricing:adjust 权限；人工修改计费量、单价和附加费，小计与总额由服务端重算并生成新版本，不回退 WAIT_SPLIT 状态。调整 CALCULATED/CONFIRMED 时生成新的 CALCULATED 版本；调整 SENT 时生成新的 SENT 版本并发布调整事件。
       parameters: [{$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -175,9 +175,11 @@ components:
   schemas:
     AdjustFeeRequest:
       type: object
-      required: [subtotalAmount, additionalAmount, reason]
+      required: [expectedFeeVersion, chargeableQuantity, unitPrice, additionalAmount, reason]
       properties:
-        subtotalAmount: {type: number, minimum: 0, multipleOf: 0.01}
+        expectedFeeVersion: {type: integer, minimum: 1}
+        chargeableQuantity: {type: number, exclusiveMinimum: 0, description: 计费量，单位沿用当前费用快照的 chargeUnit}
+        unitPrice: {type: number, minimum: 0, description: 人工确认单价}
         additionalAmount: {type: number, minimum: 0, multipleOf: 0.01}
         reason: {type: string, minLength: 1, maxLength: 500}
     CalculateRequest:

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

@@ -356,7 +356,7 @@ paths:
               type: object
               required: [boxCode, length, width, height, machineNo, picture]
               properties:
-                boxCode: {type: string, maxLength: 128, example: 'RK-2085911321565003778#4-1'}
+                boxCode: {type: string, maxLength: 128, example: 'ZBYHK2608140897#4-1'}
                 shipment_id: {type: string, maxLength: 64, example: 'FBA19L5KMY2CU000002', description: '可选；设备从Amazon FBA箱标实际扫描得到，有则原样上传；系统只保存，不生成且不覆盖客户下单值'}
                 length: {type: number, format: decimal, minimum: 0.001}
                 width: {type: number, format: decimal, minimum: 0.001}
@@ -558,7 +558,7 @@ paths:
   /api/platform/v1/inbounds/{inboundId}/measurements/approve:
     post:
       summary: 审核通过测量
-      description: 需要 firstleg:inbound:measurement-review 权限。审核事务提交后服务端自动执行计费、费用发布和入库编排并返回费用快照；若后续编排失败，审核结果保持已提交，使用同一 Idempotency-Key 重试将从持久化阶段继续，接口不会伪造 WAIT_SPLIT。
+      description: 需要 firstleg:inbound:measurement-review 权限。审核通过后立即进入 WAIT_SPLIT，并按该次测量数据尽力生成 CALCULATED 初算费用；价格未覆盖或初算异常只返回非阻断提示，不影响审核结果和待分柜状态。
       parameters:
         - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
         - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
@@ -575,7 +575,7 @@ paths:
                 expectedVersion: {type: integer, minimum: 0}
                 reason: {type: string, maxLength: 1000}
       responses:
-        '200': {description: 成功或业务失败，按响应体 code 判断；成功 data 为 FeeSnapshotResponse 且 nextStatus=WAIT_SPLIT；失败可能表示审核已提交但自动编排尚未完成、版本冲突或费用/仓库门禁失败，不得据此推断 WAIT_SPLIT}
+        '200': {description: 成功或业务失败，按响应体 code 判断；审核成功 data.processStatus 固定为 WAIT_SPLIT，initialPricingSucceeded 表示是否同时生成初算费用，初算失败时 feeStatus=UNPRICED 且主流程仍成功}
   /api/platform/v1/inbounds/{inboundId}/measurements/reject:
     post:
       summary: 驳回测量
@@ -982,7 +982,7 @@ components:
         tenantId: {type: string, pattern: '^[1-9][0-9]*$', description: 当前客户隔离 ID}
         orderId: {type: string, pattern: '^[1-9][0-9]*$'}
         orderNo: {type: string, nullable: true}
-        inboundCode: {type: string, minLength: 1, maxLength: 40, example: RK-2085308606829346818}
+        inboundCode: {type: string, minLength: 1, maxLength: 40, example: ZBYHK2608140897}
         customerId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
         customerName: {type: string, minLength: 1}
         warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
@@ -1217,7 +1217,7 @@ components:
         eventNo: {type: string, maxLength: 128, pattern: '^[A-Za-z0-9._:-]+$', example: M202608010001}
         externalDetailNo: {type: string, maxLength: 128, pattern: '^[A-Za-z0-9._:-]+$', example: BOX-20260801-0001}
         warehouseCode: {type: string, maxLength: 50, example: CN-YW-01}
-        inboundCode: {type: string, maxLength: 40, example: RK202608010001}
+        inboundCode: {type: string, maxLength: 40, example: ZBYHK2608140897}
         inboundDetailId: {type: string, example: '190000000000000001', description: 柏悦订单货物明细ID}
         deviceCode: {type: string, maxLength: 64, example: DEVICE-01}
         measuredAt: {type: string, format: date-time, example: '2026-08-01T10:30:00+08:00'}

firstleg/src/main/resources/openapi/phase3-container-overview-v1.yaml

@@ -11,6 +11,12 @@ paths:
     parameters: [{$ref: '#/components/parameters/ContainerId'}]
     post: {operationId: markContainerException, description: '权限：platform:firstleg:container:edit', parameters: [{name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}], requestBody: {$ref: '#/components/requestBodies/ExceptionRequest'}, responses: {'200': {description: OK}}}
     delete: {operationId: cancelContainerException, description: '权限：platform:firstleg:container:edit', parameters: [{name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}], requestBody: {$ref: '#/components/requestBodies/ExceptionRequest'}, responses: {'200': {description: OK}}}
+  /api/platform/v1/containers/{id}/pda/photos/{fileId}/download:
+    get:
+      operationId: downloadContainerPdaPhoto
+      description: '权限：platform:firstleg:container:list；Firstleg按柜次、装柜计划、入库单和文件归属代理下载，不暴露内部服务令牌'
+      parameters: [{$ref: '#/components/parameters/ContainerId'}, {name: fileId, in: path, required: true, schema: {type: integer, format: int64}}]
+      responses: {'200': {description: photo bytes, content: {application/octet-stream: {schema: {type: string, format: binary}}}}, '404': {description: photo missing or not owned by the container}}
   /api/platform/v1/containers/{id}/documents/{documentType}:
     get:
       operationId: getContainerDocument
@@ -50,7 +56,7 @@ components:
         exceptionHistory: {type: array, items: {$ref: '#/components/schemas/ExceptionHistory'}}
         timeline: {type: array, items: {$ref: '#/components/schemas/TimelineEntry'}}
     Container: {type: object, properties: {id: {type: integer, format: int64}, bookingNo: {type: string}, cabinetNo: {type: string}, containerNo: {type: string}, status: {type: string}, warehouseId: {type: integer, format: int64}, warehouseName: {type: string}, voyageNo: {type: string}, vesselName: {type: string}, version: {type: integer, minimum: 0}}}
-    PdaSummary: {type: object, properties: {taskId: {type: integer, format: int64}, loadingPlanId: {type: integer, format: int64}, containerBookingId: {type: integer, format: int64}, taskStatus: {type: string}, taskVersion: {type: integer}, itemCount: {type: integer}, completedItemCount: {type: integer}, unresolvedItemCount: {type: integer}, photoCounts: {type: array, items: {$ref: '#/components/schemas/PhotoCount'}}, photos: {type: array, items: {$ref: '#/components/schemas/Photo'}}, exceptionReasons: {type: array, items: {type: string}}}}
+    PdaSummary: {type: object, properties: {taskId: {type: integer, format: int64}, loadingPlanId: {type: integer, format: int64}, containerBookingId: {type: integer, format: int64}, taskStatus: {type: string, description: '持久化任务态：LOADING/COMPLETED'}, workflowStatus: {type: string, enum: [IN_PROGRESS, AWAITING_REVIEW, COMPLETED], description: 'PDA作业展示态'}, taskVersion: {type: integer}, itemCount: {type: integer}, completedItemCount: {type: integer}, unresolvedItemCount: {type: integer}, photoCounts: {type: array, items: {$ref: '#/components/schemas/PhotoCount'}}, photos: {type: array, items: {$ref: '#/components/schemas/Photo'}}, exceptionReasons: {type: array, items: {type: string}}}}
     PhotoCount: {type: object, properties: {evidenceType: {type: string}, count: {type: integer}}}
     Photo: {type: object, properties: {evidenceId: {type: integer, format: int64}, tenantId: {type: integer, format: int64}, inboundId: {type: integer, format: int64}, evidenceType: {type: string}, fileId: {type: integer, format: int64}, fileName: {type: string}, status: {type: string}, downloadPath: {type: string}, uploadedAt: {type: string, format: date-time}}}
     Document: {type: object, properties: {id: {type: integer, format: int64}, documentType: {type: string}, fileId: {type: integer, format: int64}, fileName: {type: string}, fileHash: {type: string}, uploadedBy: {type: integer, format: int64}, uploadedByName: {type: string}, uploadedAt: {type: string, format: date-time}, version: {type: integer}, completed: {type: boolean}}}

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

@@ -24,7 +24,7 @@ paths:
     get:
       summary: Query a truck appointment
       responses:
-        '200': {description: Appointment detail}
+        '200': {description: Appointment detail, content: {application/json: {schema: {$ref: '#/components/schemas/DetailStableReferences'}}}}
     put:
       summary: Update an editable truck appointment with optimistic locking
       requestBody:
@@ -78,16 +78,20 @@ paths:
     parameters: [{$ref: '#/components/parameters/AppointmentId'}]
     get:
       summary: Query attachment references owned by the appointment
+      description: 'Requires platform:firstleg:truck-appointment:list.'
       responses:
-        '200': {description: Attachment references}
+        '200': {description: Attachment references, content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/Attachment'}}}}}
     post:
       summary: Reference a file already owned by the appointment customer and business scope
+      description: 'Requires platform:firstleg:truck-appointment:edit. The file must belong to customerId + TRUCK_APPOINTMENT_ATTACHMENT + appointmentId.'
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/AttachmentRequest'}}}}
       responses:
-        '200': {description: Created attachment reference}
+        '200': {description: Created attachment reference, content: {application/json: {schema: {$ref: '#/components/schemas/Attachment'}}}}
   /api/platform/v1/truck-appointments/{id}/attachments/upload:
     parameters: [{$ref: '#/components/parameters/AppointmentId'}]
     post:
       summary: Upload and reference a truck appointment attachment
+      description: 'Requires platform:firstleg:truck-appointment:edit.'
       requestBody:
         required: true
         content:
@@ -96,7 +100,7 @@ paths:
               type: object
               required: [file]
               properties:
-                attachmentType: {type: string, maxLength: 32}
+                attachmentType: {type: string, maxLength: 64}
                 file: {type: string, format: binary}
       responses:
         '200': {description: Uploaded attachment reference}
@@ -106,6 +110,7 @@ paths:
       - {$ref: '#/components/parameters/AttachmentId'}
     delete:
       summary: Delete an attachment reference owned by the appointment
+      description: 'Requires platform:firstleg:truck-appointment:edit. Deletes the appointment reference only; the File object is retained.'
       responses:
         '200': {description: Reference deleted}
 components:
@@ -122,6 +127,26 @@ components:
     IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
     RequestHash: {name: X-Request-Hash, in: header, required: false, schema: {type: string, pattern: '^[0-9a-fA-F]{64}$'}}
   schemas:
+    AttachmentRequest:
+      type: object
+      required: [fileId]
+      properties:
+        fileId: {type: integer, format: int64, minimum: 1}
+        attachmentType: {type: string, maxLength: 64}
+        fileName: {type: string, maxLength: 255, description: Ignored; authoritative metadata comes from File service}
+        fileHash: {type: string, maxLength: 128, description: Ignored; authoritative metadata comes from File service}
+    Attachment:
+      type: object
+      properties:
+        id: {type: integer, format: int64}
+        appointmentId: {type: integer, format: int64}
+        fileId: {type: integer, format: int64}
+        attachmentType: {type: string}
+        fileName: {type: string}
+        fileHash: {type: string}
+        visibility: {type: string, enum: [PLATFORM]}
+        uploadedBy: {type: integer, format: int64}
+        uploadedAt: {type: string, format: date-time}
     ActionRequest:
       type: object
       required: [expectedVersion]
@@ -137,3 +162,23 @@ components:
         loadingPlanId: {type: integer, format: int64, minimum: 1}
         plannedLoadingAt: {type: string, format: date-time}
         expectedVersion: {type: integer, minimum: 0}
+    DetailStableReferences:
+      type: object
+      description: Stable IDs plus server-resolved saved resource names returned by appointment detail.
+      properties:
+        oceanBookingId: {type: integer, format: int64}
+        oceanBookingNo: {type: string}
+        containerBookingId: {type: integer, format: int64}
+        cabinetNo: {type: string}
+        containerNo: {type: string, nullable: true}
+        loadingPlanId: {type: integer, format: int64}
+        warehouseId: {type: integer, format: int64}
+        warehouseName: {type: string}
+        customerId: {type: integer, format: int64}
+        customerName: {type: string, description: Frozen from the associated ocean booking; request input cannot override it}
+        shippingCompanyId: {type: integer, format: int64}
+        shippingCompanyName: {type: string}
+        bookingAgentId: {type: integer, format: int64}
+        bookingAgentName: {type: string}
+        carrierId: {type: integer, format: int64}
+        carrierName: {type: string}