docs(canvas): explain legacy document and sync state boundaries

This commit is contained in:
2026-11-12 16:08:02 +08:00
parent 9b24319747
commit 5d82655e0e
6 changed files with 30 additions and 2 deletions
+4
View File
@@ -19,6 +19,7 @@ export function subgraphMoveParticipants(documents: Map<string, CanvasDocument>,
for (const node of documents.get(board)?.nodes || []) if (node.data.subgraph) addDescendants(node.data.subgraph.boardId, seen);
};
for (const node of documents.get(source)?.nodes || []) if (ids.includes(node.id) && node.data.subgraph) addDescendants(node.data.subgraph.boardId);
// 祖先端口影响只检查 parent 的直接上一层及其一层内端口映射,不是无限上溯的依赖闭包。
const ancestor = parents.get(parent);
if (ancestor) {
const frame = documents.get(ancestor.boardId)?.nodes.find((node) => node.id === ancestor.frameId);
@@ -36,6 +37,7 @@ export function subgraphMovePath(documents: Map<string, CanvasDocument>, source:
const parents = subgraphParents(documents);
/** 包含自身的父链,重复board立即拒绝,避免循环遍历。 */
const chain = (board: string) => { const result = [board]; while (parents.has(board)) { board = parents.get(board)!.boardId; if (result.includes(board)) throw new Error("subgraph_cycle"); result.push(board); } return result; };
// 相同 source/target 得到空路径;父索引只反映已加载 documents,缺数据不能据此认定全局无共同根。
const from = chain(source), to = chain(target), common = from.find((id) => to.includes(id));
if (!common) throw new Error("ownership_conflict");
const path: { parent: string; frame: string; source: string; target: string }[] = [];
@@ -56,6 +58,7 @@ export function exposedConnection(documents: Map<string, CanvasDocument>, source
while (boardId !== owner) {
const parent = parents.get(boardId)!;
const frame = documents.get(parent.boardId)?.nodes.find((node) => node.id === parent.frameId);
// handle 按 === 精确匹配,包括 undefined 与 null 的差别;不会在这里规范化端口表示。
const port = frame?.data.ports?.find((port) => port.nodeId === id && port.handle === handle && port.direction === direction);
if (!port) throw new Error("boundary_port_required");
id = parent.frameId; handle = `port:${port.id}`; boardId = parent.boardId;
@@ -71,5 +74,6 @@ export function connectionTransactionPlan(documents: Map<string, CanvasDocument>
const path = (id: string) => { const result = [id]; while (parents.has(id)) { id = parents.get(id)!.boardId; if (result.includes(id)) throw new Error("subgraph_cycle"); result.push(id); } return result; };
const from = path(source.boardId), to = path(target.boardId), owner = from.find((id) => to.includes(id));
if (!owner) throw new Error("ownership_conflict");
// 参与集按 source→owner、target→owner 首次出现顺序去重;这只是规划,不带服务版本或原子提交证明。
return { boardId: owner, participants: [...new Set([...from.slice(0, from.indexOf(owner) + 1), ...to.slice(0, to.indexOf(owner) + 1)])], source: { board_id: source.boardId, node_id: source.id, handle: source.handle }, target: { board_id: target.boardId, node_id: target.id, handle: target.handle } };
}