补齐统一数据库中文注释

firstleg/src/main/resources/db/phase2-inbound-schema.sql

@@ -832,8 +832,8 @@ CREATE TABLE IF NOT EXISTS fl_order_declaration_snapshot (
   cargoes_json JSON NOT NULL COMMENT '客户申报货物行完整快照，不覆盖实测事实',
   changes_json JSON NULL COMMENT '本版本申报字段变化摘要',
   occurred_at DATETIME(3) NOT NULL COMMENT 'Order事件发生时间',
-  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),
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '快照创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '快照更新时间',
   PRIMARY KEY (tenant_id, order_id),
   UNIQUE KEY uk_order_declaration_event (tenant_id, event_id),
   KEY idx_order_declaration_version (tenant_id, order_id, order_version)
@@ -845,7 +845,7 @@ CREATE TABLE IF NOT EXISTS fl_order_declaration_event (
   order_id BIGINT UNSIGNED NOT NULL COMMENT 'Order订单ID',
   order_version INT NOT NULL COMMENT '事件携带的Order聚合版本',
   request_hash CHAR(64) NOT NULL COMMENT '完整事件SHA-256，用于异参重放拒绝',
-  consumed_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  consumed_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '事件消费完成时间',
   PRIMARY KEY (tenant_id, event_id),
   KEY idx_order_declaration_event_order (tenant_id, order_id, order_version)
 ) ENGINE=InnoDB COMMENT='Order客户申报事件永久幂等账本';

firstleg/src/main/resources/db/phase3-container-customs-schema.sql

@@ -2,19 +2,19 @@ SET NAMES utf8mb4;
 USE baiyue_firstleg;
 
 CREATE TABLE IF NOT EXISTS fl_customs_container (
-  id BIGINT UNSIGNED NOT NULL,
+  id BIGINT UNSIGNED NOT NULL COMMENT '整柜报关聚合ID',
   loading_plan_id BIGINT UNSIGNED NOT NULL COMMENT '已完成装柜计划ID；报关柜级聚合唯一键',
   container_booking_id BIGINT UNSIGNED NOT NULL COMMENT '物理货柜ID',
-  status VARCHAR(40) NOT NULL COMMENT 'WAITING_CUSTOMER_DOCUMENTS、READY_TO_START、DECLARING、COMPLETED',
-  started_by BIGINT UNSIGNED NULL,
-  started_by_name VARCHAR(64) NULL,
-  started_at DATETIME(3) NULL,
-  completed_by BIGINT UNSIGNED NULL,
-  completed_by_name VARCHAR(64) NULL,
-  completed_at DATETIME(3) NULL,
-  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),
-  version INT UNSIGNED NOT NULL DEFAULT 0,
+  status VARCHAR(40) NOT NULL COMMENT '报关状态：WAITING_CUSTOMER_DOCUMENTS待资料、READY_TO_START可开始、DECLARING申报中、COMPLETED已完成',
+  started_by BIGINT UNSIGNED NULL COMMENT '开始报关操作人ID',
+  started_by_name VARCHAR(64) NULL COMMENT '开始报关操作人名称快照',
+  started_at DATETIME(3) NULL COMMENT '开始报关时间',
+  completed_by BIGINT UNSIGNED NULL COMMENT '完成报关操作人ID',
+  completed_by_name VARCHAR(64) NULL COMMENT '完成报关操作人名称快照',
+  completed_at DATETIME(3) NULL COMMENT '报关完成时间',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '聚合创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '聚合更新时间',
+  version INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
   PRIMARY KEY(id),
   UNIQUE KEY uk_customs_container_plan(loading_plan_id),
   UNIQUE KEY uk_customs_container_booking(container_booking_id),
