feat: expose workflow state events and persist signal transitions

docs/reports/phase-5-events.md

@@ -0,0 +1,58 @@
+# P4/P5 流程状态事件时间线验证记录
+
+日期：2026-09-18。本批范围是流程状态事件的分页、详情、HTTP、独立SDK，以及信号消费/拒绝/过期的事务事件。P4/P5全范围核对、独立POLL/人工恢复场景和P6/P7仍未完成。
+
+## 实现与接口
+
+- `GET /v1/workflows/{id}/events`及`/{event}`，对应ListWorkflowEvents和GetWorkflowEvent。两条路由都要求显式workflows:audit:read，并核对固定版本全部队列。
+- 原始workflow、workflow_step、workflow_signal事件按数据库记录时间与ID倒序，不展现内部根步骤。摘要默认20、最多100条，原元数据详情不超过64KiB。
+- 实例、步骤和信号是独立聚合，revision不能跨资源比较；时间/ID不能推断提交水位或可靠消费进度。旧事件只展示当时保存的字段，不用当前激活改写历史。
+- PENDING信号的新转换与原状态事件同事务提交。批量拒绝每32条插入事件，任一批失败时全部回滚；保留单实例1024条历史信号上限。
+- 000025增加只读派生列和分页索引，不添加外键或级联，不补造历史缺失的信号转换。索引只用于查找，实际资源归属仍由服务端核验。
+- 36个持久化模型、312个直接字段均有中文注释；新增列同步中文COMMENT。
+
+接口、字段及SDK片段见[时间线手册](../api/workflow-events.md)。[workflow完整例子](../examples/workflow.md)在真实Worker任务完成后，按每页5条核对信号原状态与赢家等待ID。原激活/轮次、Pulse尝试及操作审计仍通过各自接口关联，不能把逻辑时间线误称为所有底层记录的单一事件流。
+
+## 环境与命令
+
+macOS arm64、Go 1.27.1、Docker MySQL 8.4.10，一次性隔离数据库；真实Orbit进程、HTTP及WSS Worker。未访问生产数据库。
+
+```sh
+make fmt test vet build
+DOCKER=/usr/local/bin/docker make integration
+```
+
+本地通过GO参数指定工具链。标准集成入口增加WorkflowEventsSDK，沿用21个SDK例子和2个独立业务模块，原有流程/Worker/订阅进程故障用例继续执行。
+
+## 验证记录
+
+| 检查 | 结果 |
+| --- | --- |
+| fmt、race单元回归、vet与构建 | 通过 |
+| 流程及步骤真实推进、列表无payload、详情与摘要一致 | 定向MySQL通过 |
+| 权限、队列限制、跨实例事件与跨种类游标 | 定向MySQL通过 |
+| 消费赢家、竞争者拒绝、重复处理 | 定向MySQL通过，状态与事件不重复 |
+| 单条事件写入失败 | 定向MySQL通过，赢家等待/信号/后继全部回滚 |
+| 70条待处理信号停止结清，第二批事件写入失败 | 定向MySQL通过，70条信号仍PENDING、已插入批次全部回滚；恢复后70条REJECTED各有事件 |
+| 同一SQL批次相同微秒时间的分页 | 定向MySQL通过，每页7条覆盖相同时间组，无漏无重 |
+| 过期、错误派生范围及超大元数据 | 定向MySQL通过；不返回损坏候选的部分页 |
+| v24→v25升级与重跑 | 通过，旧8个原字段全部相同、精确JSON保留、非法范围NULL、只读生成列不可覆盖、索引列序正确、外键0 |
+| 真实HTTP独立SDK | 通过，11个原事件分6页，信号CONSUMED与流程CANCELLED保留 |
+| 完整workflow示例 | 通过，3个Worker任务成功并排空，20条事件包含PENDING→CONSUMED和赢家等待 |
+| 定义与原五组公共实例SDK回归 | 定向链路通过 |
+| 新增旧激活恢复后事件读取与损坏归属拒绝 | 全量存储回归通过，恢复后原事件保持，错误历史归属返回UNAVAILABLE |
+| 完整标准集成脚本 | 通过，退出码0；21个SDK例子、2个独立业务模块、流程/Worker/订阅进程故障全部完成 |
+
+定向存储12.734秒，SDK组26.530秒，其中时间线SDK2.26秒。这些是测试执行耗时，不是吞吐或延迟指标。当前312个模型字段中文注释检查缺失0；Markdown检查1096个本地链接、68个JSON块，错误0。
+
+回归修正了两处测试准备错误：尚在等待的错误关联信号会在受理时直接REJECTED，不能作为PENDING批量转换夹具，因此改为前置TIMER尚未结束时收到的早到信号；SDK模拟响应必须提供合法32位request_id。严格SQL模式还揭示UNHEX非法值在生成列DDL中会报错，因此转换前先核验全部字符，真实v24旧库重跑升级通过。修复没有放宽权限或移除归属检查。
+
+## 生产边界和剩余工作
+
+- 索引只是查询范围，不是授权真相；被非法范围隐藏的历史行不会由单实例分页自动检出，需要数据库写权限保护与专项核查。
+- 旧节点未保存的信号转换不会自动出现。先停止旧写入节点、应用迁移，再由新版接管；未实现无协调混合写节点升级。
+- STORED生成列和索引涉及旧行扫描及可能的表重建。大库DDL时长、空间、锁等待、查询稀疏性及信号批量事务开销仍需P6真实容量验证。
+- 本地进程故障回归不等于跨故障域高可用、MySQL主从切换或生产备份恢复验收。平台事务原子性也不等于外部业务副作用只执行一次。
+- 继续独立轮询/人工恢复示例、P4/P5原范围核对和P6/P7；当前持续目标保持进行中。
+
+完整标准集成脚本退出码0：存储组237.549秒，流程进程恢复48.726秒，最后Worker/订阅进程故障组97.407秒。新时间线6组存储场景与v24升级通过；历史v7→当前迁移再次确认70个外键全部移除、323个原索引组成部分和原任务保留。生产容量与高可用边界仍按上述未验证项处理。