优化

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

@@ -1,16 +1,21 @@
 SET NAMES utf8mb4;
 USE baiyue_firstleg;
 
-/* 装柜证据、PDA 拣货复核和派送完成。业务服务强制五类真实文件证据齐全后才能完成装柜。 */
+/* 装柜证据、PDA 拣货复核和派送完成。五类证据按有效记录计数，同类型允许多图追加；作废记录保留审计。 */
 CREATE TABLE IF NOT EXISTS fl_loading_evidence (
   id BIGINT UNSIGNED NOT NULL,
   tenant_id BIGINT UNSIGNED NOT NULL,
   inbound_id BIGINT UNSIGNED NOT NULL,
-  evidence_type VARCHAR(32) NOT NULL COMMENT 'PHOTO_STEP_1..4/SEAL',
+  evidence_type VARCHAR(32) NOT NULL COMMENT 'PHOTO_STEP_1空仓/PHOTO_STEP_2半仓/PHOTO_STEP_3满仓/PHOTO_STEP_4锁仓/SEAL带锁码照',
   file_id BIGINT UNSIGNED NOT NULL COMMENT 'File 服务逻辑文件ID',
   file_name VARCHAR(255) NULL,
   seal_no VARCHAR(64) NULL,
   remark VARCHAR(1000) NULL,
+  status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE' COMMENT 'ACTIVE/VOID，作废不硬删除',
+  void_reason VARCHAR(500) NULL,
+  voided_by BIGINT UNSIGNED NULL,
+  voided_by_name VARCHAR(64) NULL,
+  voided_at DATETIME(3) NULL,
   version INT NOT NULL DEFAULT 0,
   created_by BIGINT UNSIGNED NOT NULL,
   created_by_name VARCHAR(64) NULL,
@@ -19,11 +24,74 @@ CREATE TABLE IF NOT EXISTS fl_loading_evidence (
   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 (id),
-  UNIQUE KEY uk_loading_evidence_type (tenant_id, inbound_id, evidence_type),
-  UNIQUE KEY uk_loading_evidence_seal (tenant_id, seal_no),
+  KEY idx_loading_evidence_type (tenant_id, inbound_id, evidence_type, status),
+  KEY idx_loading_evidence_seal (tenant_id, seal_no, status),
   KEY idx_loading_evidence_time (tenant_id, inbound_id, updated_at),
   CONSTRAINT fk_loading_evidence_inbound FOREIGN KEY (inbound_id) REFERENCES fl_inbound_order (id)
-) ENGINE=InnoDB COMMENT='订单装柜四步照片和铅封证据';
+) ENGINE=InnoDB COMMENT='订单装柜空仓/半仓/满仓/锁仓/带锁码照证据';
+
+/* Repeatable migration for installations that already created the single-slot table. */
+DROP PROCEDURE IF EXISTS phase3_loading_add_column;
+DELIMITER $$
+CREATE PROCEDURE phase3_loading_add_column(IN p_column VARCHAR(64), IN p_definition VARCHAR(512))
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema=DATABASE() AND table_name='fl_loading_evidence' AND column_name=p_column
+  ) THEN
+    SET @phase3_loading_ddl = CONCAT('ALTER TABLE fl_loading_evidence ADD COLUMN `', p_column, '` ', p_definition);
+    PREPARE phase3_loading_stmt FROM @phase3_loading_ddl;
+    EXECUTE phase3_loading_stmt;
+    DEALLOCATE PREPARE phase3_loading_stmt;
+  END IF;
+END$$
+DELIMITER ;
+CALL phase3_loading_add_column('status', 'VARCHAR(16) NOT NULL DEFAULT ''ACTIVE'' COMMENT ''ACTIVE/VOID，作废不硬删除''');
+CALL phase3_loading_add_column('void_reason', 'VARCHAR(500) NULL');
+CALL phase3_loading_add_column('voided_by', 'BIGINT UNSIGNED NULL');
+CALL phase3_loading_add_column('voided_by_name', 'VARCHAR(64) NULL');
+CALL phase3_loading_add_column('voided_at', 'DATETIME(3) NULL');
+DROP PROCEDURE IF EXISTS phase3_loading_add_column;
+
+SET @phase3_loading_has_legacy_type_index = (
+  SELECT COUNT(*) FROM information_schema.statistics
+  WHERE table_schema=DATABASE() AND table_name='fl_loading_evidence' AND index_name='uk_loading_evidence_type'
+);
+SET @phase3_loading_drop_legacy_type_index = IF(@phase3_loading_has_legacy_type_index > 0,
+  'ALTER TABLE fl_loading_evidence DROP INDEX uk_loading_evidence_type', 'SELECT 1');
+PREPARE phase3_loading_drop_stmt FROM @phase3_loading_drop_legacy_type_index;
+EXECUTE phase3_loading_drop_stmt;
+DEALLOCATE PREPARE phase3_loading_drop_stmt;
+
+SET @phase3_loading_has_type_index = (
+  SELECT COUNT(*) FROM information_schema.statistics
+  WHERE table_schema=DATABASE() AND table_name='fl_loading_evidence' AND index_name='idx_loading_evidence_type'
+);
+SET @phase3_loading_add_type_index = IF(@phase3_loading_has_type_index = 0,
+  'ALTER TABLE fl_loading_evidence ADD KEY idx_loading_evidence_type (tenant_id, inbound_id, evidence_type, status)', 'SELECT 1');
+PREPARE phase3_loading_type_stmt FROM @phase3_loading_add_type_index;
+EXECUTE phase3_loading_type_stmt;
+DEALLOCATE PREPARE phase3_loading_type_stmt;
+
+SET @phase3_loading_has_legacy_seal_index = (
+  SELECT COUNT(*) FROM information_schema.statistics
+  WHERE table_schema=DATABASE() AND table_name='fl_loading_evidence' AND index_name='uk_loading_evidence_seal'
+);
+SET @phase3_loading_drop_legacy_seal_index = IF(@phase3_loading_has_legacy_seal_index > 0,
+  'ALTER TABLE fl_loading_evidence DROP INDEX uk_loading_evidence_seal', 'SELECT 1');
+PREPARE phase3_loading_drop_seal_stmt FROM @phase3_loading_drop_legacy_seal_index;
+EXECUTE phase3_loading_drop_seal_stmt;
+DEALLOCATE PREPARE phase3_loading_drop_seal_stmt;
+
+SET @phase3_loading_has_seal_index = (
+  SELECT COUNT(*) FROM information_schema.statistics
+  WHERE table_schema=DATABASE() AND table_name='fl_loading_evidence' AND index_name='idx_loading_evidence_seal'
+);
+SET @phase3_loading_add_seal_index = IF(@phase3_loading_has_seal_index = 0,
+  'ALTER TABLE fl_loading_evidence ADD KEY idx_loading_evidence_seal (tenant_id, seal_no, status)', 'SELECT 1');
+PREPARE phase3_loading_seal_stmt FROM @phase3_loading_add_seal_index;
+EXECUTE phase3_loading_seal_stmt;
+DEALLOCATE PREPARE phase3_loading_seal_stmt;
 
 CREATE TABLE IF NOT EXISTS fl_loading_operation (
   id BIGINT UNSIGNED NOT NULL,

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

@@ -10,7 +10,7 @@ paths:
       responses:
         '200': {description: Business envelope containing the stable evidence array}
     post:
-      summary: Bind one real File service object to a loading evidence slot
+      summary: Append one real File service object to a loading evidence type
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -18,6 +18,16 @@ paths:
           application/json: {schema: {$ref: '#/components/schemas/UpsertEvidenceRequest'}}
       responses:
         '200': {description: Business envelope; ownership, type and version failures use business error codes}
+  /api/platform/v1/inbounds/{inboundId}/loading/evidence/{evidenceId}/void:
+    post:
+      summary: Void an incorrect loading evidence photo without hard deletion
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/EvidenceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json: {schema: {$ref: '#/components/schemas/VoidEvidenceRequest'}}
+      responses:
+        '200': {description: Business envelope containing the voided record and audit fields}
   /api/platform/v1/inbounds/{inboundId}/loading/picking/start:
     post:
       summary: Refresh the compatibility projection from canonical container PDA tasks
@@ -50,7 +60,7 @@ paths:
         '200': {description: Business envelope containing task or null}
   /api/platform/v1/inbounds/{inboundId}/loading/complete:
     post:
-      summary: Complete loading only after picking and PHOTO_STEP_1..4 plus SEAL evidence are complete
+      summary: Complete loading only after picking and five evidence types each have an active photo
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -62,6 +72,7 @@ components:
   parameters:
     InboundId: {name: inboundId, 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}}
+    EvidenceId: {name: evidenceId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
     IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
   schemas:
     UpsertEvidenceRequest:
@@ -69,11 +80,17 @@ components:
       required: [expectedVersion, evidenceType, fileId]
       properties:
         expectedVersion: {type: integer, minimum: 0}
-        evidenceType: {type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL]}
+        evidenceType: {type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL], description: PHOTO_STEP_1=空仓，PHOTO_STEP_2=半仓，PHOTO_STEP_3=满仓，PHOTO_STEP_4=锁仓，SEAL=带锁码照；同类型可多次追加}
         fileId: {type: integer, format: int64, minimum: 1}
         fileName: {type: string, maxLength: 255, deprecated: true, description: Ignored; server uses File metadata}
         sealNo: {type: string, maxLength: 64, description: Required when evidenceType is SEAL}
         remark: {type: string, maxLength: 1000}
+    VoidEvidenceRequest:
+      type: object
+      required: [expectedVersion, reason]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        reason: {type: string, minLength: 1, maxLength: 500, description: 作废原因，记录操作人和时间}
     PickingRequest:
       type: object
       required: [expectedVersion, expectedCount, pickedCount]