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
+25
View File
@@ -1,3 +1,4 @@
// 画布快照协议的结构规范化与旧整文档 GET/PATCH;跨画布所有权变更必须走专用事务命令。
package platform
import (
@@ -13,20 +14,26 @@ import (
"unicode/utf8"
)
// canvasLimit 同时约束快照文档及该路由请求体预算,较大的嵌入图片也计算在内。
const canvasLimit = 5 << 20
var canvasColor = regexp.MustCompile(`^#[0-9a-fA-F]{6}$`)
var canvasID = regexp.MustCompile(`^[A-Za-z0-9_-]{1,128}$`)
var canvasIcon = regexp.MustCompile(`^[A-Z][A-Za-z0-9]{0,63}$`)
// canvasNumber 面向 JSON 解码后的 float64,拒绝非数、无穷和超出闭区间的值。
func canvasNumber(v any, low, high float64) bool {
n, ok := v.(float64)
return ok && !math.IsNaN(n) && !math.IsInf(n, 0) && n >= low && n <= high
}
// canvasString 按 Unicode 码点数限制展示文本,与请求体的字节预算分别约束。
func canvasString(v any, limit int) bool {
s, ok := v.(string)
return ok && utf8.RuneCountInString(s) <= limit
}
// canvasChoice 用于协议枚举白名单;缺省字段由调用处决定是否允许,不能自动匹配零值。
func canvasChoice(v any, choices ...string) bool {
for _, s := range choices {
if v == s {
@@ -35,6 +42,8 @@ func canvasChoice(v any, choices ...string) bool {
}
return false
}
// canvasFields 拒绝 nil 和未知键,但不要求所有允许键都存在;必填性由后续类型/值检查保证。
func canvasFields(m map[string]any, fields ...string) bool {
if m == nil {
return false
@@ -53,6 +62,9 @@ func canvasFields(m map[string]any, fields ...string) bool {
}
return true
}
// canvasImage 接受无用户信息的 HTTPS URL,或最多 2 MiB 且 MIME 嗅探相符的栅格 data URL。
// 此处不下载 HTTPS 图片,内嵌图也只做头部嗅探,不承担完整图片解码。
func canvasImage(v any) bool {
s, ok := v.(string)
if !ok {
@@ -71,6 +83,9 @@ func canvasImage(v any) bool {
}
return false
}
// normalizeCanvas 验证 v1/v2 文档,移除界面临时状态,再重编码为持久快照。
// 仅校验单文档结构;数据库所有权、模型能力与资产权限仍由保存流程另行检查。
func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
if len(raw) > canvasLimit {
return nil, false
@@ -95,6 +110,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
if v2 && (!canvasNumber(viewport["x"], -1e6, 1e6) || !canvasNumber(viewport["y"], -1e6, 1e6)) {
return nil, false
}
// 先收集节点类型和框端口,第二遍才检查 frameId/边引用,因此允许合法的前向引用。
kinds := map[string]string{}
framePorts := map[string]map[string]string{}
for _, v := range nodes {
@@ -102,6 +118,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
if !ok {
return nil, false
}
// 兼容前端 style 中的测量尺寸,但显式 width/height 优先;随后去除 selected/dragging 等临时状态。
if style, ok := n["style"].(map[string]any); ok {
if _, exists := n["width"]; !exists {
if v, exists := style["width"]; exists {
@@ -130,6 +147,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
}
_, w := n["width"]
_, h := n["height"]
// 普通节点与 v2 frame 使用不同尺寸预算,宽高必须同时缺省或同时合法。
low, high := float64(20), float64(3000)
if data, _ := n["data"].(map[string]any); v2 && data["kind"] == "frame" {
low, high = 32, 100000
@@ -189,6 +207,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
return nil, false
}
}
// validCanvasFrameExtensions 已检查端口对象形状,此处建立方向索引供边端点验证。
if kind == "frame" && v2 {
ports := map[string]string{}
if values, ok := d["ports"].([]any); ok {
@@ -249,6 +268,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
}
// Resolve memberships after all nodes so forward references are valid.
// Geometry never creates membership: only explicit frameId is persisted.
// 成员关系只由显式 frameId 决定,几何重叠不产生所有权;框本身不能成为框成员。
for _, value := range nodes {
data := value.(map[string]any)["data"].(map[string]any)
if id, exists := data["frameId"]; exists && kinds[id.(string)] != "frame" {
@@ -279,6 +299,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
if !ok {
return nil, false
}
// 边连接 frame 时必须使用已声明端口,源只能 output,目标只能 input。
if v2 && kinds[s] == "frame" {
handle, _ := e[key+"Handle"].(string)
direction := "input"
@@ -315,6 +336,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
return out, err == nil
}
// canvas 读取时在发送响应体前释放事务;保存时将文档、资产绑定及 AI 目标失效一并提交。
func (s *service) canvas(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet && r.Method != http.MethodPatch {
reject(w, 405, "method_not_allowed")
@@ -390,6 +412,7 @@ func (s *service) canvas(w http.ResponseWriter, r *http.Request, project, accoun
reject(w, 409, "canvas_schema_upgrade_required")
return nil
}
// 已升级文档不可通过旧客户端降回 v1,避免丢失子图和端口等结构。
if previousSchema == 2 && canvasSchema(document) != 2 {
reject(w, 409, "canvas_schema_upgrade_required")
return nil
@@ -398,6 +421,7 @@ func (s *service) canvas(w http.ResponseWriter, r *http.Request, project, accoun
reject(w, 412, "version_conflict")
return nil
}
// 通过版本检查后仍须保持现有跨画布关系;普通快照不能自行创建或重定向所有权。
if valid, e := validateCanvasRelations(r, tx, project, workspace, material, previousDocument, document); e != nil {
return e
} else if !valid {
@@ -413,6 +437,7 @@ func (s *service) canvas(w http.ResponseWriter, r *http.Request, project, accoun
reject(w, 400, "invalid_asset_reference")
return nil
}
// 在相同事务中建立资产引用、使被删除/改变的 AI 目标失效,再推进独立的 canvas_version。
if err = s.attachCanvasAssets(r, tx, project, workspace, material, document); err != nil {
return err
}