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
+46
View File
@@ -1,3 +1,4 @@
// Canonical 画布的内存模型与纯事务 reducer:元素稳定身份独立于 owner,跨画布编辑一次校验最终全图。
package platform
import (
@@ -9,20 +10,26 @@ import (
"strings"
)
// 文档格式与写入协议独立版本化,前者描述模型视图,后者描述请求/回执契约。
const canvasModelFormat = 1
const canvasModelProtocol = 2
var errCanvasModel = errors.New("invalid_canvas_model")
var errModelConflict = errors.New("canvas_model_field_conflict")
// modelParent 用父画布和入口元素描述唯一所有权;不依赖旧 frameId 或投影端口。
type modelParent struct {
CanvasID string `json:"canvasId"`
EntryElementID string `json:"entryElementId"`
}
// modelCanvas 的根 Parent 为 nil,其他画布必须有唯一且有效的入口节点。
type modelCanvas struct {
ID string `json:"id"`
Parent *modelParent `json:"parent"`
}
// canvasModel 同时保留活跃对象、删除 incarnation 和死记录;Versions 也保留已移除画布的版本。
type canvasModel struct {
Root string
Canvases map[string]modelCanvas
@@ -32,6 +39,8 @@ type canvasModel struct {
DeadRecords map[string]map[string]any
Versions map[string]int64
}
// modelView 为客户端提供完整或参与者局部模型;Removed 明确列出已归档但仍有版本的画布。
type modelView struct {
Format int `json:"documentFormatVersion"`
ProjectID string `json:"projectId"`
@@ -42,10 +51,14 @@ type modelView struct {
Complete bool `json:"complete"`
Removed []string `json:"removedCanvasIds"`
}
// modelTarget 以 ID+incarnation 定位一代元素,避免删除后恢复的同 ID 被旧操作命中。
type modelTarget struct {
ID string `json:"id"`
Incarnation int64 `json:"incarnation"`
}
// modelChange 使用 before/after 做比较交换;data 字段的 Present 指针区分缺字段和显式 null。
type modelChange struct {
Kind string `json:"kind"`
ID string `json:"id,omitempty"`
@@ -56,10 +69,14 @@ type modelChange struct {
BeforePresent *bool `json:"beforePresent,omitempty"`
AfterPresent *bool `json:"afterPresent,omitempty"`
}
// modelOperation 是需跨请求去重的逻辑操作,一次包含若干有序变更。
type modelOperation struct {
ID string `json:"id"`
Changes []modelChange `json:"changes"`
}
// modelBatch 将多逻辑操作与所有参与画布版本打包;RequestID 必须等于 HTTP 幂等键。
type modelBatch struct {
ProtocolVersion int `json:"protocol_version"`
RequestID string `json:"request_id"`
@@ -67,10 +84,15 @@ type modelBatch struct {
Operations []modelOperation `json:"operations"`
}
// emptyModel 初始化所有索引,尚无活跃画布,需迁移或构造后通过 validateCanvasModel。
func emptyModel(root string) canvasModel {
return canvasModel{Root: root, Canvases: map[string]modelCanvas{}, Elements: map[string]map[string]any{}, Tombstones: map[string]int64{}, TombstoneOwners: map[string]string{}, DeadRecords: map[string]map[string]any{}, Versions: map[string]int64{}}
}
// modelString 只读取已解码 JSON 字符串,类型错误返回空值交由上层验证。
func modelString(value any) string { text, _ := value.(string); return text }
// modelInt 只接受 JavaScript 安全正整数,防止版本/incarnation 跨端精度丢失。
func modelInt(value any) int64 {
number, ok := value.(float64)
if !ok || number < 1 || number > 9007199254740991 || math.Trunc(number) != number {
@@ -78,6 +100,8 @@ func modelInt(value any) int64 {
}
return int64(number)
}
// modelJSONSafe 递归限制深度并拒绝非有限浮点或非 JSON 类型,允许未知组件保留合法数据。
func modelJSONSafe(value any, depth int) bool {
if depth > 64 {
return false
@@ -104,6 +128,8 @@ func modelJSONSafe(value any, depth int) bool {
}
return false
}
// modelEqual 统一到 JSON 值域后比较,使 Go 整数/结构体与解码出的 float64/对象能按语义相等。
func modelEqual(left, right any) bool {
// Round-trip numeric Go structs and JSON records to the same JSON value domain.
a, ea := json.Marshal(left)
@@ -114,6 +140,8 @@ func modelEqual(left, right any) bool {
var av, bv any
return json.Unmarshal(a, &av) == nil && json.Unmarshal(b, &bv) == nil && reflect.DeepEqual(av, bv)
}
// view 按稳定 ID 排序输出,participants 为 nil 表示完整模型,否则只返回给定画布及其墓碑。
func (model canvasModel) view(participants map[string]int64) modelView {
view := modelView{Format: canvasModelFormat, ProjectID: model.Root, Canvases: []modelCanvas{}, Elements: []map[string]any{}, Tombstones: map[string]int64{}, Versions: map[string]int64{}, Complete: participants == nil, Removed: []string{}}
for _, id := range sortedKeys(model.Canvases) {
@@ -134,6 +162,7 @@ func (model canvasModel) view(participants map[string]int64) modelView {
}
view.Elements = append(view.Elements, element)
}
// 删除代数也必须处于安全整数范围;活跃元素的 incarnation 稍后要求严格高于其墓碑。
for id, incarnation := range model.Tombstones {
owner := model.TombstoneOwners[id]
if live := model.Elements[id]; live != nil {
@@ -159,6 +188,8 @@ func (model canvasModel) view(participants map[string]int64) modelView {
}
return view
}
// sortedKeys 为模型、投影和回执提供确定顺序,不依赖 Go map 遍历顺序。
func sortedKeys[T any](values map[string]T) []string {
keys := make([]string, 0, len(values))
for key := range values {
@@ -167,12 +198,16 @@ func sortedKeys[T any](values map[string]T) []string {
sort.Strings(keys)
return keys
}
// cloneModel 深拷贝 JSON 兼容模型,让 reducer 失败时输入对象及嵌套 data 不被污染。
func cloneModel(model canvasModel) canvasModel {
raw, _ := json.Marshal(model)
var copy canvasModel
_ = json.Unmarshal(raw, &copy)
return copy
}
// modelAncestors 从当前画布向根遍历,拒绝缺父、循环和超过八层边界的路径。
func modelAncestors(model canvasModel, id string) ([]string, error) {
path, seen := []string{}, map[string]bool{}
for id != "" {
@@ -189,6 +224,8 @@ func modelAncestors(model canvasModel, id string) ([]string, error) {
}
return path, nil
}
// modelCommonCanvas 从右端最近祖先向上寻找交集,确定连接唯一的最低共同祖先所有者。
func modelCommonCanvas(model canvasModel, left, right string) (string, error) {
a, err := modelAncestors(model, left)
if err != nil {
@@ -209,6 +246,9 @@ func modelCommonCanvas(model canvasModel, left, right string) (string, error) {
}
return "", errCanvasModel
}
// validateCanvasModel 对最终状态检查唯一根、入口所有权、元素代数、JSON 预算及连接最低共同祖先。
// 未知组件的合法 data/envelope 字段保留;仅已知 v1 组件追加相应业务数据约束。
func validateCanvasModel(model canvasModel) error {
if !uuidSlugPattern.MatchString(model.Root) || len(model.Canvases) == 0 || len(model.Canvases) > 256 || len(model.Elements) > 128000 {
return errCanvasModel
@@ -310,6 +350,7 @@ func validateCanvasModel(model canvasModel) error {
}
// Pure transaction reducer. Unknown component data/envelope fields are retained.
// applyModelOperations 在副本依次执行变更,允许批次中间态暂不完整,最后统一验证所有权和引用。
func applyModelOperations(initial canvasModel, operations []modelOperation) (canvasModel, map[string]bool, error) {
model, touched, seen := cloneModel(initial), map[string]bool{}, map[string]bool{}
if len(operations) == 0 || len(operations) > 2500 {
@@ -332,6 +373,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
}
switch change.Kind {
case "field":
// 字段编辑必须命中同代元素;data.<key> 是单层键,其他字段只允许明确白名单。
element := model.Elements[change.Target.ID]
if element == nil || modelInt(element["incarnation"]) != change.Target.Incarnation {
return model, nil, errModelConflict
@@ -344,6 +386,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
}
data := element["data"].(map[string]any)
prior, present := data[key]
// beforePresent 缺省表示字段存在,因此缺字段与现有 null 不会被误当作同一前态。
if present != (change.BeforePresent == nil || *change.BeforePresent) || !modelEqual(prior, before) {
return model, nil, errModelConflict
}
@@ -365,6 +408,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
}
}
case "element":
// 整记录增删替换先比较前态;删除留下死记录,恢复要求比已删除代数更新的 incarnation。
if !canvasID.MatchString(change.ID) || !modelEqual(model.Elements[change.ID], before) {
return model, nil, errModelConflict
}
@@ -393,6 +437,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
touched[modelString(record["ownerCanvasId"])] = true
}
case "canvas":
// 画布关系变动同时触及旧父和新父,确保入口所有权变化被版本向量覆盖。
prior, exists := model.Canvases[change.ID]
var priorValue any
if exists {
@@ -443,6 +488,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
}
}
}
// 每个参与者无论本批被触及多少次都只递增一次;数据库权限与预期版本仍由 HTTP 层检查。
for id := range touched {
model.Versions[id] = initial.Versions[id] + 1
}