-- ============================================================
-- 通用待办任务工作台 — 步骤实例表
--
-- 解决短板：tw_task 仅记录"当前 step_key"，tw_task_log 是事件流，
-- 无法 O(1) 查询"任务在每一步停留多久 / 输入输出快照"。
--
-- 该表在 task 内部 step_key 切换、任务提交/退回/撤销时生成/关闭一条记录，
-- 配合 tw_task_log 构成完整的流转轨迹。
-- ============================================================

CREATE TABLE IF NOT EXISTS tw_task_step_instance (
  instance_id      VARCHAR(32)  NOT NULL COMMENT '步骤实例ID',
  task_id          VARCHAR(32)  NOT NULL COMMENT '任务ID',
  step_key         VARCHAR(64)  NOT NULL COMMENT '步骤键',
  step_type        VARCHAR(32)           COMMENT '步骤类型 agent_prefill/human_form/kcp_check/...',
  executor         VARCHAR(64)           COMMENT '执行者声明（来自 process.steps[].executor）',
  entered_at       DATETIME(3)  NOT NULL COMMENT '进入时间（毫秒精度）',
  exited_at        DATETIME(3)           COMMENT '离开时间，NULL=仍停留在该步',
  duration_ms      BIGINT                COMMENT '停留毫秒（exited_at - entered_at），离开时回填',
  status           VARCHAR(20)  NOT NULL DEFAULT 'entered' COMMENT 'entered/completed/returned/cancelled/transferred',
  input_snapshot   JSON                  COMMENT '进入时输入数据快照',
  output_snapshot  JSON                  COMMENT '离开时输出数据快照',
  transition_from  VARCHAR(64)           COMMENT '上一步 step_key（来源）',
  transition_to    VARCHAR(64)           COMMENT '下一步 step_key（去向）',
  operator_id      VARCHAR(32)           COMMENT '操作者ID',
  remark           VARCHAR(500)          COMMENT '备注',
  created_at       DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (instance_id),
  INDEX idx_task_time (task_id, entered_at),
  INDEX idx_step_status (step_key, status),
  INDEX idx_open_step (task_id, exited_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='任务步骤实例（流转停留快照）';
