fix: retain appointment cancellation reasons and query history

2026-10-11 13:26:00 +08:00
parent d4b72594ab
commit 43494cbfa3
11 changed files with 255 additions and 14 deletions
@@ -34,9 +34,17 @@ paths:
        schema: {type: string}
    delete:
      summary: 取消未关联有效排车的预约并释放占用
-      description: '平台专用，权限platform:appointment:delete。校验版本后保留主单、确认事实及明细历史，设置CANCELLED并释放货源占用；不删除客户货物或回退库存。已有关联有效排车时拒绝。取消命令按系统单号、版本和操作者幂等。'
-      parameters:
-        - {name: version, in: query, required: true, schema: {type: integer, minimum: 0}}
+      description: '平台专用，权限platform:appointment:delete。校验版本后保留主单、确认事实及明细历史，设置CANCELLED并释放货源占用；不删除客户货物或回退库存。已有关联有效排车时拒绝。取消原因必填，独立保存于取消命令历史，不覆盖原业务备注；按系统单号、版本、操作者及原因校验幂等，异内容拒绝。'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [version, cancelReason]
+              properties:
+                version: {type: integer, minimum: 0}
+                cancelReason: {type: string, minLength: 1, maxLength: 1000, description: 实际取消原因，不能仅含空白}
      responses:
        '200': {description: 业务响应，成功code为字符串200；版本冲突或已关联排车返回业务错误}
        '403': {description: 无删除权限}
@@ -63,6 +71,93 @@ paths:
      responses:
        '200': {$ref: '#/components/responses/AppointmentResult'}
        '403': {description: 无写权限}
+  /api/platform/v1/last-leg/inbound-plans/fba-appointments/cancellations:
+    get:
+      summary: 分页发现预约快捷取消记录
+      description: '仅平台；权限同详情：platform:appointment:list或platform:overseas-warehouse:inbound-order:list。仅取消命令摘要，不扩展普通编辑历史。服务端分页，不逐行读取详情；按取消时间倒序。'
+      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含records、page、size、total、pages
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    type: object
+                    properties:
+                      page: {type: integer}
+                      size: {type: integer}
+                      total: {type: integer, format: int64}
+                      pages: {type: integer, format: int64}
+                      records:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            appointmentNo: {type: string}
+                            version: {type: integer}
+                            cancelReason: {type: string, nullable: true}
+                            cancelledAt: {type: string, description: UTC取消时间}
+                            fbaWarehouseCode: {type: string}
+                            selectedCount: {type: integer}
+        '400': {description: 分页参数无效}
+        '403': {description: 非平台身份或无读取权限}
+  /api/platform/v1/last-leg/inbound-plans/fba-appointments/{appointmentNo}/cancellations:
+    get:
+      summary: 分页读取此预约的快捷取消命令历史
+      description: '仅平台；权限同预约详情：platform:appointment:list或platform:overseas-warehouse:inbound-order:list。按预约业务号限定，最新取消在前。不包含普通编辑记录，不返回原始JSON、命令键或内部账号ID；历史缺原因返回null，不回填。'
+      parameters:
+        - {name: appointmentNo, in: path, required: true, schema: {type: string}}
+        - {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
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data:
+                    type: object
+                    properties:
+                      page: {type: integer}
+                      size: {type: integer}
+                      total: {type: integer, format: int64}
+                      pages: {type: integer, format: int64}
+                      records:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            appointmentNo: {type: string}
+                            version: {type: integer, description: 取消后版本}
+                            cancelReason: {type: string, nullable: true}
+                            cancelledAt: {type: string, description: UTC取消命令时间，yyyy-MM-ddTHH:mm:ss}
+                            snapshot:
+                              type: object
+                              properties:
+                                fbaWarehouseCode: {type: string}
+                                appointmentStatus: {type: string}
+                                appointmentRemark: {type: string, nullable: true, description: 原业务备注}
+                                plannedDate: {type: string, format: date, nullable: true}
+                                plannedAt: {type: string, nullable: true}
+                                plannedEndAt: {type: string, nullable: true}
+                                confirmationNo: {type: string, nullable: true}
+                                appointmentAt: {type: string, nullable: true}
+                                appointmentEndAt: {type: string, nullable: true}
+                                timezone: {type: string, nullable: true}
+                                selectedCount: {type: integer}
+        '400': {description: 分页参数无效}
+        '403': {description: 非平台身份或无详情读取权限}
+        '404': {description: 预约不存在}
  /api/platform/v1/last-leg/inbound-plans/fba-appointments/calendar:
    get:
      operationId: fbaAppointmentCalendar