@@ -24,24 +24,24 @@ CREATE TABLE IF NOT EXISTS fl_customs_container (
 ) ENGINE=InnoDB COMMENT='装柜完成后的整柜出口报关聚合';
 
 CREATE TABLE IF NOT EXISTS fl_customs_customer_document (
-  id BIGINT UNSIGNED NOT NULL,
-  customs_container_id BIGINT UNSIGNED NOT NULL,
+  id BIGINT UNSIGNED NOT NULL COMMENT '客户报送资料ID',
+  customs_container_id BIGINT UNSIGNED NOT NULL COMMENT '所属整柜报关聚合ID',
   tenant_id BIGINT UNSIGNED NOT NULL COMMENT '客户隔离键；只允许关联同客户退税票',
-  file_id BIGINT UNSIGNED NOT NULL,
-  file_name VARCHAR(255) NOT NULL,
-  file_hash CHAR(64) NOT NULL,
-  content_type VARCHAR(128) NULL,
-  size_bytes BIGINT UNSIGNED NOT NULL,
-  status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE',
-  uploaded_by BIGINT UNSIGNED NOT NULL,
-  uploaded_at DATETIME(3) NOT NULL,
-  frozen_version INT UNSIGNED NULL,
-  frozen_at DATETIME(3) NULL,
-  deleted_by BIGINT UNSIGNED NULL,
-  deleted_at DATETIME(3) NULL,
-  version INT UNSIGNED NOT NULL DEFAULT 1,
-  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),
+  file_id BIGINT UNSIGNED NOT NULL COMMENT 'File服务文件ID',
+  file_name VARCHAR(255) NOT NULL COMMENT '文件名称快照',
+  file_hash CHAR(64) NOT NULL COMMENT '文件SHA-256摘要',
+  content_type VARCHAR(128) NULL COMMENT '文件媒体类型',
+  size_bytes BIGINT UNSIGNED NOT NULL COMMENT '文件大小（字节）',
+  status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE' COMMENT '资料状态：ACTIVE有效、DELETED已删除',
+  uploaded_by BIGINT UNSIGNED NOT NULL COMMENT '上传操作人ID',
+  uploaded_at DATETIME(3) NOT NULL COMMENT '上传时间',
+  frozen_version INT UNSIGNED NULL COMMENT '开始报关时冻结的资料版本',
+  frozen_at DATETIME(3) NULL COMMENT '资料冻结时间',
+  deleted_by BIGINT UNSIGNED NULL COMMENT '删除操作人ID',
+  deleted_at DATETIME(3) NULL COMMENT '删除时间',
+  version INT UNSIGNED NOT NULL DEFAULT 1 COMMENT '资料版本号',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '资料创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '资料更新时间',
   PRIMARY KEY(id),
   KEY idx_customs_customer_document_container(customs_container_id,status,tenant_id),
   CONSTRAINT fk_customs_customer_document_container FOREIGN KEY(customs_container_id) REFERENCES fl_customs_container(id),
