docs: 新增设计决策文档并实现数组追踪器校验
- 新增决策文档:移除 preset 指令,将其合并到 create 指令中,以简化生命周期和系统复杂度 - 新增决策文档:确立 SDK 侧影子状态校验机制,实现快速失败和最小必要状态原则 - 在 ArrayTracer 中实现影子状态校验,维护数组长度并进行索引边界检查
This commit is contained in:
35
.trae/documents/decision-remove-preset.md
Normal file
35
.trae/documents/decision-remove-preset.md
Normal 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 替换,历史记录无需重型快照。
|
||||
|
||||
Reference in New Issue
Block a user