优化

2026-08-20 09:43:31 +08:00
parent f25e270f22
commit 7cf4a8d562
25 changed files with 804 additions and 41 deletions
@@ -125,6 +125,32 @@ CREATE TABLE IF NOT EXISTS fl_container_fee_source_snapshot (
  KEY idx_container_fee_snapshot_tenant (tenant_id, loading_plan_id)
 ) ENGINE=InnoDB COMMENT='柜次费用不可变版本快照';

+CREATE TABLE IF NOT EXISTS fl_finance_fee_source_command (
+  id BIGINT UNSIGNED NOT NULL COMMENT 'Finance费用来源命令ID',
+  customer_id BIGINT UNSIGNED NOT NULL COMMENT '客户隔离键，由Firstleg费用事实再次校验',
+  operator_id BIGINT UNSIGNED NOT NULL COMMENT 'Finance操作人ID',
+  operator_name VARCHAR(64) NOT NULL COMMENT 'Finance操作人名称快照',
+  action VARCHAR(24) NOT NULL COMMENT '命令动作；当前仅VOID',
+  idempotency_key VARCHAR(128) NOT NULL COMMENT 'Finance透传的幂等键',
+  request_hash CHAR(64) NOT NULL COMMENT '规范化请求SHA-256',
+  source_type VARCHAR(24) NOT NULL COMMENT 'INBOUND_FEE或CONTAINER_FEE',
+  source_fee_id BIGINT UNSIGNED NOT NULL COMMENT '稳定费用来源ID',
+  source_version INT UNSIGNED NOT NULL COMMENT '精确费用来源版本',
+  inbound_id BIGINT UNSIGNED NULL COMMENT '入库费用所属入库单ID',
+  container_id BIGINT UNSIGNED NULL COMMENT '柜次费用所属柜次ID',
+  reason VARCHAR(500) NOT NULL COMMENT '操作原因',
+  status VARCHAR(16) NOT NULL COMMENT 'PROCESSING或SUCCEEDED',
+  result_status VARCHAR(16) NULL COMMENT '成功业务结果；当前为VOIDED',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  completed_at DATETIME(3) NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_finance_fee_command_idem (customer_id, operator_id, action, idempotency_key),
+  KEY idx_finance_fee_command_source (source_type, source_fee_id, source_version, created_at),
+  CONSTRAINT chk_finance_fee_command_action CHECK (action IN ('VOID')),
+  CONSTRAINT chk_finance_fee_command_status CHECK (status IN ('PROCESSING', 'SUCCEEDED')),
+  CONSTRAINT chk_finance_fee_command_source CHECK (source_type IN ('INBOUND_FEE', 'CONTAINER_FEE'))
+) ENGINE=InnoDB COMMENT='Finance发起、Firstleg执行业务费用命令的幂等审计记录';
+
 CALL firstleg_finance_add_column('fl_container_fee_detail', 'supplier_id',
  "BIGINT UNSIGNED NULL COMMENT '应付Warehouse供应商ID快照；应收为空' AFTER direction");
 CALL firstleg_finance_add_column('fl_container_fee_detail', 'supplier_name',
@@ -153,6 +179,10 @@ BEGIN
                  WHERE table_schema = DATABASE() AND table_name = 'fl_container_fee_detail') THEN
    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Firstleg Finance迁移失败：柜次费用表不存在';
  END IF;
+  IF NOT EXISTS (SELECT 1 FROM information_schema.tables
+                  WHERE table_schema = DATABASE() AND table_name = 'fl_finance_fee_source_command') THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Firstleg Finance迁移失败：费用命令幂等审计表不存在';
+  END IF;
  IF (SELECT COUNT(*) FROM information_schema.columns
       WHERE table_schema = DATABASE() AND table_name = 'fl_container_fee_detail'
         AND column_name IN ('supplier_id', 'supplier_name', 'supplier_category')) <> 3 THEN