@@ -51,30 +51,30 @@ CREATE TABLE IF NOT EXISTS fl_customs_customer_document (
 ) ENGINE=InnoDB COMMENT='客户整份退税报送资料逻辑根';
 
 CREATE TABLE IF NOT EXISTS fl_customs_customer_document_inbound (
-  document_id BIGINT UNSIGNED NOT NULL,
-  inbound_id BIGINT UNSIGNED NOT NULL,
-  tenant_id BIGINT UNSIGNED NOT NULL,
-  order_id BIGINT UNSIGNED NOT NULL,
-  inbound_code VARCHAR(40) NOT NULL,
-  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  document_id BIGINT UNSIGNED NOT NULL COMMENT '客户报送资料ID',
+  inbound_id BIGINT UNSIGNED NOT NULL COMMENT '覆盖入仓单ID',
+  tenant_id BIGINT UNSIGNED NOT NULL COMMENT '覆盖入仓单客户ID',
+  order_id BIGINT UNSIGNED NOT NULL COMMENT '覆盖订单ID',
+  inbound_code VARCHAR(40) NOT NULL COMMENT '覆盖入仓码快照',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '关联创建时间',
   PRIMARY KEY(document_id,inbound_id),
   KEY idx_customs_document_inbound(inbound_id,tenant_id),
   CONSTRAINT fk_customs_document_inbound_document FOREIGN KEY(document_id) REFERENCES fl_customs_customer_document(id)
 ) ENGINE=InnoDB COMMENT='客户报送资料与当前柜退税入仓码多对多关系';
 
 CREATE TABLE IF NOT EXISTS fl_customs_customer_document_version (
-  id BIGINT UNSIGNED NOT NULL,
-  document_id BIGINT UNSIGNED NOT NULL,
-  document_version INT UNSIGNED NOT NULL,
-  file_id BIGINT UNSIGNED NOT NULL,
-  file_name VARCHAR(255) NOT NULL,
-  file_hash CHAR(64) NOT NULL,
-  content_type VARCHAR(128) NULL,
-  size_bytes BIGINT UNSIGNED NOT NULL,
-  scope_snapshot_json JSON NOT NULL,
-  action VARCHAR(24) NOT NULL COMMENT 'UPLOAD、REPLACE、SCOPE_CHANGE、DELETE',
-  operator_id BIGINT UNSIGNED NOT NULL,
-  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  id BIGINT UNSIGNED NOT NULL COMMENT '资料版本记录ID',
+  document_id BIGINT UNSIGNED NOT NULL COMMENT '客户报送资料ID',
+  document_version INT UNSIGNED NOT NULL COMMENT '资料版本号',
+  file_id BIGINT UNSIGNED NOT NULL COMMENT '本版本File服务文件ID',
+  file_name VARCHAR(255) NOT NULL COMMENT '本版本文件名称快照',
+  file_hash CHAR(64) NOT NULL COMMENT '本版本文件SHA-256摘要',
+  content_type VARCHAR(128) NULL COMMENT '本版本文件媒体类型',
+  size_bytes BIGINT UNSIGNED NOT NULL COMMENT '本版本文件大小（字节）',
+  scope_snapshot_json JSON NOT NULL COMMENT '本版本覆盖入仓码范围快照',
+  action VARCHAR(24) NOT NULL COMMENT '版本动作：UPLOAD上传、REPLACE替换、SCOPE_CHANGE范围变化、DELETE删除',
+  operator_id BIGINT UNSIGNED NOT NULL COMMENT '操作人ID',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '版本创建时间',
   PRIMARY KEY(id),
   UNIQUE KEY uk_customs_customer_document_version(document_id,document_version),
   CONSTRAINT fk_customs_customer_document_version FOREIGN KEY(document_id) REFERENCES fl_customs_customer_document(id),
@@ -82,77 +82,77 @@ CREATE TABLE IF NOT EXISTS fl_customs_customer_document_version (
 ) ENGINE=InnoDB COMMENT='客户报送资料文件与覆盖范围不可变版本';
 
 CREATE TABLE IF NOT EXISTS fl_customs_frozen_document_inbound (
-  document_id BIGINT UNSIGNED NOT NULL,
-  inbound_id BIGINT UNSIGNED NOT NULL,
-  tenant_id BIGINT UNSIGNED NOT NULL,
-  order_id BIGINT UNSIGNED NOT NULL,
-  inbound_code VARCHAR(40) NOT NULL,
-  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  document_id BIGINT UNSIGNED NOT NULL COMMENT '冻结的客户报送资料ID',
+  inbound_id BIGINT UNSIGNED NOT NULL COMMENT '冻结覆盖入仓单ID',
+  tenant_id BIGINT UNSIGNED NOT NULL COMMENT '冻结覆盖客户ID',
+  order_id BIGINT UNSIGNED NOT NULL COMMENT '冻结覆盖订单ID',
+  inbound_code VARCHAR(40) NOT NULL COMMENT '冻结覆盖入仓码快照',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '冻结关联创建时间',
   PRIMARY KEY(document_id,inbound_id),
   CONSTRAINT fk_customs_frozen_document FOREIGN KEY(document_id) REFERENCES fl_customs_customer_document(id)
 ) ENGINE=InnoDB COMMENT='开始报关时冻结的客户资料覆盖范围';
 
 CREATE TABLE IF NOT EXISTS fl_customs_completion_document (
-  id BIGINT UNSIGNED NOT NULL,
+  id BIGINT UNSIGNED NOT NULL COMMENT '报关完成文件ID',
   source_document_id BIGINT UNSIGNED NOT NULL COMMENT '一份冻结客户资料严格对应一份完成文件逻辑根',
-  file_id BIGINT UNSIGNED NOT NULL,
-  file_name VARCHAR(255) NOT NULL,
-  file_hash CHAR(64) NOT NULL,
-  content_type VARCHAR(128) NULL,
-  size_bytes BIGINT UNSIGNED NOT NULL,
-  uploaded_by BIGINT UNSIGNED NOT NULL,
-  uploaded_by_name VARCHAR(64) NULL,
-  uploaded_at DATETIME(3) NOT NULL,
-  version INT UNSIGNED NOT NULL DEFAULT 1,
-  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),
+  file_id BIGINT UNSIGNED NOT NULL COMMENT 'File服务文件ID',
+  file_name VARCHAR(255) NOT NULL COMMENT '完成文件名称快照',
+  file_hash CHAR(64) NOT NULL COMMENT '完成文件SHA-256摘要',
+  content_type VARCHAR(128) NULL COMMENT '完成文件媒体类型',
+  size_bytes BIGINT UNSIGNED NOT NULL COMMENT '完成文件大小（字节）',
+  uploaded_by BIGINT UNSIGNED NOT NULL COMMENT '上传操作人ID',
+  uploaded_by_name VARCHAR(64) NULL COMMENT '上传操作人名称快照',
+  uploaded_at DATETIME(3) NOT NULL COMMENT '上传时间',
+  version INT UNSIGNED NOT NULL DEFAULT 1 COMMENT '完成文件版本号',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '完成文件创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '完成文件更新时间',
   PRIMARY KEY(id),
   UNIQUE KEY uk_customs_completion_source(source_document_id),
   CONSTRAINT fk_customs_completion_source FOREIGN KEY(source_document_id) REFERENCES fl_customs_customer_document(id)
 ) ENGINE=InnoDB COMMENT='报关完成文件当前版本';
 
 CREATE TABLE IF NOT EXISTS fl_customs_completion_document_version (
-  id BIGINT UNSIGNED NOT NULL,
-  completion_document_id BIGINT UNSIGNED NOT NULL,
-  document_version INT UNSIGNED NOT NULL,
-  file_id BIGINT UNSIGNED NOT NULL,
-  file_name VARCHAR(255) NOT NULL,
-  file_hash CHAR(64) NOT NULL,
-  content_type VARCHAR(128) NULL,
-  size_bytes BIGINT UNSIGNED NOT NULL,
-  operator_id BIGINT UNSIGNED NOT NULL,
-  operator_name VARCHAR(64) NULL,
-  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  id BIGINT UNSIGNED NOT NULL COMMENT '完成文件版本记录ID',
+  completion_document_id BIGINT UNSIGNED NOT NULL COMMENT '报关完成文件ID',
+  document_version INT UNSIGNED NOT NULL COMMENT '完成文件版本号',
+  file_id BIGINT UNSIGNED NOT NULL COMMENT '本版本File服务文件ID',
+  file_name VARCHAR(255) NOT NULL COMMENT '本版本文件名称快照',
+  file_hash CHAR(64) NOT NULL COMMENT '本版本文件SHA-256摘要',
+  content_type VARCHAR(128) NULL COMMENT '本版本文件媒体类型',
+  size_bytes BIGINT UNSIGNED NOT NULL COMMENT '本版本文件大小（字节）',
+  operator_id BIGINT UNSIGNED NOT NULL COMMENT '操作人ID',
+  operator_name VARCHAR(64) NULL COMMENT '操作人名称快照',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '版本创建时间',
   PRIMARY KEY(id),
   UNIQUE KEY uk_customs_completion_version(completion_document_id,document_version),
   CONSTRAINT fk_customs_completion_version FOREIGN KEY(completion_document_id) REFERENCES fl_customs_completion_document(id)
 ) ENGINE=InnoDB COMMENT='报关完成文件不可变覆盖版本';
 
 CREATE TABLE IF NOT EXISTS fl_customs_container_history (
-  id BIGINT UNSIGNED NOT NULL,
-  customs_container_id BIGINT UNSIGNED NOT NULL,
-  action VARCHAR(40) NOT NULL,
-  from_status VARCHAR(40) NULL,
-  to_status VARCHAR(40) NULL,
-  remark VARCHAR(500) NULL,
-  operator_id BIGINT UNSIGNED NOT NULL,
-  operator_name VARCHAR(64) NULL,
-  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  id BIGINT UNSIGNED NOT NULL COMMENT '报关历史记录ID',
+  customs_container_id BIGINT UNSIGNED NOT NULL COMMENT '所属整柜报关聚合ID',
+  action VARCHAR(40) NOT NULL COMMENT '报关操作类型',
+  from_status VARCHAR(40) NULL COMMENT '变更前报关状态',
+  to_status VARCHAR(40) NULL COMMENT '变更后报关状态',
+  remark VARCHAR(500) NULL COMMENT '操作备注',
+  operator_id BIGINT UNSIGNED NOT NULL COMMENT '操作人ID',
+  operator_name VARCHAR(64) NULL COMMENT '操作人名称快照',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '历史创建时间',
   PRIMARY KEY(id),
   KEY idx_customs_container_history(customs_container_id,created_at,id),
   CONSTRAINT fk_customs_container_history FOREIGN KEY(customs_container_id) REFERENCES fl_customs_container(id)
 ) ENGINE=InnoDB COMMENT='整柜报关状态与系统触发历史';
 
 CREATE TABLE IF NOT EXISTS fl_customs_command (
-  id BIGINT UNSIGNED NOT NULL,
-  actor_id BIGINT UNSIGNED NOT NULL,
-  action VARCHAR(80) NOT NULL,
-  idempotency_key VARCHAR(128) NOT NULL,
-  request_hash CHAR(64) NOT NULL,
-  status VARCHAR(16) NOT NULL,
-  result_id BIGINT UNSIGNED NULL,
-  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
-  completed_at DATETIME(3) NULL,
+  id BIGINT UNSIGNED NOT NULL COMMENT '报关幂等命令ID',
+  actor_id BIGINT UNSIGNED NOT NULL COMMENT '命令操作人ID',
+  action VARCHAR(80) NOT NULL COMMENT '命令动作类型',
+  idempotency_key VARCHAR(128) NOT NULL COMMENT '客户端幂等键',
+  request_hash CHAR(64) NOT NULL COMMENT '规范化请求SHA-256摘要',
+  status VARCHAR(16) NOT NULL COMMENT '命令状态：PROCESSING处理中、SUCCESS成功',
+  result_id BIGINT UNSIGNED NULL COMMENT '命令结果业务记录ID',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '命令创建时间',
+  completed_at DATETIME(3) NULL COMMENT '命令完成时间',
   PRIMARY KEY(id),
   UNIQUE KEY uk_customs_command(actor_id,action,idempotency_key),
   CONSTRAINT chk_customs_command_status CHECK(status IN('PROCESSING','SUCCESS'))

firstleg/src/main/resources/db/phase3-container-overview.sql

@@ -1,10 +1,10 @@
 USE baiyue_firstleg;
 CREATE TABLE IF NOT EXISTS fl_container_exception_history (
- id BIGINT UNSIGNED NOT NULL, container_booking_id BIGINT UNSIGNED NOT NULL,
- action VARCHAR(16) NOT NULL COMMENT 'MARK/CANCEL', reason VARCHAR(500) NOT NULL,
- operator_id BIGINT UNSIGNED NOT NULL, operator_name VARCHAR(64),
+ id BIGINT UNSIGNED NOT NULL COMMENT '货柜异常历史ID', container_booking_id BIGINT UNSIGNED NOT NULL COMMENT '物理货柜ID',
+ action VARCHAR(16) NOT NULL COMMENT '操作类型：MARK标记异常、CANCEL取消异常', reason VARCHAR(500) NOT NULL COMMENT '异常原因',
+ operator_id BIGINT UNSIGNED NOT NULL COMMENT '操作人ID', operator_name VARCHAR(64) COMMENT '操作人名称快照',
  operation_id VARCHAR(128) NOT NULL COMMENT '同一操作人幂等键', request_hash CHAR(64) NOT NULL COMMENT '请求摘要',
- occurred_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+ occurred_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '操作发生时间',
  PRIMARY KEY(id), UNIQUE KEY uk_container_exception_operation(container_booking_id,operator_id,operation_id),
  KEY idx_container_exception_history(container_booking_id,occurred_at,id),
  CONSTRAINT fk_container_exception_booking FOREIGN KEY(container_booking_id) REFERENCES fl_container_booking(id),

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

@@ -344,11 +344,11 @@ CREATE TABLE IF NOT EXISTS fl_container_document (
 ) ENGINE=InnoDB COMMENT='平台货柜清关、DO与PU文件关联';
 
 CREATE TABLE IF NOT EXISTS fl_container_exception_history (
-  id BIGINT UNSIGNED NOT NULL, container_booking_id BIGINT UNSIGNED NOT NULL,
-  action VARCHAR(16) NOT NULL, reason VARCHAR(500) NOT NULL,
-  operator_id BIGINT UNSIGNED NOT NULL, operator_name VARCHAR(64) NULL,
-  operation_id VARCHAR(128) NOT NULL, request_hash CHAR(64) NOT NULL,
-  occurred_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), PRIMARY KEY(id),
+  id BIGINT UNSIGNED NOT NULL COMMENT '货柜异常历史ID', container_booking_id BIGINT UNSIGNED NOT NULL COMMENT '物理货柜ID',
+  action VARCHAR(16) NOT NULL COMMENT '操作类型：MARK标记异常、CANCEL取消异常', reason VARCHAR(500) NOT NULL COMMENT '异常原因',
+  operator_id BIGINT UNSIGNED NOT NULL COMMENT '操作人ID', operator_name VARCHAR(64) NULL COMMENT '操作人名称快照',
+  operation_id VARCHAR(128) NOT NULL COMMENT '同一操作人幂等键', request_hash CHAR(64) NOT NULL COMMENT '请求摘要',
+  occurred_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '操作发生时间', PRIMARY KEY(id),
   UNIQUE KEY uk_container_exception_operation(container_booking_id,operator_id,operation_id),
   KEY idx_container_exception_history(container_booking_id,occurred_at,id),
   CONSTRAINT fk_container_exception_booking FOREIGN KEY(container_booking_id) REFERENCES fl_container_booking(id),
@@ -587,7 +587,7 @@ CREATE TABLE IF NOT EXISTS fl_loading_completion_command (
   pick_task_id BIGINT UNSIGNED NOT NULL COMMENT 'PDA任务ID',
   operation_id VARCHAR(128) NOT NULL COMMENT '客户端全局幂等操作ID',
   request_hash CHAR(64) NOT NULL COMMENT '规范化请求摘要',
-  command_status VARCHAR(16) NOT NULL COMMENT 'PROCESSING、RETRYABLE、FAILED、COMPLETED',
+  command_status VARCHAR(16) NOT NULL COMMENT '命令状态：PROCESSING处理中、RETRYABLE可重试、FAILED失败、COMPLETED已完成',
   expected_task_version INT UNSIGNED NOT NULL COMMENT '受理时客户端任务版本',
   remark VARCHAR(500) NULL COMMENT '完成备注',
   operator_id BIGINT UNSIGNED NOT NULL COMMENT '操作人ID',
@@ -600,9 +600,9 @@ CREATE TABLE IF NOT EXISTS fl_loading_completion_command (
   failure_code VARCHAR(32) NULL COMMENT '下游或业务错误码',
   failure_request_id VARCHAR(64) NULL COMMENT '下游请求ID',
   failure_trace_id VARCHAR(64) NULL COMMENT '下游链路ID',
-  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),
-  completed_at DATETIME(3) NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '命令创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '命令更新时间',
+  completed_at DATETIME(3) NULL COMMENT '命令完成时间',
   PRIMARY KEY (id),
   UNIQUE KEY uk_loading_completion_operation (operation_id),
   KEY idx_loading_completion_dispatch (command_status,next_retry_at,lease_until),
@@ -611,13 +611,13 @@ CREATE TABLE IF NOT EXISTS fl_loading_completion_command (
 ) ENGINE=InnoDB COMMENT='PDA装柜完成可靠异步命令';
 
 CREATE TABLE IF NOT EXISTS fl_loading_completion_checkpoint (
-  command_id BIGINT UNSIGNED NOT NULL,
-  tenant_id BIGINT UNSIGNED NOT NULL,
-  inbound_id BIGINT UNSIGNED NOT NULL,
-  owner_sequence INT UNSIGNED NOT NULL,
-  checkpoint_stage VARCHAR(24) NOT NULL COMMENT 'READY、SETTLED、INBOUND_COMPLETED',
-  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),
+  command_id BIGINT UNSIGNED NOT NULL COMMENT '可靠装柜完成命令ID',
+  tenant_id BIGINT UNSIGNED NOT NULL COMMENT '入仓单客户ID',
+  inbound_id BIGINT UNSIGNED NOT NULL COMMENT '入仓单ID',
+  owner_sequence INT UNSIGNED NOT NULL COMMENT '稳定处理顺序',
+  checkpoint_stage VARCHAR(24) NOT NULL COMMENT '处理阶段：READY待处理、SETTLED资源已结算、INBOUND_COMPLETED入仓已完成',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '检查点创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '检查点更新时间',
   PRIMARY KEY (command_id,tenant_id,inbound_id),
   KEY idx_loading_completion_owner (command_id,owner_sequence),
   CONSTRAINT fk_loading_completion_checkpoint_command FOREIGN KEY (command_id)