90 lines
11 KiB
Markdown
90 lines
11 KiB
Markdown
# Canvas V2 验收记录（2026-11-06）
|
||
|
||
## 前端检查
|
||
|
||
- `npm run typecheck` 通过。
|
||
- `node --experimental-strip-types --test tests/*.test.mjs`：69 项测试通过，覆盖既有行为、V2 无损往返、端口方向与曲线字段校验、投影与逆变换、局部/远端三方合并、草稿兼容、八向 Shift 等比、LCA 连接计划和父子共同拖动不重复位移。
|
||
- `CANVAS_UI_TOOLS=/private/tmp/endoleap-ui-check node tests/canvas-ui-check.mjs`：真实 React Flow + DOM 事件回归通过，使用临时安装的 esbuild/jsdom，不访问浏览器。
|
||
- DOM 覆盖：旋转与撤销重做、三图标标签切换、八向手柄、连线选择/曲线点/marker/动画；子画布独立读取与保存、收起/展开、创建及撤销重做；模型按输出类型过滤、文本传播、图片原节点回写、取消与生成期间保留几何。
|
||
- 新跨图连接以实际 Handle 鼠标事件触发，验证能力门槛、最低共同祖先、准确的所有参与版本，以及已经提交但丢失响应后的相同 body/key 重试；不会重复创建端口或边。
|
||
- API 冒烟覆盖 V2 Accept/If-Match/Idempotency-Key、子图/连接/运行命令白名单、事件分页参数、带 Cookie 的图片二进制响应、MIME 限制、multipart 上传、原有 OAuth/会话/同源校验和 5 MiB 限制。
|
||
- 隔离生产构建 `npm run build -- --webpack` 及最终 `node tests/api-smoke.mjs` 均通过；构建在临时副本执行，不改变正在使用的开发服务器产物。
|
||
|
||
## 后端与测试画布证据边界
|
||
|
||
用户交付 Core `b4e537b` 部署、ECS CI #912/#913，以及 `/Users/zzyang/foundry-canvas-v2-migration-summary.json`：指定父画布版本 209→210，1 个真实子画布、2 个显式成员，11 个节点和 2 条边保留；重新读取和幂等验证通过。
|
||
|
||
用户提供的隔离后端真实模型验收包括文本生成和 PNG 图片产物；本轮前端没有再次调用线上模型、修改测试画布或重复迁移。模型 ID 在运行时读取，不硬编码验收 ID。
|
||
|
||
新增 connections 扩展已对照用户提供的接口说明和本机 Core `07fd678` 源码实现；主线合并为 `630ed42`。生产是否可调用以 capabilities.subgraphs.connections=true 及后端部署确认作为门槛，不把文档或合并本身当作已部署。
|
||
|
||
## 限制和交付状态
|
||
|
||
- 按用户约定未访问项目浏览器，未进行视觉布局、真实拖动手感与真实登录会话的浏览器验收。
|
||
- 子图关系备份不能作为普通单图快照导入其他画布；导出包含完整 owner 文档集合，避免仅备份父图或重复保存投影。
|
||
- 网络未知结果保留请求并暂停编辑；普通版本冲突保留本地草稿，不强推覆盖。
|
||
- Headless 库尚未创建，提取方案已改写在本地忽略的 docs/HEADLESS_CANVAS_API_DRAFT.md；已替代的分区/元素/后端需求文档已清理。会话策略文档仍保留。
|
||
- 原有 next-env.d.ts、pnpm-lock.yaml 和 pnpm-workspace.yaml 不属于本次交付，保留未提交。
|
||
|
||
|
||
## 侧栏目录与加载性能修正
|
||
|
||
- 侧栏通过 include_subgraphs=true 和完整分页展示嵌套子画布；支持展开/收起、活动路径、搜索保留祖先，关系事务完成后刷新。
|
||
- 空闲 AI 查询降至 30 秒、任务期间 1.2 秒；隐藏标签页暂停，返回或本地命令后唤醒；空响应不重渲染。
|
||
- 编辑器拆成动态模块，与元数据/快照并行加载；成功 Canvas GET 代理采用流式转发。
|
||
- 实际证据、性能边界及未执行的公网/浏览器验收见 PERFORMANCE.md；不将本地模拟测试当作公网提速实测。
|
||
- 本次最终检查通过：TypeScript、73 项单元测试、React Flow DOM 全量回归、隔离 Webpack 生产构建及 API 冒烟（含上游响应体暂停时首段透传、目录分页参数）。
|
||
|
||
## 传输中断与只读打开修正
|
||
|
||
- 大快照分离响应头、正文总时限和正文空闲时限；加入仅含时间/计数的传输、保存和 dirty 字段诊断。
|
||
- JSON 读取失败不再吞成 null；区分传输中断、不可解析响应和真实快照校验失败。
|
||
- 内容指纹忽略单独的 viewport 变化；视角保存在本机，初始化与缩放不会上传快照。浏览器日志已确认原误保存字段仅为 viewport。
|
||
- 新增慢正文、空闲超时、请求取消、失败 200、204、视口浮点与真实内容保存的测试；DOM 覆盖父/子图打开与缩放零 PATCH。
|
||
- 用户完整读取已成功（父图 477,385 字节），但链路样本仍有 2.66–32.75 秒波动；ECS/公网对照尚待补充，详见 PERFORMANCE.md。
|
||
|
||
|
||
## 附件与预览修正
|
||
|
||
- 新图片使用受管附件；旧图仅在用户明确点击后迁移，字节保持原样，快照不保存预览地址。
|
||
- 单元测试增加字节一致性、重复图片去重、幂等重试、失败不替换、V1 兼容和渲染 URL 分离；共 84 项通过。
|
||
- DOM 回归确认只读打开/缩放零 PATCH、显式迁移一次上传、位置和边不变、画布使用预览而快照保存原图引用；原有 AI/子图/连线回归通过。
|
||
- 同步 TCP/数据库证据及隐私边界见 PERFORMANCE.md。Core PR #15 已由用户合并为 b2ae48e；分支/PR CI #936/#937、主线检查 #940 和部署 #941 全部成功。用户已明确执行迁移与重开，生产验收完成：父图版本 252→253，两张原图 SHA-256 一致，节点/内容/边哈希一致；数据库 JSON 477,397→3,708 字节。成功重开请求 219.6ms（正文 1.3ms），独立图片 551.2/1,354.9ms，随后无新增保存且版本保持 253。另一次零正文取消请求与网络波动限制见 PERFORMANCE.md。
|
||
- 最终前端检查：TypeScript、84 项测试、完整 DOM 回归、隔离 Webpack 构建和 API 冒烟均通过（包括 15.2 秒慢正文、原图/预览参数及响应头）。
|
||
- 最后补充：图片按需加载/异步解码；优化提示保持到版本保存确认后才消失，并阻止与新图片上传重叠。延迟保存的 DOM 回归和最终隔离构建通过。
|
||
|
||
## 临时迁移功能清理
|
||
|
||
指定生产画布完成迁移验收后，按用户要求移除“优化图片加载”入口、专用 Hook 状态和 Base64 迁移辅助函数。保留正常附件上传、原图引用及独立预览。类型检查、4 项附件单元测试、完整 DOM 回归通过；DOM 覆盖旧内嵌图片无迁移按钮/无后台上传、只读打开零 PATCH，以及既有 AI/连线/子图功能。此次删除变更未重复执行生产构建；此前隔离构建结果保留为历史记录。
|
||
|
||
## 跨分区同步优化
|
||
|
||
- TypeScript 和 83 项单元测试通过。新增 DOM/Hook 场景覆盖：原子成员移动一次 POST/无前置 PATCH、延迟响应期间编辑和拖动其他节点、快照合并保留编辑、撤销/重做保留单一归属、丢失响应以相同 body/key 重试、412 重读版本后新命令重试、连续跨分区移动排队、旧后端兼容。
|
||
- 实际 ReactFlow DOM 手势验证 icon 跨分区后出现元素旁同步提示，无整屏同步遮罩；其他元素可继续拖动，服务器确认后位置不回退。既有 AI、连线、框、图片回归通过。无浏览器访问（沿用用户要求）。
|
||
- 最终隔离生产构建通过。Core push #946、PR #947、主线 #949、部署 #950 均成功，包含 Go 测试/构建、数据库迁移和 PostgreSQL 集成测试；PR #16 已合并为 2207c85 并部署。Core 不在本机编译。真实 icon 拖放验收仍待用户操作后的记录核对，不将发布成功当作实际性能实测。
|
||
|
||
## 慢能力响应与首次上传
|
||
|
||
生产复核发现 capabilities 请求约 1,989ms，原先 2 秒客户端截止可能误将慢响应缓存为不支持。已删除该短截止，网络错误清除缓存并重试；只有成功响应明确未声明能力才走旧流程。DOM 回归增加 2.1 秒能力响应、预取失败后重试的场景，均保持原子移动、无前置 PATCH。
|
||
|
||
上传 DOM 回归覆盖：网络未确认前本地图片已显示、可添加其他内容、快照没有 blob URL、原始附件引用与 assetId 正确、远端预览加载后释放本地 URL、失败保留文件、同键重试只创建一个节点、取消/卸载清理与原图比例。TypeScript、83 项单元测试与隔离生产构建通过。生产新上传的交互体验及修正后的能力协商仍需用户刷新后实测。
|
||
|
||
## 上传期间的真实本地节点
|
||
|
||
改为在选图时创建可编辑的本地 CanvasNode，上传确认只更新 src/assetId，并同步修正本地撤销记录，不新增无意义的撤销步骤。传输过滤临时节点与关联边，写入基线使用实际发送的干净快照。
|
||
|
||
- 84 项单元测试通过，新增上传节点/关联边不会进入网络快照、其他内容仍能保存、附件可用后正常保存的覆盖。
|
||
- DOM/Hook 回归通过：上传期间拖动/缩放/改名在确认后保留；确认前删除不会被重新插入；删除可撤销；尺寸初始化与引用补齐不消耗撤销；本地跨分区移动与复合撤销、文件确认到当前所属画布；已持久化后的归属撤销走真实事务。
|
||
- 并发回归通过：版本号型响应的重新读取、包含重复 parent 的事务快照，都保留本地上传节点；其他事务与附件完成同时发生不会覆盖新图片。AI 在文件上传完成后可执行，编辑无需等待。
|
||
- 最终 TypeScript、84 项单元测试、完整 DOM 回归和隔离生产构建均通过；未访问用户浏览器，不将 DOM 测试描述为用户已完成浏览器验收。
|
||
|
||
## Headless 方案与应用提示依赖
|
||
|
||
本地忽略的 `docs/HEADLESS_CANVAS_API_DRAFT.md` 已重写为方案：同步 command/working document 与独立 runtime、operation ledger、ACK 基线分离；提供 component/feature 组合、API A/B/C、八个 viewport slot、实例 mode、混合选择、文件恢复、幂等与撤销设计。仅为待选择方案，没有提取或发布 npm 包，也没有实现 IndexedDB/outbox。特别区分普通 CAS 快照 PATCH 与有 Idempotency-Key 的事务，避免把重试后的 412 错判为原请求零写入。
|
||
|
||
实际安装 Sonner 2.0.8、Radix Tooltip 1.4.1，并同步 `package-lock.json`。根布局挂应用 provider，固定通知 ID 避免重复；图标按钮保留实际 button/ref 与原尺寸。通用错误/归属完成使用应用通知，原保存冲突、失败上传和重试入口保留。
|
||
|
||
- TypeScript、84 项单元测试与完整 DOM 回归通过；新增真实依赖场景覆盖独立按钮原生说明、键盘 tooltip/Escape、ref/DOM 结构、点击、通知更新去重/关闭，以及 provider 内的分区完成、非法文件提示和继续编辑。
|
||
- 在临时副本执行 Webpack 生产构建和 API 冒烟，均通过；未改变当前开发服务的 `.next`，未访问用户浏览器或生产画布。DOM 布局检查不替代真实浏览器视觉验收。
|
||
- 保留用户的 `next-env.d.ts`、未跟踪的 pnpm lock/workspace 文件；docs 继续忽略，不强制跟踪。
|