docs: 新增设计决策文档并实现数组追踪器校验

- 新增决策文档:移除 preset 指令,将其合并到 create 指令中,以简化生命周期和系统复杂度
- 新增决策文档:确立 SDK 侧影子状态校验机制,实现快速失败和最小必要状态原则
- 在 ArrayTracer 中实现影子状态校验,维护数组长度并进行索引边界检查
This commit is contained in:
2026-02-06 01:56:52 +08:00
parent 7b1c87f2a4
commit 5cc4f96b46
3 changed files with 117 additions and 0 deletions

View File

@@ -0,0 +1,35 @@
# 决策:移除 ArrayTracer 的 preset 指令
## 背景
在设计 ArrayTracer 的指令集时,我们讨论了如何初始化数组数据。最初设计了 `preset` 指令用于预设数组内容,后来讨论了是否将其与 `create` 指令合并。
## 问题分析
保留独立的 `preset` 指令,特别是允许其出现在 `patch` 等操作指令之后,会带来以下系统性风险:
### 1. 语义与逻辑的二义性
* **预设 vs 重置**`preset` 本意为“预先设置”,若出现在操作流中间,语义突变为“重置”或“全量替换”,导致语义混乱。
* **状态突变**解析器需同时处理增量更新Patch和全量覆盖Preset。若 `preset` 改变数组长度会导致后续基于索引的回溯操作Time Travel失效或越界。
### 2. 可视化渲染的连续性问题
* **动画中断**`patch` 对应平滑过渡,而 `preset` 对应全量重绘。在中间插入 `preset` 会导致渲染器难以生成补间动画,造成视觉跳变。
* **对象身份丢失**:全量替换会导致 DOM 元素及其状态(如高亮)丢失,用户体验突兀。
### 3. “时间旅行”的性能代价
* **回滚成本高**:回滚 `patch` 仅需反向操作,而回滚 `preset` 需要在执行前对整个大数组进行全量快照Snapshot。若 `preset` 频繁出现,内存消耗将不可控。
## 决策结论
**移除独立的** **`preset`** **指令,将其能力作为可选参数** **`array`** **合并入** **`create`** **指令。**
### 收益
1. **生命周期明确**:强制确立“初始化(Create) -> 演变(Evolve)”的生命周期,消除“中途重置”的不确定性。
2. **系统简化**:解析器仅需处理增量更新,渲染器无需处理全量 DOM 替换,历史记录无需重型快照。