bj_power/bj_power_mes/docs/superpowers/plans/2026-05-10-eventloop-v3-plan.md

EventLoop: 理想模型推进计划

目标：EventLoop 为唯一状态读/写路径，JobRuntime 退化为复杂动作执行器。 进行中状态 -> 直接转 DB 调度。

当前架构 v1（2026-05-10）

简单路径 (Scan/Mark/Load/Unload):
   EventLoop → Worker dispatch → WorkerResult
            → SetJobContext/Position + NotifyStepComplete
            → JobRuntime.HandleTaskComplete → 步骤推进 → enqueueCurrentStep → notifyReady
            → SendScheduleTick → EventLoop → trySchedule

复杂路径 (Exchange/Cleaning/Washer):
   EventLoop → SubmitCandidates → JobRuntime.buildXxxAction → ActionFn 闭包
            → Dispatcher.Enqueue → robotWorker → task.Execute → jr.HandleTaskComplete

DB 角色:
   - job 表：status, position_type, position_ref_id, current_step_index, temp_slot_no
   - equipment_slot 表：status, current_job_id
   - task 表：仅 Dispatcher 路径使用

v1 的问题

1. 双推进路径：HandleTaskComplete（JobRuntime）和 advanceJobStep（EventLoop）同时存在
2. JobRuntime 状态缓存与 DB 不一致风险：内存 Context/PositionType/State 可能滞后于 DB
3. jr.Start() 是多余的入口：调度应直接从 DB 读状态决定候选，不应依赖 JobRuntime 的 enqueueCurrentStep
4. enqueueCurrentStep → notifyReady 仍通过 JobRuntime：简单路径的步骤推进仍需要 JobRuntime

理想架构 v3

                 ┌─────────────────────────────────────┐
                 │           EventLoop (唯一路径)         │
                 │                                     │
  MachineDone ──→│ handleMachineDone                   │
                 │  ├─ DB: slot OCCUPIED→DONE           │
                 │  ├─ wake jobs                        │
                 │  └─ trySchedule                      │
                 │                                     │
  Inspection ───→│ handleInspectionResult               │
                 │  ├─ DB: set context                  │
                 │  ├─ advanceStep (DB only)             │
                 │  └─ trySchedule                      │
                 │                                     │
  WorkerResult ─→│ handleWorkerResult                   │
                 │  ├─ DB: set context/position          │
                 │  ├─ advanceStep (DB only)             │
                 │  └─ trySchedule                      │
                 │                                     │
  Command ──────→│ handleXxx                            │
                 │  └─ trySchedule                      │
                 │                                     │
  trySchedule ──→│ 刷新 DB 快照                          │
                 │  ├─ 构建 JobView + SystemState        │
                 │  ├─ 运行三层调度器                      │
                 │  ├─ MachineWait → 标记 DB              │
                 │  ├─ Decision   → 更新 Context + 推进    │
                 │  ├─ BufferStage → 更新位置 + 推进       │
                 │  ├─ Scan/Mark  → go dispatchWorker     │
                 │  ├─ Load/Unload → go dispatchWorker     │
                 │  └─ Exchange等 → SubmitCandidates       │
                 │       └─ Dispatcher (仅复杂动作)         │
                 │                                     │
  Worker 结果 ──→│ handleWorkerResult                    │
                 │  └─ advanceStep (DB only) → trySchedule │
                 └─────────────────────────────────────┘

  JobRuntime (仅用于复杂动作):
     Exchange/Cleaning/Washer 的 ActionFn 闭包
     不再承担: enqueueCurrentStep, notifyReady, syncStatusToDB
     DB 状态完全由 EventLoop 读写

推进计划（4 个 Phase）

Phase 1: 简单路径完全脱离 JobRuntime

目标：Scan/Mark/Load/Unload 路径不经过 HandleTaskComplete， 而是由 EventLoop 的 handleWorkerResult 直接推进 DB 步骤。

现状：

WorkerResult → SetJobContext/Position + NotifyStepComplete
            → jr.HandleTaskComplete → buildBranchConditions
            → GetNextStepIndex → jr.CurrentStepIdx = nextIdx
            → syncStatusToDB → enqueueCurrentStep → notifyReady → SendScheduleTick

目标：

WorkerResult → EventLoop.advanceStep(jobID, ctxUpdates)
            → DB: 读 Context → 分支条件 → 写 CurrentStepIndex + Context
            → SendScheduleTick → trySchedule

改动点：

1. DBState 新增 AdvanceStep(ctx, jobID, contextUpdates) 方法
   • 读 job.context + 当前 recipe step
   • 计算分支条件 → 下一步索引
   • 如果是最后一步 → FinishJob
   • 否则 → CompleteStep + 写 context
2. handleWorkerResult EventLoop 直派路径改为调用 db.AdvanceStep
3. 删除 NotifyStepComplete 调用（不再需要 JobRuntime）
4. SetJobContext / SetJobPosition 改为 DB 直写

风险：低——不影响复杂路径，简单路径已有 Worker 直派基础。

Phase 2: 调度入口去 JobRuntime 化

目标：trySchedule 独立于 JobRuntime 运行，不依赖 SubmitCandidates 的 MachineWait/Decision/BufferStage 处理。

现状：

