记录、历史与撤销

三个问题，三种记录

上一节说的副作用在事务之外。这一节看事务之内留下的东西。改完数据之后，人们会问三类不同的问题，答案在三个不同的地方：

还有两个问题：怎么撤销，以及失败变多时怎么知道。它们放在最后一节。

Action Log：把决定变成对象

写了 actionLog: true 的 Action，每次成功提交，都会在同一个事务里多写一个日志对象，类型名是 log. 加 Action 名。它和别的对象一样：能查、能统计、能放进看板。属性有操作 id（也是它的主键）、Action 类型 id 与版本、时间、执行人、改了哪些对象的主键、一句话摘要，还有这个 Action 的参数值。

参数值也进日志，这一点很有用。hold-work-order 的 reason 没有写进任何工单属性，但它在 log.hold-work-order 里，事后能查到「为什么暂停」。

aidc semantic objects log.hold-work-order --order-by timestamp:desc --page-size 5
aidc semantic aggregate log.confirm-order --select '{"$count":"unordered"}' --group-by '{"userId":"exact"}'

第一条列出最近五次暂停；第二条按执行人统计确认过多少订单。要记住三条边界：日志只记成功的提交，失败的不记；不经过 Action 的改动，比如开发者直接写数据，不产生 Action Log；开启日志之前发生的 Action 不会补记。

编辑历史：一个对象的履历

Action Log 按 Action 记，编辑历史按对象记。要看一张工单是怎么一步步变成现在这样的：

aidc semantic edits-history workOrder --pk WO-2001 --previous --json

每条记录带着操作 id、执行人、时间和这次改了什么；加上 --previous，用 --json 输出时还会带出改前的属性值。操作 id 和 Action Log 里的操作 id 对得上：先从日志看「这次决定是什么」，再从编辑历史看「对象具体怎么变了」。在 /semantic 的对象视图里，「编辑历史」就是同一份数据：谁、什么时候、从什么改成什么、通过哪个 Action。

撤销与指标

通用做法里的撤销很窄：

• 「撤销」只出现在执行成功后的那条提示里，只有执行人本人能点。
• 只有这次 Action 是该对象最近一次编辑时才能撤销，之后哪怕改了别的属性也不行。
• 只退回对象上的编辑，通知和 Webhook 不会被撤销。
• 删除类 Action 错过那条提示，就没有简单的补救办法，所以删除要格外小心。

指标回答的是另一类问题：最近 30 天成功了多少次、失败了多少次、耗时的第 95 百分位是多少。失败分几类：参数不合格、超出规模上限、没通过提交条件、副作用失败、Function 失败、并发冲突。监控规则在耗时或失败次数超过阈值时发出告警。

有一个坑要提前想到：提交条件也会挡住纠错。report-output 要求累计合格数不能少于已报的数，报成 1200 想改回 120，就被拦下。所以在设计时就要留一条纠错通道：单独的纠错 Action，只给 editor 用，条件放宽，但必须写原因。

最后一节讲事务：批量、并发和上限，以及规则表达不了时该怎么办。