feat(firstleg): converge phase3 loading models and pda

firstleg/src/main/resources/db/phase3-loading-model-bridge-schema.sql

@@ -0,0 +1,65 @@
+SET NAMES utf8mb4;
+USE baiyue_firstleg;
+
+/* 入库单级预装与柜次级装柜计划的多对多关联；一单多柜和拼柜均通过关联行表达。 */
+CREATE TABLE IF NOT EXISTS fl_preload_loading_plan_link (
+  id BIGINT UNSIGNED NOT NULL COMMENT '关联ID',
+  tenant_id BIGINT UNSIGNED NOT NULL COMMENT '入库单客户隔离ID',
+  inbound_id BIGINT UNSIGNED NOT NULL COMMENT '入库单ID',
+  preload_plan_id BIGINT UNSIGNED NOT NULL COMMENT '入库单级预装计划ID',
+  loading_plan_id BIGINT UNSIGNED NOT NULL COMMENT '柜次级装柜计划ID',
+  idempotency_key VARCHAR(128) NOT NULL COMMENT '建立关联幂等键',
+  request_hash CHAR(64) NOT NULL COMMENT '建立关联请求SHA-256',
+  created_by BIGINT UNSIGNED NOT NULL,
+  created_by_name VARCHAR(64) NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_preload_loading_pair (tenant_id, inbound_id, loading_plan_id),
+  UNIQUE KEY uk_preload_loading_idempotency (created_by, idempotency_key),
+  KEY idx_preload_loading_preload (preload_plan_id, loading_plan_id),
+  KEY idx_preload_loading_plan (loading_plan_id, tenant_id, inbound_id),
+  CONSTRAINT fk_preload_loading_inbound FOREIGN KEY (inbound_id) REFERENCES fl_inbound_order (id),
+  CONSTRAINT fk_preload_loading_preload FOREIGN KEY (preload_plan_id) REFERENCES fl_preload_plan (id),
+  CONSTRAINT fk_preload_loading_plan FOREIGN KEY (loading_plan_id) REFERENCES fl_loading_plan (id),
+  CONSTRAINT chk_preload_loading_tenant CHECK (tenant_id > 0)
+) ENGINE=InnoDB COMMENT='入库单预装与柜次装柜计划多对多关联';
+
+/* 兼容已存在且可由活动装柜明细无歧义推导的关联。 */
+INSERT IGNORE INTO fl_preload_loading_plan_link
+  (id, tenant_id, inbound_id, preload_plan_id, loading_plan_id, idempotency_key,
+   request_hash, created_by, created_by_name, created_at)
+SELECT CAST(CONV(SUBSTRING(SHA2(CONCAT('PRELOAD_LOADING|', item.account_id, '|', item.inbound_id,
+                                      '|', item.loading_plan_id), 256), 1, 15), 16, 10) AS UNSIGNED),
+       item.account_id, item.inbound_id, preload.id, item.loading_plan_id,
+       CONCAT('BACKFILL-', item.loading_plan_id, '-', item.inbound_id),
+       SHA2(CONCAT('BACKFILL|', item.account_id, '|', item.inbound_id, '|', item.loading_plan_id), 256),
+       preload.created_by, preload.created_by_name, LEAST(preload.created_at, plan.created_at)
+  FROM (SELECT DISTINCT account_id, inbound_id, loading_plan_id
+          FROM fl_loading_plan_item WHERE deleted = 0) item
+  JOIN fl_preload_plan preload ON preload.tenant_id = item.account_id
+                              AND preload.inbound_id = item.inbound_id
+  JOIN fl_loading_plan plan ON plan.id = item.loading_plan_id;
+
+DROP PROCEDURE IF EXISTS assert_phase3_loading_model_bridge;
+DELIMITER $$
+CREATE PROCEDURE assert_phase3_loading_model_bridge()
+BEGIN
+  IF (SELECT COUNT(*) FROM information_schema.tables
+       WHERE table_schema = DATABASE() AND table_name = 'fl_preload_loading_plan_link') <> 1 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '装柜模型桥接表创建失败';
+  END IF;
+  IF (SELECT COUNT(DISTINCT index_name) FROM information_schema.statistics
+       WHERE table_schema = DATABASE() AND table_name = 'fl_preload_loading_plan_link'
+         AND index_name IN ('uk_preload_loading_pair', 'uk_preload_loading_idempotency',
+                            'idx_preload_loading_preload', 'idx_preload_loading_plan')) <> 4 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '装柜模型桥接索引不完整';
+  END IF;
+  IF (SELECT COUNT(*) FROM information_schema.key_column_usage
+       WHERE constraint_schema = DATABASE() AND table_name = 'fl_preload_loading_plan_link'
+         AND referenced_table_name IN ('fl_inbound_order', 'fl_preload_plan', 'fl_loading_plan')) <> 3 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '装柜模型桥接外键不完整';
+  END IF;
+END$$
+DELIMITER ;
+CALL assert_phase3_loading_model_bridge();
+DROP PROCEDURE IF EXISTS assert_phase3_loading_model_bridge;