@@ -635,7 +635,7 @@ CREATE TABLE IF NOT EXISTS fl_inbound_fee (
  subtotal_amount DECIMAL(18,2) NOT NULL COMMENT '基础费用金额',
  additional_amount DECIMAL(18,2) NOT NULL DEFAULT 0 COMMENT '附加费金额',
  total_amount DECIMAL(18,2) NOT NULL COMMENT '总金额',
-  fee_status VARCHAR(24) NOT NULL DEFAULT 'CALCULATED' COMMENT '费用状态：CALCULATED已计算、SUPERSEDED已被新版本替代',
+  fee_status VARCHAR(24) NOT NULL DEFAULT 'CALCULATED' COMMENT '费用状态：CALCULATED已计算、CONFIRMED已确认、SENT已发送、SUPERSEDED已被新版本替代、VOIDED已作废',
  review_status VARCHAR(24) NOT NULL DEFAULT 'NOT_SUBMITTED' COMMENT '费用审核状态：NOT_SUBMITTED未提交、PENDING待审核、APPROVED已通过、REJECTED已驳回、CONFIRMED已确认',
  exception_release TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否基于测量异常放行生成',
  calculated_by BIGINT UNSIGNED NOT NULL COMMENT '试算人ID',
@@ -94,6 +94,25 @@ paths:
        - {name: sourceVersion, in: query, required: true, schema: {type: integer, minimum: 1}}
      responses:
        '200': {description: 成功时 data 为 FinanceFeeSourceSnapshot；不存在精确版本时返回业务错误}
+  /internal/firstleg/v1/fee-sources/commands/void:
+    post:
+      summary: Finance 发起 Firstleg 业务费用作废
+      description: >-
+        Finance 只发起命令，不修改或伪造业务费用状态。Firstleg 按 sourceType、sourceFeeId、sourceVersion、
+        customerId 和所属入库单/柜次精确校验，原子作废业务费用并写入 FIRSTLEG_FEE_VOIDED Outbox；
+        Finance 后续仅消费该事件同步本地费用池。相同幂等键与请求哈希安全重放，异参重放返回冲突。
+      security:
+        - internalServiceToken: []
+      parameters:
+        - {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+        - {name: X-Request-Hash, in: header, required: true, schema: {type: string, pattern: '^[0-9a-f]{64}$'}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/FinanceFeeSourceVoidCommand'}
+      responses:
+        '200': {description: 成功时 data 为 FinanceFeeSourceCommandResult；业务失败仍按统一响应 code 返回}
  /api/platform/v1/first-leg/customer-dimension-config:
    get:
      summary: 查询客户固定四箱规尺寸配置
@@ -1879,3 +1898,26 @@ components:
        actualVolumeCbm: {type: number, nullable: true}
        sourceHash: {type: string}
        snapshotVersion: {type: integer, minimum: 1}
+    FinanceFeeSourceVoidCommand:
+      type: object
+      additionalProperties: false
+      required: [sourceType, sourceFeeId, sourceVersion, customerId, operatorId, operatorName, reason]
+      properties:
+        sourceType: {type: string, enum: [INBOUND_FEE, CONTAINER_FEE]}
+        sourceFeeId: {type: integer, format: int64, minimum: 1}
+        sourceVersion: {type: integer, minimum: 1}
+        customerId: {type: integer, format: int64, minimum: 1}
+        inboundId: {type: integer, format: int64, minimum: 1, nullable: true, description: INBOUND_FEE必填且containerId必须为空}
+        containerId: {type: integer, format: int64, minimum: 1, nullable: true, description: CONTAINER_FEE必填且inboundId必须为空}
+        operatorId: {type: integer, format: int64, minimum: 1}
+        operatorName: {type: string, minLength: 1, maxLength: 64}
+        reason: {type: string, minLength: 1, maxLength: 500}
+    FinanceFeeSourceCommandResult:
+      type: object
+      required: [sourceType, sourceFeeId, sourceVersion, status, replayed]
+      properties:
+        sourceType: {type: string, enum: [INBOUND_FEE, CONTAINER_FEE]}
+        sourceFeeId: {type: integer, format: int64}
+        sourceVersion: {type: integer}
+        status: {type: string, enum: [VOIDED]}
+        replayed: {type: boolean}