Initial import of HEROLL source and design documents

design/gameplay-validation/diagrams/checkpoint-recovery.mmd

@@ -0,0 +1,14 @@
+flowchart TD
+  command["接收玩家命令"] --> clone["复制当前 RunState"]
+  clone --> resolve["在副本消费 RNG 并完整结算"]
+  resolve --> validate{"不变量通过?"}
+  validate -- 否 --> rollback["丢弃副本并记录异常"]
+  validate -- 是 --> tx["提交事务与 RunState"]
+  tx --> save["序列化 Checkpoint + checksum"]
+  save --> atomic["写临时槽并原子替换主槽"]
+  atomic --> render["通知表现层"]
+  crash["刷新/崩溃/重新打开"] --> load["读取主槽；失败则读备份槽"]
+  load --> verify{"版本和 checksum 有效?"}
+  verify -- 否 --> newRun["提示存档损坏并开始新局"]
+  verify -- 是 --> dedupe["恢复已提交 transactionId 集合"]
+  dedupe --> resume["从最近安全 phase 恢复"]

design/gameplay-validation/diagrams/reward-transaction.mmd

@@ -0,0 +1,13 @@
+flowchart TD
+  click["点击即时增强"] --> eligible{"实例可用且未领取?"}
+  eligible -- 否 --> reject["保持原状态并提示"]
+  eligible -- 是 --> create["创建 transactionId 与 PENDING 事务"]
+  create --> persist["写入安全存档"]
+  persist --> apply["应用确定收益"]
+  apply --> commit["事务标记 COMMITTED"]
+  commit --> checkpoint["写完整结算安全点"]
+  checkpoint --> render["播放图标反馈与收益动画"]
+  recover["刷新/崩溃恢复"] --> lookup{"transactionId 状态"}
+  lookup -- COMMITTED --> renderOnly["只恢复表现，不再发奖"]
+  lookup -- PENDING --> apply
+  lookup -- 不存在 --> click

design/gameplay-validation/diagrams/run-state.mmd

@@ -0,0 +1,28 @@
+stateDiagram-v2
+  [*] --> RunInit
+  RunInit --> FloorSetup
+  FloorSetup --> AwaitRoll
+  AwaitRoll --> DiceResolve: 手动掷骰
+  DiceResolve --> ThirdDieChoice: 持有第三骰祝福
+  DiceResolve --> Moving: 无第三骰
+  ThirdDieChoice --> Moving: 替换A/替换B/放弃
+  Moving --> TileResolve
+  TileResolve --> Battle
+  TileResolve --> Event
+  TileResolve --> Shop
+  TileResolve --> RewardChoice
+  Battle --> ReviveResolve: 玩家生命归零
+  ReviveResolve --> Battle: 祝福或即时复活成功
+  ReviveResolve --> RunFailed: 无复活
+  Battle --> Checkpoint: 胜利
+  Event --> Checkpoint
+  Shop --> Checkpoint
+  RewardChoice --> Checkpoint
+  Checkpoint --> FloorTransition: 越过起点
+  Checkpoint --> AwaitRoll: 未过层
+  FloorTransition --> BossBattle: 完成第10层
+  FloorTransition --> FloorSetup: 继续
+  BossBattle --> RunClear: 胜利
+  BossBattle --> ReviveResolve: 死亡
+  RunClear --> [*]
+  RunFailed --> [*]