diff --git a/docs/superpowers/specs/2026-11-03-operation-history-execution-design.md b/docs/superpowers/specs/2026-11-03-operation-history-execution-design.md new file mode 100644 index 0000000..b82cf31 --- /dev/null +++ b/docs/superpowers/specs/2026-11-03-operation-history-execution-design.md @@ -0,0 +1,232 @@ +# 操作历史与防重复执行:详细执行逻辑 + +状态:设计细化,尚未实施。本文延续《operation-history-resume-research》,用户已明确重复执行场景为同一个任务继续或重启后;不修改 DSH 功能。 + +用户已确认:某个 CBB 失败后,只要已经证明没有残留改动且资源已释放,跳过本次失败,继续后面的工程;结果不确定或核验失败时仍停止。 + +## 1. 执行范围与基本约束 + +“CBB 工程执行过”不等于“该工程所有替换都做完”。不能按文件名、工程路径或任务状态一个字段去重。 + +使用三层范围: + +1. 任务:绑定实际工程,保留用户的任务身份。 +2. 轮次:一次明确确认的工程改动目标。继续、重启、清空历史不创建新轮次。 +3. 执行项:一次原生执行器实际接受的完整范围,通常为某工程/图页的一条替换规则及其目标集合。一项可能涉及多个位号;页面展开后可显示逐位号结果。 + +现有领域模型是一任务绑定一个工程。多个 CBB 组成批次,每个工程分别对应自己的任务和轮次;批次层负责顺序、依赖与失败后继续策略,不把多个工程塞入同一个新任务。整图页规则模式和精确位号模式均适用,不能仅在 BOM 模式下防重复。 + +同一任务、同一轮次中,已核验成功的执行项永不因“继续”而再次派发。一个图页完成,不代表其他图页完成;一条规则完成,不代表该 CBB 已完成。 + +正常默认行为:前面的完整项跳过,当前未完成项接续,结果不确定时停止。不得为了让进度走完,把失败、未命中、用户跳过或核验失败统一标为“替换成功”。 + +## 2. 稳定身份与冻结计划 + +### 2.1 身份 + +`operation_id` 在确认计划时生成一次,保存后不重新编号。必须区分以下身份,不能只对随机 ID 做唯一约束: + +- `plan_snapshot_hash`:包含计划版本的完整冻结快照,用于检查确认范围有没有变化。 +- `logical_operation_key`:可重算的同轮次逻辑项身份,**不包含计划版本、operation_id、attempt_id 或临时 job_id**,防止重复冻结/换版本绕过去重。 +- `target_claim`:已核验目标的占用记录,防止把同一目标重新拆组/合组后再次派发。精确位号执行须对 `(task_id, round_id, 原目标身份)` 做完成占用约束,成功后不能释放该占用来准备普通重试。 + +逻辑项身份输入至少包含: + +- `task_id`、显式持久化的 `round_id`; +- 规范工程身份与路径(使用现有 canonical/path identity 工具,不能只比较 CBB 名称); +- 原理图、图页; +- 执行模式:整图页规则或精确目标; +- 旧料号、新料号;目标 Cell; +- 全部目标 UID/位号及其必要的原始身份;目标集合按稳定顺序编码; +- Value 策略及自定义 Value、NC 策略。 + +`attempt_id` 代表一次尝试,每次获准重试都不同;临时 `job_id` 只关联执行器,不是防重复的唯一身份。数据库对同任务/同轮次逻辑项以及原目标完成占用同时约束,另以 CAS 约束单项活动尝试,禁止相同执行项被并发领走。 + +整图页规则模式在不能提供稳定目标身份时,不允许把已派发项重新拆组或扩大后继续。必须复用原冻结范围;需要改变范围则先核验,再显式确认新轮次,不能因为另一个版本的逻辑项 key 不同就重新处理成功目标。 + +### 2.2 冻结 + +确认前展示真实待执行范围和计数,事务内持久化轮次、计划及全部执行项,再允许启动执行器。计划保存失败,不派发 CAD。 + +第一次派发后原计划保持冻结。筛选、排序、页面切换不能改变计划。需要修正失败项时生成明确的失败项修订计划,预览并重新确认;已成功项不纳入该重试范围。不能通过随手换一个计划 hash,让原成功项变成“新任务”。 + +新轮次通过现有“开始新一轮”的显式入口进行:核验旧轮次、归档旧证据、创建新的活动轮次身份、重新采集当前工程基线、重新确认。新轮次的数据库变更与归档日志沿用现有崩溃恢复机制,不在启动时自动创建。 + +## 3. 执行项状态与允许操作 + +下表为执行项的设计状态,不表示现有 `TaskStatus` 已新增这些枚举。 + +| 状态 | 判定依据 | 点击继续 | 能否调用替换 | +| --- | --- | --- | --- | +| 待执行 `pending` | 已冻结计划,无已派发尝试 | 检查准入后领取 | 可以 | +| 已领取/准备 `prepared` | 派发身份已持久化,还未确认执行结果 | 核对进程、租约和尝试证据 | 仅明确证明未进入修改且旧执行器已退出后可重新领取 | +| 可能已修改 `mutation_possible` | 修改前保护标记已落盘,或运行中断无法排除修改 | 进入核验,不能当待执行 | 不可以 | +| 保存待核验 `saved_unverified` | 有保存结果,缺少完整重开回读证明 | 只做核验/恢复 | 不可以 | +| 已核验完成 `verified` | 当前项身份匹配,保存、重开回读和范围核验通过 | 跳过,读取下一项 | 不可以 | +| 未命中 `no_match` | 原确认范围的只读检查明确为零匹配 | 本轮跳过,不反复枚举 | 不可以 | +| 已确认失败 `failed_safe` | 明确未修改,或已核验回滚到基线 | 普通继续不重试;用户显式准备失败项重试 | 通过重试准入后可以 | +| 结果不确定 `uncertain` | 证据缺失/矛盾、租约不明、保存结果无法确认 | 阻断并指引核验 | 不可以 | +| 用户跳过 `skipped` | 用户明确跳过并给出原因 | 本轮不执行,计为跳过 | 不可以 | + +`restored_ok` 必须按其具体恢复证明解释:恢复到旧基线表示回滚已核验,不是替换成功;只有恢复流程明确证明目标结果已保存并重开核验,才能归并为 `verified`。 + +“未命中”只在当前冻结范围及有效工程状态下成立。它不是已保存修改,历史页不得将其列入替换成功数;要重新查找不同工程内容,走新范围确认,而不是在本轮继续中自动重置。 + +## 4. 一项操作的实际执行顺序 + +1. **准入**:取得现有队列/监督进程租约,核对项目身份、原计划、资源释放状态和停止意图。并发窗口不能同时执行一个工程或一个执行项。 +2. **核对回执**:命中本轮终态就跳过;遇到不完整尝试先恢复,不创建新队列绕过它。 +3. **领取**:用数据库比较并更新(CAS)将 `pending` 或已显式获准重试的项转为 `prepared`,保存 attempt 身份。领取失败或刷盘失败,不派发。 +4. **修改前检查**:确认旧执行器已结束,工程当前状态与预期基线一致,目标身份、料号和策略相符;完成备份。 +5. **写前保护**:沿用 `batch_attempt.prepare_attempt` / `mark_mutation_possible` 的身份和代次绑定。进入原生修改前必须可靠发布“可能已修改”证据,失败时拒绝修改。 +6. **执行与核验**:执行当前项,保存、关闭、重新打开回读;核对目标结果及现有非目标保护条件,关闭/释放本项资源。 +7. **提交回执**:在任务数据库同一事务中写入终态回执、推进轮次计数/工程预期状态、追加用户历史源事件。事务成功后才允许派发下一项。 +8. **更新页面**:UI 从已提交记录展示结果。页面刷新、回调或弹窗失败不会改变已提交终态,更不能触发重试。 + +任务数据库与外部 CAD 保存无法组成一个跨进程原子事务。因此只承诺“有可靠完成证据的不重放;不确定时先核验”,不承诺无法兑现的严格 exactly-once。 + +## 5. 暂停、继续、重启分别怎么走 + +### 5.1 完成当前项后暂停 + +- 先立即设置现有内存停止控制以阻止领取下一项,再持久化本轮暂停意图。 +- 暂停意图落盘失败时,当前进程仍保持停止状态并明确提示“暂停请求未能保存,请等待当前项收尾”;不能因保存异常而继续执行。重启后默认不自动执行,因此丢失暂停意图也不能成为自动派发依据。 +- 当前正在执行的项按现有安全机制收尾;其真实结果先提交,再停止领取下一项。 +- 暂停请求本身不代表当前项成功;如果当前项核验失败,显示待核验或安全失败。 +- 如果请求落在最后一项结束时,仍保留用户暂停意图,不能因“队列刚好耗尽”而自动开始失败项重试。 +- 重启后继续是用户对剩余范围的明确授权,不能由应用启动自动替代。 + +### 5.2 点击继续 + +1. 读取原任务、原轮次和冻结计划;显示上次完成/未命中/失败/待执行/待核验计数。 +2. 与持久化逐项回执及现有原生执行证据对账;原队列 ID 丢失不能导致逐项身份丢失。 +3. 验证当前工程是工具上次已核验后的预期状态。 +4. 汇总并提示本次实际待执行范围。例如:“原计划 12 项,已完成 7 项、未命中 2 项,本次继续 3 项”。 +5. 若存在待核验项,先阻断;否则只领取剩余合法 `pending` 项。 + +普通继续只处理可派发的待执行项,不包含失败项,也不解除“同工程失败后暂缓”的项。若只剩失败和暂缓项,显示“需处理失败项”,提供失败项重试/核验入口,而不是仍提供会反复空跑的继续按钮。 + +### 5.3 重启工具 + +启动只恢复显示和核对状态,不自动执行 CAD,不默认清空状态,不凭任务为 paused 就断言可重试。 + +- 原执行器仍存活或资源释放未证实:显示处理中/等待释放,不创建第二个执行器。 +- 记录完整且所有尝试均已收尾:保留原完成项,展示可继续的剩余范围。 +- 存在可能修改但未提交结果的项:转为待核验。 +- 数据库、文件、计划或步骤身份冲突:展示“恢复受阻”,保留原记录供核对。 + +### 5.4 强制结束 + +沿用原有强制结束确认与保护记录。不能把强制结束当作回滚成功,也不能把它之后的所有项统一标失败后自动重试。只把确实无法排除修改的当前项转为待核验;从未派发的后续项保持待执行。 + +## 6. 崩溃位置与恢复决定 + +| 中断位置/证据组合 | 恢复决定 | +| --- | --- | +| 冻结计划事务尚未提交,且没有派发/修改痕迹 | 不执行;重新确认计划 | +| 已领取,有匹配的 prepared 证明,旧进程已退出且明确未进入修改 | 原执行项保留;在重新授权后创建新 attempt | +| 修改标记已发布,未收到完整结果 | 待核验,不重放 | +| 已保存或 worker 报成功,但终态回执尚未提交 | 从绑定的原生证据核验;证明通过后补记回执,不再次替换 | +| 回执已提交,UI 尚未显示就退出 | 读取已提交终态,跳过该项 | +| 命令还在但状态文件缺失/损坏 | 有有效新回执时对账;否则阻断,不返回“0 项、未执行” | +| 数据库终态与文件终态冲突,或回执引用的证据无法验证 | 已终态项不重新派发;暂停续跑,核对冲突 | +| 旧版本没有新回执,只有完整且可绑定的旧执行证据 | 经兼容校验导入同轮次记录;无法证明的项进入待核验,不按进度数字补造成功 | +| 一次执行涵盖多个位号,结果部分通过 | 整项待核验,展开列出各位号观测;使用现有核验/恢复能力处理,禁止对整组盲目重试 | + +任何“缺文件就创建新状态文件”“读取失败就归零”“找不到原队列就从头新建”的降级都不允许。 + +### 6.1 记录权威与旧回调隔离 + +- 已提交的数据库终态是调度依据;TSV、普通日志、UI 回调不能把它降级成待执行,也不能覆盖为另一次尝试的结果。 +- 提交必须匹配当前 `operation_id + attempt_id + generation`。旧尝试晚到的回调只保留为诊断证据,不推进新尝试、汇总进度或新的工程基线。 +- 证据与数据库冲突时阻断并核验,不任意挑一份覆盖另一份。恢复只能按证据补齐合法的单调状态转换。 +- 租约超时只意味着需要检查,不证明旧进程已退出。只有已证明旧进程退出或原执行代次被有效隔离,且修改风险已解决,才允许新的尝试。 + +## 7. 工程变化、失败与其他 CBB 的处理 + +### 7.1 工具自己改过的工程 + +不能把暂停后的工程与最初项目文件哈希直接比较:前面的合法替换必然会改变它。 + +保存基线链:初始已确认工程状态 → 第 1 项核验后状态 → 第 2 项核验后状态。继续时比较最近已提交回执对应的预期状态,核对将要执行的目标及现有工程/库安全身份。 + +工程语义检查沿用原生快照和目标身份核验。证据文件字节哈希用于检验证据完整性;不能把易变数据库时间戳直接等同于工程语义变化,也不能因路径相同而忽略实际工程被替换。 + +检测到额外修改时,先列出差异,阻断当前续跑,由用户核验并重新确认范围;不自动“接受新基线”来清掉旧回执。 + +### 7.2 失败后是否继续其他 CBB + +用户已选择“跳过这次失败,继续后面的工程”。因此默认按以下规则处理: + +1. 明确确认当前工程未修改,或已经完整回滚且核验通过,并确认资源释放后,该 CBB 本次收尾,进入确认范围内下一个可独立执行的工程。 +2. 原失败项仍记为失败,带错误和证据,不改成成功,也不把它伪装成普通的“用户跳过”。同一 CBB 中尚未派发的后续项保持“待执行/本次未执行”,带 `project_failure` 暂缓原因,不误标完成,不在该次失败后继续领走。只有该工程失败项已妥善解决、范围仍有效并重新确认,才解除暂缓。 +3. 如果后续工程对失败工程有已声明的依赖,则该后续工程记为依赖受阻;继续其他无依赖且可执行的工程,不自动忽略依赖。 +4. 未知结果、核验失败、资源未释放、证据冲突始终阻断整队,不能使用“继续后面的工程”覆盖该保护。 +5. 本次结束显示“X 个工程完成、Y 个工程失败、Z 个工程未执行/依赖受阻”。“队列收尾”不能等同于“所有改动成功”。 + +失败项重试通过明确的“准备失败项重试”入口,限定原失败项,建立新 attempt 并保留原失败记录。成功项、未命中项和未派发项不被整体清空后重新编号。 + +### 7.3 汇总状态 + +- 有活动执行项:执行中。 +- 有不确定/证据冲突项:待核验/恢复受阻。 +- 用户暂停且仍有待执行项:已暂停。 +- 所有项都有明确终态,但存在失败或用户跳过:执行已收尾、有失败/跳过,不能显示“全部替换成功”。 +- 所有项均为 verified 或有效 no_match:本轮完成,并分别显示保存与未命中数量。 + +补充任务/批次层级的收尾规则: + +- 单工程任务存在 `failed_safe`,其余未执行项均因 `project_failure` 暂缓时,显示“需处理失败项”,禁用普通继续,提供失败项处理入口;不把它归成用户暂停。 +- 批次所有可独立派发工程已经收尾,剩余仅失败、暂缓或依赖受阻时,显示“本次执行已收尾,有失败/未执行”。它不是全部完成,也不反复提供会空跑的批次继续按钮。 +- 只有仍存在通过准入的独立待执行项时,才显示可执行的“继续剩余项”及其确切数量。 + +以上是汇总推导规则,映射到现有任务状态时保留兼容性;不能只依赖一个 `TaskStatus.COMPLETED` 字段代替逐项判定。 + +## 8. 历史记录与清空 + +执行回执、原始诊断证据、用户历史分别管理;“分别管理”不要求拆成不同数据库。 + +建议回执、历史源事件与汇总更新使用同一任务数据库事务,避免“CAD 已完成、页面显示成功但没有完成回执”。历史页是可查询的显示记录,不是继续执行的判定来源。 + +### 8.1 历史记录内容 + +保存动作发生时间、任务/轮次、工程、执行项、动作来源、尝试编号、实际结果、图页位号、新旧料号,以及有证据支持的 Value/NC/Cell 差异。开始请求和完成结果是不同事件。无改动和失败不能填造成功差异。 + +用户历史覆盖实际的新建/编辑/归档任务、规则及位号计划保存、执行/暂停/恢复、核验结果和因完成回执跳过的摘要。搜索、翻页、轮询、读取快照不生成新的操作历史,避免页面自己制造海量记录。配置改动保存有证据的前后差异;不记录模型密钥等凭据。 + +搜索参数化查询任务、工程、位号、新旧料号和说明;结果按数据库全局单调的 `history_event_id` 倒序做游标分页,同时间事件不漏页。现有 JSONL 的 `sequence` 是每任务序号,不能当全局分页或清空序号。详情展示原计划、真实改动、核验结论及失败原因。旧版本缺少的字段明确显示“旧版本未记录”。 + +### 8.2 清空的精确语义 + +- 默认明确命名“清空全部历史”,确认框展示即将清理的历史数量;即使搜索正在生效,也不能让按钮范围含糊成“只清当前页还是全部”。 +- 不清理任务、完成回执、检查点、原生证据及备份,不改变本轮任何执行项状态。 +- 打开确认框时,用同一数据库快照取得全局 `history_event_id` 截止值与将清理的数量。用户确认后严格按该截止值清理,不能重新读取更大的截止值,把确认期间的新事件也清掉。 +- 清空事务更新持久化 `cleared_through_id`;查询只显示该边界之后的记录。需要物理清理时只删除截止值以内的独立历史行。重建索引或重启不能清除这个水位;事件序号使用不会因删除全部历史而复用的序列(如 AUTOINCREMENT 或独立持久计数器),清空不重置序号。 +- 新历史源事件与执行回执同事务写入,因此不存在“成功回执很早提交,历史却以新时间延迟生成”导致旧记录复活的窗口。UI 延迟读取不会改变事件序号。 +- 旧 JSONL 兼容导入单独保存来源去重键、迁移完成状态及清理水位,不能仅因源文件轮转或重建索引再次导入。首次历史迁移未完成时禁用清空;正常查询刷新不禁用清空。 +- 建议活动执行/恢复期间禁用清空,以降低用户对范围的误解;并发新事件仍以事务边界保证:截止值之后的事件保留,不能误删用户确认后才完成的操作。 +- 清空失败时保留原页面及记录,提示重试;不能先把表格清掉再假装后端成功。 + +## 9. 示例 + +批次 G 包含任务 TA 与 TB,分别绑定 CBB 工程 A 和 B,各自保留轮次 RA/RB。每工程两个图页、每图页两条规则,共 8 项。 + +先完成 A 的第 1 页两项,再完成 A 第 2 页第一项,然后暂停: + +- A:3 项已核验,1 项待执行;不能因“A 跑过了”跳过余下一项。 +- B:4 项待执行。 +- 重启后点击继续:显示跳过 3 项,本次执行 5 项;不再执行 A 已完成的前三项。 +- 如 A 第三项的保存核验尚未结束就强制退出:保留前 2 项已核验,第三项待核验,之后 5 项待执行;先恢复第三项,不能重新跑前 2 项或直接运行 B。 +- 清空操作历史:页面旧记录清理,但以上执行项状态原样保留。 +- 如 A 第三项明确安全失败:A 保留失败项和 1 项因工程失败暂缓的待执行项;跳转 B 执行其 4 项。再次普通继续不会偷偷重试 A;处理 A 的失败项后重新确认,才接续其剩余范围。 +- 全部完成后再次点击执行:显示“本轮已完成”,不启动执行器;用户明确开始新一轮后,重新确认基于当前工程的改动目标。 + +## 10. 实施与验收拆分 + +1. 最小保护补丁:复现状态文件丢失/损坏/截断,并在快照读取、准备队列、服务派发入口统一阻断;验证现有首次执行和正常续跑不被误阻断。 +2. 持久化计划与逐项回执:补齐任务/轮次身份、CAS 领取、attempt 绑定、终态原子提交,以及旧记录兼容对账。 +3. 恢复矩阵:对本文第 6 节逐点故障注入,实际统计同一逻辑项的执行器派发次数,不能仅检查按钮和进度数字。 +4. 历史页:接入真实事务事件、搜索分页、展开详情和明确范围的清空;覆盖“清空后重启不再现旧历史,但不重复执行”。 +5. UI 回归及原生窗口验收:保留玻璃隔离、分类/搜索、未保存编辑保护及 980×700 可见性。 + +验收底线:正常继续只派发剩余项;不确定结果没有替换派发;完成回执与清空历史互不影响;任何跨进程崩溃窗口都不能靠归零掩盖。 diff --git a/docs/superpowers/specs/2026-11-03-operation-history-resume-research.md b/docs/superpowers/specs/2026-11-03-operation-history-resume-research.md new file mode 100644 index 0000000..b64a0f5 --- /dev/null +++ b/docs/superpowers/specs/2026-11-03-operation-history-resume-research.md @@ -0,0 +1,88 @@ +# 操作历史与同任务断点续跑:研究及建议方案 + +状态:研究完成,方案待实施;未修改产品代码、DSH 功能或真实工程。 + +执行项身份、状态机、暂停/重启、崩溃恢复矩阵和清空语义已进一步细化,见 [详细执行逻辑](2026-11-03-operation-history-execution-design.md)。 + +## 用户目标与已确认场景 + +- 增加独立的操作历史页面,让用户知道工具实际做过哪些改动。 +- 页面可以搜索、清空历史。 +- 用户已明确:重复执行发生在**同一个任务点击继续或重启工具后**,本轮不把它解释成重新导入 CBB 或重新新建任务。 +- 用户进一步确认:一个 CBB 已确认安全失败且资源已释放后,跳过这次失败并继续后面的工程;不确定结果仍停止。 +- 保留既有 UI 风格,DSH 功能仍不在本轮修改范围内。 + +## 当前实现与证据 + +1. 现有“替换结果/日志”按当前任务展示,数据来自 `tasks//events.jsonl`,已经提供分段读取和日志轮转;没有全局可搜索的操作历史页面,也没有独立的用户历史清理语义。 +2. `task_queue.execute_task_queue` 有持久化的任务级队列检查点。`QuickRunPreparer` 根据命令与状态文件重建每个工程/图页/规则的完成进度,正常情况下跳过已完成项。 +3. UI 的批次 `_project_queues` 为内存状态,重启后不保留,但**这本身不等于必然重放**:独立探针在不复用原任务队列 ID 时仍正确跳过了已完成步骤。 +4. 已复现保护缺口:`quick_run_snapshot._read_snapshot_once` 只认同时存在 `command.tsv` 和 `status.tsv` 的候选目录。状态文件缺失时,已有命令及任务的暂停状态没有阻止其返回“无证据、未中断、0 项完成”。后续继续可以重新建立执行队列。 + +### 独立复现 + +使用真实 TaskStore、TaskCenterService、QuickRunPreparer 和任务队列;CAD 执行器为受控替身。一个任务包含 2 个图页 × 2 条规则,共 4 项。先完成 2 项并暂停,关闭数据库,重新实例化服务和数据库,再继续。 + +| 重启场景 | 重启读取的完成项 | 总执行器调用 | 重复的逻辑项 | +| --- | ---: | ---: | ---: | +| 原队列 ID,状态文件完整 | 2 | 4 | 0 | +| 新队列 ID,状态文件完整 | 2 | 4 | 0 | +| 原队列 ID,状态文件缺失 | 0 | 6 | 2 | +| 新队列 ID,状态文件缺失 | 0 | 6 | 2 | + +缺失文件用例中,原状态文件仅在临时夹具内改名保存,未删除用户数据。任务重启读取仍为 paused,`interrupted=False`,随后重放了前两项。不能据此断言用户现场的文件一定缺失;现场日志与任务证据仍需用于定位其具体触发原因。 + +探针:本地 `build/research_task_resume.py`。结果:本地 `build/task-resume-research.json`。这两项不是发布组件。 + +既有回归:`python -m pytest -q tests/v1_1/test_multi_project_regression.py tests/v1_1/test_task_queue.py tests/v1_1/test_new_round.py --tb=short`:**26 passed**。 + +## 实施方式比较 + +| 方式 | 优点 | 不足 | +| --- | --- | --- | +| 在现有日志弹窗上添加搜索及清空 | 改动小 | 仍按单任务查看;日志清理容易与恢复证据混淆;无法补足丢失状态文件的防重复保护 | +| 独立操作历史页面+独立完成回执(建议) | 可跨任务查改动,重启后可查询,清空页面与续跑互不影响 | 需要明确区分用户历史、执行回执和诊断日志,并覆盖原子写入/恢复边界 | + +建议采用第二种。本方案是实现建议,尚未由用户选择实现细节。 + +## 操作历史页面 + +- 顶部增加“操作历史”导航,和“任务中心”并列;沿用 SVG、玻璃导航与实色数据表,独立于 DSH 页面。 +- 默认按时间倒序。列表包含时间、任务/CBB 工程、操作、结果、改动摘要;展开显示位号、图页、旧料号→新料号、Value/NC 改动以及对应证据来源(有记录时才显示)。 +- 搜索覆盖任务名、工程名/路径、位号、新旧料号及改动说明;提供结果筛选及分页,避免大批记录加载阻塞 UI。 +- 区分“请求执行”“实际保存并核验”“未命中”“失败”“已跳过”,不能把按钮点击或 AI 建议当作已完成修改。旧日志缺少的配置差异不追溯编造。 +- 搜索为空时展示空态,异步读取失败可以重试;清空需要确认并展示影响数量。 +- “清空历史”只清理独立的用户可见历史记录。它不删除工程、任务、备份、诊断证据、执行检查点或完成回执。清空后新操作照常记录,旧记录不会在轮询或重启后自动重新导入页面。 + +## 防重复执行 + +### 第一层:立即补齐恢复门禁 + +- 已存在命令、活动步骤或原执行痕迹,但命令/状态文件缺失、损坏、截断或相互矛盾时,不将任务当作从未执行。 +- 显示“执行记录不完整,请核验后恢复”,阻止重新准备队列和写入派发。 +- 检查必须在服务端执行入口也生效,不能只隐藏/禁用 UI 按钮。 +- 旧任务没有足够证据时保持阻断,不能根据进度数字或一条普通日志补造“已核验完成”。 + +### 第二层:持久化到每个执行项的完成回执 + +- 保存任务、轮次、原确认计划指纹、规范工程路径、图页、目标范围/UID、新旧料号、Value/NC/Cell 策略、结果与证据关联。 +- 使用同一任务和轮次内稳定的操作身份;不能只靠每次重新生成的 job_id 或单独的 CBB 文件名去重。 +- `saved_ok`、明确核验通过的恢复结果和 `no_match` 应按各自含义保留终态;失败、未核验保存和未知结果不能冒充成功。 +- 继续前核对回执、原计划和现有证据:完整完成项跳过;待执行项接续;证据缺失或不一致时停止并提示核验。 +- 进程可能在 CAD 保存完成、回执落盘之前退出,因此不能承诺跨外部 CAD 写入与数据库的严格 exactly-once。该窗口必须依靠已有 attempt/快照证据核验,不能自动重放。 +- 只有用户明确启动“新一轮”并重新确认计划,才建立新的执行范围;清空历史、重启或点击继续都不产生新轮次。 + +## 验收重点 + +1. 同任务正常暂停/重启后,已完成项的执行器调用次数不增加;只执行余下项。 +2. 不带原队列 ID 的重启仍不能重放已完成项。 +3. 命令/状态缺失、文件损坏/截断、状态互相矛盾时阻止 CAD 派发,并保留原始证据。 +4. 写入成功但回执未落盘时,进入核验流程而不是再次调用替换。 +5. 未命中、失败和未核验保存分别显示,并遵守现有恢复/重试门禁。 +6. 清空页面历史后重启,完成回执与防重复保护仍有效,旧页面记录不重新出现。 +7. 全局搜索、筛选、翻页、失败重试和清空确认可用,大记录量下主界面保持响应。 +8. 页面切换、980×700 布局、玻璃及实色回退沿用现有验收。 + +## 下一步实施顺序 + +先补缺失/损坏状态文件的最小失败回归与服务端门禁,再增加独立历史记录和完成回执,最后接入可搜索/分页/清空的历史页面。分别验证,再提交可审查的改动;不在研究阶段修改 DSH 或运行真实 CAD。