docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]

This commit is contained in:
2026-11-16 17:52:11 +08:00
parent 30829eeb86
commit 1090591503
123 changed files with 1279 additions and 3 deletions
+16
View File
@@ -1,3 +1,4 @@
// 按执行相关边懒读取画布树,避免为一次 AI 操作扫描无关或无权限的子画布。
package platform
import (
@@ -8,6 +9,7 @@ import (
"strings"
)
// canvasAIReader 通过注入 Load/Parent 解耦数据库,缓存快照、解码文档和已知父关系,并记录实际用到的边。
type canvasAIReader struct {
Load func(string) (canvasSnapshot, error)
Parent func(string) (subgraphRelation, error)
@@ -18,6 +20,7 @@ type canvasAIReader struct {
used map[string]map[string]bool
}
// snapshot 每个 board 只加载/解码一次,返回同一捕获快照供本次计划复用。
func (reader *canvasAIReader) snapshot(board string) (canvasSnapshot, map[string]any, error) {
if snapshot, ok := reader.snapshots[board]; ok {
return snapshot, reader.documents[board], nil
@@ -34,6 +37,8 @@ func (reader *canvasAIReader) snapshot(board string) (canvasSnapshot, map[string
reader.documents[board] = doc
return snapshot, doc, nil
}
// parent 将无父行归一为空关系并缓存 parentKnown,避免根画布被反复查询。
func (reader *canvasAIReader) parent(board string) (subgraphRelation, error) {
if reader.parentKnown[board] {
return reader.parents[board], nil
@@ -50,6 +55,8 @@ func (reader *canvasAIReader) parent(board string) (subgraphRelation, error) {
reader.parents[board] = relation
return relation, nil
}
// node 返回已加载画布中的节点 data,缺失节点按所有权冲突处理,不凭同名跨画布寻找。
func (reader *canvasAIReader) node(board, node string) (map[string]any, error) {
_, doc, err := reader.snapshot(board)
if err != nil {
@@ -63,6 +70,8 @@ func (reader *canvasAIReader) node(board, node string) (map[string]any, error) {
}
return nil, errGraphOwnership
}
// resolve 按方向递归解开 frame port,并验证数据库父关系与文档 subgraph 相符,最多跨八层。
func (reader *canvasAIReader) resolve(board, node, handle, direction string, depth int) (string, error) {
if depth > 8 {
return "", errGraphCapacity
@@ -98,6 +107,7 @@ func (reader *canvasAIReader) resolve(board, node, handle, direction string, dep
// Follow only real edges and the port chains exposing this node. Empty or
// unrelated child boards are never traversed merely because their frame exists.
// edges 从真实节点沿其祖先暴露端口查入/出边;execution.enabled=false 的边不参与,结果按逻辑边 ID 去重排序。
func (reader *canvasAIReader) edges(board, node string, outgoing bool) ([]canvasAIEdgePlan, error) {
type exposure struct {
Board, Node, Handle string
@@ -161,6 +171,7 @@ func (reader *canvasAIReader) edges(board, node string, outgoing bool) ([]canvas
logical := canvasAIEdgePlan{ID: canvasNodeKey(current.Board, id), Source: source, Target: target}
found[logical.ID] = logical
}
// 向上只跟踪暴露当前节点/handle 的端口,不因看见其他 frame 就遍历其孩子。
relation, err := reader.parent(current.Board)
if err != nil {
return nil, err
@@ -194,6 +205,8 @@ func (reader *canvasAIReader) edges(board, node string, outgoing bool) ([]canvas
sort.Slice(result, func(i, j int) bool { return result[i].ID < result[j].ID })
return result, nil
}
// plan 每次重置缓存,收集根及可传播节点和其静态前驱,再把实际使用边交给纯拓扑规划器。
func (reader *canvasAIReader) plan(board, node string, propagate bool) (canvasAIPlan, error) {
reader.snapshots = map[string]canvasSnapshot{}
reader.documents = map[string]map[string]any{}
@@ -235,6 +248,7 @@ func (reader *canvasAIReader) plan(board, node string, propagate bool) (canvasAI
}
}
}
// 保留已读节点数据但裁去无关边,避免纯规划阶段解析未加载或无权限的邻接子图。
filtered := map[string]canvasSnapshot{}
for id, snapshot := range reader.snapshots {
doc := reader.documents[id]
@@ -255,6 +269,8 @@ func (reader *canvasAIReader) plan(board, node string, propagate bool) (canvasAI
}
return buildCanvasAIPlan(filtered, board, node, propagate)
}
// loadCanvasAIPlan 注入事务内权限检查与持锁快照读取;每个实际读取画布都要求编辑权限。
func loadCanvasAIPlan(r *http.Request, tx *sql.Tx, project, workspace, account string, parent canvasSnapshot, node string, propagate bool) (canvasAIPlan, error) {
reader := canvasAIReader{Load: func(board string) (canvasSnapshot, error) {
_, role, err := lockMaterial(r.Context(), tx, project, workspace, board, account)