设计文档简化状态机

script/sql/mysql/item/gear_stock_io_order.sql

@@ -19,7 +19,7 @@ CREATE TABLE gear_stock_io_order (
   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',
-  status                 char(1)         NOT NULL DEFAULT '0'      COMMENT '单据状态（0草稿 1已提交 2已审核 3已执行 4已作废 5已冲销）',
+  status                 char(1)         NOT NULL DEFAULT '0'      COMMENT '单据状态（0进行中 1已完成）',
   exec_flag              char(1)         NOT NULL DEFAULT '0'      COMMENT '执行标志（0未执行 1已执行）',
   reversal_flag          char(1)         NOT NULL DEFAULT '0'      COMMENT '是否冲销单（0否 1是）',
   reversal_order_id      bigint(20)      DEFAULT NULL              COMMENT '对应原单据ID',

script/sql/mysql/item/gear_stock_io_order_design.md

@@ -14,8 +14,8 @@
 ## 2. 设计目标
 
 1. 所有库存变动都先落单据
-2. 单据必须支持草稿、提交、审核、执行、作废、冲销
-3. 单据执行后自动生成实际出入库流水
+2. 单据状态只保留“进行中”和“已完成”两个状态
+3. 单据完成后自动生成实际出入库流水
 4. 做错时通过反向单据回退，不直接改历史流水
 5. 保留完整审计链路，方便追责和排查
 
@@ -34,19 +34,15 @@
 - `biz_type`：业务类型，如 `purchase`、`sale`、`return`、`transfer`、`other`
 - `source_type` / `source_no` / `source_order_id`：关联来源业务单
 - `warehouse_id` / `from_warehouse_id` / `to_warehouse_id`：仓库维度信息
-- `status`：单据状态
+- `status`：单据状态（0进行中 1已完成）
 - `exec_flag`：是否已执行
 - `reversal_flag` / `reversal_order_id`：冲销标记与原单关联
 - `source_io_id`：对应实际执行的出入库单
 
 状态建议：
 
-- `0` 草稿
-- `1` 已提交
-- `2` 已审核
-- `3` 已执行
-- `4` 已作废
-- `5` 已冲销
+- `0` 进行中
+- `1` 已完成
 
 ### 3.2 单据明细表 `gear_stock_io_order_detail`
 
@@ -69,14 +65,14 @@
 
 ## 4. 错单、超量、回退怎么处理
 
-### 4.1 未执行前发现错误
+### 4.1 进行中发现错误
 
-如果单据还没执行，处理方式最简单：
+如果单据还没完成，处理方式最简单：
 
-1. 撤回到草稿，修改明细
-2. 或直接作废单据，重新建正确单据
+1. 直接修改进行中的单据明细
+2. 或者作废当前单据，重新创建正确单据
 
-这种场景不涉及库存回退，因为库存还没变。
+这种场景不涉及库存回退，因为库存还没真正落地。
 
 ### 4.2 已执行后发现多入/多出/录错
 
@@ -188,18 +184,15 @@
 
 建议在代码里明确状态流转校验：
 
-- 草稿 -> 提交
-- 已提交 -> 审核
-- 已审核 -> 执行
-- 已执行 -> 冲销完成 / 已冲销
-- 草稿/已提交/已审核 -> 作废（未执行时）
+- 进行中 -> 已完成
+- 已完成 -> 冲销完成 / 已冲销（通过反向单据实现）
 
 禁止的操作：
 
-- 已执行后直接修改明细
-- 已执行后再次执行
-- 作废单据再执行
+- 已完成后直接修改明细
+- 已完成后再次执行
 - 冲销单再次冲销自己
+- 通过 UI 做一个“取消”状态，但数据库不保留该状态
 
 ### 5.6 事务控制
 
@@ -249,6 +242,92 @@
 - 影响物料
 - 影响批次
 
+### 5.10 负责人监管与延迟统计
+
+这套设计**可以监管到负责人**，而且可以统计“货到了但没及时入库”“货提走了但没点完成”等延迟问题。关键是要把“负责人字段 + 节点时间 + 完成时间”都保存下来。
+
+建议新增或在业务上补充以下维度：
+
+- `responsible_id`：责任人ID
+- `responsible_name`：责任人姓名
+- `plan_arrival_time`：预计到货时间
+- `actual_arrival_time`：实际到货时间
+- `plan_finish_time`：预计完成时间
+- `actual_finish_time`：实际完成时间
+- `delay_minutes`：延迟分钟数（可计算字段）
+- `delay_reason`：延迟原因
+- `delay_status`：是否超时/待处理/已处理
+
+如果是仓库入库场景，可以分成两个监管点：
+
+1. **到货未入库**
+   - 记录货到仓时间 `actual_arrival_time`
+   - 记录入库完成时间 `actual_finish_time`
+   - 通过两者差值统计“到货后未及时入库”的时长
+
+2. **提货未完成**
+   - 记录提货/出库开始时间
+   - 记录完成点击时间 `actual_finish_time`
+   - 若超过 SLA 仍未完成，系统自动标记为超时
+
+### 5.11 统计方式建议
+
+建议新增一个任务或查询逻辑，用于统计超时单据：
+
+- 按责任人统计未完成单据数
+- 按责任人统计平均延迟时长
+- 按仓库统计超时单据数
+- 按业务类型统计超时率
+- 按日期统计历史延迟趋势
+
+统计口径建议：
+
+- `actual_finish_time` 为空且当前时间 > `plan_finish_time`：视为超时未完成
+- `actual_finish_time` 不为空且 `actual_finish_time - plan_finish_time > 0`：视为超时完成
+- `actual_arrival_time` 不为空且 `actual_finish_time - actual_arrival_time > 0`：视为到货后入库延迟
+
+### 5.12 后端实现建议
+
+1. **单据主表增加责任人与时间字段**
+   - 在出入库单据创建时写入负责人
+   - 审核、执行、完成时分别回写对应时间
+
+2. **完成动作单独做接口**
+   - 不要只靠“执行成功”代表完成
+   - 增加 `finishOrder(orderId)` 或 `completeOrder(orderId)`
+   - 这样才能区分“已提货但未完成”和“真正完成”
+
+3. **超时扫描任务**
+   - 定时任务扫描 `plan_finish_time` 已超时但未完成的单据
+   - 自动更新超时状态
+   - 生成待办/消息通知给责任人和主管
+
+4. **统计报表接口**
+   - 按责任人、仓库、业务类型、时间段查询
+   - 前端做排行榜、明细表、超时趋势图
+
+5. **责任链闭环**
+   - 单据创建时指定责任人
+   - 单据执行时记录执行人
+   - 单据完成时记录完成人
+   - 超时时记录当前责任归属，避免“没人负责”
+
+### 5.13 如果要落到 SQL 的建议字段
+
+如果你希望这部分真正能统计，建议在 `gear_stock_io_order` 中补这些字段：
+
+- `responsible_id`
+- `responsible_name`
+- `plan_finish_time`
+- `actual_finish_time`
+- `plan_arrival_time`
+- `actual_arrival_time`
+- `delay_minutes`
+- `delay_reason`
+- `delay_status`
+
+这样数据库层就能直接支撑统计和报表。
+
 ---
 
 ## 6. 代码改造建议
@@ -275,6 +354,7 @@
 4. 再把库存执行逻辑抽到统一方法
 5. 再把原直接操作入口改成单据入口
 6. 最后补冲销接口
+7. 将前端状态显示简化为“进行中 / 已完成”
 
 ### 6.3 推荐接口拆分