设计文档简化状态机

script/sql/mysql/item/gear_stock_io_order.sql

@@ -1,9 +1,9 @@
 -- ================================
 -- 出入库单据控制层
--- 目标：通过“单据 -> 审核 -> 执行”控制库存变更，避免直接操作出入库流水
+-- 目标：通过“单据 -> 完成 -> 执行”控制库存变更，避免直接操作出入库流水
 -- 说明：
 -- 1) 业务先创建出入库单据，再由单据驱动实际 gear_stock_io / gear_stock_io_detail
--- 2) 单据支持草稿、提交、审核、执行、作废、冲销
+-- 2) 单据仅保留两种状态：进行中、已完成
 -- 3) 通过关联字段保留来源单、回退单、执行单之间的链路
 -- ================================
 
@@ -16,6 +16,15 @@ CREATE TABLE gear_stock_io_order (
   source_type            varchar(32)     DEFAULT ''                COMMENT '来源单据类型（采购单/销售单/退货单/调拨单等）',
   source_no              varchar(64)     DEFAULT ''                COMMENT '来源单据编号',
   source_order_id        bigint(20)      DEFAULT NULL              COMMENT '来源单据ID（业务单ID）',
+  responsible_id         bigint(20)      DEFAULT NULL              COMMENT '责任人ID',
+  responsible_name       varchar(64)     DEFAULT ''                COMMENT '责任人姓名',
+  plan_arrival_time      datetime                                  COMMENT '预计到货时间',
+  actual_arrival_time    datetime                                  COMMENT '实际到货时间',
+  plan_finish_time       datetime                                  COMMENT '预计完成时间',
+  actual_finish_time     datetime                                  COMMENT '实际完成时间',
+  delay_minutes          int(11)         NOT NULL DEFAULT 0         COMMENT '延迟分钟数',
+  delay_reason           varchar(500)    DEFAULT ''                COMMENT '延迟原因',
+  delay_status           char(1)         NOT NULL DEFAULT '0'      COMMENT '延迟状态（0正常 1超时 2已处理）',
   warehouse_id           bigint(20)      DEFAULT NULL              COMMENT '主仓库ID',
   from_warehouse_id      bigint(20)      DEFAULT NULL              COMMENT '调出仓库ID',
   to_warehouse_id        bigint(20)      DEFAULT NULL              COMMENT '调入仓库ID',
@@ -47,6 +56,8 @@ CREATE TABLE gear_stock_io_order (
   KEY idx_biz_type (biz_type),
   KEY idx_source_no (source_no),
   KEY idx_source_order_id (source_order_id),
+  KEY idx_responsible_id (responsible_id),
+  KEY idx_delay_status (delay_status),
   KEY idx_create_time (create_time),
   KEY idx_source_io_id (source_io_id),
   KEY idx_reversal_flag (reversal_flag)

script/sql/mysql/item/gear_stock_io_order_design.md

@@ -16,8 +16,9 @@
 1. 所有库存变动都先落单据
 2. 单据状态只保留“进行中”和“已完成”两个状态
 3. 单据完成后自动生成实际出入库流水
-4. 做错时通过反向单据回退，不直接改历史流水
-5. 保留完整审计链路，方便追责和排查
+4. 需要监管责任人、到货时间、完成时间和延迟时间
+5. 做错时通过反向单据回退，不直接改历史流水
+6. 保留完整审计链路，方便追责和排查
 
 ---
 
@@ -36,6 +37,10 @@
 - `warehouse_id` / `from_warehouse_id` / `to_warehouse_id`：仓库维度信息
 - `status`：单据状态（0进行中 1已完成）
 - `exec_flag`：是否已执行
+- `responsible_id` / `responsible_name`：责任人信息
+- `plan_arrival_time` / `actual_arrival_time`：到货时间
+- `plan_finish_time` / `actual_finish_time`：完成时间
+- `delay_minutes` / `delay_reason` / `delay_status`：延迟统计信息
 - `reversal_flag` / `reversal_order_id`：冲销标记与原单关联
 - `source_io_id`：对应实际执行的出入库单
 
@@ -299,7 +304,8 @@
 
 3. **超时扫描任务**
    - 定时任务扫描 `plan_finish_time` 已超时但未完成的单据
-   - 自动更新超时状态
+   - 自动更新 `delay_status`
+   - 计算并回写 `delay_minutes`
    - 生成待办/消息通知给责任人和主管
 
 4. **统计报表接口**
@@ -328,6 +334,22 @@
 
 这样数据库层就能直接支撑统计和报表。
 
+### 5.14 SQL 已落地字段说明
+
+当前 SQL 已直接加入这些字段，因此后端实体、Mapper、VO、DTO 需要同步补齐：
+
+- 责任人字段用于监管归属
+- 计划/实际时间字段用于对比差异
+- 延迟字段用于列表筛选和报表聚合
+
+建议后端在以下时机回写字段：
+
+- 创建单据时：写入责任人、计划时间
+- 到货确认时：写入 `actual_arrival_time`
+- 完成时：写入 `actual_finish_time`、`delay_minutes`
+- 定时任务发现超时：写入 `delay_status=1`
+- 人工处理后：写入 `delay_status=2`
+
 ---
 
 ## 6. 代码改造建议