docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]
This commit is contained in:
@@ -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, ©)
|
||||
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
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user