feat(appointments): discover external booking candidates through fleet boundary

2026-10-10 14:03:42 +08:00
parent 369613a2e7
commit 71111bf21b
9 changed files with 265 additions and 0 deletions
@@ -6,6 +6,44 @@ info:
 security:
  - bearerAuth: []
 paths:
+  /api/platform/v1/last-leg/appointment-planning/external-candidates:
+    get:
+      operationId: listExternalAppointmentCandidates
+      summary: 分页发现已确认承运的美国FBA外接货
+      description: '仅平台；同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。按权威启用美国接仓点/FBA目录筛选原拼车登记，排除询价、取消和已完成车次。来货前后仅返回同一BOOKING来源；已有预约仍展示覆盖状态，不能重复加入。整页批量解析及核对覆盖，不逐条HTTP请求。'
+      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}}
+        - {name: warehouseId, in: query, schema: {type: string}}
+        - {name: destination, in: query, schema: {type: string}, description: 美国FBA仓码}
+        - {name: keyword, in: query, schema: {type: string, maxLength: 128}, description: 登记号、车次号、客户名称或来货号}
+      responses:
+        '200':
+          description: 业务响应；data为服务器分页结果
+          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:
+                            customerName: {type: string, nullable: true}
+                            tripNo: {type: string}
+                            source: {$ref: '#/components/schemas/PlanningSource'}
+                            coverage: {$ref: '#/components/schemas/Coverage'}
+        '403': {description: 非平台或缺少读取权限}
+        '503': {description: 仓库目录失败，不能当作无货}
  /api/platform/v1/last-leg/appointment-planning/appointments:
    post:
      operationId: createAppointmentFromSources