docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]
This commit is contained in:
@@ -1,3 +1,4 @@
|
||||
// AI 与 canonical 模型适配:稳定身份跟随 owner,窄字段 patch 保留未知组件 envelope 和无关几何。
|
||||
package platform
|
||||
|
||||
import (
|
||||
@@ -13,6 +14,7 @@ var errAIInvalidPatch = errors.New("invalid_ai_patch")
|
||||
|
||||
// The snapshot is an AI reader projection only. Canonical changes retain the
|
||||
// original rows, including unknown envelopes, geometry and reference metadata.
|
||||
// canvasAIChange 携带待保存快照及可选 canonical 前后模型,避免将兼容投影反写为权威模型。
|
||||
type canvasAIChange struct {
|
||||
Snapshot canvasSnapshot
|
||||
Before *canvasModel
|
||||
@@ -23,6 +25,8 @@ type canvasAIChange struct {
|
||||
// Until a narrower read-set protocol exists, admission binds every active
|
||||
// canvas in this canonical project. Archived versions are not graph inputs.
|
||||
// Workspace locking keeps validation, plan freezing and admission atomic.
|
||||
// validateCanvasAIVersions 暂要求 Expected 精确覆盖全部活跃 canonical 画布且当前 board 与 If-Match 一致。
|
||||
// 归档版本不作为规划输入;完整 read-set 检查与冻结在同一工作区锁内。
|
||||
func validateCanvasAIVersions(model canvasModel, board string, header int64, expected map[string]int64) string {
|
||||
if len(expected) != len(model.Canvases) || expected[board] != header {
|
||||
return "invalid_ai_versions"
|
||||
@@ -39,6 +43,7 @@ func validateCanvasAIVersions(model canvasModel, board string, header int64, exp
|
||||
return ""
|
||||
}
|
||||
|
||||
// prepareModelAIPatch 仅在同 owner 的可执行 v1 节点副本修改 ai/text/src/assetId,推进该画布版本并验证全模型。
|
||||
func prepareModelAIPatch(before canvasModel, board, node string, patch response) (canvasModel, error) {
|
||||
element := before.Elements[node]
|
||||
if element == nil || element["structure"] != "node" || element["ownerCanvasId"] != board || modelInt(element["dataVersion"]) != 1 || !canvasChoice(element["componentId"], "text", "script", "plain-text", "image", "plain-image") {
|
||||
@@ -61,6 +66,8 @@ func prepareModelAIPatch(before canvasModel, board, node string, patch response)
|
||||
}
|
||||
return after, nil
|
||||
}
|
||||
|
||||
// prepareCanvasAIPatch 按是否迁入 canonical 分派:前者改权威模型再生成投影,后者改快照副本再 normalize。
|
||||
func prepareCanvasAIPatch(r *http.Request, tx *sql.Tx, project, workspace string, snapshot canvasSnapshot, node string, patch response) (canvasAIChange, error) {
|
||||
change := canvasAIChange{Snapshot: snapshot}
|
||||
root, err := canonicalRoot(r.Context(), tx, project, workspace, snapshot.BoardID)
|
||||
@@ -123,12 +130,16 @@ func prepareCanvasAIPatch(r *http.Request, tx *sql.Tx, project, workspace string
|
||||
change.Snapshot.Version++
|
||||
return change, nil
|
||||
}
|
||||
|
||||
// saveCanvasAIChange 根据 change 的模型形态选择持久化路径,复用调用方事务,不自行提交。
|
||||
func (s *service) saveCanvasAIChange(r *http.Request, tx *sql.Tx, project, workspace, account string, change canvasAIChange) error {
|
||||
if change.After == nil {
|
||||
return s.saveCanvas(r, tx, project, workspace, change.Snapshot)
|
||||
}
|
||||
return s.saveCanvasModel(r, tx, project, workspace, account, *change.Before, *change.After, map[string]bool{change.Snapshot.BoardID: true})
|
||||
}
|
||||
|
||||
// addCanonical 仅在 canonical 响应附格式、代数与当前 owner 局部模型,旧快照协议不增加这些字段。
|
||||
func (change canvasAIChange) addCanonical(result response) {
|
||||
if change.After == nil {
|
||||
return
|
||||
@@ -138,6 +149,7 @@ func (change canvasAIChange) addCanonical(result response) {
|
||||
result["model"] = change.After.view(map[string]int64{board: change.Snapshot.Version})
|
||||
}
|
||||
|
||||
// canvasAIIdentity 查当前 owner 下活跃且可执行的节点身份;旧图返回空根,非法目标返回零代数。
|
||||
func canvasAIIdentity(ctx context.Context, tx *sql.Tx, project, workspace, board, node string) (string, int64, string, error) {
|
||||
root, err := canonicalRoot(ctx, tx, project, workspace, board)
|
||||
if err != nil || root == "" {
|
||||
@@ -157,6 +169,8 @@ func canvasAIIdentity(ctx context.Context, tx *sql.Tx, project, workspace, board
|
||||
}
|
||||
return root, incarnation, kind, nil
|
||||
}
|
||||
|
||||
// bindCanvasAIIdentities 在准入时给每步冻结根/代数,旧图仍保留 board-local 身份。
|
||||
func bindCanvasAIIdentities(ctx context.Context, tx *sql.Tx, project, workspace string, plan *canvasAIPlan) error {
|
||||
for i, step := range plan.Steps {
|
||||
root, incarnation, kind, err := canvasAIIdentity(ctx, tx, project, workspace, step.BoardID, step.NodeID)
|
||||
@@ -173,6 +187,7 @@ func bindCanvasAIIdentities(ctx context.Context, tx *sql.Tx, project, workspace
|
||||
|
||||
// Run URLs remain anchored at their admission board, even after that partition
|
||||
// is archived. Canonical ownership grants are inherited from the same root.
|
||||
// lockCanvasAIRunRoute 将 canonical 原 run 路径转到根级授权,原分区归档后仍可查询/取消该 run。
|
||||
func lockCanvasAIRunRoute(ctx context.Context, tx *sql.Tx, project, workspace, board, account string) (string, string, error) {
|
||||
root, err := canonicalRoot(ctx, tx, project, workspace, board)
|
||||
if err != nil {
|
||||
@@ -183,6 +198,8 @@ func lockCanvasAIRunRoute(ctx context.Context, tx *sql.Tx, project, workspace, b
|
||||
}
|
||||
return lockMaterial(ctx, tx, project, workspace, board, account)
|
||||
}
|
||||
|
||||
// lockCanvasAIWorkspace 只取得工作区行锁;具体目标权限必须在后续独立检查。
|
||||
func lockCanvasAIWorkspace(ctx context.Context, tx *sql.Tx, project, workspace string) error {
|
||||
var id string
|
||||
return tx.QueryRowContext(ctx, `SELECT id::text FROM workspaces WHERE project=$1 AND id=$2 FOR UPDATE`, project, workspace).Scan(&id)
|
||||
@@ -190,6 +207,8 @@ func lockCanvasAIWorkspace(ctx context.Context, tx *sql.Tx, project, workspace s
|
||||
|
||||
// Caller holds the workspace lock. Frozen identity is stable; owner is resolved
|
||||
// afresh at execution, hydration and write time, never written into the plan.
|
||||
// resolveCanvasAITarget 在调用方持锁时重新解析当前 owner,要求同根、同代、同种类且 owner 未归档。
|
||||
// 原计划 BoardID 不被更新,避免破坏步骤身份、指纹和重放结果。
|
||||
func resolveCanvasAITarget(ctx context.Context, tx *sql.Tx, project, workspace string, step canvasAIStepPlan) (string, bool, error) {
|
||||
if step.CanonicalRoot == "" {
|
||||
root, err := canonicalRoot(ctx, tx, project, workspace, step.BoardID)
|
||||
@@ -206,10 +225,14 @@ func resolveCanvasAITarget(ctx context.Context, tx *sql.Tx, project, workspace s
|
||||
}
|
||||
return board, incarnation == step.TargetIncarnation && incarnation > 0 && kind == step.Kind && version == 1, nil
|
||||
}
|
||||
|
||||
// canvasAIIdentityMatches 是只关心有效性的包装,仍沿用完整 owner/生命周期检查。
|
||||
func canvasAIIdentityMatches(ctx context.Context, tx *sql.Tx, project, workspace string, step canvasAIStepPlan) (bool, error) {
|
||||
_, ok, err := resolveCanvasAITarget(ctx, tx, project, workspace, step)
|
||||
return ok, err
|
||||
}
|
||||
|
||||
// addTargetContext 同时返回原来源与当前应用上下文;owner 改变时附完整模型供客户端恢复新位置。
|
||||
func (change canvasAIChange) addTargetContext(result response, step canvasAIStepPlan) {
|
||||
change.addCanonical(result)
|
||||
if step.CanonicalRoot != "" {
|
||||
@@ -222,6 +245,8 @@ func (change canvasAIChange) addTargetContext(result response, step canvasAIStep
|
||||
|
||||
// Whole identity transitions cancel old jobs even when delete/restore happens
|
||||
// in a single atomic batch and the compatibility projection looks identical.
|
||||
// invalidateCanonicalAIIdentities 比较整代身份而非快照外观;删除/恢复同批或组件版本变化也取消旧任务。
|
||||
// 纯 owner 移动不失效,后续执行/写回按稳定身份跟随新位置。
|
||||
func invalidateCanonicalAIIdentities(r *http.Request, tx *sql.Tx, project, workspace string, before, after canvasModel) error {
|
||||
removed := map[string][]any{}
|
||||
for id, element := range before.Elements {
|
||||
|
||||
Reference in New Issue
Block a user