feat: expose transaction failure stages and conservative outcomes

examples/transactions/README.md

@@ -0,0 +1,24 @@
+# 事务失败与结果不确定
+
+在框架根目录运行：
+
+```sh
+go run ./examples/transactions
+```
+
+示例使用确定性的演示 SQL 驱动，没有真实数据库、上传文件或外部服务。业务调用仍走真实 `database/sql` 和 `database.InTx`；`demoDriver.go` 仅用来注入数据库操作成功后确认丢失的情况，项目继续使用自己的正常驱动。
+
+```text
+success: committed, stored=true
+beginFailure: stage=begin outcome=notStarted stored=false cleanup=true
+workFailure: stage=work outcome=rolledBack stored=false cleanup=true
+rollbackFailure: stage=work outcome=unknown stored=false cleanup=false
+commitRejected: stage=commit outcome=unknown stored=false cleanup=false
+commitAcknowledgementLost: stage=commit outcome=unknown stored=true cleanup=false
+```
+
+最后两个场景收到一样的提交错误，但一个没有保存、另一个已经保存。调用方不能从提交错误推断数据库没记录，因此示例只在已知未执行回调或已回滚时考虑清理，不确定时保留。`cleanup` 只是演示业务决策，没有执行任何删除；实际业务仍需考虑文件是否只属于本次操作、其他事务或外部副作用。
+
+`errors.As` 取得 TxError 的阶段/结果，`errors.Is` 仍找到原始演示错误。回滚失败有独立原因；TxError 不规定业务码、HTTP 状态或清理策略。
+
+完整接口、自动回滚的观察边界和兼容注意见 [database](../../database/README.md#事务阶段与结果)。真实 MySQL 和故障回归见 [验收记录](../../reports/transactionAcceptance.md)。