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
@@ -1,3 +1,4 @@
// 子图迁移 HTTP 编排及跨画布命令共用的回执/快照保存工具。
package platform
import (
@@ -9,6 +10,7 @@ import (
"time"
)
// transactionRetry 在调用方持锁并鉴权后查同作用域回执;true 表示已经响应重放或幂等冲突,应立即退出。
func transactionRetry(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, account, board, action, key, hash string) (bool, error) {
var previousHash string
var status int
@@ -34,11 +36,16 @@ func transactionRetry(w http.ResponseWriter, r *http.Request, tx *sql.Tx, projec
reply(w, status, previous)
return true, nil
}
// payloadDigest 将可 JSON 编码的内部请求结构编码并散列,用于比较幂等请求内容而非认证。
func payloadDigest(v any) string {
raw, _ := json.Marshal(v)
h := sha256.Sum256(raw)
return hex.EncodeToString(h[:])
}
// saveCanvas 使用调用方事务保存给定版本,追加资产绑定;非 canonical 文档还需使失效 AI 目标停止。
// canonical 写入已按稳定身份统一做生命周期失效,兼容投影不能将 owner 移动误判为删除。
func (s *service) saveCanvas(r *http.Request, tx *sql.Tx, project, workspace string, snapshot canvasSnapshot) error {
var before json.RawMessage
if err := tx.QueryRowContext(r.Context(), `SELECT 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, snapshot.BoardID).Scan(&before); err != nil {
@@ -63,6 +70,7 @@ func (s *service) saveCanvas(r *http.Request, tx *sql.Tx, project, workspace str
return err
}
// migrateSubgraphs 区分只读预览与执行:执行必须同时匹配 If-Match 和当前 PlanID,并提供幂等键。
func (s *service) migrateSubgraphs(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -130,6 +138,7 @@ func (s *service) migrateSubgraphs(w http.ResponseWriter, r *http.Request, proje
plan := legacyPlan(project, workspace, parent)
// Preflight runs the actual transform with placeholder canonical IDs. It
// never inserts materials or relation records.
// 预检使用占位 UUID 跑同一变换算法,不插素材/关系;能在建孩子前暴露几何与容量问题。
placeholders := map[string]string{}
for _, f := range plan.Frames {
placeholders[f.FrameID] = "00000000-0000-0000-0000-000000000000"
@@ -152,6 +161,7 @@ func (s *service) migrateSubgraphs(w http.ResponseWriter, r *http.Request, proje
reply(w, 200, plan)
return nil
}
// 版本相同仍要求计划摘要相同,避免把另一项目或另一文档的预览拿来执行。
if expected != parent.Version || input.PlanID != plan.PlanID {
reject(w, 412, "version_conflict")
return nil
@@ -160,6 +170,7 @@ func (s *service) migrateSubgraphs(w http.ResponseWriter, r *http.Request, proje
reply(w, 413, response{"error": "graph_limit_exceeded", "details": plan.Issues})
return nil
}
// 只有预检与版本均通过才分配真实孩子;全部文档与关系由同一个事务提交或回滚。
before := parent
children := map[string]string{}
childInfo := []any{}
@@ -180,6 +191,7 @@ func (s *service) migrateSubgraphs(w http.ResponseWriter, r *http.Request, proje
}
snapshots := []canvasSnapshot{}
versions := map[string]int64{board: parent.Version}
// 没有待迁移框时仍记录幂等结果,但不无故推进父画布版本。
if len(children) > 0 {
migrated, documents, err := migrateLegacyDocument(parent.Document, children)
if err != nil {