firstleg/src/main/resources/db/phase3-pda-convergence-schema.sql

@@ -0,0 +1,133 @@
+SET NAMES utf8mb4;
+USE baiyue_firstleg;
+
+CREATE TABLE IF NOT EXISTS fl_loading_pick_assignment (
+  pick_task_id BIGINT UNSIGNED NOT NULL,
+  assignee_id BIGINT UNSIGNED NOT NULL,
+  assignee_name VARCHAR(64) NOT NULL,
+  assigned_by BIGINT UNSIGNED NOT NULL,
+  assigned_by_name VARCHAR(64) NULL,
+  assignment_type VARCHAR(16) NOT NULL COMMENT 'CLAIMED/ASSIGNED',
+  version INT UNSIGNED NOT NULL DEFAULT 0,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (pick_task_id),
+  KEY idx_loading_pick_assignee (assignee_id, updated_at),
+  CONSTRAINT fk_loading_pick_assignment_task FOREIGN KEY (pick_task_id) REFERENCES fl_loading_pick_task (id),
+  CONSTRAINT chk_loading_pick_assignment_type CHECK (assignment_type IN ('CLAIMED', 'ASSIGNED'))
+) ENGINE=InnoDB COMMENT='柜次PDA任务领取与作业员分配';
+
+CREATE TABLE IF NOT EXISTS fl_loading_pick_review (
+  pick_task_id BIGINT UNSIGNED NOT NULL,
+  review_status VARCHAR(16) NOT NULL DEFAULT 'APPROVED',
+  reviewed_by BIGINT UNSIGNED NOT NULL,
+  reviewed_by_name VARCHAR(64) NULL,
+  remark VARCHAR(500) NULL,
+  version INT UNSIGNED NOT NULL DEFAULT 0,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (pick_task_id),
+  KEY idx_loading_pick_reviewer (reviewed_by, created_at),
+  CONSTRAINT fk_loading_pick_review_task FOREIGN KEY (pick_task_id) REFERENCES fl_loading_pick_task (id),
+  CONSTRAINT chk_loading_pick_review_status CHECK (review_status = 'APPROVED')
+) ENGINE=InnoDB COMMENT='柜次PDA任务完成复核';
+
+CREATE TABLE IF NOT EXISTS fl_loading_pick_operation (
+  id BIGINT UNSIGNED NOT NULL,
+  pick_task_id BIGINT UNSIGNED NOT NULL,
+  operation_id VARCHAR(128) NOT NULL,
+  request_hash CHAR(64) NOT NULL,
+  action_type VARCHAR(16) NOT NULL COMMENT 'CLAIM/ASSIGN/REVIEW',
+  operator_id BIGINT UNSIGNED NOT NULL,
+  operator_name VARCHAR(64) NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_loading_pick_operation_id (operation_id),
+  KEY idx_loading_pick_operation_task (pick_task_id, created_at),
+  CONSTRAINT fk_loading_pick_operation_task FOREIGN KEY (pick_task_id) REFERENCES fl_loading_pick_task (id),
+  CONSTRAINT chk_loading_pick_operation_action CHECK (action_type IN ('CLAIM', 'ASSIGN', 'REVIEW'))
+) ENGINE=InnoDB COMMENT='柜次PDA任务级幂等审计';
+
+DROP TRIGGER IF EXISTS trg_loading_pick_review_before_update;
+DELIMITER $$
+CREATE TRIGGER trg_loading_pick_review_before_update
+BEFORE UPDATE ON fl_loading_pick_review
+FOR EACH ROW
+BEGIN
+  SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'PDA复核记录不可修改';
+END$$
+DELIMITER ;
+
+DROP TRIGGER IF EXISTS trg_loading_pick_review_before_delete;
+DELIMITER $$
+CREATE TRIGGER trg_loading_pick_review_before_delete
+BEFORE DELETE ON fl_loading_pick_review
+FOR EACH ROW
+BEGIN
+  SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'PDA复核记录不可删除';
+END$$
+DELIMITER ;
+
+DROP TRIGGER IF EXISTS trg_loading_pick_operation_before_update;
+DELIMITER $$
+CREATE TRIGGER trg_loading_pick_operation_before_update
+BEFORE UPDATE ON fl_loading_pick_operation
+FOR EACH ROW
+BEGIN
+  SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'PDA任务操作历史不可修改';
+END$$
+DELIMITER ;
+
+DROP TRIGGER IF EXISTS trg_loading_pick_operation_before_delete;
+DELIMITER $$
+CREATE TRIGGER trg_loading_pick_operation_before_delete
+BEFORE DELETE ON fl_loading_pick_operation
+FOR EACH ROW
+BEGIN
+  SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'PDA任务操作历史不可删除';
+END$$
+DELIMITER ;
+
+USE baiyue_iam;
+
+DROP PROCEDURE IF EXISTS assert_phase3_pda_permission_ids;
+DELIMITER $$
+CREATE PROCEDURE assert_phase3_pda_permission_ids()
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM iam_permission
+     WHERE id BETWEEN 5102190 AND 5102193
+       AND permission_code NOT IN (
+         'platform:firstleg:pda:view', 'platform:firstleg:pda:assign',
+         'platform:firstleg:pda:work', 'platform:firstleg:pda:review'
+       )
+  ) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'PDA权限ID已被其他资源占用';
+  END IF;
+END$$
+DELIMITER ;
+CALL assert_phase3_pda_permission_ids();
+DROP PROCEDURE assert_phase3_pda_permission_ids;
+
+INSERT INTO iam_permission
+  (id, tenant_id, app_code, permission_type, parent_id, permission_code,
+   permission_name, route_path, http_method, sort_no, status, built_in, deleted)
+VALUES
+  (5102190, 0, 'PLATFORM', 'MENU', 5102094, 'platform:firstleg:pda:view',
+   'PDA装柜拣货', '/first-leg/pda-loading', 'GET', 10, 'ACTIVE', 1, 0),
+  (5102191, 0, 'PLATFORM', 'BUTTON', 5102190, 'platform:firstleg:pda:assign',
+   '分配PDA任务', NULL, 'POST', 20, 'ACTIVE', 1, 0),
+  (5102192, 0, 'PLATFORM', 'BUTTON', 5102190, 'platform:firstleg:pda:work',
+   '执行PDA拣货', NULL, 'POST', 30, 'ACTIVE', 1, 0),
+  (5102193, 0, 'PLATFORM', 'BUTTON', 5102190, 'platform:firstleg:pda:review',
+   '复核PDA任务', NULL, 'POST', 40, 'ACTIVE', 1, 0)
+ON DUPLICATE KEY UPDATE
+  permission_name=VALUES(permission_name), parent_id=VALUES(parent_id), route_path=VALUES(route_path),
+  http_method=VALUES(http_method), sort_no=VALUES(sort_no), status='ACTIVE', built_in=1, deleted=0;
+
+INSERT IGNORE INTO iam_role_permission (role_id, permission_id, tenant_id)
+SELECT role.id, permission.id, 0
+  FROM iam_role role
+  JOIN iam_permission permission ON permission.id BETWEEN 5102190 AND 5102193
+ WHERE role.tenant_id=0 AND role.role_code IN ('PLATFORM_ADMIN', 'ORDER_OPERATOR')
+   AND role.deleted=0 AND permission.deleted=0;

