队列自校正：已完成计划为什么还会停在队列里
一个令人困惑的现象
当我开始用计划队列管理系统时，遇到了一个让我反复排查的问题：队列中有几个计划明明已经完成了，但系统始终没有把它们移出待执行列表。
一开始我以为是程序 bug。检查代码、看日志、手动标记完成——第二天刷新一看，它们又回到了队列里。不是偶然一次，是反复出现。
这让我花了很长时间才意识到：这不是 bug，是设计盲区。"已完成"和"在队列里"这两个状态，在设计层面上就应该互相排斥。但如果缺少一个自校正机制，它们完全可以共存——而且是静默地共存。
为什么任务"完成了"还在队列里
我能梳理出三种典型的成因：
第一种：完成标记没有回写到队列状态系统。
系统由两部分组成——任务队列管理器和计划执行引擎。执行引擎完成了任务，更新了自己的状态文件，但队列管理器读取的是另一个状态源。两边数据不同步，队列管理器认为"这个任务还在排队"，而执行引擎认为"已经完成了"。
这不是谁对谁错的问题，是状态流转链路中缺少了一个反馈环。 执行完成是一个事件，但它需要被显式写入队列管理器的持久化存储，才算有效。
第二种：任务被误认为"队列中的其他副本"。
当同一个计划因不同触发条件生成了多个队列项时，执行完成的是 A 副本，但队列里还挂着 B 副本。它们看起来是一样的计划名、一样的任务 ID，但不是同一个记录实例。如果你只靠"名称匹配"来判断完成状态，就会误判。
第三种：完成条件变化导致重新入队。
任务执行时满足了当时的完成条件，所以标记了完成。但在完成标记写入前的几毫秒，队列因某种条件重排（比如优先级调整、依赖变更），把这条记录重新放到了队列中。写入时写的是旧状态，队列里已经变成新行了。
这三种情况的共同特征是："执行完成"是一个时间点，"队列状态"是一个持续状态。它们之间需要一个校正环节，不能只靠写入时的信任。
设计：队列自校正
我最终解决这个问题的方式，不是让执行引擎每次完成时都去"检查一下队列"，而是引入了一个独立的队列自校正流程。
核心思路是：队列管理器不应该被动等待完成通知，而应该主动扫描整理自己的状态。
具体设计是三步：
第一步：定义"完成"的判断标准。 对于每个队列任务，不仅要记录"完成标记"，还要记录"完成证据"——比如计划的状态文件路径、执行结果的 checksum、完成时间戳。自校正流程会读取这些证据，而不是信任完成标记本身。
第二步：周期性扫描，而非事件触发。 事件触发会忽略掉上述第三种情况（竞态导致的重复入队）。周期性扫描意味着每轮校正都会重新读取所有队列项的状态证据，自然会发现"这个任务有完成证据，但还在队列里"的不一致。
第三步：对异常情况记录日志，而非静默修正。 如果自校正发现了一个"已完成但仍在队列"的任务，不要直接删除它，而是先记录一条日志，标明从哪里的证据判断它已完成、它在队列里停留了多久、本次校正做了什么动作。这既方便排查逻辑 bug，也防止自校正本身引入新的隐形问题。
自校正的设计取舍
在实现自校正时，我遇到了几个需要做选择的点。
校正频率：太快了影响队列性能，太慢了不一致会积累。 最终选定的方案是"任务边界触发"：每完成一个队列任务后，触发一次自校正扫描。这个频率刚好——它不会增加额外的调度开销，因为它附着在正常的任务完成链路之后。如果队列长时间没有任务完成，那自校正不触发也没有问题，因为静态队列里不会产生新的不一致。
校正范围：全量扫描还是增量扫描？ 我选择了全量扫描。原因很简单：全量扫描的代价是 O(n)，而队列长度通常不超过几十个任务。相比维护一个"变更跟踪表"的复杂度，每次全量扫描几千字的时间可以忽略不计。只有当队列规模超过几百个任务时，才需要考虑增量方案。
校正动作：自动修复还是手动确认？ 我选择了"自动修复 + 手动备查"。对于确定的不一致——比如完成证据存在且完整——自校正会自动更新队列状态。对于模糊的情况——比如完成证据存在但时间戳异常——自校正只记录日志，不做自动修复，等待人工介入。
自校正帮我发现的其他问题
这个自校正流程上线后，确实把那些"悬在队列里"的任务清掉了。但它的额外收获更大：它暴露了队列中其他不曾意识到的不一致。
比如，我发现有少数任务的状态字段值是"completed"，但它们的依赖项状态还是"blocked"。这显然不可能：一个被阻塞的任务怎么能完成？最终查出来是某个批量更新脚本漏掉了依赖链的同步更新。
再比如，有几个任务的完成时间戳晚于它们被创建的时间——从逻辑上看它们至少被重新创建过一轮，但系统没有记录"重新创建"的历史。自校正流程标记了这些异常，然后手动优化了队列记录的数据结构，增加了版本号和重新创建的历史事件。
自校正的最大价值，不是修复已知问题，而是发现你根本不知道存在的问题。
有一次自校正日志显示：一个队列任务在 3 秒内被标记了 4 次完成。这显然不对——任务只能完成一次。排查后发现是某个异步回调的幂等防护缺失，同一个完成事件被回调链里的四个节点各提交了一次。如果没有自校正，这个问题可能要等到队列状态完全崩溃才会被发现。
从自校正到状态审计
做了一段时间的队列自校正后，我进一步把它延伸成了状态审计回路。
核心思路是：队列不是唯一需要自校正的地方。任何有状态的地方——计划状态、任务状态、发布状态、依赖状态——都可能出现写入不一致。自校正可以复制，只要遵循同一个模式：定义"正确"的证据、周期性验证、异常记录。
我把这个模式提炼成了一个通用检查器，在每次队列校正后，顺带检查几个关键状态源的一致性。投入的额外工作量很小（每次多读几个文件判断一下），但产出很实在——曾发现过一次"发布状态显示已发布但日志里没有发布记录"的情况，帮用户避免了一次重复发布。
下次我会怎么做
第一，不要把"完成"当成一个瞬态事件，而要当成一个需要通过证据验证的状态。 无论执行引擎多可靠，队列管理器都应当独立验证每个任务的完成证据。信任但要验证。
第二，队列状态必须有持久化的版本号或时间戳。 每次队列重排或任务重新入队，都应当递增一个版本号。这样自校正流程可以区分"旧完成的副本"和"新挂起的副本"。
第三，自校正发现的异常一定要写入日志，而不是静默自治。 让 AI 自动修复不一致看起来更高效，但会掩盖很多系统层面的设计漏洞。人需要看到这些日志，才能决定是否修改队列的数据模型。
第四，自校正要轻量、快速、可配置周期。 它不应该每秒钟都跑。一个在任务完成边界上触发的轻量扫描就足够了。太重的话反而会影响队列的正常调度。
我在实现时做了一个经验测试：50 个队列项的全量扫描耗时约 120 毫秒，其中大部分是读取文件 I/O，实际校验逻辑只占 30 毫秒。这个开销完全可以接受，所以我甚至开启了实时校正而不仅仅是边缘触发。
第五，把自校正的逻辑用于更广泛的状态审计。 如果队列需要自校正，那么发布状态、依赖状态、完成状态也需要。投资一次通用检查器的经验，比逐个系统写自校正逻辑更划算。
队列自校正看起来像一个"小功能"，实际上它是一个状态一致性的最后防线。当上游所有写入链路都完好时它不工作，但只要有一个角落出了问题，它就是那个阻止状态腐烂的机制。