Initial TrueGrowth source import

docs/CANVAS_BATCH_INSERTION_LESSONS.md

@@ -0,0 +1,86 @@
+# 批量插入画布流式布局经验总结
+
+更新日期：2026-05-25
+
+## 背景
+
+批量插入最初是按纵向顺序堆叠，宽屏桌面下会浪费大量横向空间。后来改成视口流式排布后，又遇到一个更隐蔽的问题：图片在插入后仍会按原始比例回写尺寸，导致同一批内容的间距忽大忽小。
+
+## 相关文档
+
+- **2026-05-25 重要更新**：[批量插入图片叠加问题修复经验总结](./CANVAS_BATCH_INSERTION_FIX_LESSONS.md)
+  - 详细记录了素材库批量插入图片叠加问题的完整修复过程
+  - 包括问题根源分析、正确的解决方案、风险评估
+  - 新增 `calculateImageDisplayDimensions` 统一尺寸计算函数
+
+## 架构变更
+
+### 1. 布局层抽成共享流式布局器
+
+批量插入不再由服务层、MCP 层、自动入画布各自维护 `currentX/currentY`，而是统一走共享布局器。
+
+- 先读取画布容器宽度和 `zoom`
+- 按插入顺序横向排布
+- 超过当前行宽后换行
+- 每行高度由当行最高元素决定
+
+这让“怎么算点位”只剩一处实现。
+
+### 2. 尺寸层改成“批量固定参考尺寸”
+
+图片和视频批量插入时，不再允许加载完成后按原始比例悄悄改写最终尺寸。
+
+- 批量路径统一传入参考尺寸
+- 图片插入显式开启 `lockReferenceDimensions`
+- `skipImageLoad` 继续保留，保证批量插入是流式的
+
+这样布局阶段和渲染阶段看到的是同一套尺寸，间距就会稳定。
+
+### 3. 插入入口统一收敛
+
+服务层、MCP、自动入画布都复用同一个批量执行入口，而不是各自拼自己的插入循环。
+
+好处是：
+
+- 行为一致
+- 日志一致
+- 修复一次能覆盖多条路径
+
+### 4. 滚动目标改为整批中心
+
+批量完成后，滚动不再盯第一项，而是对准整批内容包围盒中心。这样宽屏和窄屏都更容易看到整批结果。
+
+## 经验
+
+### 1. 不要把“预估尺寸”当成“最终尺寸”
+
+只要插入后还可能回写尺寸，后面的布局游标就一定会漂。
+
+### 2. 批量链路只保留一个布局源
+
+多个入口各自维护排布逻辑，最后一定会分叉。共享布局器比“各处抄一份”更省心，也更容易加日志定位。
+
+### 3. `groupId` 只负责相邻语义，不负责硬性竖排
+
+同组内容可以相邻，但不再强制单独竖排。空间不足时自然换行，比手工维护特殊分支更稳。
+
+### 4. 调试要能看见“点位”和“最终尺寸”
+
+批量插入日志最好同时包含：
+
+- 解析出的视口宽度
+- `zoom`
+- 每项的估算尺寸
+- 每项的实际插入点
+- 批次 bounds 和 center
+
+只看“开始/结束”日志，很难抓到漂移来源。
+
+## 回归检查清单
+
+- 宽屏下是否先横排再换行
+- `zoom` 变化时换行点是否正确
+- 图片批量插入后间距是否稳定
+- 服务层、MCP 层、自动入画布是否共用同一套布局
+- 批量结束后的滚动中心是否覆盖整批内容
+- 只改批量路径，单项插入是否保持原有行为