firstleg/src/main/resources/openapi/phase3-loading-delivery-v1.yaml

@@ -20,7 +20,9 @@ paths:
         '200': {description: Business envelope; ownership, type and version failures use business error codes}
   /api/platform/v1/inbounds/{inboundId}/loading/picking/start:
     post:
-      summary: Start the inbound-level PDA picking review task
+      summary: Refresh the compatibility projection from canonical container PDA tasks
+      deprecated: true
+      description: expectedCount and pickedCount must exactly match the server-derived container-task aggregate.
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -30,7 +32,9 @@ paths:
         '200': {description: Business envelope containing IN_PROGRESS task}
   /api/platform/v1/inbounds/{inboundId}/loading/picking/complete:
     post:
-      summary: Complete a started PDA picking task when planned and picked counts match
+      summary: Mark the compatibility projection complete after all container PDA tasks are reviewed
+      deprecated: true
+      description: This endpoint cannot complete canonical picking; counts must match the server aggregate and every related container task must already be completed.
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true

firstleg/src/main/resources/openapi/phase3-loading-model-bridge-v1.yaml

@@ -0,0 +1,58 @@
+openapi: 3.0.3
+info:
+  title: Phase 3 Preload and Container Loading Bridge API
+  version: 1.0.0
+paths:
+  /api/platform/v1/inbounds/{inboundId}/preload/loading-plans:
+    get:
+      summary: Query all container loading plans linked to one inbound preload
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
+      responses:
+        '200': {description: Business envelope containing zero or more stable links}
+  /api/platform/v1/inbounds/{inboundId}/preload/loading-plans/{loadingPlanId}:
+    post:
+      summary: Atomically link an inbound preload and a container loading plan
+      description: Both optimistic-lock versions must match; either conflict rolls back the whole link operation.
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/LoadingPlanId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json: {schema: {$ref: '#/components/schemas/BindRequest'}}
+      responses:
+        '200': {description: Business envelope containing the persisted link or a business conflict}
+  /api/platform/v1/first-leg/smart-loading/plans/{loadingPlanId}/preloads:
+    get:
+      summary: Query all inbound preloads linked to one container loading plan
+      parameters: [{$ref: '#/components/parameters/LoadingPlanId'}]
+      responses:
+        '200': {description: Business envelope containing links across authorized customers}
+components:
+  parameters:
+    InboundId: {name: inboundId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    LoadingPlanId: {name: loadingPlanId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    TenantId: {name: tenantId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
+  schemas:
+    BindRequest:
+      type: object
+      required: [expectedPreloadVersion, expectedLoadingPlanVersion]
+      properties:
+        expectedPreloadVersion: {type: integer, minimum: 0}
+        expectedLoadingPlanVersion: {type: integer, minimum: 0}
+    Link:
+      type: object
+      required: [id, tenantId, inboundId, preloadPlanId, preloadStatus, preloadVersion, loadingPlanId, containerBookingId, loadingPlanStatus, loadingPlanVersion, allocatedPackageCount, linkedAt]
+      properties:
+        id: {type: integer, format: int64}
+        tenantId: {type: integer, format: int64}
+        inboundId: {type: integer, format: int64}
+        preloadPlanId: {type: integer, format: int64}
+        preloadStatus: {type: string, enum: [PENDING, CONFIRMING, CONFIRMED]}
+        preloadVersion: {type: integer, minimum: 0}
+        loadingPlanId: {type: integer, format: int64}
+        containerBookingId: {type: integer, format: int64}
+        containerNo: {type: string, nullable: true}
+        loadingPlanStatus: {type: string, enum: [EDITING, LOADING, COMPLETED]}
+        loadingPlanVersion: {type: integer, minimum: 0}
+        allocatedPackageCount: {type: integer, minimum: 1}
+        linkedAt: {type: string, format: date-time}

firstleg/src/main/resources/openapi/phase3-pda-convergence-v1.yaml

@@ -0,0 +1,87 @@
+openapi: 3.0.3
+info:
+  title: Phase 3 Container PDA Picking API
+  version: 1.0.0
+paths:
+  /api/platform/v1/first-leg/pda-loading/tasks:
+    get:
+      summary: Find the active container picking task in one platform warehouse
+      parameters:
+        - {name: containerNo, in: query, required: true, schema: {type: string}}
+        - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
+      responses:
+        '200': {description: Task with assignment, review and item-level versions}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/claim:
+    post:
+      summary: Atomically claim an unassigned task for the authenticated operator
+      parameters: [{$ref: '#/components/parameters/TaskId'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/ClaimRequest'}}}
+      responses:
+        '200': {description: Claimed task or A0409 when another operator owns it}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/assign:
+    post:
+      summary: Assign or reassign a task with optimistic locking
+      parameters: [{$ref: '#/components/parameters/TaskId'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/AssignRequest'}}}
+      responses:
+        '200': {description: Assigned task or A0409 on assignment version conflict}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/items/{itemId}/pick:
+    post:
+      summary: Increment a picked item owned by the authenticated assignee
+      parameters: [{$ref: '#/components/parameters/TaskId'}, {$ref: '#/components/parameters/ItemId'}]
+      responses: {'200': {description: Updated task}}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/items/{itemId}/partial:
+    post:
+      summary: Record the final partial quantity for one assigned item
+      parameters: [{$ref: '#/components/parameters/TaskId'}, {$ref: '#/components/parameters/ItemId'}]
+      responses: {'200': {description: Task awaiting review when every item is resolved}}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/items/{itemId}/skip:
+    post:
+      summary: Resolve an untouched assigned item as skipped
+      parameters: [{$ref: '#/components/parameters/TaskId'}, {$ref: '#/components/parameters/ItemId'}]
+      responses: {'200': {description: Task awaiting review when every item is resolved}}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/review:
+    post:
+      summary: Review all resolved items, settle partial and skipped quantities, then complete the plan
+      parameters: [{$ref: '#/components/parameters/TaskId'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/ReviewRequest'}}}
+      responses:
+        '200': {description: Completed task or A0409 when items or task version changed}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/operations:
+    get:
+      summary: Read immutable task-level claim, assignment and review audit records
+      parameters: [{$ref: '#/components/parameters/TaskId'}]
+      responses:
+        '200': {description: Ordered operation history}
+components:
+  parameters:
+    TaskId: {name: taskId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    ItemId: {name: itemId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+  schemas:
+    ClaimRequest:
+      type: object
+      required: [expectedAssignmentVersion, operationId]
+      properties:
+        expectedAssignmentVersion: {type: integer, minimum: 0}
+        operationId: {type: string, maxLength: 128}
+    AssignRequest:
+      type: object
+      required: [assigneeId, assigneeName, expectedAssignmentVersion, operationId]
+      properties:
+        assigneeId: {type: integer, format: int64, minimum: 1}
+        assigneeName: {type: string, maxLength: 64}
+        expectedAssignmentVersion: {type: integer, minimum: 0}
+        operationId: {type: string, maxLength: 128}
+    ReviewRequest:
+      type: object
+      required: [expectedTaskVersion, operationId]
+      properties:
+        expectedTaskVersion: {type: integer, minimum: 0}
+        operationId: {type: string, maxLength: 128}
+        remark: {type: string, maxLength: 500}