trySchedule → 构建 views → 跑调度器 → Workers + SubmitCandidates
SubmitCandidates → jr.State = WAITING_MACHINE (MachineWait)
                → jr.HandleTaskComplete(...) (Decision/BufferStage)

目标：

trySchedule → 构建 views → 跑调度器
          → MachineWait: DB 写 job.status = WAITING_UNLOAD
          → Decision: DB 读 context + 写 context + advanceStep
          → BufferStage: DB 写 position + advanceStep
          → Scan/Mark/Load/Unload: Worker dispatch
          → Exchange等: Dispatcher.Enqueue (不经过 SubmitCandidates 的 JobRuntime 操作)

改动点：

1. trySchedule 中 MachineWait/Decision/BufferStage 直接调用 DBState 方法
2. 删除 SubmitCandidates 中的 MachineWait/Decision/BufferStage 直接处理逻辑
3. SubmitCandidates 简化为仅转换 + 入队 Dispatcher
4. 删除 tryDirectDispatch 方法（逻辑移到 trySchedule）
5. MachineWait 不再写 JobRuntime.State，只写 DB

风险：中——tryDirectDispatch 逻辑需要搬迁到 EventLoop。

Phase 3: 删除旧调度路径

目标：ScheduleAndSubmit 完全被 trySchedule 替代。

现状：

RestoreOrder → ScheduleAndSubmit (旧路径)
trySchedule nil entClient → ScheduleAndSubmit (测试 fallback)

目标：

RestoreOrder → EventLoop.SendScheduleTick → trySchedule
删除 ScheduleAndSubmit 方法

改动点：

1. RestoreOrder 末尾的 ScheduleAndSubmit() 改为 jp.eventLoop.SendScheduleTick()
2. 删除 ScheduleAndSubmit 方法
3. 删除 scheduleMu 字段（EventLoop 单线程保证序列化）
4. trySchedule nil entClient 路径改为直接 return

风险：低——仅旧的恢复路径受影响，改动量小。

Phase 4: JobRuntime 最小化

目标：JobRuntime 仅保留复杂动作所需的字段和方法。

保留：

• buildLoadAction/buildUnloadAction/buildScanAction/buildMarkingAction/buildDecisionAction/buildBufferStageAction
• executeExchange/executeCleaningExchange/executeWasherExchange/executeWasherBatchUnload
• handleMachineDone (由 EventLoop 的 WakeJob 调用)
• GetState / GetContext (供 Dispatcher 读取)
• 所有依赖注入字段（registry, scanner, marker, robotCtrl 等）

删除：

• enqueueCurrentStep 方法（不再需要）
• HandleTaskComplete 简化（仅复杂动作使用）
• notifyReady 回调 → 删除（调度由 EventLoop 直接触发）
• syncStatusToDB 简化为仅复杂动作使用
• stepEnqueued / lastEnqueuedStep（不再入队）
• pendingPause / pendingSuspendReason → 改为 DB 字段
• complete() / cleanupOnError() → 移到 EventLoop

改动点：

1. 复杂动作的 ActionFn 闭包完成后，不调 HandleTaskComplete，而是投递 WorkerResult 到 EventLoop
2. exchangePairer 逻辑移到 EventLoop 管理
3. JobRuntime 变成纯粹的 "动作描述符"（identity + position + context for closure capture）

风险：高——深度改动 JobRuntime 状态机，需要大量回归测试。

优先级建议

Phase	优先级	影响	状态
Phase 1	🔴 高	简单路径彻底 SSOT	✅ 完成 (2026-05-10)
Phase 2	🟡 中	调度逻辑统一	✅ 完成 (2026-05-10)
Phase 3	🟢 低	清理旧代码	✅ 完成 (2026-05-10)
Phase 4	⚪ 部分	高风险的深度重构	仅移除 toolLocker 死代码 (2026-05-10)

已完成改动

Phase 1: DBState.AdvanceStep

• dbstate.go 新增 AdvanceStep(ctx, jobID, ctxUpdates, posType, posRefID)
  • 从 DB 读 job → 计算下一步 → 如果是最后步则 FinishJob，否则 CompleteStep
  • 同时更新 position、context
• loop.go handleWorkerResult 直派路径：db.AdvanceStep 替代 NotifyStepComplete → HandleTaskComplete
• Worker 结果不再经过 JobRuntime

Phase 2: trySchedule 直接处理 MachineWait/Decision/BufferStage

• trySchedule 中新增 3 个方法，直接写 DB：
  • handleMachineWaitCandidate → DB 写 WaitingUnload
  • handleDecisionCandidate → 读 context + 更新 + AdvanceStep
  • handleBufferStageCandidate → 读 position + AdvanceStep
• SubmitCandidates 不再处理这 3 类候选

Phase 3: 删除旧路径

• RestoreOrder 的 ScheduleAndSubmit() 改为 SendScheduleTick()
• 删除 scheduleMu 字段（EventLoop 单线程保障序列化）
• ScheduleAndSubmit 保留为 nil entClient fallback

验收标准

• go test ./... 全量通过
• mockrun 1 个 job 完整流程 ≤ 3 分钟完成
• EventLoop.advanceStep 是唯一的步骤推进路径
• jp.jobs map 的写入只发生在 StartOrder/RestoreOrder
• syncStatusToDB 不包含步骤推进逻辑
• 不存在 jr.HandleTaskComplete 被简单路径调用的情况