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
+8
View File
@@ -1,3 +1,4 @@
// 子图创建事务与共享快照读取;父 frame、子素材、关系和撤销回执必须一起提交。
package platform
import (
@@ -9,18 +10,21 @@ import (
"time"
)
// canvasSnapshot 使用独立 canvas_version,与素材标题/内容的 version 区分,Document 保留完整 JSON。
type canvasSnapshot struct {
BoardID string `json:"board_id"`
Version int64 `json:"version"`
Document json.RawMessage `json:"document"`
}
// loadCanvas 读取并锁定素材行,旧 board 无快照时投影为空 v1 文档;调用方先做类型和权限检查。
func loadCanvas(r *http.Request, tx *sql.Tx, project, workspace, board string) (canvasSnapshot, error) {
result := canvasSnapshot{BoardID: board}
err := tx.QueryRowContext(r.Context(), `SELECT canvas_version,COALESCE(canvas_document,'{"schema_version":1,"nodes":[],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}'::jsonb) FROM materials WHERE project=$1 AND workspace_id=$2 AND id=$3 FOR UPDATE`, project, workspace, board).Scan(&result.Version, &result.Document)
return result, err
}
// createSubgraph 要求 v2、幂等 UUID 和父 If-Match;创建空 v2 子画布并在父文档加对应 frame。
func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -78,6 +82,7 @@ func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project
reject(w, 403, "forbidden")
return nil
}
// 取得工作区锁后先重放历史回执,再检查当前版本,因此丢响应重试不会因版本已推进而失败。
var previousHash string
var previous json.RawMessage
var status int
@@ -121,6 +126,7 @@ func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project
reject(w, 413, "graph_limit_exceeded")
return nil
}
// 子素材先在未提交事务中创建;后续深度/父文档校验失败时 defer 回滚,不留下孤儿孩子。
var childID, slug string
err = tx.QueryRowContext(r.Context(), `INSERT INTO materials(project,workspace_id,kind,title,created_by,canvas_document) VALUES($1,$2,'board',$3,$4,'{"schema_version":2,"nodes":[],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}') RETURNING id::text,slug`, project, workspace, f.Title, account).Scan(&childID, &slug)
if err != nil {
@@ -150,6 +156,7 @@ func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project
reject(w, 400, "invalid_canvas")
return nil
}
// before 只包含原父快照;撤销时据此识别本次新建的孩子,将其归档保留恢复记录。
before := parent
parent.Document = normalized
parent.Version++
@@ -167,6 +174,7 @@ func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project
if err != nil {
return err
}
// 回执记录父子版本与七天撤销期限,和所有文档/关系同事务持久化,成功提交后才响应。
result := response{"transaction_id": transaction, "frame_id": f.ID, "child_board": response{"id": childID, "slug": slug, "workspace_id": workspace}, "parent": parent, "child": child, "undo_receipt": response{"transaction_id": transaction, "valid_for_seconds": 604800, "expires_at": receiptExpiry}}
encoded, _ := json.Marshal(result)
savedBefore, _ := json.Marshal([]canvasSnapshot{before})