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
+20
View File
@@ -1,3 +1,4 @@
// 预览派生与进程内缓存:只缓存不可变图片字节,权限必须由调用方每次读取前另行检查。
package platform
import (
@@ -17,23 +18,30 @@ import (
"golang.org/x/image/draw"
)
// assetPreviewResult 只包含编码字节和 MIME,可与原图共用只读切片,禁止调用者原地修改。
type assetPreviewResult struct {
data []byte
mime string
}
// assetPreviewEntry 存储在 LRU 链表中,key 同时作为 map 索引,便于常数时间淘汰。
type assetPreviewEntry struct {
key string
value assetPreviewResult
}
// 缓存最多保留 32 MiB/128 项编码结果,互斥锁只覆盖索引操作,不覆盖解码缩放。
var previewMemory = struct {
sync.Mutex
entries map[string]*list.Element
order *list.List
bytes int
}{entries: make(map[string]*list.Element), order: list.New()}
// previewSlots 将所有预览完整解码限制为单并发,避免多个大图同时分配像素内存。
var previewSlots = make(chan struct{}, 1)
// previewWidth 仅接受原图或固定 1024 预览,不允许任意宽度组合造成无界缓存键。
func previewWidth(variant, width string) (int, error) {
if variant == "" && width == "" {
return 0, nil
@@ -46,6 +54,7 @@ func previewWidth(variant, width string) (int, error) {
// Cache only immutable bytes, after the caller checks current asset permission.
// Bound both decoded concurrency and retained encoded data.
// cachedAssetPreview 用原图摘要与宽度做键,命中即提升 LRU;等待执行槽可随请求取消。
func cachedAssetPreview(ctx context.Context, encoded []byte, mime string, width int) (assetPreviewResult, error) {
key := fmt.Sprintf("%x:%d", sha256.Sum256(encoded), width)
previewMemory.Lock()
@@ -75,6 +84,7 @@ func cachedAssetPreview(ctx context.Context, encoded []byte, mime string, width
if err != nil {
return result, err
}
// 单项过大仍可响应,但不留在缓存;其余按字节和项数双预算淘汰末尾最久未用项。
if len(result.data) > 8<<20 {
return result, nil
}
@@ -95,6 +105,7 @@ func cachedAssetPreview(ctx context.Context, encoded []byte, mime string, width
return result, nil
}
// makeAssetPreview 保留 GIF 动画和足够小的原图,其余应用 EXIF 后等比例缩至最长边预算。
func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResult, error) {
original := assetPreviewResult{encoded, mime}
// Keep animation intact. Original bytes remain the canonical AI/download input.
@@ -134,6 +145,7 @@ func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResul
draw.CatmullRom.Scale(resized, resized.Bounds(), source, source.Bounds(), draw.Src, nil)
var output bytes.Buffer
outputMime := "image/png"
// 不透明预览编码 JPEG 以减体积,透明预览保留 PNG;原图字节始终不被覆盖。
if resized.Opaque() {
err = jpeg.Encode(&output, resized, &jpeg.Options{Quality: 82})
outputMime = "image/jpeg"
@@ -143,6 +155,7 @@ func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResul
if err != nil {
return original, err
}
// 无需修正方向且重编码没有变小时直接用原图,避免更大派生文件。
if output.Len() >= len(encoded) && orientation == 1 {
return original, nil
}
@@ -151,6 +164,7 @@ func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResul
// JPEG EXIF orientation is applied to previews instead of silently rotating a
// phone photograph after its EXIF metadata is removed by the image encoder.
// jpegOrientation 仅解析 JPEG APP1 中 TIFF 的 Orientation,逐层检查长度,异常/缺省均返回正常方向一。
func jpegOrientation(data []byte) int {
if len(data) < 4 || data[0] != 0xff || data[1] != 0xd8 {
return 1
@@ -206,11 +220,13 @@ func jpegOrientation(data []byte) int {
return 1
}
// orientedAsset 是只读坐标适配视图,不复制像素;5–8 方向旋转后宽高交换。
type orientedAsset struct {
image.Image
orientation int
}
// Bounds 报告纠正方向后的零起点矩形,供缩放器计算目标比例。
func (im orientedAsset) Bounds() image.Rectangle {
b := im.Image.Bounds()
if im.orientation >= 5 {
@@ -218,7 +234,11 @@ func (im orientedAsset) Bounds() image.Rectangle {
}
return image.Rect(0, 0, b.Dx(), b.Dy())
}
// ColorModel 继承原图颜色模型,实际像素读取交由 At 做反向坐标映射。
func (im orientedAsset) ColorModel() color.Model { return im.Image.ColorModel() }
// At 将显示坐标映回原图,再补 Bounds.Min,覆盖 EXIF 八种旋转/镜像组合。
func (im orientedAsset) At(x, y int) color.Color {
b := im.Image.Bounds()
w, h := b.Dx(), b.Dy()
+10
View File
@@ -1,3 +1,4 @@
// 画布与资产纯函数回归;测试说明对应实际断言,不依赖浏览器或真实模型。
package platform
import (
@@ -11,6 +12,7 @@ import (
"testing"
)
// TestAssetPreviewDownscalesWithoutChangingOriginal 生成 1600×900 不透明图,验证缩至 512×288、转 JPEG、体积变小且原图字节不变,并比对缓存结果。
func TestAssetPreviewDownscalesWithoutChangingOriginal(t *testing.T) {
source := image.NewNRGBA(image.Rect(0, 0, 1600, 900))
for y := 0; y < 900; y++ {
@@ -39,6 +41,8 @@ func TestAssetPreviewDownscalesWithoutChangingOriginal(t *testing.T) {
t.Fatal("cache result mismatch")
}
}
// TestAssetPreviewPreservesTransparencyAndAnimation 验证透明图继续用 PNG,GIF 分支直接保留传入字节;该 GIF 样本不验证真实动画解码。
func TestAssetPreviewPreservesTransparencyAndAnimation(t *testing.T) {
source := image.NewNRGBA(image.Rect(0, 0, 800, 400))
source.SetNRGBA(1, 1, color.NRGBA{255, 0, 0, 255})
@@ -62,6 +66,8 @@ func TestAssetPreviewPreservesTransparencyAndAnimation(t *testing.T) {
t.Fatal("GIF animation changed")
}
}
// TestAssetPreviewRejectsUnboundedWidths 验证公开参数仅接受原图或 1024 预览,拒绝任意宽度/未知变体;额外检查坏图片拒绝。
func TestAssetPreviewRejectsUnboundedWidths(t *testing.T) {
for _, value := range []string{"0", "1", "256", "512", "2048", "999999", "-1", "abc"} {
if _, err := previewWidth("preview", value); err == nil {
@@ -83,6 +89,8 @@ func TestAssetPreviewRejectsUnboundedWidths(t *testing.T) {
t.Fatal("malformed image accepted")
}
}
// TestAssetPreviewAppliesJPEGOrientation 手工插入小端 EXIF 方向六,验证缩图前旋转使最终尺寸由横向变为 128×256。
func TestAssetPreviewAppliesJPEGOrientation(t *testing.T) {
source := image.NewNRGBA(image.Rect(0, 0, 800, 400))
for y := 0; y < 400; y++ {
@@ -116,6 +124,8 @@ func TestAssetPreviewAppliesJPEGOrientation(t *testing.T) {
t.Fatalf("rotated dimensions %dx%d %v", config.Width, config.Height, err)
}
}
// TestAllAssetOrientationMappings 在八个方向视图中遍历像素,检查唯一红像素不丢失或重复;不逐点断言每种方向的完整布局。
func TestAllAssetOrientationMappings(t *testing.T) {
source := image.NewNRGBA(image.Rect(0, 0, 3, 2))
source.SetNRGBA(0, 0, color.NRGBA{255, 0, 0, 255})
+20
View File
@@ -1,3 +1,4 @@
// 不可变画布图片资产:上传原图字节并保留身份,读取时按当前绑定画布权限决定可见性。
package platform
import (
@@ -20,9 +21,11 @@ import (
_ "golang.org/x/image/webp"
)
// assetLimit 是单图编码字节上限,assetPixelLimit 在完整解码前限制像素分配预算。
const assetLimit = 20 << 20
const assetPixelLimit = 40_000_000
// assetInfo 是公开元数据,URL 稳定引用私有原图路由,不包含图片内容或上传者身份。
type assetInfo struct {
ID string `json:"id"`
MIME string `json:"mime_type"`
@@ -32,12 +35,14 @@ type assetInfo struct {
URL string `json:"url"`
}
// assetURL 将项目与工作区按路径段转义,所有绑定校验使用同一 URL 生成规则。
func (s *service) assetURL(project, workspace, id string) string {
return s.origin + "/projects/" + url.PathEscape(project) + "/workspaces/" + url.PathEscape(workspace) + "/assets/" + id
}
// Decode headers first and bound allocation before decoding the actual image.
// The MIME comes from the decoder, never from the filename or upload header.
// inspectAsset 先读取尺寸预算再完整解码,并比较两次识别格式/尺寸,拒绝截断或伪造头部图片。
func inspectAsset(encoded []byte) (string, int, int, error) {
config, format, err := image.DecodeConfig(bytes.NewReader(encoded))
if err != nil {
@@ -55,6 +60,9 @@ func inspectAsset(encoded []byte) (string, int, int, error) {
}
return "image/" + format, config.Width, config.Height, nil
}
// uploadAsset 分两次事务检查编辑权限:接收慢 multipart 正文和解码时不持有工作区锁。
// 幂等键限定在上传者/工作区,重复请求必须保持相同图片摘要和可选资源 ID。
func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -70,6 +78,7 @@ func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, a
reject(w, 400, "invalid_resource_id")
return nil
}
// 兼容旧版直接返回 assetInfo;指定 X-Resource-Id 的客户端获得带请求 ID 的 v2 应用回执。
respond := func(info assetInfo) {
if resourceID == "" {
reply(w, 201, info)
@@ -152,6 +161,7 @@ func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, a
reject(w, 403, "forbidden")
return nil
}
// 第二次取锁后重读权限和幂等记录,防止上传期间撤权或并发重试产生重复资产。
digest := sha256.Sum256(encoded)
hash := hex.EncodeToString(digest[:])
info := assetInfo{MIME: mime, Bytes: len(encoded), Width: width, Height: height}
@@ -192,6 +202,7 @@ func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, a
}
// A missing receipt is unknown: callers may only retry the same resource/key/bytes.
// assetOperation 在当前成员授权下查找本人上传回执;缺记录为 unknown,不能据此换键重传或判定零写入。
func (s *service) assetOperation(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -223,6 +234,9 @@ func (s *service) assetOperation(w http.ResponseWriter, r *http.Request, project
reply(w, 200, response{"protocol_version": 2, "request_id": key, "status": "applied", "asset": info})
return nil
}
// assetReadable 依赖调用方持有工作区锁:无绑定时只允许上传者/admin,有绑定时需至少一个绑定画布可读。
// 绑定可读性复用 lockMaterial,因此继承根画布权限并尊重子图归档状态。
func assetReadable(r *http.Request, tx *sql.Tx, project, workspace, id, account string) (bool, error) {
var uploader string
err := tx.QueryRowContext(r.Context(), `SELECT uploaded_by::text FROM canvas_assets WHERE project=$1 AND workspace_id=$2 AND id=$3`, project, workspace, id).Scan(&uploader)
@@ -273,6 +287,7 @@ func assetReadable(r *http.Request, tx *sql.Tx, project, workspace, id, account
}
// Metadata uses the same read policy as original bytes; it is not a persistent grant.
// getAssetMetadata 每次重新鉴权,读取不可变身份摘要后先提交释放锁,再写 JSON,不发放持久权限。
func (s *service) getAssetMetadata(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -318,6 +333,7 @@ func (s *service) getAssetMetadata(w http.ResponseWriter, r *http.Request, proje
return nil
}
// getAsset 同时服务原图与固定预览变体;先一致读取权限/字节,释放事务后才缩图或写响应。
func (s *service) getAsset(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -383,6 +399,7 @@ func (s *service) getAsset(w http.ResponseWriter, r *http.Request, project, acco
return err
}
// attachCanvasAssets 为文档内显式 assetId 或同工作区托管 URL 追加绑定;不删除旧绑定,调用方先验证权限。
func (s *service) attachCanvasAssets(r *http.Request, tx *sql.Tx, project, workspace, board string, raw json.RawMessage) error {
for _, data := range canvasNodeData(raw) {
id, _ := data["assetId"].(string)
@@ -406,6 +423,9 @@ func (s *service) attachCanvasAssets(r *http.Request, tx *sql.Tx, project, works
}
return nil
}
// validateCanvasAssets 对托管 URL 强制 ID/URL 一致并实时验证可读性,合法引用在同事务中建立当前画布绑定。
// 普通外部图片 URL 在此跳过,交给快照结构校验;它们不会成为私有资产绑定。
func (s *service) validateCanvasAssets(r *http.Request, tx *sql.Tx, project, workspace, account string, raw json.RawMessage) (bool, error) {
for _, data := range canvasNodeData(raw) {
id, explicit := data["assetId"].(string)
+2
View File
@@ -1,3 +1,4 @@
// 资产解码纯函数回归,编码小型真实栅格样本后检查格式与尺寸,不访问数据库。
package platform
import (
@@ -10,6 +11,7 @@ import (
"testing"
)
// TestAssetDecodersUseActualContent 验证 PNG/JPEG/GIF 从实际内容识别,拒绝截断样本和未支持的 SVG。
func TestAssetDecodersUseActualContent(t *testing.T) {
im := image.NewRGBA(image.Rect(0, 0, 3, 2))
im.Set(1, 1, color.RGBA{R: 255, A: 255})
+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
}
+15
View File
@@ -1,3 +1,4 @@
// AI 步骤开始/完成的事务边界:执行前与回写前分别校验权限、租约和目标身份,防止迟到输出覆盖新状态。
package platform
import (
@@ -8,6 +9,8 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// startCanvasStep 持工作区锁解析目标当前 owner,再检查租约、编辑权限与内容指纹,成功才将 queued 改 running。
// 不可执行时先释放事务,再调用完成流程记录拒绝状态,避免嵌套事务互锁。
func (s *service) startCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan) (bool, error) {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
@@ -78,9 +81,13 @@ func (s *service) startCanvasStep(ctx context.Context, run canvasQueueRun, step
}
return true, nil
}
// finishCanvasStep 是文本/无输出失败路径的兼容包装,所有落库与事件逻辑集中在结构化完成函数。
func (s *service) finishCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, text, code string, started bool) (string, error) {
return s.finishCanvasStepOutput(ctx, run, step, codex.CanvasOutput{Kind: "text", Text: text}, code, started)
}
// finishCanvasStepOutput 在同一事务中保存输出、条件应用、步骤终态与事件;已终态或租约失效则直接保留旧结果。
func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, generated codex.CanvasOutput, code string, started bool) (string, error) {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
@@ -104,12 +111,14 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
if err != nil {
return "", err
}
// 取消、删除失效和其他完成者已写出的终态优先,迟到 worker 结果不得改回成功。
if oldStatus != "queued" && oldStatus != "running" {
return oldStatus, nil
}
if runStatus != "running" || !lease.Valid || lease.String != run.Lease {
return oldStatus, nil
}
// 统一映射依赖失败、内容冲突、取消与生成错误,run.cancel_requested 优先于局部生成结果。
status := "succeeded"
switch code {
case "dependency_failed":
@@ -139,6 +148,7 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
var appliedEvent response
var output any
var version any
// 生成成功才保存可供恢复的输出;内容指纹冲突时仍保留 output,但不覆盖当前节点。
if code == "" && started {
var outputID string
err = tx.QueryRowContext(ctx, `SELECT gen_random_uuid()::text`).Scan(&outputID)
@@ -177,6 +187,7 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
return "", err
}
}
// 仍使用原计划来源构造指纹,owner 变化由 canonical 稳定身份单独解析,拖动不造成假冲突。
if !identityOK || target == nil || canvasTargetFingerprint(step.BoardID, step.NodeID, target) != step.Fingerprint {
status, code = "conflict", "target_changed"
} else {
@@ -199,6 +210,7 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
}
}
}
// output 与 applied 是不同事件;换 owner 后的冲突附完整模型,客户端可定位当前显式应用目标。
if output != nil {
event := response{"step_id": step.ID, "board_id": eventBoard, "origin_board_id": step.BoardID, "canonical_root": step.CanonicalRoot, "target_incarnation": step.TargetIncarnation, "node_id": step.NodeID, "output": output}
if status == "conflict" && identityOK && step.CanonicalRoot != "" && eventBoard != step.BoardID {
@@ -249,6 +261,9 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
}
return status, nil
}
// completeCanvasRun 从数据库步骤聚合实际终态而非信任内存 results;仍有活跃步骤则不提前结束 run。
// 仅当前租约可清空租约并写 run.completed,兼容部分成功、全冲突和取消。
func (s *service) completeCanvasRun(ctx context.Context, run canvasQueueRun, _ map[string]canvasStepResult) error {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
+5
View File
@@ -1,3 +1,4 @@
// 用户取消 AI run:立即冻结数据库终态与回执,worker 心跳在随后一秒级检查中停止在途调用。
package platform
import (
@@ -7,6 +8,7 @@ import (
"net/http"
)
// cancelCanvasAIRun 接受旧空体或完整 v2 身份;重试先返回原回执,再决定是否需要取消 queued/running 步骤。
func (s *service) cancelCanvasAIRun(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -107,6 +109,7 @@ func (s *service) cancelCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err = json.Unmarshal(rawPlan, &plan); err != nil {
return err
}
// 取消也要求所有步骤当前目标可编辑,目标移动后按新 owner 权限判断,不能借原 run 路径越权。
for _, step := range plan.Steps {
target, ok, e := resolveCanvasAITarget(r.Context(), tx, project, workspace, step)
if e != nil {
@@ -123,6 +126,7 @@ func (s *service) cancelCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
return rejectRequest(403, "forbidden")
}
}
// 已成功的步骤不回滚;只把仍活跃步骤设 cancelled,并为受影响边写 skipped 事件。
if status == "queued" || status == "running" {
_, err = tx.ExecContext(r.Context(), `UPDATE canvas_ai_runs SET status='cancelled',cancel_requested=true,completed_at=now() WHERE project=$1 AND workspace_id=$2 AND id=$3`, project, workspace, id)
if err != nil {
@@ -170,6 +174,7 @@ func (s *service) cancelCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err != nil {
return err
}
// 回执分别列出此前已经应用的版本与本次/既有取消步骤,避免把取消误解为撤销所有已生效结果。
applied, cancelledSteps := []any{}, []any{}
for rows.Next() {
var step, board, node, state string
+4
View File
@@ -1,3 +1,4 @@
// 节点 AI 配置结构校验与目标内容指纹,供快照保存、计划冻结和异步写回共享。
package platform
import (
@@ -5,6 +6,7 @@ import (
"strings"
)
// validCanvasAI 限定可生成节点类型及 AI 字段形状;这里只校验参数 JSON 预算,模型目录和参数支持另查。
func validCanvasAI(value any, kind string) bool {
if !canvasChoice(kind, "text", "script", "plain-text", "image", "plain-image") {
return false
@@ -46,6 +48,8 @@ func validCanvasAI(value any, kind string) bool {
// after a concurrent drag. The board is the immutable plan origin, not the
// current canonical owner; canonical target identity is checked separately.
// Content/configuration edits invalidate the result.
// canvasTargetFingerprint 绑定计划来源 board/node、内容与 AI 配置,故意忽略几何/样式以允许生成期间拖动。
// Canonical owner 迁移用稳定身份单独校验,不能把当前位置代入原计划 board 重新计算。
func canvasTargetFingerprint(board, node string, data map[string]any) string {
target := map[string]any{"board_id": board, "node_id": node, "kind": data["kind"], "ai": data["ai"]}
if canvasChoice(data["kind"], "image", "plain-image") {
@@ -1,3 +1,4 @@
// 用户确认应用冲突生成输出:不重新生成,只在当前目标代数、位置和版本均确认后写入已存结果。
package platform
import (
@@ -7,6 +8,7 @@ import (
"unicode/utf8"
)
// applyCanvasAIOutput 要求 conflict、尚未应用且 run 未取消;v2 显式绑定目标画布/incarnation 和逻辑操作身份。
func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -96,6 +98,7 @@ func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, pr
if err != sql.ErrNoRows {
return err
}
// 输出必须属于该 run 并与请求 node 匹配,不能拿另一输出 ID 或已应用结果重复写入。
var stepID, targetBoard, node, status string
var outputRaw, frozenRaw json.RawMessage
var applied sql.NullInt64
@@ -125,6 +128,7 @@ func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, pr
if canonical && (frozen.TargetIncarnation != input.TargetIncarnation || frozen.CanonicalRoot == "") {
return rejectRequest(409, "target_changed")
}
// 生成后 owner 可能改变,使用权威身份重新解析;请求确认的 TargetCanvasID 必须仍是当前位置。
targetBoard, identityOK, err := resolveCanvasAITarget(r.Context(), tx, project, workspace, frozen)
if err != nil {
return err
@@ -149,6 +153,7 @@ func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, pr
if snapshot.Version != expected {
return rejectRequest(412, "version_conflict")
}
// 显式应用允许覆盖已编辑的内容,但仍检查输出模态、字节/字符预算及图片当前可读性。
patch := response{}
switch output.Kind {
case "text":
@@ -190,6 +195,7 @@ func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, pr
if target["kind"] != frozen.Kind {
return rejectRequest(409, "ownership_conflict")
}
// 通过共享窄字段 patch 保存,原几何和未知元数据不被旧输出快照回滚;应用版本与事件/回执同事务提交。
change, err := prepareCanvasAIPatch(r, tx, project, workspace, snapshot, node, patch)
if err != nil {
return rejectRequest(413, "canvas_too_large")
@@ -1,3 +1,4 @@
// 图片输入冻结与执行前装载:远程引用转为私有不可变资产,实际执行再次校验目标及资产权限。
package platform
import (
@@ -18,6 +19,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// canvasPublicIP 排除本地/私有/链路/保留测试网和已列元数据地址,IPv4 映射先 Unmap 再检查。
func canvasPublicIP(ip netip.Addr) bool {
ip = ip.Unmap()
if !ip.IsValid() || !ip.IsGlobalUnicast() || ip.IsPrivate() || ip.IsLoopback() || ip.IsLinkLocalUnicast() {
@@ -30,10 +32,15 @@ func canvasPublicIP(ip netip.Addr) bool {
}
return true
}
// canvasImageURL 仅允许短 HTTPS URL 且无用户信息,具体 DNS/IP 约束由 fetchCanvasImage 执行。
func canvasImageURL(raw string) bool {
u, err := url.Parse(raw)
return err == nil && u.Scheme == "https" && u.Hostname() != "" && u.User == nil && len(raw) < 2048
}
// fetchCanvasImage 每次连接解析并校验完整 DNS 结果,再直连已验证字面 IP,避免二次解析重绑定。
// 重定向仍需 HTTPS 且每次重新验证目标,响应字节和请求时间都有上限。
func fetchCanvasImage(ctx context.Context, src string) ([]byte, error) {
if !canvasImageURL(src) {
return nil, errors.New("invalid_image_input")
@@ -92,6 +99,8 @@ func fetchCanvasImage(ctx context.Context, src string) ([]byte, error) {
}
return data, nil
}
// freezeCanvasImage 已托管图片只重查可读性并保存 assetId;data/远程图完整检查后写不可变资产及来源画布绑定。
func (s *service) freezeCanvasImage(ctx context.Context, tx *sql.Tx, project, workspace, board, account string, content map[string]any) (map[string]any, error) {
id, _ := content["assetId"].(string)
src, _ := content["src"].(string)
@@ -141,6 +150,9 @@ func (s *service) freezeCanvasImage(ctx context.Context, tx *sql.Tx, project, wo
}
return map[string]any{"assetId": id}, nil
}
// hydrateCanvasTask 汇集自身冻结图、静态前驱和本轮前驱输出资产,去重后加载原图到私有 IPC task。
// 执行前重新解析 canonical owner/代数并核对编辑及资产权限,最多四图和二十 MiB。
func (s *service) hydrateCanvasTask(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, results map[string]canvasStepResult, task *codex.CanvasTask) error {
ids := []string{}
if id, _ := step.FrozenContent["assetId"].(string); id != "" {
@@ -1,3 +1,4 @@
// 图片抓取网络约束回归:直接检查地址分类和 URL 格式,并实际拒绝回环目标,不访问公网图片。
package platform
import (
@@ -7,6 +8,7 @@ import (
"time"
)
// TestCanvasImageFetchRejectsPrivateAndMetadataNetworks 覆盖私有/映射 IPv4/元数据/保留网段,确认公网样本分类可接受及非 HTTPS/带凭据 URL 被拒。
func TestCanvasImageFetchRejectsPrivateAndMetadataNetworks(t *testing.T) {
for _, raw := range []string{"127.0.0.1", "10.0.0.1", "169.254.169.254", "172.16.0.1", "192.168.1.1", "100.100.100.200", "168.63.129.16", "0.0.0.1", "198.18.0.1", "224.0.0.1", "255.255.255.255", "::1", "::ffff:127.0.0.1", "fe80::1", "fc00::1", "2001:db8::1"} {
if canvasPublicIP(netip.MustParseAddr(raw)) {
+6
View File
@@ -1,3 +1,4 @@
// AI 图片输出持久化与模型输入/输出模态能力检查。
package platform
import (
@@ -10,6 +11,8 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// persistCanvasImage 完整解码 worker 图片并核对 MIME,以 outputID 作为幂等键存原图。
// 先绑定 run 来源素材,使冲突输出在用户显式应用前仍能按原 run 权限读取。
func (s *service) persistCanvasImage(ctx context.Context, tx *sql.Tx, run canvasQueueRun, outputID string, image *codex.CanvasImage) (response, error) {
if image == nil || len(image.Data) == 0 || len(image.Data) > assetLimit {
return nil, errors.New("invalid_image_output")
@@ -32,6 +35,8 @@ func (s *service) persistCanvasImage(ctx context.Context, tx *sql.Tx, run canvas
}
return response{"output_id": outputID, "kind": "image", "assetId": id, "src": s.assetURL(run.Project, run.Workspace, id), "mime_type": mime, "bytes": len(image.Data), "width": width, "height": height}, nil
}
// canvasModelSupports 检查输出模态;支持图片输入并不意味着可生成图片。
func canvasModelSupports(model codex.CanvasModel, modality string) bool {
for _, value := range model.OutputModalities {
if value == modality {
@@ -41,6 +46,7 @@ func canvasModelSupports(model codex.CanvasModel, modality string) bool {
return false
}
// canvasModelAccepts 检查输入模态,准入阶段据此拒绝给纯文本输入模型喂图。
func canvasModelAccepts(model codex.CanvasModel, modality string) bool {
for _, value := range model.InputModalities {
if value == modality {
@@ -1,3 +1,4 @@
// 旧快照 AI 生命周期数据库回归:需隔离 PLATFORM_TEST_DATABASE_URL,生成由 Unix 假 worker 固定,不调用真实模型。
package platform
import (
@@ -23,6 +24,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// TestCanvasAIJobLifecycle 通过真实准入/认领/写回验证几何并发、内容冲突、取消、租约恢复、图片和传播失败分支。
func TestCanvasAIJobLifecycle(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -78,6 +80,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if err := png.Encode(&pngOutput, image.NewRGBA(image.Rect(0, 0, 3, 2))); err != nil {
t.Fatal(err)
}
// hooks 在 worker 已接收任务但尚未返回时注入并发变更;busyNext/failNext 分别模拟未执行忙碌和生成失败。
var imageInputs atomic.Int32
var busyNext atomic.Bool
var failNext atomic.Bool
@@ -175,6 +178,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
t.Errorf("concurrent fixture edit: %v", err)
}
}
// 同键准入只建一个任务,生成中拖动 x 应被保留,结果只更新文本并在最新版本上加一。
first := start(1, 1)
retry := start(1, 1)
if first["run_id"] != retry["run_id"] || first["canvas_version"] != float64(2) {
@@ -193,6 +197,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
t.Fatal("result overwrote geometry/style or failed to update text")
}
firstPath := base + "/ai/runs/" + first["run_id"].(string)
// 以小事件页回放整个运行,检查 seq 严格单调且最终 run.completed 可恢复。
after := int64(0)
completed := false
for page := 0; page < 30; page++ {
@@ -218,6 +223,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if !completed {
t.Fatal("terminal event not replayable")
}
// 正文并发编辑产生 conflict,输出仍可查询;旧协议显式应用失败后允许按当前版本再试。
second := start(4, 3)
hooks <- func() { mutate("{nodes,0,data,text}", `"user edit"`) }
execute(second["run_id"].(string))
@@ -244,6 +250,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if calls.Load() != 2 {
t.Fatal("cancelled queued run invoked worker")
}
// 人工让运行租约过期,恢复流程必须标 execution_interrupted,不能再次调用未知是否执行的模型。
fourth := start(8, 7)
run, err := s.claimCanvasRun(ctx)
if err != nil || run == nil || run.ID != fourth["run_id"] {
@@ -262,6 +269,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if recovered["status"] != "failed" || recovered["error"] != "execution_interrupted" || calls.Load() != 2 {
t.Fatal("uncertain execution was retried or misreported")
}
// 删除再创建同名节点不能使旧 running 步复活,迟到输出必须保持 cancelled。
fifth := start(9, 8)
removedRun, err := s.claimCanvasRun(ctx)
if err != nil || removedRun == nil || removedRun.ID != fifth["run_id"] {
@@ -299,6 +307,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if len(active["runs"].([]any)) != 0 {
t.Fatal("terminal jobs returned as active")
}
// 图片输入先冻结为资产再装载,结果也存托管资产;节点原显示尺寸和可授权下载的原图都需保留。
imageDoc := call("GET", base, nil, 200, 0, "")["document"].(map[string]any)
imageDoc["nodes"] = append(imageDoc["nodes"].([]any), response{"id": "image-node", "type": "plainImage", "position": response{"x": 40, "y": 50}, "width": 240, "height": 160, "data": response{"kind": "plain-image", "title": "Image", "text": "", "src": "data:image/png;base64," + base64.StdEncoding.EncodeToString(pngOutput.Bytes())}})
call("PATCH", base, response{"document": imageDoc}, 200, 12, "")
@@ -336,6 +345,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
t.Fatal("image inputs were not frozen/hydrated through authorized assets")
}
// 首前驱成功后让下游收到 codex_busy,只回队下游;恢复不重复上游付费调用或版本推进。
chainDoc := call("GET", base, nil, 200, 0, "")["document"].(map[string]any)
chainDoc["nodes"].([]any)[1].(map[string]any)["data"].(map[string]any)["ai"] = response{"enabled": true, "modelId": "fixture-model", "prompt": "Use upstream result", "parameters": response{}}
call("PATCH", base, response{"document": chainDoc}, 200, 18, "")
@@ -366,6 +376,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
}
// Cancellation after worker admission must reject an otherwise successful late output.
// 生成中通过真实取消接口结束 run,随后即使假 worker 返回成功也不能再写回。
cancelRunning := start(22, 13)
cancelRunningPath := base + "/ai/runs/" + cancelRunning["run_id"].(string)
hooks <- func() {
@@ -377,6 +388,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
}
// Permission is checked again inside the final write transaction.
// 生成返回前删除成员权限,最终事务重查应拒绝输出应用;恢复权限仅为读取测试结果。
revoked := start(23, 15)
hooks <- func() {
if _, err := db.ExecContext(ctx, `DELETE FROM workspace_members WHERE project=$1 AND workspace_id=$2 AND account_id=$3`, project, workspace, account); err != nil {
@@ -393,6 +405,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
}
// A failed branch stops its dependents while its independent sibling finishes.
// 一支失败只跳过依赖者,独立兄弟仍可成功,run 汇总为 partially_succeeded。
branchSnapshot := aiPlanFixture([][2]string{{"a", "b"}, {"a", "c"}, {"b", "d"}}, nil, "")["board"]
var branchDoc any
if err := json.Unmarshal(branchSnapshot.Document, &branchDoc); err != nil {
@@ -412,6 +425,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
t.Fatalf("partial failure lost independent branch: %+v %v", states, branchResult["status"])
}
// 含回边的图可以存储,但执行准入必须识别环,既不调用 worker 也不推进配置版本。
cyclic := call("GET", base, nil, 200, 0, "")
cyclicVersion := int64(cyclic["version"].(float64))
cyclicDoc := cyclic["document"].(map[string]any)
@@ -1,3 +1,4 @@
// 旧快照语义的 AI 生命周期失效,与节点删除/种类变化或子图关系更新处于同一事务。
package platform
import (
@@ -9,6 +10,8 @@ import (
// Deletion or kind/ownership changes revoke active steps in the same snapshot
// transaction. Recreating an identical node ID later cannot revive that step.
// invalidateCanvasAITargets 找出从本 board 消失或种类变化的节点,取消对应 queued/running 步骤并写事件。
// 仅视觉/正文编辑不在此取消,执行/写回时再由内容指纹检测冲突。
func invalidateCanvasAITargets(r *http.Request, tx *sql.Tx, project, workspace, board string, before, after json.RawMessage) error {
old, next := canvasNodeData(before), canvasNodeData(after)
removed := []string{}
@@ -71,6 +74,7 @@ func invalidateCanvasAITargets(r *http.Request, tx *sql.Tx, project, workspace,
return nil
}
// invalidateCanvasAISubtree 收集活跃后代并逐张模拟清空节点,使关系变更涉及的旧树任务失效;不删除实际文档。
func invalidateCanvasAISubtree(r *http.Request, tx *sql.Tx, project, workspace, child string) error {
rows, err := tx.QueryContext(r.Context(), `WITH RECURSIVE descendants(id,depth) AS(SELECT $3::uuid,0 UNION ALL SELECT s.child_board_id,d.depth+1 FROM descendants d JOIN canvas_subgraphs s ON s.project=$1 AND s.workspace_id=$2 AND s.parent_board_id=d.id AND s.archived_at IS NULL WHERE d.depth<8) SELECT m.id::text,COALESCE(m.canvas_document,'{"nodes":[]}'::jsonb) FROM descendants d JOIN materials m ON m.project=$1 AND m.workspace_id=$2 AND m.id=d.id ORDER BY m.id`, project, workspace, child)
if err != nil {
+4
View File
@@ -1,3 +1,4 @@
// AI run 列表使用创建时间/UUID 的复合游标,支持状态和活跃子图范围筛选。
package platform
import (
@@ -9,11 +10,13 @@ import (
"time"
)
// canvasRunCursor 用时间加 ID 处理同一时间创建的 run,不依赖不稳定的 OFFSET。
type canvasRunCursor struct {
Time time.Time `json:"created_at"`
ID string `json:"id"`
}
// listCanvasAIRuns 先查范围候选,再核对各 run 来源画布的可见性;返回列表不含冻结提示或原始输出文本。
func (s *service) listCanvasAIRuns(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -88,6 +91,7 @@ func (s *service) listCanvasAIRuns(w http.ResponseWriter, r *http.Request, proje
if err != nil {
return err
}
// SQL 多取一条判断后页;权限过滤可能使公开本页少于 limit,游标仍按扫描到的候选末尾前进。
hasMore := len(candidates) > limit
if hasMore {
candidates = candidates[:limit]
+25
View File
@@ -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 {
@@ -1,3 +1,4 @@
// Canonical AI 数据库集成回归:Unix 假 worker 只固定生成传输,权威模型、生命周期与回执均走真实事务。
package platform
import (
@@ -24,6 +25,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// TestCanonicalAIAdmissionAndLifecycle 需隔离 PLATFORM_TEST_DATABASE_URL,覆盖 owner 迁移、代数失效及 v2 确定拒绝恢复。
func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -75,6 +77,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if err = png.Encode(&pngBytes, image.NewRGBA(image.Rect(0, 0, 3, 2))); err != nil {
t.Fatal(err)
}
// worker 入口执行一次 hook,可精确在模型返回前注入内容、身份或所有权变化。
hooks := make(chan func(), 1)
var executions atomic.Int32
worker := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -156,6 +159,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
}
return model
}
// mutate 在持锁事务中改权威模型并同步投影,用于模拟其他客户端编辑,不绕过模型完整性校验。
mutate := func(edit func(*canvasModel)) {
t.Helper()
tx, e := db.BeginTx(ctx, nil)
@@ -214,6 +218,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
model.Elements["future"]["dataVersion"] = float64(12)
})
next := 6100
// 每次创建不同 request/operation ID,Expected 取全部活跃画布版本,排除已归档 scope。
command := func(board, target, model string, incarnation int64) (response, string) {
next += 2
key := modelTestID(next)
@@ -227,6 +232,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
}(), "node_id": target, "model_id": model, "prompt": "Generate", "parameters": response{}, "propagate": false}, key
}
start := func(board, target, model string, incarnation int64) response {
// 准入原响应可按相同键重放和查询;改 If-Match 或换键复用已准入逻辑操作必须拒绝。
input, key := command(board, target, model, incarnation)
return call("POST", base(board)+"/ai/runs", input, 202, read().Versions[board], key)
}
@@ -272,6 +278,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
t.Fatal("AI lost canonical fields, geometry or future records")
}
// A content conflict retains its output; explicit application is still a narrow canonical write.
// 内容冲突保留输出,显式应用仍是窄字段写;同键重放保留原模型/版本且可查询回执。
conflictRun := start(root, node, "text", 1)
hooks <- func() {
mutate(func(model *canvasModel) { model.Elements[node]["data"].(map[string]any)["text"] = "user edit" })
@@ -297,6 +304,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
}
call("POST", conflictPath+"/apply", applyInput, 409, expected+1, applyKey)
// Keep one unapplied old output, then replace the target incarnation atomically.
// 保存旧输出并让另一运行开始后升级 incarnation,旧完成回调与旧输出显式应用都不能冒领新一代。
stale := start(root, node, "text", 1)
hooks <- func() {
mutate(func(model *canvasModel) { model.Elements[node]["data"].(map[string]any)["text"] = "keep this" })
@@ -352,6 +360,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
t.Fatal("duplicate/cancelled/old execution called the model")
}
// Image output resolves a managed resource while retaining the element envelope.
// canonical 大几何与未知字段不受 legacy 限制回滚,图片输出成为可按权限下载的托管资产。
imageID := modelTestID(6300)
mutate(func(model *canvasModel) {
record := modelTestNode(imageID, root)
@@ -382,6 +391,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if ok, e := s.startCanvasStep(ctx, *moving, moving.Plan.Steps[0]); e != nil || !ok {
t.Fatalf("start move %v", e)
}
// 运行中把目标换 owner,新 owner 准入仍应识别 node_busy;原任务成功只推进当前位置版本。
child, frame := modelTestID(6301), modelTestID(6302)
mutate(func(model *canvasModel) {
entry := modelTestNode(frame, root)
@@ -419,6 +429,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if e = s.completeCanvasRun(ctx, *moving, nil); e != nil {
t.Fatal(e)
}
// 即使目标版本当前,祖先 read-set 陈旧也必须零效果拒绝;环境变化后原拒绝键不能重算。
staleInput, staleKey := command(child, imageID, "image", 1)
staleVersions := staleInput["expected_versions"].(map[string]int64)
staleVersions[root]-- // The target version is current; its ancestor context is not.
@@ -447,6 +458,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
delete(missingInput, "expected_versions")
call("POST", base(child)+"/ai/runs", missingInput, 400, read().Versions[child], missingKey)
// An explicit replan can reuse a logical operation after its known zero-effect rejection.
// 已知零效果允许显式新键重计划并复用逻辑操作;完成后再取消不得假装撤销成功结果。
replanned := response{}
for key, value := range staleInput {
replanned[key] = value
@@ -465,6 +477,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if read().Elements[imageID]["ownerCanvasId"] != child {
t.Fatal("child result moved its target back")
}
// 排队期间换 owner 并归档原分区,run 的原 URL 仍可读取/取消,执行写入当前根 owner。
queuedMove := start(child, imageID, "image", 1)
mutate(func(model *canvasModel) {
model.Elements[imageID]["ownerCanvasId"] = root
@@ -481,6 +494,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
t.Fatal("archived route lost cancellation identity")
}
// Content changes still conflict after a move; explicit application targets the current owner.
// 换 owner 同时改正文仍产生冲突;用户显式应用须确认当前 owner,不能写回冻结来源画布。
movedConflict := start(root, node, "text", 2)
hooks <- func() {
mutate(func(model *canvasModel) {
@@ -501,6 +515,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if movedApplied["board_id"] != child || movedApplied["origin_board_id"] != root || read().Elements[node]["ownerCanvasId"] != child {
t.Fatal("explicit application wrote to the frozen owner")
}
// 删除已移动目标并记录墓碑,应使原任务在调用 worker 之前取消。
doomed := start(child, node, "text", 2)
mutate(func(model *canvasModel) {
record := model.Elements[node]
@@ -522,6 +537,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
t.Fatal("deleting a moved target failed to revoke its old job")
}
// 换 owner 后把账户降为 viewer,执行前必须重新检查编辑资格且不增加模型调用次数。
revoked := start(root, imageID, "image", 1)
mutate(func(model *canvasModel) { model.Elements[imageID]["ownerCanvasId"] = child })
beforeRevoked := executions.Load()
@@ -1,3 +1,4 @@
// AI canonical 适配的纯回归:验证窄字段更新、未知组件保留和准入 read-set 版本,不运行真实生成。
package platform
import (
@@ -5,6 +6,7 @@ import (
"testing"
)
// TestCanonicalAIPatchPreservesOpaqueModelAndGeometry 检查大尺寸几何/未知 envelope 保留、输入不变,拒绝改 geometry、未知 dataVersion 和错误 owner。
func TestCanonicalAIPatchPreservesOpaqueModelAndGeometry(t *testing.T) {
before := modelTestDocument()
before.Elements["a"]["geometry"].(map[string]any)["width"] = float64(9000)
@@ -37,6 +39,7 @@ func TestCanonicalAIPatchPreservesOpaqueModelAndGeometry(t *testing.T) {
}
}
// TestCanonicalAIProjectionDoesNotExecuteFutureConnections 未来版本连接仍可保存在模型中,但不能被旧 AI 投影误当作可执行连线。
func TestCanonicalAIProjectionDoesNotExecuteFutureConnections(t *testing.T) {
model := modelTestDocument()
model.Elements["b"] = modelTestNode("b", modelRootID)
@@ -57,6 +60,8 @@ func TestCanonicalAIProjectionDoesNotExecuteFutureConnections(t *testing.T) {
}
}
// TestCanonicalAIAdmissionVersions 验证 Expected 精确覆盖活跃画布而排除归档版本,缺项/错头与陈旧版本使用不同错误码。
// 该用例仅测版本函数,构造模型并不满足完整树校验。
func TestCanonicalAIAdmissionVersions(t *testing.T) {
model := modelTestDocument()
model.Canvases[modelChildID] = modelCanvas{ID: modelChildID}
+5
View File
@@ -1,3 +1,4 @@
// 画布可用模型目录与保存时配置验证,模型能力来源是私有 worker 过滤后的目录。
package platform
import (
@@ -9,6 +10,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// canvasAIModels 要求 board 可读;worker 不可用时返回空目录及原因,不把基础能力发现变成请求失败。
func (s *service) canvasAIModels(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -47,6 +49,9 @@ func (s *service) canvasAIModels(w http.ResponseWriter, r *http.Request, project
reply(w, 200, response{"models": models, "image_generation": capability})
return nil
}
// validateCanvasAIModels 无 AI 配置则不访问 worker;存在配置时验证模型可用且参数对象为空。
// 禁用配置可不填模型 ID,但填入 ID 仍需有效;失败已经写响应,调用者应退出并回滚。
func (s *service) validateCanvasAIModels(w http.ResponseWriter, r *http.Request, raw json.RawMessage) bool {
data := canvasNodeData(raw)
configured := []map[string]any{}
+16
View File
@@ -1,3 +1,4 @@
// AI 执行计划的纯规划器:解析真实端点、选择传播范围、冻结静态内容并按依赖拓扑排序。
package platform
import (
@@ -7,6 +8,7 @@ import (
"strings"
)
// canvasAIStaticInput 保存不由本轮生成的输入内容及其逻辑边身份,后续编辑不会改变已经冻结的输入。
type canvasAIStaticInput struct {
EdgeID string `json:"logical_edge_id"`
BoardID string `json:"board_id"`
@@ -14,6 +16,8 @@ type canvasAIStaticInput struct {
Kind string `json:"kind"`
Content map[string]any `json:"content"`
}
// canvasAIStepPlan 固定来源、配置、内容指纹与依赖;canonical 根/incarnation 由准入阶段另行绑定。
type canvasAIStepPlan struct {
CanonicalRoot string `json:"canonical_root,omitempty"`
TargetIncarnation int64 `json:"target_incarnation,omitempty"`
@@ -30,19 +34,25 @@ type canvasAIStepPlan struct {
Status string `json:"status"`
Dependencies []string `json:"dependencies"`
}
// canvasAIEdgePlan 的 ID 由拥有者画布/边 ID 组成,端点是解析后的真实步骤复合 ID。
type canvasAIEdgePlan struct {
ID string `json:"logical_edge_id"`
Source string `json:"source_step_id"`
Target string `json:"target_step_id"`
}
// canvasAIPlan 是可持久化的确定执行输入,Versions 标明规划时读取的所有快照版本。
type canvasAIPlan struct {
Steps []canvasAIStepPlan `json:"steps"`
Edges []canvasAIEdgePlan `json:"edges"`
Versions map[string]int64 `json:"frozen_versions"`
}
// canvasNodeKey 在旧画布局部 ID 域内组合唯一键,canonical 元素仍保留原计划来源作为步骤身份。
func canvasNodeKey(board, node string) string { return board + "/" + node }
// buildCanvasAIPlan 只操作传入快照,不访问数据库;最多选择 64 步,拓扑最长路径不得超过 32。
func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string, propagate bool) (canvasAIPlan, error) {
plan := canvasAIPlan{Steps: []canvasAIStepPlan{}, Edges: []canvasAIEdgePlan{}, Versions: map[string]int64{}}
data := map[string]map[string]any{}
@@ -53,6 +63,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
}
}
var resolve func(string, string, string, string, int) (string, error)
// frame 的连接必须经方向匹配端口下钻到真实节点,图标等不可执行节点不能成为输入/目标。
resolve = func(board, node, handle, direction string, depth int) (string, error) {
if depth > 8 {
return "", errors.New("graph_limit_exceeded")
@@ -119,6 +130,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
for key := range outgoing {
sort.Slice(outgoing[key], func(i, j int) bool { return outgoing[key][i].ID < outgoing[key][j].ID })
}
// 根由显式请求执行;下游未启用 AI 或没有模型则记录 skipped 并停止从该节点继续传播。
selected := map[string]bool{}
skipped := map[string]bool{}
queue := []string{root}
@@ -149,6 +161,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
}
}
// Kahn's algorithm waits for every participating predecessor at a diamond.
// Kahn 入度等待所有参与前驱,菱形汇合只能在两支都处理完后出队,不能按首次访问就执行。
indegree := map[string]int{}
incoming := map[string][]string{}
depths := map[string]int{}
@@ -177,6 +190,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
content := canvasFrozenContent(d)
static := []canvasAIStaticInput{}
sort.Slice(allIncoming[id], func(i, j int) bool { return allIncoming[id][i].ID < allIncoming[id][j].ID })
// 本轮将生成的有效前驱作为动态依赖,其余入边内容冻结为静态输入,包括传播关闭时的前驱。
for _, edge := range allIncoming[id] {
if propagate && selected[edge.Source] && !skipped[edge.Source] {
continue
@@ -209,6 +223,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
}
}
}
// 有入度永远无法归零的已选节点表示执行环,拒绝整个计划而不是执行可排序前缀。
if len(plan.Steps) != len(selected) {
return plan, errors.New("execution_cycle")
}
@@ -216,6 +231,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
return plan, nil
}
// canvasFrozenContent 只捕获语义输入:图片为引用身份,文本为正文,不含位置和纯展示样式。
func canvasFrozenContent(data map[string]any) map[string]any {
if canvasChoice(data["kind"], "image", "plain-image") {
return map[string]any{"src": data["src"], "assetId": data["assetId"]}
+10
View File
@@ -1,3 +1,4 @@
// AI 规划纯算法回归,覆盖传播范围、拓扑汇合、内容冻结与嵌套端口解析,不调用真实模型。
package platform
import (
@@ -6,6 +7,7 @@ import (
"testing"
)
// aiPlanFixture 从边对建立节点与执行开关,可指定一个未配置 AI 的中间节点来验证传播停止。
func aiPlanFixture(edges [][2]string, disabled map[string]bool, unconfigured string) map[string]canvasSnapshot {
ids := map[string]bool{"a": true}
for _, e := range edges {
@@ -28,6 +30,8 @@ func aiPlanFixture(edges [][2]string, disabled map[string]bool, unconfigured str
raw, _ := json.Marshal(map[string]any{"schema_version": 2, "nodes": nodes, "edges": values, "viewport": map[string]any{"x": 0, "y": 0, "zoom": 1}})
return map[string]canvasSnapshot{"board": {BoardID: "board", Version: 4, Document: raw}}
}
// TestAIPlanDiamondAndPropagationBoundaries 验证菱形末端只执行一次且等待两前驱,关闭传播/禁用边/无配置可截断遍历,环必须拒绝。
func TestAIPlanDiamondAndPropagationBoundaries(t *testing.T) {
graph := aiPlanFixture([][2]string{{"a", "b"}, {"a", "c"}, {"b", "d"}, {"c", "d"}}, nil, "")
plan, err := buildCanvasAIPlan(graph, "board", "a", true)
@@ -59,6 +63,9 @@ func TestAIPlanDiamondAndPropagationBoundaries(t *testing.T) {
t.Fatal("cycle accepted")
}
}
// TestAITargetFingerprintIgnoresVisualEdits 检查标题/样式不改指纹,正文或计划来源 board 改变则改指纹;JSON 键顺序不影响摘要。
// 同时覆盖超长提示和图标不允许 AI 配置,不把该用例视为 canonical owner 移动验证。
func TestAITargetFingerprintIgnoresVisualEdits(t *testing.T) {
data := map[string]any{"kind": "text", "text": "original", "title": "Title", "rotation": 0, "ai": map[string]any{"modelId": "fixture", "prompt": "prompt", "enabled": true}}
original := canvasTargetFingerprint("board", "node", data)
@@ -90,6 +97,7 @@ func TestAITargetFingerprintIgnoresVisualEdits(t *testing.T) {
}
}
// TestAIPlanFreezesAdditionalStaticInputs 从 x→a→b 的 a 启动,x 只作为冻结静态来源,不倒向执行;关闭传播仍保留输入。
func TestAIPlanFreezesAdditionalStaticInputs(t *testing.T) {
graph := aiPlanFixture([][2]string{{"x", "a"}, {"a", "b"}}, nil, "")
plan, err := buildCanvasAIPlan(graph, "board", "a", true)
@@ -111,6 +119,8 @@ func TestAIPlanFreezesAdditionalStaticInputs(t *testing.T) {
t.Fatal("static input not supplied to model")
}
}
// TestAIPlanLeavesChildThroughNestedPortChain 解析两层 frame port 到同一真实 deep 节点,边可有两条但目标步骤不重复,祖先版本也冻结。
func TestAIPlanLeavesChildThroughNestedPortChain(t *testing.T) {
raw := memberFixture(t)
child := "11111111-1111-4111-8111-111111111111"
+9
View File
@@ -1,3 +1,4 @@
// AI 运行详情、事件增量和准入回执查询;所有结果读取都重新检查当前资源权限。
package platform
import (
@@ -7,6 +8,7 @@ import (
"strconv"
)
// publicAIPlan 只公开计划结构、依赖及来源身份,静态输入标记 frozen_snapshot,不暴露冻结正文/图片。
func publicAIPlan(plan canvasAIPlan) response {
steps := []any{}
for _, step := range plan.Steps {
@@ -18,6 +20,8 @@ func publicAIPlan(plan canvasAIPlan) response {
}
return response{"steps": steps, "edges": plan.Edges, "frozen_versions": plan.Versions}
}
// getCanvasAIRun 按 after_seq 增量返回事件,查询步骤前按 canonical 稳定身份解析当前目标并检查权限。
func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -66,6 +70,7 @@ func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project
if err = json.Unmarshal(rawPlan, &plan); err != nil {
return err
}
// 目标可能已换 owner;解析失败退回计划来源做路由授权,避免查询绕过撤权或归档约束。
checked := map[string]bool{board: true}
for _, step := range plan.Steps {
target, ok, e := resolveCanvasAITarget(r.Context(), tx, project, workspace, step)
@@ -82,6 +87,7 @@ func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project
checked[target] = true
}
}
// 步骤输出剔除 text,仅返回元信息和可应用版本;AppliedBoard 反映实际写回位置而非原计划位置。
rows, err := tx.QueryContext(r.Context(), `SELECT id,COALESCE(applied_board_id,board_id)::text,node_id,status,error_code,applied_version,CASE WHEN output IS NULL THEN NULL ELSE output-'text' END FROM canvas_ai_steps WHERE project=$1 AND workspace_id=$2 AND run_id=$3 ORDER BY ordinal`, project, workspace, id)
if err != nil {
return err
@@ -134,6 +140,7 @@ func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project
rows.Close()
return err
}
// 事件页既限条数又限累计 data 字节;至少保留首事件,next_seq 仅推进到真正返回的最后事件。
if size+len(data) > 800<<10 && len(events) > 0 {
break
}
@@ -168,6 +175,8 @@ func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project
// Resolve admission by the original client key, before the caller knows a run ID.
// Absence is unknown, not a terminal proof that an earlier invocation had no effect.
// getCanvasAIAdmission 用原客户端键恢复准入结果,先查 v2 请求表,再兼容旧 run 的 create_response。
// 没有记录只说明 unknown,不构成确定零效果证明,客户端应保留原键继续恢复。
func (s *service) getCanvasAIAdmission(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
+16
View File
@@ -1,3 +1,4 @@
// 按执行相关边懒读取画布树,避免为一次 AI 操作扫描无关或无权限的子画布。
package platform
import (
@@ -8,6 +9,7 @@ import (
"strings"
)
// canvasAIReader 通过注入 Load/Parent 解耦数据库,缓存快照、解码文档和已知父关系,并记录实际用到的边。
type canvasAIReader struct {
Load func(string) (canvasSnapshot, error)
Parent func(string) (subgraphRelation, error)
@@ -18,6 +20,7 @@ type canvasAIReader struct {
used map[string]map[string]bool
}
// snapshot 每个 board 只加载/解码一次,返回同一捕获快照供本次计划复用。
func (reader *canvasAIReader) snapshot(board string) (canvasSnapshot, map[string]any, error) {
if snapshot, ok := reader.snapshots[board]; ok {
return snapshot, reader.documents[board], nil
@@ -34,6 +37,8 @@ func (reader *canvasAIReader) snapshot(board string) (canvasSnapshot, map[string
reader.documents[board] = doc
return snapshot, doc, nil
}
// parent 将无父行归一为空关系并缓存 parentKnown,避免根画布被反复查询。
func (reader *canvasAIReader) parent(board string) (subgraphRelation, error) {
if reader.parentKnown[board] {
return reader.parents[board], nil
@@ -50,6 +55,8 @@ func (reader *canvasAIReader) parent(board string) (subgraphRelation, error) {
reader.parents[board] = relation
return relation, nil
}
// node 返回已加载画布中的节点 data,缺失节点按所有权冲突处理,不凭同名跨画布寻找。
func (reader *canvasAIReader) node(board, node string) (map[string]any, error) {
_, doc, err := reader.snapshot(board)
if err != nil {
@@ -63,6 +70,8 @@ func (reader *canvasAIReader) node(board, node string) (map[string]any, error) {
}
return nil, errGraphOwnership
}
// resolve 按方向递归解开 frame port,并验证数据库父关系与文档 subgraph 相符,最多跨八层。
func (reader *canvasAIReader) resolve(board, node, handle, direction string, depth int) (string, error) {
if depth > 8 {
return "", errGraphCapacity
@@ -98,6 +107,7 @@ func (reader *canvasAIReader) resolve(board, node, handle, direction string, dep
// Follow only real edges and the port chains exposing this node. Empty or
// unrelated child boards are never traversed merely because their frame exists.
// edges 从真实节点沿其祖先暴露端口查入/出边;execution.enabled=false 的边不参与,结果按逻辑边 ID 去重排序。
func (reader *canvasAIReader) edges(board, node string, outgoing bool) ([]canvasAIEdgePlan, error) {
type exposure struct {
Board, Node, Handle string
@@ -161,6 +171,7 @@ func (reader *canvasAIReader) edges(board, node string, outgoing bool) ([]canvas
logical := canvasAIEdgePlan{ID: canvasNodeKey(current.Board, id), Source: source, Target: target}
found[logical.ID] = logical
}
// 向上只跟踪暴露当前节点/handle 的端口,不因看见其他 frame 就遍历其孩子。
relation, err := reader.parent(current.Board)
if err != nil {
return nil, err
@@ -194,6 +205,8 @@ func (reader *canvasAIReader) edges(board, node string, outgoing bool) ([]canvas
sort.Slice(result, func(i, j int) bool { return result[i].ID < result[j].ID })
return result, nil
}
// plan 每次重置缓存,收集根及可传播节点和其静态前驱,再把实际使用边交给纯拓扑规划器。
func (reader *canvasAIReader) plan(board, node string, propagate bool) (canvasAIPlan, error) {
reader.snapshots = map[string]canvasSnapshot{}
reader.documents = map[string]map[string]any{}
@@ -235,6 +248,7 @@ func (reader *canvasAIReader) plan(board, node string, propagate bool) (canvasAI
}
}
}
// 保留已读节点数据但裁去无关边,避免纯规划阶段解析未加载或无权限的邻接子图。
filtered := map[string]canvasSnapshot{}
for id, snapshot := range reader.snapshots {
doc := reader.documents[id]
@@ -255,6 +269,8 @@ func (reader *canvasAIReader) plan(board, node string, propagate bool) (canvasAI
}
return buildCanvasAIPlan(filtered, board, node, propagate)
}
// loadCanvasAIPlan 注入事务内权限检查与持锁快照读取;每个实际读取画布都要求编辑权限。
func loadCanvasAIPlan(r *http.Request, tx *sql.Tx, project, workspace, account string, parent canvasSnapshot, node string, propagate bool) (canvasAIPlan, error) {
reader := canvasAIReader{Load: func(board string) (canvasSnapshot, error) {
_, role, err := lockMaterial(r.Context(), tx, project, workspace, board, account)
@@ -1,3 +1,4 @@
// 懒读取回归通过注入快照计数 Load,证明范围选择没有隐式扫描无关子树。
package platform
import (
@@ -7,6 +8,7 @@ import (
"testing"
)
// readerFromSnapshots 从快照 subgraph 字段建立测试父关系,并给实际 Load 调用计数,不预填 reader 缓存。
func readerFromSnapshots(snapshots map[string]canvasSnapshot, loads map[string]int) *canvasAIReader {
parents := map[string]subgraphRelation{}
for board, snapshot := range snapshots {
@@ -32,6 +34,8 @@ func readerFromSnapshots(snapshots map[string]canvasSnapshot, loads map[string]i
return subgraphRelation{}, sql.ErrNoRows
}}
}
// TestAIReaderDoesNotLoadUnrelatedSubgraphs 在含 499 个无关 frame 的根上运行,传播开/关都只能加载根一次。
func TestAIReaderDoesNotLoadUnrelatedSubgraphs(t *testing.T) {
nodes := []any{map[string]any{"id": "a", "type": "material", "position": map[string]any{"x": 0, "y": 0}, "data": map[string]any{"kind": "text", "title": "A", "text": "input", "ai": map[string]any{"enabled": true, "modelId": "fixture", "prompt": "transform", "parameters": map[string]any{}}}}}
for i := 0; i < 499; i++ {
@@ -50,6 +54,8 @@ func TestAIReaderDoesNotLoadUnrelatedSubgraphs(t *testing.T) {
}
}
}
// TestAIReaderResolvesChildOutputAndFrozenPredecessor 从孩子 b 跨父端口传播到 outside,冻结 a 输入,同时不加载空兄弟子图。
func TestAIReaderResolvesChildOutputAndFrozenPredecessor(t *testing.T) {
raw := memberFixture(t)
child := "11111111-1111-4111-8111-111111111111"
+7
View File
@@ -1,3 +1,4 @@
// 可选真实模型回归:只有明确配置专用 worker socket 与隔离数据库才运行,会调用实际文本和图片生成。
package platform
import (
@@ -23,6 +24,8 @@ import (
// Opt in only on the confirmed remote runner with its dedicated CLI worker.
// Normal CI never invokes a paid/real model as a side effect of unit tests.
// TestCanvasAIRealWorker 选择配对文本/图片模型,走准入、认领、生成写回和授权下载,最后完整解码生成图片。
// 环境变量只是测试开关,执行前仍须确认专用远程 runner 和真实模型调用授权。
func TestCanvasAIRealWorker(t *testing.T) {
socket, dsn := os.Getenv("FOUNDRY_REAL_CODEX_SOCKET"), os.Getenv("PLATFORM_TEST_DATABASE_URL")
if socket == "" || dsn == "" {
@@ -34,6 +37,7 @@ func TestCanvasAIRealWorker(t *testing.T) {
if err != nil {
t.Fatal(err)
}
// 先选显式已验证图片输出条目,再按去掉 Image 后缀的标签寻找对应文本模型,缺能力直接失败。
var imageModel, textModel codex.CanvasModel
for _, model := range models {
if model.Available && canvasModelSupports(model, "image") {
@@ -119,6 +123,7 @@ func TestCanvasAIRealWorker(t *testing.T) {
}
return result
}
// 手动认领指定 run,避免后台轮询干扰;数据库必须隔离,否则最早队列任务可能不是本用例。
execute := func(id string) {
t.Helper()
run, err := s.claimCanvasRun(ctx)
@@ -132,6 +137,7 @@ func TestCanvasAIRealWorker(t *testing.T) {
t.Fatalf("real worker run %s: %s", result["status"], encoded)
}
}
// 文本用例只检查标记包含及原几何保留,不把模型自然语言差异当作精确输出契约。
textRun := call("POST", base+"/ai/runs", response{"node_id": "a", "model_id": textModel.ID, "prompt": "Return exactly the text CANVAS_V2_OK", "parameters": response{}, "propagate": false}, 202, 1, "20000000-0000-4000-8000-000000000001")
execute(textRun["run_id"].(string))
textSaved := call("GET", base, nil, 200, 0, "")
@@ -146,6 +152,7 @@ func TestCanvasAIRealWorker(t *testing.T) {
}
doc["nodes"] = append(doc["nodes"].([]any), response{"id": "real-image", "type": "plainImage", "position": response{"x": 40, "y": 50}, "width": 240, "height": 160, "data": response{"kind": "plain-image", "title": "Real image", "text": "", "src": "data:image/png;base64," + base64.StdEncoding.EncodeToString(input.Bytes())}})
call("PATCH", base, response{"document": doc}, 200, 3, "")
// 图片结果必须成为托管资产,保留节点显示尺寸;实际原图尺寸/格式由下载后的完整解码验证。
imageRun := call("POST", base+"/ai/runs", response{"node_id": "real-image", "model_id": imageModel.ID, "prompt": "Generate one image: a solid blue circle centered on a white square background, no text.", "parameters": response{}, "propagate": false}, 202, 4, "20000000-0000-4000-8000-000000000002")
execute(imageRun["run_id"].(string))
saved := call("GET", base, nil, 200, 0, "")
+11
View File
@@ -1,3 +1,4 @@
// AI 变更回执协议:在工作区锁内以 savepoint 隔离副作用,确定拒绝也冻结同一请求身份。
package platform
import (
@@ -6,6 +7,7 @@ import (
"net/http"
)
// canvasAIRequest 绑定请求键、逻辑操作、动作、来源画布和可选 run,Hash 固定原始有效载荷。
type canvasAIRequest struct {
Key, Hash, Action, Board, Run, Operation string
}
@@ -13,6 +15,8 @@ type canvasAIRequest struct {
// The workspace lock is acquired by the caller before this savepoint. Rejected
// requests roll back every staged effect and retain that lock while recording
// their zero-effect receipt, so a response can never race a second invocation.
// beginCanvasAIRequest 先重放同请求或拒绝身份复用,再查已应用逻辑操作,最后建立副作用 savepoint。
// 调用方必须先取得工作区锁;返回 true 表示已响应,nil request 兼容旧协议且不建立 savepoint。
func beginCanvasAIRequest(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account string, request *canvasAIRequest) (bool, error) {
if request == nil {
return false, nil
@@ -44,6 +48,8 @@ func beginCanvasAIRequest(w http.ResponseWriter, r *http.Request, tx *sql.Tx, pr
_, err = tx.ExecContext(r.Context(), `SAVEPOINT canvas_ai_effects`)
return false, err
}
// bindCanvasAIReceipt 将协议/请求/操作/动作身份写入公开回执,旧协议 nil request 不改响应。
func bindCanvasAIReceipt(body response, request *canvasAIRequest) {
if request == nil {
return
@@ -53,6 +59,8 @@ func bindCanvasAIReceipt(body response, request *canvasAIRequest) {
body["run_id"] = request.Run
}
}
// commitCanvasAIReceipt 把冻结结果与业务副作用一起提交;数据库提交成功后才确认给客户端。
func commitCanvasAIReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account string, request *canvasAIRequest, status int, outcome string, body response) error {
if request != nil {
bindCanvasAIReceipt(body, request)
@@ -71,6 +79,9 @@ func commitCanvasAIReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, p
reply(w, status, body)
return nil
}
// rejectCanvasAIRequest 回滚 savepoint 后的全部副作用,再保留工作区锁写 terminal not-applied 回执。
// 旧协议没有回执时只响应拒绝,由外层 defer 回滚整个事务。
func rejectCanvasAIRequest(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account string, request *canvasAIRequest, status int, code string) error {
if request == nil {
reject(w, status, code)
+4
View File
@@ -1,3 +1,4 @@
// 仅 worker 明确未开始执行的忙碌准入可持久回队;已完成步骤结果保留供恢复后继续。
package platform
import (
@@ -6,6 +7,7 @@ import (
"encoding/json"
)
// canvasRunResults 读取非 queued 终态与文本/资产输出;遇仍 running 步骤拒绝恢复,避免重复调用未定执行。
func (s *service) canvasRunResults(ctx context.Context, run canvasQueueRun) (map[string]canvasStepResult, error) {
rows, err := s.db.QueryContext(ctx, `SELECT id,status,output FROM canvas_ai_steps WHERE project=$1 AND workspace_id=$2 AND run_id=$3 ORDER BY ordinal`, run.Project, run.Workspace, run.ID)
if err != nil {
@@ -41,6 +43,8 @@ func (s *service) canvasRunResults(ctx context.Context, run canvasQueueRun) (map
// A 429 codex_busy response proves the worker did not invoke the CLI. Only this
// admission failure can return a step to the persistent queue for safe retry.
// requeueCanvasStep 核对当前 run 租约和取消位,将唯一 running 步退回 queued,并把 run 延迟五秒可认领。
// 返回 true 表示已提交回队,外层必须结束当前执行;旧结果和逻辑身份不会重建。
func (s *service) requeueCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan) (bool, error) {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
+13
View File
@@ -1,3 +1,4 @@
// AI run 准入入口:冻结依赖和输入、验证模型及队列预算,再原子保存配置、run、steps、事件和回执。
package platform
import (
@@ -15,6 +16,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// appendAIEvent 用单条 SQL 原子递增 run.last_seq 并插入事件,序号与业务状态一起提交。
func appendAIEvent(rctx context.Context, tx *sql.Tx, project, workspace, run, kind string, data any) error {
raw, err := json.Marshal(data)
if err != nil {
@@ -23,6 +25,8 @@ func appendAIEvent(rctx context.Context, tx *sql.Tx, project, workspace, run, ki
_, err = tx.ExecContext(rctx, `WITH next AS (UPDATE canvas_ai_runs SET last_seq=last_seq+1 WHERE project=$1 AND workspace_id=$2 AND id=$3 RETURNING last_seq) INSERT INTO canvas_ai_events(project,workspace_id,run_id,seq,type,data) SELECT $1,$2,$3,last_seq,$4,$5 FROM next`, project, workspace, run, kind, raw)
return err
}
// createCanvasAIRun 接受旧快照协议或 canonical v2;先按原请求身份恢复结果,后续确定拒绝可冻结零效果回执。
func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -76,6 +80,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
reject(w, 413, "context_too_large")
return nil
}
// v2 的 If-Match 也是不可变请求的一部分,不能只换版本头重用原始准入键。
hash := payloadDigest(input)
if input.ProtocolVersion != 0 {
// The version header is part of the immutable canonical admission request.
@@ -91,6 +96,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err != nil {
return err
}
// 只有完整 v2 请求身份才建立副作用 savepoint;旧请求沿用原 run.create_response 幂等路径。
var receipt *canvasAIRequest
if input.ProtocolVersion == 2 && input.RequestID == key && uuidSlugPattern.MatchString(input.OperationID) && input.TargetIncarnation > 0 {
receipt = &canvasAIRequest{Key: key, Hash: hash, Action: "run.start", Board: board, Operation: input.OperationID}
@@ -158,6 +164,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if !canvasChoice(target["kind"], "text", "script", "plain-text", "image", "plain-image") {
return rejectRequest(422, "model_incompatible")
}
// canonical 目标必须显式提供当前 incarnation,旧树请求不能夹带 canonical 字段越过迁移屏障。
root, incarnation, _, err := canvasAIIdentity(r.Context(), tx, project, workspace, board, input.NodeID)
if err != nil {
return err
@@ -172,6 +179,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
} else if input.ProtocolVersion != 0 || input.RequestID != "" || input.TargetIncarnation != 0 || input.OperationID != "" || input.ExpectedVersions != nil {
return rejectRequest(409, "canonical_migration_required")
}
// 先在内存准备目标 AI 配置;所有规划与预算检查通过后才随 run 一起落库,拒绝不能泄漏配置更新。
change, err := prepareCanvasAIPatch(r, tx, project, workspace, parent, input.NodeID, response{"ai": map[string]any{"enabled": true, "modelId": input.ModelID, "prompt": input.Prompt, "parameters": input.Parameters, "propagate": input.Propagate}})
if err != nil {
return rejectRequest(400, "invalid_ai_request")
@@ -207,12 +215,14 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err = bindCanvasAIIdentities(r.Context(), tx, project, workspace, &plan); err != nil {
return err
}
// 规划结果绑定稳定目标身份后,再验证每步输出模态和所有静态/动态图片来源是否被所选模型支持。
stepKinds := map[string]string{}
for _, step := range plan.Steps {
stepKinds[step.ID] = step.Kind
}
freezeCtx, stopFreeze := context.WithTimeout(r.Context(), 10*time.Second)
defer stopFreeze()
// 同一来源图片只冻结一次,十秒总上下文限制外部抓取;入队后不再依赖可变化远程 URL。
frozenImages := map[string]map[string]any{}
for index, step := range plan.Steps {
if step.Status == "skipped" {
@@ -292,6 +302,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if len(prompt)+len(text) > model.MaxInputBytes {
return rejectRequest(413, "context_too_large")
}
// canonical 忙碌检查按根/稳定 ID/incarnation,owner 移动不能绕过同一目标的在途任务约束。
var busy bool
if step.CanonicalRoot != "" {
err = tx.QueryRowContext(r.Context(), `SELECT EXISTS(SELECT 1 FROM canvas_ai_steps WHERE project=$1 AND workspace_id=$2 AND frozen_input->>'canonical_root'=$3 AND node_id=$4 AND frozen_input->>'target_incarnation'=$5::bigint::text AND status IN('queued','running'))`, project, workspace, step.CanonicalRoot, step.NodeID, step.TargetIncarnation).Scan(&busy)
@@ -306,6 +317,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
}
}
// A project-scoped advisory lock makes the queue limit atomic across workspaces.
// 项目级事务锁跨工作区串行化队列计数与插入,防止多个工作区同时越过 128 活跃 run 上限。
_, err = tx.ExecContext(r.Context(), `SELECT pg_advisory_xact_lock(hashtextextended($1,0))`, project+"/canvas-ai-queue")
if err != nil {
return err
@@ -343,6 +355,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err = appendAIEvent(r.Context(), tx, project, workspace, id, "run.queued", response{"status": "queued"}); err != nil {
return err
}
// 拓扑顺序作为 ordinal 持久化;skipped 步也保存状态和初始事件,使查询能解释未执行原因。
for ordinal, step := range plan.Steps {
frozen, _ := json.Marshal(step)
_, err = tx.ExecContext(r.Context(), `INSERT INTO canvas_ai_steps(project,workspace_id,run_id,id,board_id,node_id,ordinal,status,model_id,frozen_input,target_fingerprint) VALUES($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)`, project, workspace, id, step.ID, step.BoardID, step.NodeID, ordinal, step.Status, step.ModelID, frozen, step.Fingerprint)
+23
View File
@@ -1,3 +1,4 @@
// 持久 AI 队列:跨 Core 实例串行认领、租约恢复、按冻结拓扑执行,并把结果交事务写回器。
package platform
import (
@@ -12,15 +13,20 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// canvasQueueRun 保存本轮认领租约,后续状态写入必须匹配 Lease,旧执行者不能冒充新认领者。
type canvasQueueRun struct {
Project, Workspace, Board, ID, Account, Lease string
Plan canvasAIPlan
}
// canvasStepResult 在调度进程内保存终态及可传给后继的文本/资产 ID,Output 承载 worker 的结构化生成结果。
type canvasStepResult struct {
Status, Text, AssetID string
Output codex.CanvasOutput
}
// runCanvasQueue 每秒尝试取得专用连接的 session advisory lock,持锁期间最多执行一个完整 run。
// 此锁与事务锁不同,需在同一连接显式释放,再将连接归还池。
func (s *service) runCanvasQueue(ctx context.Context) {
ticker := time.NewTicker(time.Second)
defer ticker.Stop()
@@ -48,6 +54,8 @@ func (s *service) runCanvasQueue(ctx context.Context) {
conn.Close()
}
}
// claimCanvasRun 先恢复过期租约,再用 SKIP LOCKED 选最早可用 run,原子设 running、租约并记录事件。
func (s *service) claimCanvasRun(ctx context.Context) (*canvasQueueRun, error) {
if err := s.recoverCanvasRuns(ctx); err != nil {
return nil, err
@@ -81,6 +89,9 @@ func (s *service) claimCanvasRun(ctx context.Context) (*canvasQueueRun, error) {
}
return &run, nil
}
// recoverCanvasRuns 对已过期 running 租约逐个加锁重查,运行中步骤失败、未开始步骤跳过,不自动重付费执行。
// 已有成功步骤则 run 标为 partially_succeeded,否则 failed,并补齐终态事件。
func (s *service) recoverCanvasRuns(ctx context.Context) error {
rows, err := s.db.QueryContext(ctx, `SELECT project,workspace_id::text,id::text FROM canvas_ai_runs WHERE status='running' AND lease_until<now()`)
if err != nil {
@@ -188,6 +199,8 @@ func (s *service) recoverCanvasRuns(ctx context.Context) error {
}
return nil
}
// executeCanvasRun 复用持久终态结果,按计划拓扑顺序逐步执行;前驱非成功则跳过依赖步骤。
func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
results, err := s.canvasRunResults(ctx, run)
if err != nil {
@@ -224,6 +237,7 @@ func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
results[step.ID] = canvasStepResult{Status: status}
continue
}
// 先从冻结引用装入图片并重查权限,再将步骤从 queued 改为 running,之后才调用真实生成。
if err = s.hydrateCanvasTask(ctx, run, step, results, &task); err != nil {
code := "model_incompatible"
if err.Error() == "context_too_large" {
@@ -245,6 +259,7 @@ func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
continue
}
generated, generationErr := s.generateCanvasStep(ctx, run, step, task)
// 只有明确未进入 CLI 的忙碌结果可安全回队;网络超时/中断不证明没有执行,不能盲重试。
if generationErr != nil && generationErr.Error() == "codex_busy" {
requeued, e := s.requeueCanvasStep(ctx, run, step)
if e != nil || requeued {
@@ -270,6 +285,7 @@ func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
code = "generation_failed"
}
}
// 输出格式与文本预算检查后再持锁写回;返回状态决定后继能否消费本次输出。
status, err := s.finishCanvasStepOutput(ctx, run, step, generated, code, true)
if err != nil {
return
@@ -284,6 +300,8 @@ func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
}
_ = s.completeCanvasRun(ctx, run, results)
}
// assembleCanvasTask 按计划边顺序合并成功上游结果、静态输入和当前冻结内容,整体 JSON 与最终前缀提示都检查预算。
func assembleCanvasTask(plan canvasAIPlan, step canvasAIStepPlan, results map[string]canvasStepResult) (codex.CanvasTask, error) {
incoming := []any{}
for _, edge := range plan.Edges {
@@ -318,6 +336,8 @@ func assembleCanvasTask(plan canvasAIPlan, step canvasAIStepPlan, results map[st
}
return task, nil
}
// generateCanvasStep 限制模型调用时长,每秒心跳续租并确认 run/step 仍活跃;撤销或丢租约时取消 IPC。
func (s *service) generateCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, task codex.CanvasTask) (codex.CanvasOutput, error) {
duration := 90 * time.Second
if step.MaxExecutionMS > 0 && step.MaxExecutionMS <= 180000 {
@@ -325,6 +345,7 @@ func (s *service) generateCanvasStep(ctx context.Context, run canvasQueueRun, st
}
callCtx, cancel := context.WithTimeout(ctx, duration)
defer cancel()
// 缓冲一项保证主循环因取消提前返回后,调用 goroutine 仍能发送收尾结果而不永久阻塞。
done := make(chan canvasStepResult, 1)
go func() {
output, err := s.canvasAI.GenerateOutput(callCtx, task)
@@ -356,4 +377,6 @@ func (s *service) generateCanvasStep(ctx context.Context, run canvasQueueRun, st
}
}
}
// queueRequest 为共用 HTTP 风格数据库辅助函数创建仅含 context 的请求,不用于公开路由解析。
func queueRequest(ctx context.Context) *http.Request { return (&http.Request{}).WithContext(ctx) }
@@ -1,3 +1,4 @@
// 调度器任务组装纯回归,不启动队列、数据库或真实 CLI。
package platform
import (
@@ -5,6 +6,7 @@ import (
"testing"
)
// TestCanvasTaskUsesStableIncomingEdgeOrderAndFrozenContent 验证冻结正文与两条有序前驱输出进入提示,组装后超过上下文字节限额必须报错。
func TestCanvasTaskUsesStableIncomingEdgeOrderAndFrozenContent(t *testing.T) {
step := canvasAIStepPlan{ID: "board/d", ModelID: "fixture", Config: map[string]any{"prompt": "summarize", "parameters": map[string]any{}}, FrozenContent: map[string]any{"text": "original"}}
plan := canvasAIPlan{Edges: []canvasAIEdgePlan{{ID: "edge-a", Source: "board/b", Target: step.ID}, {ID: "edge-b", Source: "board/c", Target: step.ID}}}
+4
View File
@@ -1,3 +1,4 @@
// 画布能力发现:公布静态协议支持与运行时模型可用性,供无界面客户端选择可用命令。
package platform
import (
@@ -6,6 +7,7 @@ import (
"time"
)
// canvasCapabilities 先验证 board 可读,再释放工作区锁探测 worker,避免外部调用延长数据库锁。
func (s *service) canvasCapabilities(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -27,6 +29,7 @@ func (s *service) canvasCapabilities(w http.ResponseWriter, r *http.Request, pro
if err = tx.Rollback(); err != nil {
return err
}
// 模型探测最多五秒;失败仍返回能力契约,但将 AI 标为不可用并给出稳定原因。
ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
defer cancel()
models, modelErr := s.canvasAI.Models(ctx)
@@ -43,6 +46,7 @@ func (s *service) canvasCapabilities(w http.ResponseWriter, r *http.Request, pro
if modelErr != nil {
ai["unavailable_reason"] = "codex_unavailable"
}
// 协议版本、规模预算和回执期限应与服务实现同步;available 单独反映当前 AI 后端状态。
reply(w, 200, response{
"contract_version": "canvas-headless-2026-11-07",
"canonical_model": response{"document_format_version": canvasModelFormat, "protocol_version": canvasModelProtocol, "explicit_migration": true, "stable_element_ids": true, "atomic_multi_canvas": true, "logical_operation_dedup": true, "legacy_snapshot_writes": false},
+15
View File
@@ -1,3 +1,4 @@
// 跨子图连线事务:从真实端点向共同祖先暴露端口,并在祖先画布上保存唯一逻辑边。
package platform
import (
@@ -11,11 +12,14 @@ import (
)
// Endpoints name real nodes, never transient projected copies or client-created ports.
// canvasConnectionEndpoint 引用真实所有者画布中的节点,公开请求不能把投影副本或临时端口当真实节点。
type canvasConnectionEndpoint struct {
Board string `json:"board_id"`
Node string `json:"node_id"`
Handle string `json:"handle"`
}
// canvasConnectionInput 包含两端真实位置、边配置与完整参与画布版本表。
type canvasConnectionInput struct {
Source canvasConnectionEndpoint `json:"source"`
Target canvasConnectionEndpoint `json:"target"`
@@ -27,6 +31,7 @@ type canvasConnectionInput struct {
}
// Paths run from a leaf board upwards to (but excluding) the coordinator.
// connectionPath 从叶画布向协调者向上追溯,不含协调者本身;循环、过深、归档或断链都视为所有权冲突。
func connectionPath(r *http.Request, tx *sql.Tx, project, workspace, coordinator, board string) ([]subgraphRelation, error) {
path := []subgraphRelation{}
seen := map[string]bool{}
@@ -51,6 +56,7 @@ func connectionPath(r *http.Request, tx *sql.Tx, project, workspace, coordinator
return path, nil
}
// connectionNode 查找已校验节点数组中的对象,返回引用以便后续原地追加端口。
func connectionNode(doc map[string]any, id string) map[string]any {
for _, value := range doc["nodes"].([]any) {
node := value.(map[string]any)
@@ -63,6 +69,7 @@ func connectionNode(doc map[string]any, id string) map[string]any {
// Reuse ports by logical endpoint, including legacy ports with non-derived IDs.
// A derived ID collision must never retarget an existing port.
// connectionPort 先按逻辑端点复用旧端口,否则由方向/节点/handle 派生 ID;同 ID 异目标不能覆盖。
func connectionPort(data map[string]any, node, handle, direction string) (string, bool, error) {
ports, _ := data["ports"].([]any)
sum := sha256.Sum256([]byte(direction + "/" + node + "/" + handle))
@@ -85,6 +92,7 @@ func connectionPort(data map[string]any, node, handle, direction string) (string
return id, true, nil
}
// exposeConnectionEndpoint 逐层把真实端点转成父 frame 的 port 端点,返回祖先映射及实际新增端口清单。
func exposeConnectionEndpoint(endpoint canvasConnectionEndpoint, direction string, path []subgraphRelation, documents map[string]map[string]any) (canvasConnectionEndpoint, []any, error) {
node := connectionNode(documents[endpoint.Board], endpoint.Node)
if node == nil {
@@ -117,6 +125,7 @@ func exposeConnectionEndpoint(endpoint canvasConnectionEndpoint, direction strin
return endpoint, created, nil
}
// createCanvasConnection 校验 v2、幂等键与编辑权限后收集参与者;所有快照校验通过才开始持久化。
func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -176,6 +185,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
reject(w, 403, "forbidden")
return nil
}
// 在已授权且持锁后先重放相同请求回执,避免重试因版本已推进而误判冲突。
action, hash := "create_connection", payloadDigest(input)
done, err := transactionRetry(w, r, tx, project, account, coordinator, action, key, hash)
if err != nil || done {
@@ -211,6 +221,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
}
}
// Require the lowest common ancestor, so the logical edge has one owner.
// 两侧路径在协调者以下不得还有共同子画布,否则协调者不是最低共同祖先,边会放错所有者。
left := map[string]bool{}
for _, relation := range paths[0] {
left[relation.Child] = true
@@ -225,6 +236,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
for id := range participants {
ids = append(ids, id)
}
// 稳定排序参与者,生成可重复的版本要求、快照与事务记录。
sort.Strings(ids)
before := []canvasSnapshot{}
snapshots := map[string]canvasSnapshot{}
@@ -250,6 +262,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
}
documents[id] = doc
}
// 版本表必须恰好覆盖所有参与者,缺漏返回 required_board_ids,陈旧版本返回 412。
if len(input.Expected) != len(ids) {
reply(w, 428, response{"error": "version_required", "details": response{"required_board_ids": ids}})
return nil
@@ -293,6 +306,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
mapped = append(mapped, exposed)
created = append(created, ports...)
}
// 保存的是映射后祖先端点,但回执同时保留原始 source/target,供调用方恢复逻辑身份。
edge := map[string]any{"id": input.Edge.ID, "source": mapped[0].Node, "sourceHandle": mapped[0].Handle, "target": mapped[1].Node, "targetHandle": mapped[1].Handle}
if input.Edge.Data != nil {
edge["data"] = input.Edge.Data
@@ -336,6 +350,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
}
result := response{"transaction_id": id, "parent": snapshots[coordinator], "snapshots": updated, "connection": response{"board_id": coordinator, "edge": edge, "source": input.Source, "target": input.Target}, "created_ports": created, "undo_receipt": response{"transaction_id": id, "valid_for_seconds": 604800, "expires_at": expiry}}
encoded, _ := json.Marshal(result)
// before 快照和 after_versions 支持七天撤销;响应体与幂等摘要一同入库,提交后才对外确认。
prior, _ := json.Marshal(before)
after, _ := json.Marshal(versions)
_, err = tx.ExecContext(r.Context(), `INSERT INTO canvas_transactions(project,workspace_id,board_id,id,account_id,action,idempotency_key,payload_hash,response_status,response_body,before_state,after_versions) VALUES($1,$2,$3,$4,$5,$6,$7,$8,201,$9,$10,$11)`, project, workspace, coordinator, id, account, action, key, hash, encoded, prior, after)
@@ -1,3 +1,4 @@
// 跨画布连线数据库回归需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移测试库;未配置则跳过。
package platform
import (
@@ -17,6 +18,7 @@ import (
"testing"
)
// TestCanvasConnectionTransactions 在隔离 PostgreSQL 中走完整 HTTP 连线/撤销/重试链路,并验证拒绝请求与容量失败没有部分持久化。
func TestCanvasConnectionTransactions(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -69,6 +71,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
Register(mux, db, map[string]string{project: "https://app.example.com/auth/callback"}, "https://api.example.com", nil)
base := "/projects/" + project + "/workspaces/" + workspace + "/materials/"
path := func(board string) string { return base + board + "/canvas" }
// do 只组请求,call 再验证状态/解码;全部请求显式协商 v2,避免旧客户端丢失端口数据。
do := func(method, url, token string, body any, version int64, key string) *httptest.ResponseRecorder {
raw, _ := json.Marshal(body)
r := httptest.NewRequest(method, url, bytes.NewReader(raw))
@@ -97,6 +100,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
return out
}
key := func(n int) string { return fmt.Sprintf("a0000000-0000-4000-8000-%012d", n) }
// 每次从真实 GET 读取参与者当前版本,构造恰好覆盖端口链的 expected_versions。
versions := func(ids ...string) map[string]int64 {
t.Helper()
out := map[string]int64{}
@@ -128,6 +132,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
command := func(source, node, target, targetNode, id string, ids ...string) response {
return response{"source": response{"board_id": source, "node_id": node, "handle": "right"}, "target": response{"board_id": target, "node_id": targetNode, "handle": "left"}, "edge": response{"id": id, "data": response{"appearance": response{"color": "#123456", "width": 2}, "path": response{"type": "bezier-chain", "knots": []any{response{"id": "k", "position": response{"x": 200, "y": 300}, "in": response{"x": -20, "y": 0}, "out": response{"x": 20, "y": 0}, "mode": "symmetric"}}}}}, "expected_versions": versions(ids...)}
}
// 从嵌套叶节点连到根节点,需要中间与根两个端口;叶文档本身不得被投影逻辑改写。
firstBody := command(leaf, "deep", root, "a", "external", root, left, leaf)
beforeLeaf := call("GET", path(leaf), tokens[0], nil, 200, 0, "")["document"]
first := call("POST", path(root)+"/connections", tokens[0], firstBody, 201, 0, key(4))
@@ -152,6 +157,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
if len(parent["document"].(map[string]any)["edges"].([]any)) != 2 {
t.Fatal("existing edge lost")
}
// 撤销还原所有参与快照并移除新端口;再次执行应恢复同一稳定逻辑端点映射。
undo := call("POST", path(root)+"/transactions/"+first["transaction_id"].(string)+"/undo", tokens[0], response{"expected_versions": versions(root, left, leaf)}, 200, 0, key(5))
if len(undo["snapshots"].([]any)) != 3 {
t.Fatal("undo did not restore complete chain")
@@ -181,6 +187,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
t.Fatal("input chain reused output ports")
}
// Missing/stale participant versions, bad endpoints and permission failures are atomic.
// 收集拒绝前版本,随后缺版本、旧版本、非法端点及权限失败都必须保持整个向量不变。
stable := versions(root, left, leaf)
missing := command(leaf, "deep", root, "a", "missing", root, left)
required := call("POST", path(root)+"/connections", tokens[0], missing, 428, 0, key(10))
@@ -203,6 +210,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
t.Fatal("rejected transaction partially changed versions")
}
// The actual nested mapping is resolvable by the same reader used by AI propagation.
// 将真实保存的快照交给 AI reader,确认连接生成的端口链可解析回真实叶节点。
graph := map[string]canvasSnapshot{}
for _, board := range []string{root, left, leaf} {
read := call("GET", path(board), tokens[0], nil, 200, 0, "")
@@ -257,6 +265,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
t.Fatal("capabilities omitted connection transaction")
}
// Four simultaneous retries create exactly one edge/receipt and advance versions once.
// 四个同键请求同时放行,必须共用回执并让每个参与画布恰好递增一次。
concurrent := command(left, "l2", root, "a", "concurrent", root, left)
prior := versions(root, left)
start := make(chan struct{})
@@ -285,6 +294,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
}
}
// A full coordinator rejects the entire operation, including new leaf ports.
// 填满协调者边数再建新端口链,最终容量拒绝必须回滚叶端口、版本和事务记录。
snapshot := call("GET", path(root), tokens[0], nil, 200, 0, "")
doc := snapshot["document"].(map[string]any)
edges := []any{}
@@ -1,3 +1,4 @@
// 画布与资产纯函数回归;测试说明对应实际断言,不依赖浏览器或真实模型。
package platform
import (
@@ -6,6 +7,7 @@ import (
"testing"
)
// TestConnectionPortReuseCollisionAndCapacity 验证按逻辑端点复用历史 ID,输入输出分离,派生 ID 冲突不可换绑,容量耗尽也不部分改写端口表。
func TestConnectionPortReuseCollisionAndCapacity(t *testing.T) {
data := map[string]any{"ports": []any{map[string]any{"id": "custom-stable", "nodeId": "n", "handle": "left", "direction": "input"}}}
id, created, err := connectionPort(data, "n", "left", "input")
@@ -30,6 +32,7 @@ func TestConnectionPortReuseCollisionAndCapacity(t *testing.T) {
}
}
// TestConnectionExposureBuildsNestedDirectionChain 构造 leaf→middle→root 两层边界,检查逐层端口映射、同方向复用、反方向独立创建及叶节点文档不变。
func TestConnectionExposureBuildsNestedDirectionChain(t *testing.T) {
frame := func(child string) map[string]any {
return map[string]any{"id": "frame", "data": map[string]any{"kind": "frame", "subgraph": map[string]any{"boardId": child}, "ports": []any{}}}
@@ -1,3 +1,4 @@
// 可选端到端回归:在获授权远程环境使用真实 Endoleap Node runtime 对接 Foundry HTTP 和隔离数据库。
package platform
import (
@@ -19,6 +20,7 @@ import (
// Runs the real Endoleap runtime against authenticated Foundry HTTP and PostgreSQL.
// This opt-in is enabled by the existing remote schema runner, never local builds.
// TestHeadlessClientHTTPIntegration 需 FOUNDRY_HEADLESS_SOURCE 指向客户端源码;缺省跳过,显式开启却无隔离数据库则失败。
func TestHeadlessClientHTTPIntegration(t *testing.T) {
source, dsn := os.Getenv("FOUNDRY_HEADLESS_SOURCE"), os.Getenv("PLATFORM_TEST_DATABASE_URL")
if source == "" {
@@ -66,6 +68,7 @@ func TestHeadlessClientHTTPIntegration(t *testing.T) {
server := httptest.NewServer(mux)
defer server.Close()
// 子进程最多两分钟,环境传递临时项目/账户/会话;所有输出先替换 token 再报告。
commandContext, cancel := context.WithTimeout(ctx, 2*time.Minute)
defer cancel()
command := exec.CommandContext(commandContext, "node", filepath.Join(source, "tests/headless/foundry.integration.mjs"))
@@ -76,6 +79,7 @@ func TestHeadlessClientHTTPIntegration(t *testing.T) {
if err != nil {
t.Fatalf("headless HTTP client failed: %v\n%s", err, report)
}
// 仅退出零不够,报告必须声明 status ok 且 runtimeAI 实际执行过。
if !strings.Contains(report, `"status":"ok"`) || !strings.Contains(report, `"runtimeAI":true`) {
t.Fatalf("headless HTTP client did not return success: %s", report)
}
@@ -1,3 +1,4 @@
// Headless 测试专用 worker 适配:固定生成输出,但准入、认领、取消、事件和 canonical 落库仍走生产实现。
package platform
import (
@@ -20,8 +21,10 @@ import (
// Only the generation transport is deterministic. Admission, claims, events,
// canonical writes and action receipts use the real service and isolated DB.
// headlessWorkerRoutes 搭建 Unix 假 worker 与私有控制路由,返回给端到端客户端;不是生产服务注册入口。
func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string, project, account string) http.Handler {
t.Helper()
// gate 同步确认生成已进入并控制释放,sync.Once 防止并发控制重复 close 通道。
type gate struct {
entered, release chan struct{}
started, released sync.Once
@@ -80,6 +83,7 @@ func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string,
reply(w, 200, response{"result": "headless fixture output"})
}
})}
// 清理先释放正在阻塞的生成再关闭 server,避免用例失败后泄漏等待 goroutine。
go worker.Serve(listener)
t.Cleanup(func() {
mu.Lock()
@@ -89,6 +93,7 @@ func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string,
mu.Unlock()
worker.Close()
})
// 不启动周期队列,测试通过 execute 控制认领时刻,以稳定覆盖运行中目标移动/取消等竞态。
s := &service{db: db, origin: "https://api.example.com", canvasAI: codex.NewCanvasClient(socket)}
mux := http.NewServeMux()
prefix := "/projects/{project}/workspaces/{workspace}/materials/{material}/canvas/ai"
@@ -104,6 +109,7 @@ func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string,
reject(w, 403, "forbidden")
return nil
}
// arm/wait/release 管理传输门闩,execute 驱动一次真实队列认领,stats 暴露调用计数。
switch r.PathValue("action") {
case "arm":
mu.Lock()
@@ -143,6 +149,7 @@ func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string,
reply(w, 200, response{"executions": executions.Load()})
return nil
}))
// 其他平台请求走常规 Register;只有 AI 路径分流到可受测试精确控制的 service。
regular := http.NewServeMux()
Register(regular, db, callbacks, "https://api.example.com", nil)
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+5
View File
@@ -1,3 +1,4 @@
// 图规模预检与幂等键归一化,供多种画布 HTTP 命令共享。
package platform
import (
@@ -6,9 +7,13 @@ import (
"strings"
)
// canvasIdempotencyKey 统一 UUID 大小写,格式合法性由具体入口继续验证。
func canvasIdempotencyKey(r *http.Request) string {
return strings.ToLower(r.Header.Get("Idempotency-Key"))
}
// canvasExceededGraphLimits 只判断节点/边/knot 数量超限;坏 JSON 返回 false 交给完整校验报告 400。
// 与 normalizeCanvas 分离,使合法可解码但规模过大的请求能明确返回 413。
func canvasExceededGraphLimits(raw json.RawMessage) bool {
var doc struct {
Nodes []json.RawMessage `json:"nodes"`
+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
}
@@ -1,3 +1,4 @@
// Canonical 原子性数据库回归:需 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移测试库,未配置则跳过。
package platform
import (
@@ -16,6 +17,7 @@ import (
"time"
)
// canonicalAtomicFixture 持有随机项目、真实路由与源快照,所有请求共用有效账户和独立工作区。
type canonicalAtomicFixture struct {
db *sql.DB
mux *http.ServeMux
@@ -23,6 +25,7 @@ type canonicalAtomicFixture struct {
legacy json.RawMessage
}
// newCanonicalAtomicFixture 建账户/会话/admin/旧图,并按外键关系注册数据清理;不自动执行迁移脚本。
func newCanonicalAtomicFixture(t *testing.T) *canonicalAtomicFixture {
t.Helper()
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
@@ -68,10 +71,12 @@ func newCanonicalAtomicFixture(t *testing.T) *canonicalAtomicFixture {
return f
}
// path 返回本 fixture 根的 canonical 入口,避免测试错用旧快照路径。
func (f *canonicalAtomicFixture) path() string {
return "/projects/" + f.project + "/workspaces/" + f.workspace + "/materials/" + f.root + "/canvas/model"
}
// request 携带会话、预期账户及 v2 协商,并沿用传入 context 以测试数据库写入中途取消。
func (f *canonicalAtomicFixture) request(ctx context.Context, method, path, key string, raw []byte) *httptest.ResponseRecorder {
r := httptest.NewRequest(method, path, bytes.NewReader(raw)).WithContext(ctx)
r.Header.Set("Authorization", "Bearer "+f.token)
@@ -85,6 +90,7 @@ func (f *canonicalAtomicFixture) request(ctx context.Context, method, path, key
return w
}
// canonicalAtomicResponse 先断言实际 HTTP 状态,再解码响应,避免把错误 JSON 当作正常模型使用。
func canonicalAtomicResponse(t *testing.T, w *httptest.ResponseRecorder, status int) response {
t.Helper()
if w.Code != status {
@@ -97,6 +103,7 @@ func canonicalAtomicResponse(t *testing.T, w *httptest.ResponseRecorder, status
return body
}
// read 直接从权威模型表装配完整模型,检查 HTTP 应答外的持久化事实。
func (f *canonicalAtomicFixture) read(t *testing.T) canvasModel {
t.Helper()
tx, err := f.db.BeginTx(context.Background(), nil)
@@ -111,6 +118,7 @@ func (f *canonicalAtomicFixture) read(t *testing.T) canvasModel {
return model
}
// concurrent 同时放行多请求并按原索引收集,二十秒上下文限制等待,不以返回顺序猜赢家。
func (f *canonicalAtomicFixture) concurrent(t *testing.T, path string, keys []string, bodies [][]byte) []*httptest.ResponseRecorder {
t.Helper()
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
@@ -139,6 +147,8 @@ func (f *canonicalAtomicFixture) concurrent(t *testing.T, path string, keys []st
return out
}
// TestCanonicalConcurrentMigrationAndOwnershipWrites 验证同键迁移/编辑只执行一次,不同条件所有权写只有一个赢家。
// 成功和冲突都必须有可查询冻结回执,未涉及元素和树不得被部分改写。
func TestCanonicalConcurrentMigrationAndOwnershipWrites(t *testing.T) {
f := newCanonicalAtomicFixture(t)
ctx := context.Background()
@@ -176,6 +186,7 @@ func TestCanonicalConcurrentMigrationAndOwnershipWrites(t *testing.T) {
if before.Versions[child] != 2 || before.Versions[f.root] != 2 || modelString(before.Elements[ids["a"]]["data"].(map[string]any)["title"]) != "renamed" {
t.Fatal("concurrent edit executed more than once")
}
// 两请求共享同一版本向量,各移动不同节点但都移动其连接,验证条件写竞争而非简单串行重放。
var batches []modelBatch
var keys []string
var bodies [][]byte
@@ -223,6 +234,8 @@ func TestCanonicalConcurrentMigrationAndOwnershipWrites(t *testing.T) {
}
}
// TestCanonicalMigrationLateCancellationRollsBack 用独占表锁卡住后期身份映射 INSERT,观察确实到达后才取消请求。
// 所有模型/关系/新素材和旧版本应回滚,随后同原请求能安全重试且只分配一次最终身份映射。
func TestCanonicalMigrationLateCancellationRollsBack(t *testing.T) {
f := newCanonicalAtomicFixture(t)
ctx, stop := context.WithTimeout(context.Background(), 20*time.Second)
@@ -247,6 +260,7 @@ func TestCanonicalMigrationLateCancellationRollsBack(t *testing.T) {
go func() { done <- f.request(requestContext, "POST", f.path()+"/migrate", key, modelJSON(input)) }()
// Observe the actual late INSERT blocked behind this transaction. A timer
// alone cannot prove migration reached canonical/material/subgraph writes.
// 查询 pg_stat_activity/pg_blocking_pids 证明是目标后期写被阻塞,不用单纯 sleep 推断执行进度。
ticker := time.NewTicker(10 * time.Millisecond)
defer ticker.Stop()
observed := false
@@ -299,6 +313,8 @@ func TestCanonicalMigrationLateCancellationRollsBack(t *testing.T) {
}
}
// TestCanonicalMigrationPermissionVersionAndRunGuards 检查 viewer、陈旧版本及 queued/running AI 阻止身份屏障。
// 原拒绝键在版本或任务状态改变后仍冻结,新的请求键才能在条件满足后执行迁移。
func TestCanonicalMigrationPermissionVersionAndRunGuards(t *testing.T) {
f := newCanonicalAtomicFixture(t)
ctx := context.Background()
+3
View File
@@ -1,3 +1,4 @@
// Canonical 树的旧入口屏障,防止旧快照或子图命令覆盖已迁入的稳定身份模型。
package platform
import (
@@ -7,6 +8,8 @@ import (
// Old frozen receipts remain readable. Old whole-snapshot/ownership writers may
// not edit a migrated tree, even when their old client has not seen the barrier.
// guardLegacyCanonicalRequest 在 protected 分派前执行;历史回执 GET 可读,但旧快照读取和旧写命令被引导到模型接口。
// 返回 true 表示已经响应 409,调用方必须停止后续业务处理。
func (s *service) guardLegacyCanonicalRequest(w http.ResponseWriter, r *http.Request, project, account string) (bool, error) {
if r.PathValue("material") == "" {
return false, nil
+23
View File
@@ -1,3 +1,4 @@
// Canonical 读/迁移/写入口:冻结请求回执与逻辑操作去重,业务数据和回执同事务提交。
package platform
import (
@@ -13,6 +14,7 @@ import (
const modelMigrateAction = "model.migrate.v1"
const modelEditAction = "model.operations.v2"
// newModelID 用随机字节生成 UUIDv4,随机源失败返回空值,由调用方拒绝后续处理。
func newModelID() string {
var value [16]byte
if _, err := rand.Read(value[:]); err != nil {
@@ -22,6 +24,8 @@ func newModelID() string {
text := hex.EncodeToString(value[:])
return text[:8] + "-" + text[8:12] + "-" + text[12:16] + "-" + text[16:20] + "-" + text[20:]
}
// legacyModelRoot 沿活跃父链寻找旧树根,拒绝循环、归档和过深树。
func legacyModelRoot(r *http.Request, tx *sql.Tx, project, workspace, board string) (string, error) {
seen := map[string]bool{}
for len(seen) <= 8 {
@@ -43,6 +47,8 @@ func legacyModelRoot(r *http.Request, tx *sql.Tx, project, workspace, board stri
}
return "", errCanvasModel
}
// collectLegacyModel 收集根下最多 256 个 board 快照及关系,限额多取一项用于检测超限。
func collectLegacyModel(r *http.Request, tx *sql.Tx, project, workspace, root string) (map[string]canvasSnapshot, []subgraphRelation, error) {
rows, err := tx.QueryContext(r.Context(), `WITH RECURSIVE tree(id,path) AS (SELECT $3::uuid,ARRAY[$3::uuid] UNION ALL SELECT s.child_board_id,t.path||s.child_board_id FROM tree t JOIN canvas_subgraphs s ON s.project=$1 AND s.workspace_id=$2 AND s.parent_board_id=t.id WHERE s.archived_at IS NULL AND NOT s.child_board_id=ANY(t.path) AND cardinality(t.path)<=8) SELECT m.id::text,m.canvas_version,COALESCE(m.canvas_document,'{"schema_version":2,"nodes":[],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}'::jsonb) FROM tree t JOIN materials m ON m.project=$1 AND m.workspace_id=$2 AND m.id=t.id WHERE m.kind='board' ORDER BY m.id LIMIT 257`, project, workspace, root)
if err != nil {
@@ -82,6 +88,8 @@ func collectLegacyModel(r *http.Request, tx *sql.Tx, project, workspace, root st
}
return snapshots, relations, rows.Err()
}
// modelRequestRetry 按项目/工作区/账户/request ID 查冻结回执,并核对根、动作和载荷摘要防止跨用途复用。
func modelRequestRetry(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account, root, action, key, hash string) (bool, error) {
var previousRoot, previousAction, previousHash string
var status int
@@ -100,6 +108,8 @@ func modelRequestRetry(w http.ResponseWriter, r *http.Request, tx *sql.Tx, proje
reply(w, status, body)
return true, nil
}
// commitModelReceipt 注入协议和请求 ID,保存应用或终局拒绝回执后提交;提交成功才对外响应。
func commitModelReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account, root, action, key, hash string, status int, body response) error {
body["request_id"], body["protocol_version"] = key, canvasModelProtocol
raw, err := json.Marshal(body)
@@ -116,6 +126,8 @@ func commitModelReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, proj
reply(w, status, body)
return nil
}
// decodeModelRequest 限制五 MiB、未知字段与尾随 JSON;失败立即写出 400。
func decodeModelRequest(w http.ResponseWriter, r *http.Request, input any) bool {
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, canvasLimit))
decoder.DisallowUnknownFields()
@@ -126,6 +138,7 @@ func decodeModelRequest(w http.ResponseWriter, r *http.Request, input any) bool
return true
}
// getCanvasModel 未迁移时返回根和源版本表;已迁移时读模型表,在发送 JSON/NDJSON 前释放锁。
func (s *service) getCanvasModel(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -181,6 +194,7 @@ func (s *service) getCanvasModel(w http.ResponseWriter, r *http.Request, project
return nil
}
// migrateCanonicalCanvas 是显式身份屏障:完整确认旧树版本、等待在途 AI 结束,再保存模型及身份映射。
func (s *service) migrateCanonicalCanvas(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -232,6 +246,7 @@ func (s *service) migrateCanonicalCanvas(w http.ResponseWriter, r *http.Request,
if err != nil || done {
return err
}
// 已鉴权且可冻结的业务拒绝也入回执表,同请求不能在外部条件改变后变成新的执行。
rejectMigration := func(status int, code string) error {
return commitModelReceipt(w, r, tx, project, workspace, account, root, modelMigrateAction, key, payloadDigest(input), status, response{"status": "not-applied", "terminal": true, "error": code})
}
@@ -289,6 +304,7 @@ func (s *service) migrateCanonicalCanvas(w http.ResponseWriter, r *http.Request,
return commitModelReceipt(w, r, tx, project, workspace, account, root, modelMigrateAction, key, payloadDigest(input), 200, response{"status": "applied", "model": migration.Model.view(nil), "identity_map": migration.Identities, "source_versions": input.Expected})
}
// submitCanvasModelOperations 校验预期版本与跨请求逻辑操作 ID,运行纯 reducer 后检查完整参与者和资产权限。
func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -339,6 +355,7 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
if err != nil || done {
return err
}
// terminal not-applied 冻结本次确定拒绝;连接故障等未定结果返回依赖错误,由客户端同键查询/重试。
rejectBatch := func(status int, code string) error {
return commitModelReceipt(w, r, tx, project, workspace, account, root, modelEditAction, key, payloadDigest(input), status, response{"status": "not-applied", "terminal": true, "error": code})
}
@@ -351,6 +368,7 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
return rejectBatch(412, "version_conflict")
}
}
// operation_id 独立于 request_id,防止同一逻辑编辑被换请求键再次应用。
for _, operation := range input.Operations {
if !uuidSlugPattern.MatchString(operation.ID) {
return rejectBatch(400, "invalid_model_operation")
@@ -371,6 +389,7 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
}
return rejectBatch(409, code)
}
// reducer 识别的读写参与者都必须在 Expected 中;额外明确参与者也推进一次版本。
for id := range touched {
if _, exists := input.Expected[id]; !exists {
return rejectBatch(428, "version_required")
@@ -394,6 +413,7 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
after.Versions[id] = before.Versions[id] + 1
}
}
// 新身份不能占用同项目其他树的元素 ID;新增或更换资产引用须按当前授权重新核对。
for id, element := range after.Elements {
if before.Elements[id] == nil {
var foreign bool
@@ -445,6 +465,8 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
}
return commitModelReceipt(w, r, tx, project, workspace, account, root, modelEditAction, key, payloadDigest(input), 200, response{"status": "applied", "operation_ids": ids, "model": after.view(input.Expected)})
}
// getCanvasModelOperation 当前授权后只返回本人同根冻结回执;缺记录为 unknown,不能声称确定没有执行。
func (s *service) getCanvasModelOperation(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -490,6 +512,7 @@ func (s *service) getCanvasModelOperation(w http.ResponseWriter, r *http.Request
return nil
}
// modelExists 为其他平台流程提供是否已进入 canonical 树的轻量查询。
func modelExists(ctx context.Context, tx *sql.Tx, project, workspace, board string) (bool, error) {
root, err := canonicalRoot(ctx, tx, project, workspace, board)
return root != "", err
@@ -1,3 +1,4 @@
// Canonical 生命周期综合回归:使用真实 HTTP 与隔离 PostgreSQL,覆盖迁移屏障和增量写入持久化。
package platform
import (
@@ -15,6 +16,8 @@ import (
"testing"
)
// TestCanonicalModelMigrationAndIncrementalLifecycle 从旧 frame 分区迁移开始,逐步验证稳定身份、局部版本、墓碑和逻辑去重。
// 依赖 PLATFORM_TEST_DATABASE_URL;后续各段沿用前段版本,失败应在最早断言处定位。
func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -58,6 +61,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
mux := http.NewServeMux()
Register(mux, db, map[string]string{project: "https://app.example.com/auth/callback"}, "https://api.example.com", nil)
base := "/projects/" + project + "/workspaces/" + workspace + "/materials/" + root + "/canvas"
// call 经完整认证路由发请求;read 则从模型表独立重建,避免只相信回执中的内存结果。
call := func(method, path string, input any, key string, status int) response {
t.Helper()
raw, _ := json.Marshal(input)
@@ -93,6 +97,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
}
return model
}
// GET 只返回迁移需求,不隐式分配身份;显式迁移成功后旧 HTTP/数据库快照写入都应被屏障拦住。
if call("GET", base+"/model", nil, "", 409)["error"] != "canonical_migration_required" {
t.Fatal("legacy read silently migrated")
}
@@ -136,6 +141,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
if _, err = db.ExecContext(ctx, `UPDATE materials SET canvas_document=$4,canvas_version=canvas_version+1 WHERE project=$1 AND workspace_id=$2 AND id=$3`, project, workspace, root, legacy); err == nil {
t.Fatal("database identity barrier allowed an old writer")
}
// 每个 edit 分配不同请求与逻辑操作 ID,预期版本由用例显式给出,避免辅助函数掩盖版本错误。
edit := func(n int, versions map[string]int64, changes ...modelChange) response {
t.Helper()
key := modelTestID(n)
@@ -164,6 +170,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("missing receipt claimed zero writes")
}
// Move is a row owner update, retaining ElementId and incarnation.
// 元素移动只改 owner 与几何,不能删除再新建或改变 incarnation。
geometry := model.Elements[nodeID]["geometry"]
edit(1002, map[string]int64{root: 2, child: 2}, modelChange{Kind: "field", Target: modelTarget{ID: nodeID, Incarnation: 1}, Field: "ownerCanvasId", Before: modelJSON(child), After: modelJSON(root)}, modelChange{Kind: "field", Target: modelTarget{ID: nodeID, Incarnation: 1}, Field: "geometry", Before: modelJSON(geometry), After: modelJSON(map[string]any{"x": 150, "y": 260, "width": 240, "height": 72, "rotation": 0})})
model = read()
@@ -171,6 +178,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("move recreated the element")
}
// Future component/envelope bytes survive editing another object and legacy projections.
// 不认识的组件/数据版本和 envelope 作为不透明 JSON 保留,不因生成兼容快照而丢失。
opaqueID := modelTestID(3000)
opaque := modelTestNode(opaqueID, root)
opaque["componentId"], opaque["dataVersion"], opaque["data"], opaque["futureEnvelope"] = "future.plugin", float64(9), map[string]any{"raw": []any{map[string]any{"keep": true}}}, map[string]any{"extension": "retained"}
@@ -184,6 +192,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
if model.Tombstones[nodeID] != 1 {
t.Fatal("delete did not persist its lifecycle tombstone")
}
// 恢复同 ID 需升级 incarnation,旧代回调得到确定拒绝且不得改动任何版本或旁观元素。
restored := modelTestNode(nodeID, root)
restored["componentId"] = "plain-text"
restored["incarnation"] = float64(2)
@@ -215,6 +224,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("initial read has no explicit coverage")
}
// Negotiate the same authenticated canonical read as a streamed transfer.
// 相同授权入口协商 NDJSON,头部版本与真实模型一致,末尾必须存在 complete。
streamRequest := httptest.NewRequest("GET", base+"/model", nil)
streamRequest.Header.Set("Authorization", "Bearer "+token)
streamRequest.Header.Set("Accept", modelStreamType)
@@ -225,6 +235,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("authenticated stream lost canonical snapshot coverage")
}
// An object created and removed inside one transaction still has a lifecycle fact.
// 同批创建又删除仍要留下墓碑和死记录,不能当作未发生而允许旧生命周期被再次接受。
ghostID := modelTestID(4000)
ghost := modelTestNode(ghostID, root)
edit(1008, map[string]int64{root: 6}, modelChange{Kind: "element", ID: ghostID, Before: modelJSON(nil), After: modelJSON(ghost)}, modelChange{Kind: "element", ID: ghostID, Before: modelJSON(ghost), After: modelJSON(nil)})
@@ -247,6 +258,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("expected-account barrier was ignored")
}
// A new partition's entry, owning canvas and versions publish atomically.
// 新画布以期望版本零参与,入口节点和树关系同批创建;归档/恢复保留版本围栏。
newCanvas, newFrame := modelTestID(5000), modelTestID(5001)
frame := modelTestNode(newFrame, root)
frame["componentId"] = "frame"
@@ -269,6 +281,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
}
// A cross-scale entry move writes ownership, child binding and presentation units together.
// 跨缩放移动同时更改 owner、geometry、presentation 单位元数据和孩子 Parent,内部成员记录应不变。
innerCanvas, innerFrame, memberID := modelTestID(5100), modelTestID(5101), modelTestID(5102)
container := modelTestNode(innerFrame, root)
container["componentId"] = "frame"
@@ -312,6 +325,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("scaled move inverse did not restore absent unit metadata and the original child binding")
}
// Several logical edits share one atomic request while retaining every deduplication identity.
// 多逻辑编辑共用一个事务和版本增量,但每个原操作 ID 都必须登记并禁止换请求键重放。
batchKey, firstLogical, secondLogical := modelTestID(1016), modelTestID(22001), modelTestID(22002)
batchVersion := model.Versions[innerCanvas]
batch := modelBatch{ProtocolVersion: 2, RequestID: batchKey, Expected: map[string]int64{innerCanvas: batchVersion}, Operations: []modelOperation{
@@ -336,6 +350,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("a covered logical ID was executable under a new request key")
}
// A later failed condition cannot publish the earlier edit or consume its logical identity.
// 后一个 before 条件失败必须回滚先成功的内存前缀,也不能消费该前缀的逻辑操作 ID。
failedKey := modelTestID(1018)
batch.RequestID = failedKey
batch.Operations = []modelOperation{
@@ -355,6 +370,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
}
// A compacted wire projection retains prefix IDs with conditional no-ops, including in a child scope.
// 压缩后的 wire 批次用条件无操作保留前缀身份;只触及孩子版本且保留创建/删除生命周期事实。
projectedKey, guardLogical, effectLogical := modelTestID(1019), modelTestID(22005), modelTestID(22006)
projectedGhost := modelTestID(5200)
finalGhost := modelTestNode(projectedGhost, innerCanvas)
@@ -381,6 +397,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
}
// A locally canceled incarnation was never sent; undo may first publish incarnation 2.
// 本地取消且从未发送的第一代没有服务端墓碑;首次发布第二代仍合法,旧代回调不可冒领。
locallyElidedID := modelTestID(5201)
locallyRestored := modelTestNode(locallyElidedID, innerCanvas)
locallyRestored["incarnation"] = float64(2)
@@ -1,3 +1,4 @@
// 将旧快照树显式迁入 canonical 模型,保存完整旧→新稳定身份映射,原输入文档保持不变。
package platform
import (
@@ -6,21 +7,27 @@ import (
"strings"
)
// modelIdentity 包含来源画布和结构类型,避免不同画布或 node/edge 同名时映射碰撞。
type modelIdentity struct {
SourceCanvasID string `json:"sourceCanvasId"`
Structure string `json:"structure"`
SourceID string `json:"sourceId"`
ElementID string `json:"elementId"`
}
// modelMigration 返回模型、身份映射和普通旧 frame 新生成的画布 ID,由外层事务一次保存。
type modelMigration struct {
Model canvasModel
Identities []modelIdentity
NewCanvases []string
}
// modelSpace 描述累积到根的平移/缩放,用于迁移曲线路径,不应用 viewport。
type modelSpace struct{ X, Y, Scale float64 }
// No source document is changed. IDs are allocated once inside the eventual
// migration transaction and the complete mapping is stored with its receipt.
// migrateCanvasModel 通过注入 allocate 分配一次性稳定 ID;重复或非法分配结果直接拒绝。
func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relations []subgraphRelation, allocate func() string) (modelMigration, error) {
result := modelMigration{Model: emptyModel(root), Identities: []modelIdentity{}, NewCanvases: []string{}}
documents, nodes := map[string]map[string]any{}, map[string]map[string]any{}
@@ -73,6 +80,7 @@ func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relati
}
}
}
// 已有独立子图保留画布 ID,入口节点换为新元素 ID;关系必须与快照 subgraph 一致。
for _, relation := range relations {
if relation.Archived {
continue
@@ -91,6 +99,7 @@ func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relati
result.Model.Canvases[relation.Child] = modelCanvas{ID: relation.Child, Parent: &modelParent{CanvasID: relation.Parent, EntryElementID: identities[identityKey(relation.Parent, "node", relation.Frame)]}}
}
// Ordinary legacy frameId groups also become actual canvases, even if empty.
// 没有独立子图的旧框也变成真实画布(包括空框),随后把显式 frameId 成员迁入。
for _, key := range sortedKeys(nodes) {
node := nodes[key]
data := node["data"].(map[string]any)
@@ -149,6 +158,7 @@ func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relati
if err != nil {
return result, err
}
// 解开最多八层旧 port 链,得到 canonical 真实元素端点;方向错误或循环均拒绝。
resolve := func(board, node, handle, direction string) (map[string]any, error) {
seen := map[string]bool{}
for depth := 0; depth <= 8; depth++ {
@@ -217,6 +227,8 @@ func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relati
}
return result, nil
}
// modelContentScale 读取正展示缩放,缺省一;仅在迁移几何和路径空间计算时使用。
func modelContentScale(data map[string]any) float64 {
presentation, _ := data["presentation"].(map[string]any)
if scale, ok := presentation["contentScale"].(float64); ok && scale > 0 {
@@ -224,6 +236,8 @@ func modelContentScale(data map[string]any) float64 {
}
return 1
}
// legacyModelGeometry 为旧节点缺省尺寸补种类默认值,将 position/rotation 汇总到 canonical geometry。
func legacyModelGeometry(node map[string]any, kind string) map[string]any {
width, height := float64(260), float64(200)
switch kind {
@@ -247,6 +261,8 @@ func legacyModelGeometry(node map[string]any, kind string) map[string]any {
rotation, _ := data["rotation"].(float64)
return map[string]any{"x": position["x"], "y": position["y"], "width": width, "height": height, "rotation": rotation}
}
// modelSpaces 迭代从已知父空间求孩子累计空间,九轮仍未覆盖或无进展表示树无效。
func modelSpaces(model canvasModel) (map[string]modelSpace, error) {
result := map[string]modelSpace{model.Root: {Scale: 1}}
remaining := len(model.Canvases) - 1
+11
View File
@@ -1,3 +1,4 @@
// Canonical 模型持久化及旧快照投影;数据库模型表是权威来源,canvas_document 是内部兼容视图。
package platform
import (
@@ -8,6 +9,7 @@ import (
"sort"
)
// canonicalRoot 查询所属模型根,尚未迁移返回空字符串而非缺行错误。
func canonicalRoot(ctx context.Context, tx *sql.Tx, project, workspace, board string) (string, error) {
var root string
err := tx.QueryRowContext(ctx, `SELECT root_id::text FROM canvas_model_canvases WHERE project=$1 AND workspace_id=$2 AND canvas_id=$3`, project, workspace, board).Scan(&root)
@@ -16,6 +18,8 @@ func canonicalRoot(ctx context.Context, tx *sql.Tx, project, workspace, board st
}
return root, err
}
// loadCanvasModel 读取根下所有画布/元素,保留归档版本与删除记录,重建后执行完整模型校验。
func loadCanvasModel(ctx context.Context, tx *sql.Tx, project, workspace, root string) (canvasModel, error) {
model := emptyModel(root)
rows, err := tx.QueryContext(ctx, `SELECT canvas_id::text,parent_canvas_id::text,entry_element_id,version,archived FROM canvas_model_canvases WHERE project=$1 AND workspace_id=$2 AND root_id=$3 ORDER BY canvas_id`, project, workspace, root)
@@ -81,6 +85,8 @@ func loadCanvasModel(ctx context.Context, tx *sql.Tx, project, workspace, root s
// Only changed element rows are written. canvas_document is a compatibility
// projection for internal AI readers, never the source of a canonical GET/replay.
// saveCanvasModel 在调用方事务中写参与画布与真正变化的元素,更新所有权关系并同步兼容快照。
// 先按 canonical 稳定身份使 AI 目标失效,再开启事务级 canonical_writer 以通过数据库旧写入屏障。
func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspace, account string, before, after canvasModel, participants map[string]bool) error {
ctx := r.Context()
if err := invalidateCanonicalAIIdentities(r, tx, project, workspace, before, after); err != nil {
@@ -120,6 +126,7 @@ func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspac
return err
}
}
// 只更新变化记录;同项目元素 ID 已属于其他 workspace/root 时,受限 upsert 不覆盖并报冲突。
for _, id := range sortedKeys(after.Elements) {
element := after.Elements[id]
if modelEqual(before.Elements[id], element) && before.Tombstones[id] == after.Tombstones[id] {
@@ -139,6 +146,7 @@ func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspac
return errModelConflict
}
}
// 删除也持久保留最后记录及代数,后续恢复/去重不能把墓碑当成从未存在。
for _, id := range sortedKeys(after.Tombstones) {
if after.Elements[id] != nil || before.Elements[id] == nil && before.Tombstones[id] == after.Tombstones[id] {
continue
@@ -169,6 +177,7 @@ func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspac
}
}
}
// 先归档旧关系,再按祖先深度由外向内安装最终树,避免父入口变动时出现重复活跃关系。
canvases := sortedKeys(after.Canvases)
sort.SliceStable(canvases, func(i, j int) bool {
a, _ := modelAncestors(after, canvases[i])
@@ -202,6 +211,7 @@ func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspac
return nil
}
// projectCanvasModel 为旧 AI reader 生成 v2 快照,只投影已知 v1 组件,未知组件仍完整保存在 canonical 表。
func projectCanvasModel(model canvasModel) (map[string]json.RawMessage, error) {
documents := map[string]map[string]any{}
for id := range model.Canvases {
@@ -251,6 +261,7 @@ func projectCanvasModel(model canvasModel) (map[string]json.RawMessage, error) {
owner := modelString(element["ownerCanvasId"])
documents[owner]["nodes"] = append(documents[owner]["nodes"].([]any), node)
}
// Canonical 连接直接指真实元素;投影时才沿祖先树生成旧式 frame/port 链,不能反向作为权威身份。
for _, id := range elements {
element := model.Elements[id]
if element["structure"] != "connection" || element["componentId"] != "connection" || modelInt(element["dataVersion"]) != 1 {
+5
View File
@@ -1,3 +1,4 @@
// Canonical 模型 NDJSON 传输:从已一致捕获的内存模型编码,不边读库边向慢客户端发送。
package platform
import (
@@ -11,6 +12,7 @@ const modelStreamType = "application/vnd.foundry.canvas-model+ndjson;version=1"
// The caller captures a coherent model while holding the workspace lock, then
// releases its transaction before writing. A slow reader must not hold a writer.
// This streams transfer/encoding; it does not stream database row acquisition.
// writeCanvasModelStream 发送 header、elements 批次和 complete,统一 token/sequence 供客户端检测截断或混流。
func writeCanvasModelStream(ctx context.Context, w http.ResponseWriter, model canvasModel) {
token := newModelID()
if token == "" {
@@ -19,6 +21,7 @@ func writeCanvasModelStream(ctx context.Context, w http.ResponseWriter, model ca
}
view := model.view(nil)
// A count covers direct members only; an empty canvas is explicit too.
// 头部显式声明每画布直接元素数、总数与身份 owner,空画布也必须覆盖。
counts := map[string]int{}
owners := map[string]string{}
for _, canvas := range view.Canvases {
@@ -45,6 +48,7 @@ func writeCanvasModelStream(ctx context.Context, w http.ResponseWriter, model ca
const maxBytes = 64 * 1024 * 1024
sequence, total := 0, 0
started := false
// 每行/总字节/记录数均有预算;开始前可写结构化错误,开始后只能停流让缺 complete 表示失败。
write := func(value response) bool {
if ctx.Err() != nil {
return false
@@ -78,6 +82,7 @@ func writeCanvasModelStream(ctx context.Context, w http.ResponseWriter, model ca
}
batch := []map[string]any{}
batchBytes := 0
// 批次最多 64 元素或约 512 KiB,单个大元素仍受统一 maxLine 限制。
flush := func() bool {
if len(batch) == 0 {
return true
@@ -1,3 +1,4 @@
// 模型/协议纯回归:用内存对象与 recorder 验证身份、原子变更或流传输契约,不访问真实数据库。
package platform
import (
@@ -9,6 +10,7 @@ import (
"testing"
)
// streamRecords 把 recorder 内每行 JSON 转为断言对象;用例中的小记录不需要增大 Scanner 缺省预算。
func streamRecords(t *testing.T, writer *httptest.ResponseRecorder) []response {
t.Helper()
var records []response
@@ -25,6 +27,8 @@ func streamRecords(t *testing.T, writer *httptest.ResponseRecorder) []response {
}
return records
}
// TestCanonicalModelStreamFramesAndSnapshot 用超过两个批次的元素验证 header/批次/complete 分帧,token、序号、墓碑和全元素 owner 清单必须一致且无重复漏项。
func TestCanonicalModelStreamFramesAndSnapshot(t *testing.T) {
model := modelTestDocument()
for i := 0; i < 129; i++ {
@@ -80,15 +84,19 @@ func TestCanonicalModelStreamFramesAndSnapshot(t *testing.T) {
}
}
// cancelStreamWriter 在首个 flush 后取消请求,用于验证已开始流的中途停止语义。
type cancelStreamWriter struct {
*httptest.ResponseRecorder
cancel context.CancelFunc
}
// Flush 先模拟实际输出,再取消,使下一次编码检测到上下文结束。
func (writer cancelStreamWriter) Flush() {
writer.ResponseRecorder.Flush()
writer.cancel()
}
// TestCanonicalModelStreamCancellationNeverClaimsCompletion 第一次 Flush 即取消上下文,验证仅发 header,不能追加 complete 或假成功尾记录。
func TestCanonicalModelStreamCancellationNeverClaimsCompletion(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
@@ -100,6 +108,7 @@ func TestCanonicalModelStreamCancellationNeverClaimsCompletion(t *testing.T) {
}
}
// TestCanonicalModelStreamDeclaresDirectScopeCountsIncludingEmptyCanvases 验证每个 scope 只计直接成员且显式保留零元素画布,未知 owner 必须在首次 Flush 前拒绝。
func TestCanonicalModelStreamDeclaresDirectScopeCountsIncludingEmptyCanvases(t *testing.T) {
model := modelTestDocument()
empty, nested := modelTestID(41), modelTestID(42)
@@ -124,6 +133,7 @@ func TestCanonicalModelStreamDeclaresDirectScopeCountsIncludingEmptyCanvases(t *
}
}
// TestCanonicalModelStreamRejectsAmbiguousIdentityManifest 构造空或重复内部元素 ID,验证不发布有歧义的身份清单,返回 500 且未开始流。
func TestCanonicalModelStreamRejectsAmbiguousIdentityManifest(t *testing.T) {
for _, id := range []string{"", "a"} {
model := modelTestDocument()
+22 -1
View File
@@ -1,3 +1,4 @@
// 模型/协议纯回归:用内存对象与 recorder 验证身份、原子变更或流传输契约,不访问真实数据库。
package platform
import (
@@ -17,15 +18,24 @@ const modelLegacyFrame = `{"id":"f","type":"frame","position":{"x":100,"y":200},
//go:embed testdata/foundry-model-operation-v2.json
var canonicalFrontendFixture []byte
// modelJSON 将测试值统一编码为 before/after 原始 JSON。
func modelJSON(value any) json.RawMessage { raw, _ := json.Marshal(value); return raw }
func modelTestID(n int) string { return fmt.Sprintf("90000000-0000-4000-8000-%012d", n) }
// modelTestID 生成确定 UUID,便于跨回归复用可预期的请求/操作/资源身份。
func modelTestID(n int) string { return fmt.Sprintf("90000000-0000-4000-8000-%012d", n) }
// modelTestAllocator 返回有独立计数器的分配器,让迁移身份分配可重复断言。
func modelTestAllocator() func() string {
next := 0
return func() string { next++; return modelTestID(next) }
}
// modelTestNode 构造最小有效 v1 text 节点,其嵌套 data/geometry 每次独立创建。
func modelTestNode(id, owner string) map[string]any {
return map[string]any{"id": id, "incarnation": float64(1), "ownerCanvasId": owner, "componentId": "text", "dataVersion": float64(1), "structure": "node", "data": map[string]any{"title": id, "text": "preserved"}, "geometry": map[string]any{"x": float64(0), "y": float64(0), "width": float64(260), "height": float64(200), "rotation": float64(0)}}
}
// modelTestDocument 提供版本一根画布和一个 a 节点的最小完整模型。
func modelTestDocument() canvasModel {
model := emptyModel(modelRootID)
model.Canvases[modelRootID] = modelCanvas{ID: modelRootID}
@@ -34,6 +44,7 @@ func modelTestDocument() canvasModel {
return model
}
// TestCanonicalFramesRetainRotationAcrossOwnerChanges 检查 canonical frame 跨 owner 后保留旋转、兼容投影和无关 AI patch 不抹角度,同时旧快照写契约仍拒绝旋转 frame。
func TestCanonicalFramesRetainRotationAcrossOwnerChanges(t *testing.T) {
model := modelTestDocument()
frame := modelTestNode("f", modelRootID)
@@ -97,6 +108,7 @@ func TestCanonicalFramesRetainRotationAcrossOwnerChanges(t *testing.T) {
}
}
// TestCanonicalMigrationResolvesCanvasLocalIdentitiesAndPorts 用父子同名节点证明迁移分配不同全局身份,并将端口边解析为真实子节点、推进版本屏障且保留输入快照。
func TestCanonicalMigrationResolvesCanvasLocalIdentitiesAndPorts(t *testing.T) {
root := `{"schema_version":2,"nodes":[{"id":"a","type":"plainText","position":{"x":0,"y":0},"width":240,"height":72,"data":{"kind":"plain-text","title":"parent","text":""}},{"id":"f","type":"frame","position":{"x":100,"y":200},"width":640,"height":400,"data":{"kind":"frame","title":"F","text":"","subgraph":{"boardId":"` + modelChildID + `"},"ports":[{"id":"p","nodeId":"a","handle":"right","direction":"output"}]}}],"edges":[{"id":"e","source":"f","sourceHandle":"port:p","target":"a","targetHandle":"left"}],"viewport":{"x":0,"y":0,"zoom":1}}`
child := `{"schema_version":2,"nodes":[{"id":"a","type":"plainText","position":{"x":10,"y":20},"width":240,"height":72,"data":{"kind":"plain-text","title":"child","text":""}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
@@ -133,6 +145,8 @@ func TestCanonicalMigrationResolvesCanvasLocalIdentitiesAndPorts(t *testing.T) {
}
}
}
// TestCanonicalMigrationTurnsImplicitFramesIntoOwningCanvases 验证旧 frameId 分区成为新画布,成员几何改为 owner 局部坐标且 data 中不再存第二份 frameId 所有权。
func TestCanonicalMigrationTurnsImplicitFramesIntoOwningCanvases(t *testing.T) {
root := `{"schema_version":1,"nodes":[` + modelLegacyFrame + `,{"id":"a","type":"plainText","position":{"x":150,"y":260},"width":240,"height":72,"data":{"kind":"plain-text","title":"a","text":"","frameId":"f"}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
result, err := migrateCanvasModel(modelRootID, map[string]canvasSnapshot{modelRootID: {BoardID: modelRootID, Version: 1, Document: json.RawMessage(root)}}, nil, modelTestAllocator())
@@ -156,6 +170,8 @@ func TestCanonicalMigrationTurnsImplicitFramesIntoOwningCanvases(t *testing.T) {
t.Fatal("second ownership fact leaked into canonical data")
}
}
// TestCanonicalOperationsPreserveOpaquePayloadAndStableMoveIdentity 移动已知元素 owner 时保留 ID,触及新旧画布,并原样保留未知组件数据及 envelope,输入模型不被修改。
func TestCanonicalOperationsPreserveOpaquePayloadAndStableMoveIdentity(t *testing.T) {
model := modelTestDocument()
frame := modelTestNode("f", modelRootID)
@@ -180,6 +196,8 @@ func TestCanonicalOperationsPreserveOpaquePayloadAndStableMoveIdentity(t *testin
t.Fatal("opaque payload or old snapshot was mutated")
}
}
// TestCanonicalDeleteRestoreRejectsOldIncarnation 删除产生墓碑,恢复升级 incarnation;旧代异步字段编辑不能命中新一代同 ID 元素。
func TestCanonicalDeleteRestoreRejectsOldIncarnation(t *testing.T) {
model := modelTestDocument()
deleted, _, err := applyModelOperations(model, []modelOperation{{ID: modelTestID(1), Changes: []modelChange{{Kind: "element", ID: "a", Before: modelJSON(model.Elements["a"]), After: modelJSON(nil)}}}})
@@ -200,6 +218,8 @@ func TestCanonicalDeleteRestoreRejectsOldIncarnation(t *testing.T) {
t.Fatal("old callback claimed the restored incarnation")
}
}
// TestCanonicalValidationRejectsPartialChangesAndWrongEdgeOwner 第二个变更失败时输入不变;另构造跨父子的连接却归孩子所有,要求最终模型校验拒绝。
func TestCanonicalValidationRejectsPartialChangesAndWrongEdgeOwner(t *testing.T) {
model := modelTestDocument()
before := modelJSON(model)
@@ -222,6 +242,7 @@ func TestCanonicalValidationRejectsPartialChangesAndWrongEdgeOwner(t *testing.T)
}
}
// TestCanonicalFrontendProtocolFixture 读取嵌入的前端协议样本,验证请求 envelope 与 reducer 兼容,且仅改变预期标题和一次版本。
func TestCanonicalFrontendProtocolFixture(t *testing.T) {
var input modelBatch
decoder := json.NewDecoder(bytes.NewReader(canonicalFrontendFixture))
+6
View File
@@ -1,3 +1,4 @@
// 旧快照操作协议 v1 的纯批处理器,canonical 模型协议 v2 使用另一套 before/after reducer。
package platform
import (
@@ -8,6 +9,7 @@ import (
const canvasOperationsProtocol = 1
// canvasOperation 表示节点/边创建、patch 或删除,元素 ID 与完整 Record 内 ID 必须一致。
type canvasOperation struct {
ID string `json:"id"`
Type string `json:"type"`
@@ -16,6 +18,8 @@ type canvasOperation struct {
Record json.RawMessage `json:"record,omitempty"`
Patch map[string]json.RawMessage `json:"patch,omitempty"`
}
// canvasOperationBatch 用请求键及参与画布版本表包裹有序操作,HTTP 编排负责授权和事务。
type canvasOperationBatch struct {
ProtocolVersion int `json:"protocol_version"`
RequestID string `json:"request_id"`
@@ -27,6 +31,7 @@ var errInvalidCanvasOperation = errors.New("invalid_canvas_operation")
// applyCanvasOperations stages a complete batch. Input snapshots are never mutated.
// HTTP/auth/version/idempotency are checked by the transaction coordinator.
// applyCanvasOperations 复制所有输入,执行完全部操作才统一 normalize 并各增一次版本,失败不返回部分结果。
func applyCanvasOperations(initial map[string]canvasSnapshot, operations []canvasOperation) (map[string]canvasSnapshot, error) {
if len(operations) == 0 || len(operations) > 2500 {
return nil, errInvalidCanvasOperation
@@ -96,6 +101,7 @@ func applyCanvasOperations(initial map[string]canvasSnapshot, operations []canva
if !allowed {
return nil, errInvalidCanvasOperation
}
// data 是逐键 merge(null 删除),几何等字段整体替换,避免位置 patch 覆盖其他已保存内容。
if field == "data" {
// Merge individual data fields; a geometry-only patch never rolls back titles/assets.
var before, patch map[string]json.RawMessage
@@ -1,3 +1,4 @@
// 旧无界面操作批次 HTTP 协调器,原子验证多快照并冻结成功/终局拒绝回执。
package platform
import (
@@ -11,6 +12,7 @@ import (
const canvasOperationsAction = "headless.operations.v1"
// submitCanvasOperations 严格验证协议和参与者,稳定取锁后先重放回执,再比较版本并执行纯批处理。
func (s *service) submitCanvasOperations(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -100,6 +102,7 @@ func (s *service) submitCanvasOperations(w http.ResponseWriter, r *http.Request,
snapshots := make([]canvasSnapshot, 0, len(participants))
versions := map[string]int64{}
// Validate all participant documents before writing any of them.
// 写快照前逐一验证所有权、AI 模型和资产;任一拒绝结束整个批次。
for _, id := range participants {
snapshot := staged[id]
valid, e := validateCanvasRelations(r, tx, project, workspace, id, initial[id].Document, snapshot.Document)
@@ -137,6 +140,7 @@ func (s *service) submitCanvasOperations(w http.ResponseWriter, r *http.Request,
// A terminal rejection also reserves the frozen key/body. Losing that response must
// not turn a definite zero-write result into a future execution of the same request.
// commitCanvasOperationReceipt 将应用或 terminal 拒绝写入七天回执,与本事务已做的变更一起提交。
func commitCanvasOperationReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, account, board string, input canvasOperationBatch, status int, body response, before []canvasSnapshot, versions map[string]int64) error {
var transactionID string
if err := tx.QueryRowContext(r.Context(), `SELECT gen_random_uuid()::text`).Scan(&transactionID); err != nil {
@@ -171,6 +175,7 @@ func commitCanvasOperationReceipt(w http.ResponseWriter, r *http.Request, tx *sq
return nil
}
// getCanvasOperation 查询本人请求的冻结结果,返回前重查回执内全部快照当前可读性,缺记录为 unknown。
func (s *service) getCanvasOperation(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -1,3 +1,4 @@
// 旧 headless 操作批次数据库回归:需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移测试库。
package platform
import (
@@ -17,6 +18,7 @@ import (
"testing"
)
// TestCanvasOperationsTransactions 检查应用/拒绝回执可恢复、同键同体重试、权限隔离及多画布批次整体回滚。
func TestCanvasOperationsTransactions(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -72,6 +74,7 @@ func TestCanvasOperationsTransactions(t *testing.T) {
Register(mux, db, map[string]string{project: "https://app.example.com/auth/callback"}, "https://api.example.com", nil)
path := "/projects/" + project + "/workspaces/" + workspace + "/materials/" + boards[0] + "/canvas/operations"
key := func(n int) string { return fmt.Sprintf("a0000000-0000-4000-8000-%012d", n) }
// do 执行真实路由,call 断言状态并解码,version 从数据库读取真实 canvas_version。
do := func(method, path, token string, input canvasOperationBatch) *httptest.ResponseRecorder {
encoded, _ := json.Marshal(input)
request := httptest.NewRequest(method, path, bytes.NewReader(encoded))
@@ -124,6 +127,7 @@ func TestCanvasOperationsTransactions(t *testing.T) {
t.Fatal("missing receipt must not claim terminal zero writes")
}
// Terminal zero-write responses must remain queryable and reserve their frozen body.
// 终局拒绝冻结原键和请求体,不能修正版本后沿用同一键让先前零效果变为实际执行。
stale := batch(3, 1)
rejected := call("POST", path, tokens[0], stale, 412)
proof := call("GET", path+"/"+key(3), tokens[0], canvasOperationBatch{}, 200)
@@ -135,6 +139,7 @@ func TestCanvasOperationsTransactions(t *testing.T) {
t.Fatal("rejected request performed a write")
}
// Concurrent exact retries serialize to one transaction and one version increment.
// 四条同键并发请求共享原回执,数据库版本只能前进一次。
concurrent := batch(4, 2)
var wait sync.WaitGroup
results := make(chan *httptest.ResponseRecorder, 4)
@@ -153,6 +158,7 @@ func TestCanvasOperationsTransactions(t *testing.T) {
t.Fatal("concurrent request executed more than once")
}
// A valid first participant and an invalid second participant produce no partial write.
// 首画布 patch 合法但次画布删除不存在节点,检查两者版本都不变且拒绝回执可查。
atomic := batch(5, 3)
atomic.ExpectedVersions[boards[1]] = 1
atomic.Operations = append(atomic.Operations, canvasOperation{ID: key(500), Type: "node.delete", CanvasID: boards[1], ElementID: "missing"})
@@ -1,3 +1,4 @@
// 模型/协议纯回归:用内存对象与 recorder 验证身份、原子变更或流传输契约,不访问真实数据库。
package platform
import (
@@ -7,6 +8,7 @@ import (
const operationsFixture = `{"schema_version":2,"nodes":[{"id":"a","type":"plainText","position":{"x":0,"y":0},"width":240,"height":72,"data":{"kind":"plain-text","title":"original","text":"hello"}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
// TestCanvasOperationBatchStagesAndMerges 连续执行 data 标题 patch 和位置 patch,验证无关文本保留、整批只加一次版本且输入 JSON 不变。
func TestCanvasOperationBatchStagesAndMerges(t *testing.T) {
initial := map[string]canvasSnapshot{"board": {BoardID: "board", Version: 7, Document: json.RawMessage(operationsFixture)}}
operations := []canvasOperation{
@@ -39,6 +41,8 @@ func TestCanvasOperationBatchStagesAndMerges(t *testing.T) {
t.Fatal("input snapshot mutated")
}
}
// TestCanvasOperationBatchRejectsWithoutPartialOutput 拒绝改 ID、缺目标及指向缺失节点的边,要求错误时不返回任何部分批次结果。
func TestCanvasOperationBatchRejectsWithoutPartialOutput(t *testing.T) {
initial := map[string]canvasSnapshot{"board": {BoardID: "board", Version: 1, Document: json.RawMessage(operationsFixture)}}
for _, operation := range []canvasOperation{
@@ -51,6 +55,8 @@ func TestCanvasOperationBatchRejectsWithoutPartialOutput(t *testing.T) {
}
}
}
// TestCanvasOperationBatchValidatesFinalGraphInsteadOfIntermediateState 先创建指向 b 的边再创建 b,验证只对整批最终图做引用校验。
func TestCanvasOperationBatchValidatesFinalGraphInsteadOfIntermediateState(t *testing.T) {
initial := map[string]canvasSnapshot{"board": {BoardID: "board", Version: 1, Document: json.RawMessage(operationsFixture)}}
operations := []canvasOperation{
+8
View File
@@ -1,3 +1,4 @@
// frame 子图扩展与普通快照的所有权守卫,防止绕开多画布事务改写关系。
package platform
import (
@@ -8,6 +9,8 @@ import (
"strings"
)
// validCanvasFrameExtensions 仅允许 v2 frame 携带子图、端口和折叠展示配置,检查形状与本地 ID 唯一性。
// 端口 nodeId 的跨文档存在性留给持锁关系命令验证。
func validCanvasFrameExtensions(d map[string]any, v2 bool) bool {
for _, key := range []string{"subgraph", "ports", "presentation"} {
value, exists := d[key]
@@ -74,6 +77,7 @@ func validCanvasFrameExtensions(d map[string]any, v2 bool) bool {
return true
}
// canvasNodeData 从已规范化文档提取 id→data;依赖节点形状已验证,不适合直接读取未校验请求。
func canvasNodeData(raw json.RawMessage) map[string]map[string]any {
var doc map[string]any
_ = json.Unmarshal(raw, &doc)
@@ -88,6 +92,7 @@ func canvasNodeData(raw json.RawMessage) map[string]map[string]any {
// Ordinary saves cannot create, replace, detach or retarget ownership/ports.
// Cross-board commands validate these changes while holding the workspace lock.
// validateCanvasRelations 在工作区锁下将新快照与数据库活跃子图关系比较,普通保存不得删除/换绑 frame 或端口。
func validateCanvasRelations(r *http.Request, tx *sql.Tx, project, workspace, board string, before, after json.RawMessage) (bool, error) {
old, next := canvasNodeData(before), canvasNodeData(after)
rows, err := tx.QueryContext(r.Context(), `SELECT frame_id,child_board_id::text FROM canvas_subgraphs WHERE project=$1 AND workspace_id=$2 AND parent_board_id=$3 AND archived_at IS NULL`, project, workspace, board)
@@ -115,6 +120,7 @@ func validateCanvasRelations(r *http.Request, tx *sql.Tx, project, workspace, bo
return false, nil
}
}
// 新增伪子图、无关系的非空端口,或把本地图节点挂进已拥有独立子画布的 frame 都拒绝。
for id, d := range next {
if sub, exists := d["subgraph"]; exists {
m, _ := sub.(map[string]any)
@@ -130,6 +136,7 @@ func validateCanvasRelations(r *http.Request, tx *sql.Tx, project, workspace, bo
}
}
// A child node referenced by its parent's ports must not disappear or change kind.
// 若当前画布是孩子,还要保持父端口引用的节点存在且种类不变;无父关系则无需此检查。
var parentRaw json.RawMessage
err = tx.QueryRowContext(r.Context(), `SELECT m.canvas_document FROM canvas_subgraphs s JOIN materials m ON m.project=s.project AND m.workspace_id=s.workspace_id AND m.id=s.parent_board_id WHERE s.project=$1 AND s.workspace_id=$2 AND s.child_board_id=$3 AND s.archived_at IS NULL`, project, workspace, board).Scan(&parentRaw)
if err == sql.ErrNoRows {
@@ -155,6 +162,7 @@ func validateCanvasRelations(r *http.Request, tx *sql.Tx, project, workspace, bo
return true, nil
}
// validCanvasPortHandle 接受四个基础方向,或指向另一个已命名端口的 port:<id>。
func validCanvasPortHandle(value any) bool {
if canvasChoice(value, "top", "right", "bottom", "left") {
return true
+8
View File
@@ -1,3 +1,4 @@
// 画布与资产纯函数回归;测试说明对应实际断言,不依赖浏览器或真实模型。
package platform
import (
@@ -6,8 +7,10 @@ import (
"testing"
)
// canvasFixture 同时供多组回归使用:含中文文本、脚本、不可连线图标及临时 selected。
const canvasFixture = `{"schema_version":1,"nodes":[{"id":"a","type":"material","position":{"x":100,"y":200},"width":320,"height":220,"selected":true,"data":{"kind":"text","title":"灵感笔记","text":"正文","rotation":30,"fontSize":24,"textStyle":{"color":"#37352f","background":"transparent","bold":true,"italic":false,"underline":false,"align":"left","fontFamily":"sans","lineHeight":1.5}}},{"id":"b","type":"material","position":{"x":0,"y":0},"data":{"kind":"script","title":"Script","text":""}},{"id":"icon","type":"icon","position":{"x":500,"y":200},"width":80,"height":80,"data":{"kind":"icon","title":"火箭","text":"","icon":"Rocket","rotation":0}}],"edges":[{"id":"e","source":"a","target":"b","sourceHandle":"top","targetHandle":"bottom"}],"viewport":{"x":0,"y":0,"zoom":1}}`
// TestCanvasValidation 从合法快照逐项破坏类型、范围、引用和版本,检查临时 selected 不落库以及必需文档结构。
func TestCanvasValidation(t *testing.T) {
out, ok := normalizeCanvas(json.RawMessage(canvasFixture))
if !ok || strings.Contains(string(out), "selected") {
@@ -27,6 +30,8 @@ func TestCanvasValidation(t *testing.T) {
}
}
}
// TestSlugValidation 检查小写连字符别名可用,拒绝空值、空格大写、路径穿越和超长别名。
func TestSlugValidation(t *testing.T) {
for _, v := range []string{"my-board", "workspace-2026"} {
if !validSlug(&v) {
@@ -41,8 +46,10 @@ func TestSlugValidation(t *testing.T) {
}
// Frame nodes follow the frontend contract: membership is data, not containment.
// frameFixture 把重叠的 outside 留在框外,以区分几何包含与显式 frameId 成员关系。
const frameFixture = `{"schema_version":1,"nodes":[{"id":"text","type":"material","position":{"x":100,"y":100},"data":{"kind":"text","title":"成员","text":"正文","frameId":"frame"}},{"id":"plain","type":"plainText","position":{"x":0,"y":0},"data":{"kind":"plain-text","title":"纯文本","text":"文字","frameId":"frame"}},{"id":"icon","type":"icon","position":{"x":10,"y":10},"data":{"kind":"icon","title":"图标","text":"","icon":"Star","frameId":"frame"}},{"id":"frame","type":"frame","position":{"x":0,"y":0},"width":600,"height":400,"zIndex":-1,"style":{"width":600,"height":400,"pointerEvents":"none"},"data":{"kind":"frame","title":"框选区","text":"","rotation":0,"labelMode":"fixed"}},{"id":"outside","type":"material","position":{"x":100,"y":100},"data":{"kind":"script","title":"重叠但未加入","text":""}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
// TestCanvasFrames 检查三种标签模式、显式成员关系、临时渲染字段剔除;框不可旋转/嵌套为成员,v1 边不可连到框。
func TestCanvasFrames(t *testing.T) {
for _, mode := range []string{"hidden", "fixed", "scaled"} {
t.Run(mode, func(t *testing.T) {
@@ -89,6 +96,7 @@ func TestCanvasFrames(t *testing.T) {
}
}
// TestCanvasPlainImages 验证 v1 plainImage 的类型与源地址契约,以及显式 frameId;v1 下纯图片不能作为连线端点。
func TestCanvasPlainImages(t *testing.T) {
fixture := `{"schema_version":1,"nodes":[{"id":"photo","type":"plainImage","position":{"x":20,"y":30},"width":320,"height":240,"data":{"kind":"plain-image","title":"Photo","text":"","src":"https://example.com/photo.png","rotation":30,"frameId":"frame"}},{"id":"frame","type":"frame","position":{"x":0,"y":0},"width":640,"height":400,"data":{"kind":"frame","title":"Frame","text":"","labelMode":"fixed"}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
if _, ok := normalizeCanvas(json.RawMessage(fixture)); !ok {
+8
View File
@@ -1,3 +1,4 @@
// 旧多画布事务撤销:校验回执有效性与当前后态,恢复文档/关系并创建独立幂等撤销回执。
package platform
import (
@@ -7,6 +8,7 @@ import (
"strings"
)
// undoCanvasTransaction 只支持列出的子图/连接动作,过期或已撤销回执不可再次执行。
func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -91,6 +93,7 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
if err = json.Unmarshal(relationsRaw, &changes); err != nil {
return err
}
// 归档孩子无法按普通素材路径授权,需通过其当前父画布验证编辑权限;关系必须仍等于原 After。
archivedParticipants := map[string]bool{}
for _, change := range changes {
actual, err := readSubgraphRelation(r, tx, project, workspace, change.After.Child)
@@ -122,6 +125,7 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
if err = json.Unmarshal(afterResponse, &recorded); err != nil {
return err
}
// 从原响应的不同形态收集操作后文档,用内容相等而非原版本号判断是否仍可安全栈式撤销。
afterStates := map[string]json.RawMessage{}
if recorded.Parent.BoardID != "" {
afterStates[recorded.Parent.BoardID] = recorded.Parent.Document
@@ -153,12 +157,14 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
reject(w, 428, "version_required")
return nil
}
// 客户端确认当前版本,服务端还确认当前内容等于原后态,防止覆盖后续独立编辑。
if expected != snapshot.Version || !sameCanvasDocument(snapshot.Document, afterStates[id]) {
reject(w, 412, "version_conflict")
return nil
}
current[id] = snapshot
}
// 全部参与者校验完再恢复关系与快照;版本以当前值加一推进,绝不倒退到历史版本。
for _, change := range changes {
if err = writeSubgraphRelation(r, tx, project, workspace, change.Before); err != nil {
return err
@@ -176,6 +182,7 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
updated = append(updated, snapshot)
appliedVersions[snapshot.BoardID] = snapshot.Version
}
// 原操作前不存在的孩子不删除,归档并使旧版本失效,保留完整数据供恢复。
archived := []string{}
for id, snapshot := range current {
if beforeIDs[id] {
@@ -223,6 +230,7 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
return nil
}
// sameCanvasDocument 解码后重编码比较摘要,忽略 JSON 对象键顺序,无法解码时明确不相等。
func sameCanvasDocument(a, b json.RawMessage) bool {
var first, second any
if json.Unmarshal(a, &first) != nil || json.Unmarshal(b, &second) != nil {
+8
View File
@@ -1,3 +1,4 @@
// schema v2 的协商、点与边扩展校验;这些纯检查被快照、连接和事务命令复用。
package platform
import (
@@ -9,6 +10,7 @@ import (
"strings"
)
// canvasSchema 只读取版本字段,无法解码时返回零;不能替代 normalizeCanvas 的完整验证。
func canvasSchema(raw json.RawMessage) int {
var d struct {
Version int `json:"schema_version"`
@@ -17,6 +19,7 @@ func canvasSchema(raw json.RawMessage) int {
return d.Version
}
// acceptsCanvasV2 逐项解析 Accept 媒体类型,要求明确 version=2,且存在 q 时必须在 (0,1]。
func acceptsCanvasV2(r *http.Request) bool {
for _, value := range strings.Split(r.Header.Get("Accept"), ",") {
typ, params, err := mime.ParseMediaType(strings.TrimSpace(value))
@@ -33,11 +36,13 @@ func acceptsCanvasV2(r *http.Request) bool {
return false
}
// canvasPoint 要求完整 x/y 与有限百万坐标范围,供贝塞尔控制点和结点偏移使用。
func canvasPoint(v any) bool {
p, ok := v.(map[string]any)
return ok && canvasFields(p, "x", "y") && canvasNumber(p["x"], -1e6, 1e6) && canvasNumber(p["y"], -1e6, 1e6)
}
// validCanvasEdgeData 分别检查外观、动画、执行开关和贝塞尔链;省略分组合法,出现时拒绝未知键。
func validCanvasEdgeData(v any) bool {
d, ok := v.(map[string]any)
if !ok || !canvasFields(d, "appearance", "animation", "path", "execution") {
@@ -117,6 +122,7 @@ func validCanvasEdgeData(v any) bool {
}
}
case "execution":
// 执行事件是否启用与展示动画独立,协议只允许布尔 enabled。
if !canvasFields(m, "enabled") {
return false
}
@@ -126,6 +132,7 @@ func validCanvasEdgeData(v any) bool {
}
}
case "path":
// 路径仅支持 bezier-chain,最多 64 个唯一 ID 的 knot,每个 knot 有位置与进/出切线。
if !canvasFields(m, "type", "startControl", "endControl", "knots") || m["type"] != "bezier-chain" {
return false
}
@@ -157,6 +164,7 @@ func validCanvasEdgeData(v any) bool {
if !canvasChoice(knot["mode"], "corner", "smooth", "symmetric") {
return false
}
// smooth 要求非零切线反向共线;symmetric 进一步要求长度相等,使用相对误差容忍浮点噪声。
if knot["mode"] != "corner" {
a, b := knot["in"].(map[string]any), knot["out"].(map[string]any)
ax, ay, bx, by := a["x"].(float64), a["y"].(float64), b["x"].(float64), b["y"].(float64)
+5
View File
@@ -1,3 +1,4 @@
// 画布与资产纯函数回归;测试说明对应实际断言,不依赖浏览器或真实模型。
package platform
import (
@@ -10,6 +11,7 @@ import (
"testing"
)
// TestCanvasV2EdgeRoundTrip 保存带外观、动画、曲线和执行配置的 v2 边,并逐项破坏范围/枚举/切线关系,验证不丢字段且拒绝非法配置。
func TestCanvasV2EdgeRoundTrip(t *testing.T) {
raw := strings.Replace(canvasFixture, `"schema_version":1`, `"schema_version":2`, 1)
data := `{"appearance":{"color":"#AA968B","width":2,"opacity":1,"line":"dashed","head":{"type":"triangle","size":12,"filled":true},"tail":{"type":"circle","size":8,"filled":false}},"animation":{"mode":"executing","effect":"flow","direction":"reverse","durationMs":1600,"color":"#FFFFFF"},"path":{"type":"bezier-chain","startControl":{"x":90,"y":0},"endControl":{"x":-90,"y":0},"knots":[{"id":"k1","position":{"x":450,"y":280},"in":{"x":-60,"y":0},"out":{"x":60,"y":0},"mode":"symmetric"}]},"execution":{"enabled":true}}`
@@ -39,6 +41,7 @@ func TestCanvasV2EdgeRoundTrip(t *testing.T) {
}
}
// TestCanvasSchemaAccept 验证媒体类型列表中的显式 version=2 协商,拒绝 q=0、NaN 和相似但不同的版本号。
func TestCanvasSchemaAccept(t *testing.T) {
for _, tc := range []struct {
accept string
@@ -59,6 +62,7 @@ func TestCanvasSchemaAccept(t *testing.T) {
}
}
// TestCanvasV2CurveLimits 检查 64 个 knot 的边界、重复 knot ID 及非有限/越界点;直接构造 float64 覆盖 JSON 不表示的 NaN。
func TestCanvasV2CurveLimits(t *testing.T) {
knot := func(id string) map[string]any {
return map[string]any{"id": id, "position": map[string]any{"x": 0.0, "y": 0.0}, "in": map[string]any{"x": -1.0, "y": 0.0}, "out": map[string]any{"x": 1.0, "y": 0.0}, "mode": "smooth"}
@@ -86,6 +90,7 @@ func TestCanvasV2CurveLimits(t *testing.T) {
}
}
// TestCanvasV2AppearanceAndAnimationEnums 遍历受支持标记/线型与动画模式/效果/方向的组合,保证合法枚举组合可被接受。
func TestCanvasV2AppearanceAndAnimationEnums(t *testing.T) {
for _, marker := range []string{"none", "open-arrow", "triangle", "circle", "diamond", "square"} {
for _, line := range []string{"solid", "dashed", "dotted"} {
+19
View File
@@ -1,3 +1,4 @@
// 素材内容 schema v1 的纯校验与规范化,不负责网络抓图或数据库存储。
package platform
import (
@@ -8,32 +9,43 @@ import (
"regexp"
)
// Paragraph 与 Section 的 ID 在同一文章内共享唯一命名空间,用于稳定引用内容块。
type Paragraph struct {
ID string `json:"id"`
Text string `json:"text"`
Description string `json:"description,omitempty"`
}
// Section 聚合标题、描述和有序段落;数量及总段落预算由 validArticle 检查。
type Section struct {
ID string `json:"id"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
Paragraphs []Paragraph `json:"paragraphs"`
}
// Article 是有序章节容器,可为空文章,但必须有非 nil 的 Article 对象。
type Article struct {
Sections []Section `json:"sections"`
}
// Image 仅保存 HTTPS 引用及展示信息,尺寸零值表示未提供,不在这里读取远程资源。
type Image struct {
URL string `json:"url"`
Alt string `json:"alt,omitempty"`
Width int `json:"width,omitempty"`
Height int `json:"height,omitempty"`
}
// CardPart 是带 Kind 的互斥联合,一次只能提供对应的 text/article/image 内容。
type CardPart struct {
Kind string `json:"kind"`
Text *string `json:"text,omitempty"`
Article *Article `json:"article,omitempty"`
Image *Image `json:"image,omitempty"`
}
// Content 按素材种类使用互斥字段;board 只存 schema 标记,画布节点通过专用协议管理。
type Content struct {
SchemaVersion int `json:"schema_version"`
Text *string `json:"text,omitempty"`
@@ -44,6 +56,7 @@ type Content struct {
var blockID = regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`)
// validArticle 限制章节、段落和文本字节数,并用一个 seen 集合拒绝章节/段落间任何重复 ID。
func validArticle(article *Article) bool {
if article == nil || len(article.Sections) > 200 {
return false
@@ -68,6 +81,8 @@ func validArticle(article *Article) bool {
}
return true
}
// validImage 校验 URL、替代文本及尺寸范围;拒绝用户名密码和 fragment,不执行资源可达性检查。
func validImage(image *Image) bool {
if image == nil || len(image.URL) > 2048 || len(image.Alt) > 2000 || image.Width < 0 || image.Width > 100000 || image.Height < 0 || image.Height > 100000 {
return false
@@ -75,6 +90,8 @@ func validImage(image *Image) bool {
u, err := url.Parse(image.URL)
return err == nil && u.Scheme == "https" && u.Hostname() != "" && u.User == nil && u.Fragment == ""
}
// validPart 按判别字段检查唯一有效分支,额外的异类内容即使本身合法也会被拒绝。
func validPart(part CardPart) bool {
switch part.Kind {
case "text":
@@ -87,6 +104,8 @@ func validPart(part CardPart) bool {
return false
}
}
// normalizeContent 严格解码单个对象,将缺省版本补为一,并重编码为统一存储形式。
func normalizeContent(kind string, raw json.RawMessage) (json.RawMessage, bool) {
if raw = bytes.TrimSpace(raw); len(raw) == 0 || raw[0] != '{' {
return nil, false
+2
View File
@@ -1,3 +1,4 @@
// 内容 schema 的纯函数回归,不访问数据库或远程图片。
package platform
import (
@@ -5,6 +6,7 @@ import (
"testing"
)
// TestContentValidation 按素材种类检查合法草稿、重复块 ID、未知字段/版本、图片 URL 和互斥内容,并检查规范化输出仍为合法 JSON。
func TestContentValidation(t *testing.T) {
cases := []struct {
name, kind, body string
+4
View File
@@ -1,7 +1,9 @@
// 素材显式授权由有效 admin 管理;授权写入与撤销都先取得相同的工作区/素材权限锁。
package platform
import "net/http"
// materialGrants 返回最多一千条显式授权,或按账户 upsert editor/viewer;不允许授予素材 admin。
func (s *service) materialGrants(w http.ResponseWriter, r *http.Request, project, account string) error {
workspace, material := r.PathValue("workspace"), r.PathValue("material")
if r.Method != http.MethodGet && r.Method != http.MethodPost {
@@ -65,6 +67,8 @@ ON CONFLICT(project,workspace_id,material_id,account_id) DO UPDATE SET role=EXCL
reply(w, 204, nil)
return nil
}
// deleteMaterialGrant 幂等撤销目标账户的素材授权;不存在也返回 204,工作区成员权限不受此操作影响。
func (s *service) deleteMaterialGrant(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
+14
View File
@@ -1,3 +1,4 @@
// Package platform 提供项目隔离的工作区、素材、画布和协作 API;HTTP 认证与业务事务分层处理。
package platform
import (
@@ -17,6 +18,7 @@ import (
"github.com/jackc/pgx/v5/pgconn"
)
// service 共享连接池与启动配置;canvasAI 可缺省,队列仅在配置了客户端时启动。
type service struct {
canvasAI *codex.CanvasClient
db *sql.DB
@@ -25,8 +27,10 @@ type service struct {
onboardingConfigs map[string]OnboardingConfig
}
// response 用于小型 JSON 对象;大型画布文档通常保留 RawMessage 避免重编码字段。
type response map[string]any
// reply 写出 JSON 与 no-store;value 为 nil 时只写状态,供 204 响应使用。
func reply(w http.ResponseWriter, status int, value any) {
w.Header().Set("Content-Type", "application/json")
w.Header().Set("Cache-Control", "no-store")
@@ -36,10 +40,12 @@ func reply(w http.ResponseWriter, status int, value any) {
}
}
// reject 用稳定错误码表示可预期业务拒绝;调用者随后返回 nil,避免 protected 重复响应。
func reject(w http.ResponseWriter, status int, code string) {
reply(w, status, response{"error": code})
}
// decode 对普通业务 JSON 限制 1 MiB,拒绝未知字段以及第二个 JSON 值;失败已经写出 400。
func decode(w http.ResponseWriter, r *http.Request, value any) bool {
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20))
decoder.DisallowUnknownFields()
@@ -54,8 +60,10 @@ func decode(w http.ResponseWriter, r *http.Request, value any) bool {
return true
}
// endpoint 接收已认证的 project/account;具体资源可见性仍由业务处理器在事务内校验。
type endpoint func(http.ResponseWriter, *http.Request, string, string) error
// protected 是统一路由包装:项目白名单/CORS、会话续期、资源别名解析、canonical 写入守卫和错误映射。
func (s *service) protected(callbacks map[string]string, handle endpoint) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
project := r.PathValue("project")
@@ -74,6 +82,7 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
w.Header().Set("Access-Control-Allow-Origin", origin)
w.Header().Set("Access-Control-Expose-Headers", "ETag, X-Canvas-Schema-Version, "+auth.SessionExpiryHeader)
}
// 预检只验证项目和 Origin,不要求 bearer;真正业务请求仍必须通过会话认证。
if r.Method == http.MethodOptions {
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type, If-Match, Idempotency-Key, X-Expected-Account, X-Resource-Id")
@@ -88,11 +97,13 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
account := session.AccountID
if err == nil {
auth.WriteSessionHeaders(w, session)
// 客户端可携带预期账户,阻止浏览器切换身份后把旧页面的写入落到新账户。
if expected := r.Header.Get("X-Expected-Account"); expected != "" && expected != account {
reject(w, 409, "identity_changed")
return
}
}
// 将 slug 或 UUID 统一为 UUID 后再分派,后续 SQL 无需兼容两种引用;这一步不替代资源授权。
if err == nil && r.PathValue("workspace") != "" {
var id string
err = s.db.QueryRowContext(r.Context(), "SELECT id::text FROM workspaces WHERE project=$1 AND (id::text=$2 OR slug=$2)", project, r.PathValue("workspace")).Scan(&id)
@@ -117,6 +128,7 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
if err == nil {
err = handle(w, r, project, account)
}
// 只公开可识别的约束/领域错误;其余依赖错误记录类型并统一返回 503。
if err != nil {
var pg *pgconn.PgError
switch {
@@ -140,6 +152,7 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
}
}
// Register 由 main 装配平台路径;私有 AI 客户端存在时启动进程级队列,公开短链接单独处理。
func Register(mux *http.ServeMux, db *sql.DB, callbacks map[string]string, origin string, configs map[string]OnboardingConfig, clients ...*codex.CanvasClient) {
s := &service{db: db, origin: origin, callbacks: callbacks, onboardingConfigs: configs}
if len(clients) > 0 {
@@ -198,6 +211,7 @@ func Register(mux *http.ServeMux, db *sql.DB, callbacks map[string]string, origi
var usernamePattern = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]{2,39}$`)
// profile 只操作当前项目的本人账户;PATCH 规范化用户名后与 GET 共用完整资料响应。
func (s *service) profile(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method == http.MethodPatch {
var input struct {
+29
View File
@@ -1,3 +1,5 @@
// 平台综合数据库回归:需要 PLATFORM_TEST_DATABASE_URL 指向已迁移的隔离测试库,缺省会跳过。
// 使用随机项目和真实 HTTP handler 覆盖权限、版本、子图事务与资源生命周期,不连接真实 OAuth 或邮件服务。
package platform
import (
@@ -27,6 +29,8 @@ import (
_ "github.com/jackc/pgx/v5/stdlib"
)
// TestOnboardingAndSharing 是跨模块流程测试,后续画布/资产/邮箱检查复用最初创建的三个账户。
// tokens[0] 为所有者,tokens[1] 经邀请成为 viewer,tokens[2] 只按阶段授予局部素材权限。
func TestOnboardingAndSharing(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -60,6 +64,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
tokens = append(tokens, token)
}
// 按引用关系先删除资产绑定、事务和子图,再删除工作区/账户,避免回归数据残留。
defer func() {
_, _ = db.ExecContext(ctx, "DELETE FROM canvas_asset_bindings WHERE project=$1", project)
_, _ = db.ExecContext(ctx, "DELETE FROM canvas_assets WHERE project=$1", project)
@@ -79,6 +84,7 @@ func TestOnboardingAndSharing(t *testing.T) {
Register(mux, db, callbacks, "https://api.example.com", map[string]OnboardingConfig{
project: {RequireWorkspace: true, Questions: []Question{{Key: "purpose", Required: true}}},
})
// call 在内存 recorder 上走真实路由;可选参数依次代表 If-Match、Accept 和幂等键。
call := func(method, path, token string, body any, status int, versions ...string) response {
t.Helper()
encoded, err := json.Marshal(body)
@@ -111,6 +117,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
return out
}
// 首段验证引导重试不重复建工作区,以及分享次数、重复兑换、owner 不可降级和撤销效果。
base := "/projects/" + project
call("GET", base+"/workspaces", "", nil, 401)
call("POST", base+"/onboarding", tokens[0], response{"answers": response{}}, 400)
@@ -145,6 +152,7 @@ func TestOnboardingAndSharing(t *testing.T) {
contentShare := call("POST", workspacePath+"/shares", tokens[0], response{"role": "editor", "material_id": material}, 201)
call("POST", base+"/shares/redeem", tokens[2], response{"token": contentShare["token"]}, 200)
call("GET", workspacePath, tokens[2], nil, 404)
// 素材局部授权不授予工作区可见性;随后验证 viewer/editor 区别与 If-Match 防止旧版本覆盖。
articleContent := response{"schema_version": 1, "article": response{"sections": []any{response{
"id": "chapter-1", "title": "Chapter", "description": "Chapter summary", "paragraphs": []any{response{"id": "p1", "text": "Paragraph", "description": "Paragraph summary"}},
}}}}
@@ -173,6 +181,7 @@ func TestOnboardingAndSharing(t *testing.T) {
board := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Board", "content": response{}}, 201)
boardPath := workspacePath + "/materials/" + board["id"].(string)
// 画布快照版本与素材元数据版本相互独立,保存/改名各自只推进对应版本。
canvasPath := boardPath + "/canvas"
empty := call("GET", canvasPath, tokens[0], nil, 200)
if empty["version"] != float64(1) {
@@ -221,6 +230,7 @@ func TestOnboardingAndSharing(t *testing.T) {
// Restore the material version expected by the pre-existing layout checks below.
// Exercise two independent HTTP transactions against the same expected version.
// 同一旧版本的两个并发保存必须一成一败,不能都成功或出现部分持久化。
encodedSnapshot, _ := json.Marshal(snapshot)
statuses := make(chan int, 2)
start := make(chan struct{})
@@ -253,6 +263,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
// Frames round-trip through PostgreSQL with all label modes and explicit memberships.
// 三种框标签模式逐次落库并回读;失效成员引用必须拒绝且不推进版本。
for index, mode := range []string{"hidden", "fixed", "scaled"} {
version := strconv.Itoa(4 + index)
raw := strings.Replace(frameFixture, `"labelMode":"fixed"`, `"labelMode":"`+mode+`"`, 1)
@@ -304,6 +315,7 @@ func TestOnboardingAndSharing(t *testing.T) {
// Subgraph creation is atomic and idempotent, and cannot be undone by
// a stale or legacy whole-document save.
// 子图创建将文档、子素材、关系和事务回执原子保存;同键重放只返回原结果,不再递增版本。
subBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Subgraphs", "content": response{}}, 201)
subPath := workspacePath + "/materials/" + subBoard["id"].(string) + "/canvas"
accept := "application/vnd.foundry.canvas+json;version=2"
@@ -367,6 +379,7 @@ func TestOnboardingAndSharing(t *testing.T) {
call("POST", dissolveUndoPath, tokens[0], response{"expected_versions": map[string]int64{subBoard["id"].(string): 3, childID: 2}}, 200, "", accept, "88888888-8888-4888-8888-888888888888")
call("GET", childPath, tokens[0], nil, 200, "", accept)
// 旧框迁移先 dry-run 生成计划,陈旧计划不得留下孤儿素材;执行与撤销都验证幂等回执。
migrationBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Legacy migration", "content": response{}}, 201)
migrationPath := workspacePath + "/materials/" + migrationBoard["id"].(string) + "/canvas"
call("PATCH", migrationPath, tokens[0], response{"document": json.RawMessage(legacyMigrationFixture)}, 200, `"1"`)
@@ -423,6 +436,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
parentID := migrationBoard["id"].(string)
memberPath := migrationPath + "/subgraphs/f/members"
// 多画布移动携带完整预期版本及来源局部坐标,要求节点所有权、几何位置和撤销一起生效。
moveCommand := response{"source_board_id": membersSource, "target_board_id": membersTarget, "node_ids": []string{"a"}, "positions": map[string]memberDropPosition{"a": {X: 40, Y: 50}}, "expected_versions": map[string]int64{parentID: 5, membersSource: 1, membersTarget: 1}}
call("POST", memberPath, tokens[0], response{"source_board_id": membersSource, "target_board_id": membersTarget, "node_ids": []string{"a"}, "positions": response{"wrong": response{"x": 1, "y": 2}}, "expected_versions": map[string]int64{parentID: 5, membersSource: 1, membersTarget: 1}}, 400, "", accept, "eeeeeeee-1111-4111-8111-111111111111")
movedMembers := call("POST", memberPath, tokens[0], moveCommand, 200, "", accept, "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb")
@@ -448,6 +462,7 @@ func TestOnboardingAndSharing(t *testing.T) {
parentMove := call("POST", memberPath, tokens[0], response{"source_board_id": parentID, "target_board_id": membersSource, "node_ids": []string{"outside"}, "expected_versions": map[string]int64{parentID: 7, membersSource: 3}}, 200, "", accept, "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee")
call("POST", migrationPath+"/transactions/"+parentMove["transaction_id"].(string)+"/undo", tokens[0], response{"expected_versions": map[string]int64{parentID: 8, membersSource: 4}}, 200, "", accept, "ffffffff-ffff-4fff-8fff-ffffffffffff")
innerCreated := call("POST", sourceCanvasPath+"/subgraphs", tokens[0], response{"frame": response{"id": "inner-frame", "title": "Inner", "position": response{"x": 20, "y": 40}, "width": 400, "height": 300, "labelMode": "fixed"}}, 201, `"5"`, accept, "10000000-0000-4000-8000-000000000001")
// 移动包含子图的框必须重挂原子图关系,而非复制孩子;撤销要恢复原父级。
innerID := innerCreated["child_board"].(map[string]any)["id"].(string)
nestedMove := call("POST", memberPath, tokens[0], response{"source_board_id": membersSource, "target_board_id": membersTarget, "node_ids": []string{"inner-frame"}, "expected_versions": map[string]int64{parentID: 9, membersSource: 6, membersTarget: 3, innerID: 1}}, 200, "", accept, "10000000-0000-4000-8000-000000000002")
var nestedParent string
@@ -461,6 +476,7 @@ func TestOnboardingAndSharing(t *testing.T) {
// Moving an externally exposed node inside a nested frame must repair the
// ancestor boundary atomically and preserve its port/edge identities.
// 嵌套移动和解散需同时修复祖先端口,保留逻辑端点身份;漏报祖先版本应返回 428。
innerMemberPath := sourceCanvasPath + "/subgraphs/inner-frame/members"
nestedMemberCommand := response{"source_board_id": membersSource, "target_board_id": innerID, "node_ids": []string{"b"}, "expected_versions": map[string]int64{parentID: 11, membersSource: 8, innerID: 3}}
nestedMemberMove := call("POST", innerMemberPath, tokens[0], nestedMemberCommand, 200, "", accept, "30000000-0000-4000-8000-000000000001")
@@ -495,6 +511,7 @@ func TestOnboardingAndSharing(t *testing.T) {
if err := png.Encode(&assetPNG, image.NewRGBA(image.Rect(0, 0, 3, 2))); err != nil {
t.Fatal(err)
}
// 上传使用故意错误的文件扩展名验证真实 MIME 嗅探,并可指定客户端预分配资源 ID。
upload := func(encoded []byte, key string, status int, resourceIDs ...string) response {
t.Helper()
var body bytes.Buffer
@@ -538,6 +555,7 @@ func TestOnboardingAndSharing(t *testing.T) {
if !modelEqual(managed, repeated) {
t.Fatal("resource retry changed receipt")
}
// 模拟响应丢失后查询回执:已应用可恢复原资产,未知请求不能被误报为已确定零写入。
lookup := call("GET", workspacePath+"/assets/operations/"+resourceKey, tokens[0], nil, 200)
if lookup["status"] != "applied" || !modelEqual(lookup["asset"], managed["asset"]) {
t.Fatal("lost upload acknowledgment cannot be recovered")
@@ -613,6 +631,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
// Neither a snapshot nor an asset response may keep the workspace locked
// while a slow downstream consumer is accepting its body.
// 在真正写出响应体时另开事务 NOWAIT 抢工作区锁,防止慢消费者拖长数据库锁生命周期。
for _, path := range []string{canvasPath, workspacePath + "/assets/" + uploaded["id"].(string), metadataPath} {
var probeErr error
writer := &readLockProbe{ResponseRecorder: httptest.NewRecorder(), probe: func() {
@@ -634,6 +653,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
// A slow multipart body must not hold the workspace lock either.
func() {
// 管道先交付 multipart 头再暂停正文,探测接收慢上传期间是否错误持有工作区锁。
reader, pipe := io.Pipe()
defer reader.Close()
defer pipe.Close()
@@ -688,6 +708,7 @@ func TestOnboardingAndSharing(t *testing.T) {
download(tokens[0], 200)
download(tokens[1], 404)
download(tokens[2], 404)
// 资产由上传者可读,写入可访问画布并绑定后才允许该画布协作者读取。
assetBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Assets", "content": response{}}, 201)
assetDoc := response{"schema_version": 2, "nodes": []any{response{"id": "asset-node", "type": "plainImage", "position": response{"x": 0, "y": 0}, "data": response{"kind": "plain-image", "title": "Image", "text": "", "src": uploaded["url"], "assetId": uploaded["id"]}}}, "edges": []any{}, "viewport": response{"x": 0, "y": 0, "zoom": 1}}
call("PATCH", workspacePath+"/materials/"+assetBoard["id"].(string)+"/canvas", tokens[0], response{"document": assetDoc}, 200, `"1"`, accept)
@@ -709,6 +730,7 @@ func TestOnboardingAndSharing(t *testing.T) {
// A warm metadata/original cache is not a future permission grant. An external
// collaborator can read through a source board grant, but a new canonical
// target write must recheck asset readability after that grant is revoked.
// 先暖元数据/原图缓存再撤销来源权限,确保新目标写入实时检查授权而非信任缓存命中。
sourceGrantPath := workspacePath + "/materials/" + assetBoard["id"].(string) + "/grants"
call("POST", sourceGrantPath, tokens[0], response{"account_id": accounts[2], "role": "viewer"}, 204)
call("GET", metadataPath, tokens[2], nil, 200)
@@ -752,6 +774,7 @@ func TestOnboardingAndSharing(t *testing.T) {
if !modelEqual(denied, replayedDenial) {
t.Fatal("permission restoration changed a terminal receipt")
}
// 恢复权限后必须新建请求才可成功;目标获得独立绑定后,撤销来源不应破坏目标读权限。
acceptedID := modelTestID(9204)
call("POST", targetPath+"/canvas/model/operations", tokens[2], adoptionRequest(acceptedID, modelTestID(9205)), 200, "", accept, acceptedID)
call("DELETE", sourceGrantPath+"/"+accounts[2], tokens[0], nil, 204)
@@ -765,6 +788,7 @@ func TestOnboardingAndSharing(t *testing.T) {
download(tokens[1], 200)
upload([]byte("not an image"), "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", 400)
// 超出节点预算要求确定拒绝且版本不变;UUID 幂等键大小写应归一到同一次操作。
limitBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Limits", "content": response{}}, 201)
limitPath := workspacePath + "/materials/" + limitBoard["id"].(string) + "/canvas"
oversizedNodes := []any{}
@@ -787,6 +811,7 @@ func TestOnboardingAndSharing(t *testing.T) {
code int
body []byte
}
// 四条并发同键请求应收敛到同一 transaction 和一个子图,而不是各创建一次。
results := make(chan concurrentResult, 4)
startConcurrent := make(chan struct{})
encodedFrame, _ := json.Marshal(caseFrame)
@@ -821,6 +846,7 @@ func TestOnboardingAndSharing(t *testing.T) {
if err := db.QueryRowContext(ctx, `SELECT count(*) FROM canvas_subgraphs WHERE project=$1 AND parent_board_id=$2`, project, concurrentBoard["id"]).Scan(&concurrentChildren); err != nil || concurrentChildren != 1 {
t.Fatalf("concurrent retry duplicated children: %d %v", concurrentChildren, err)
}
// 让父文档接近字节预算,使创建子图在最终父文档校验失败,验证孩子和父版本共同回滚。
rollbackBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Rollback", "content": response{}}, 201)
rollbackPath := workspacePath + "/materials/" + rollbackBoard["id"].(string) + "/canvas"
nearLimit := []any{}
@@ -851,6 +877,7 @@ func TestOnboardingAndSharing(t *testing.T) {
t.Fatal("failed create changed parent version")
}
// 最后用 outbox 内链接完成邮箱验证:未验证不能登录,验证码不可重放,注销后的会话不可访问资料。
email := "fixture@example.invalid"
password := "a-long-fixture-password"
call("POST", base+"/auth/register", "", response{"email": email, "password": password}, 202)
@@ -882,11 +909,13 @@ func TestOnboardingAndSharing(t *testing.T) {
// A real SQL NOWAIT probe at the response-write boundary catches locks that
// would otherwise remain invisible in a buffered httptest recorder.
// readLockProbe 在首个 Write 前执行外部锁探测;只运行一次以免多段响应反复探测。
type readLockProbe struct {
*httptest.ResponseRecorder
probe func()
}
// Write 先清空 probe 再调用,随后交给 recorder 保存实际响应体。
func (w *readLockProbe) Write(body []byte) (int, error) {
if w.probe != nil {
probe := w.probe
+7
View File
@@ -1,3 +1,4 @@
// 旧 board_layouts 路由:布局变更与父素材版本递增同事务执行,canonical 画布由入口守卫限制旧写入。
package platform
import (
@@ -7,6 +8,7 @@ import (
"net/http"
)
// placement 是素材在旧画布内的矩形位置,MaterialID 指向工作区内可访问且非 board 的素材。
type placement struct {
MaterialID string `json:"material_id"`
X float64 `json:"x"`
@@ -16,12 +18,15 @@ type placement struct {
ZIndex int `json:"z_index"`
}
// valid 限制有限坐标、正尺寸和层级范围;NaN 显式拒绝,无穷值也会被范围判断拒绝。
func (p placement) valid() bool {
return !math.IsNaN(p.X) && !math.IsNaN(p.Y) && !math.IsNaN(p.Width) && !math.IsNaN(p.Height) &&
p.X >= -1000000 && p.X <= 1000000 && p.Y >= -1000000 && p.Y <= 1000000 &&
p.Width >= 1 && p.Width <= 100000 && p.Height >= 1 && p.Height <= 100000 &&
p.ZIndex >= -1000000 && p.ZIndex <= 1000000
}
// layouts 对集合提供 GET/POST,对单条提供 PATCH/DELETE;所有写入都比较父画布 If-Match。
func (s *service) layouts(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet && r.Method != http.MethodPost && r.Method != http.MethodPatch && r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
@@ -84,6 +89,7 @@ ORDER BY l.z_index,l.id LIMIT 2000
if !ok {
return nil
}
// 工作区锁保护当前事务内版本检查与写入;不匹配立即返回 412,不进入布局变更。
if expected != version {
reject(w, 412, "version_conflict")
return nil
@@ -141,6 +147,7 @@ WHERE project=$1 AND workspace_id=$2 AND board_id=$3 AND id=$4
return sql.ErrNoRows
}
}
// 即使只移动或删除一条布局,也递增父素材版本,供其他客户端发现画布变更。
_, err = tx.ExecContext(r.Context(), "UPDATE materials SET version=version+1,modified_at=now() WHERE project=$1 AND workspace_id=$2 AND id=$3", project, workspace, board)
if err != nil {
return err
+13
View File
@@ -1,3 +1,4 @@
// 素材 CRUD、根画布授权继承与乐观版本控制;画布专用结构由其他文件处理。
package platform
import (
@@ -8,6 +9,8 @@ import (
"strconv"
)
// lockMaterial 先锁工作区,再向上遍历最多八层子图祖先获取根素材授权,返回目标类型与有效角色。
// 任一祖先关系归档则不可访问;子素材单独授权不能绕过父级。事务由调用方持有。
func lockMaterial(ctx context.Context, tx *sql.Tx, project, workspace, material, account string) (string, string, error) {
var locked, kind, role string
err := tx.QueryRowContext(ctx, "SELECT id::text FROM workspaces WHERE project=$1 AND id=$2 FOR UPDATE", project, workspace).Scan(&locked)
@@ -36,6 +39,7 @@ func lockMaterial(ctx context.Context, tx *sql.Tx, project, workspace, material,
return kind, role, err
}
// expectedVersion 解析带双引号的正整数 If-Match;缺少返回 428,格式错误返回 400。
func expectedVersion(w http.ResponseWriter, r *http.Request) (int64, bool) {
header := r.Header.Get("If-Match")
if header == "" {
@@ -53,10 +57,13 @@ func expectedVersion(w http.ResponseWriter, r *http.Request) (int64, bool) {
}
return version, true
}
// setVersion 将素材版本写成带引号 ETag,与 expectedVersion 的输入格式对应。
func setVersion(w http.ResponseWriter, version int64) {
w.Header().Set("ETag", strconv.Quote(strconv.FormatInt(version, 10)))
}
// materials 的 GET 转入筛选列表,POST 要求工作区编辑权限并按种类验证内容后创建版本一。
func (s *service) materials(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method == http.MethodGet {
return s.listMaterials(w, r, project, account)
@@ -110,6 +117,7 @@ VALUES($1,$2,$3,$4,$5,$6,$7,$8) RETURNING id::text,slug
return nil
}
// material 先校验根级权限;读取返回完整内容与 ETag,修改/删除同时要求角色和预期版本。
func (s *service) material(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet && r.Method != http.MethodPatch && r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
@@ -182,6 +190,7 @@ WHERE project=$1 AND workspace_id=$2 AND id=$3 AND version=$7
if err != nil {
return err
}
// 已通过可见性检查但版本条件未命中,视为并发冲突;事务回滚,不能覆盖其他客户端更新。
if n == 0 {
reject(w, 412, "version_conflict")
return nil
@@ -196,6 +205,7 @@ WHERE project=$1 AND workspace_id=$2 AND id=$3 AND version=$7
return nil
}
// openMaterial 记录当前账户最近打开时间,重复打开更新同一记录,不修改素材内容版本。
func (s *service) openMaterial(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -224,6 +234,7 @@ ON CONFLICT(project,workspace_id,material_id,account_id) DO UPDATE SET opened_at
return nil
}
// listMaterials 按授权与筛选返回元数据,默认隐藏子图;排序片段只从固定白名单选择。
func (s *service) listMaterials(w http.ResponseWriter, r *http.Request, project, account string) error {
sort := r.URL.Query().Get("sort")
orders := map[string]string{
@@ -267,6 +278,7 @@ func (s *service) listMaterials(w http.ResponseWriter, r *http.Request, project,
reject(w, 400, "invalid_filter")
return nil
}
// 子图默认通过父画布进入;显式请求后仍需根级权限且整条祖先链未归档。
includeSubgraphs := false
if value := r.URL.Query().Get("include_subgraphs"); value != "" {
if value != "true" && value != "false" {
@@ -314,6 +326,7 @@ ORDER BY `+order+` LIMIT $7 OFFSET $8`, project, r.PathValue("workspace"), accou
if err := rows.Err(); err != nil {
return err
}
// SQL 多取一条探测后页;响应截回 limit,并给出下一次应使用的 offset。
var next *int
if len(items) > limit {
items = items[:limit]
+5
View File
@@ -1,3 +1,4 @@
// 子图成员拖放可附带来源画布局部坐标;此处只更新来源文档,目标坐标转换由所有权事务完成。
package platform
import (
@@ -8,11 +9,13 @@ import (
// Positions are expressed in the source board's local coordinates. The existing
// ownership transaction converts them into destination coordinates exactly once.
// memberDropPosition 必须显式携带 x/y,避免遗漏字段被当作零而让节点意外跳位。
type memberDropPosition struct {
X float64 `json:"x"`
Y float64 `json:"y"`
}
// validMemberDropPositions 兼容缺省坐标的旧客户端;提供时必须与成员 ID 集合完全一致且坐标有限。
func validMemberDropPositions(ids []string, positions map[string]memberDropPosition) bool {
if positions == nil {
return true
@@ -31,6 +34,7 @@ func validMemberDropPositions(ids []string, positions map[string]memberDropPosit
return true
}
// positionMemberDrop 在 JSON 节点数组中替换所有指定位置,缺节点或非法文档返回所有权错误。
func positionMemberDrop(raw json.RawMessage, positions map[string]memberDropPosition) (json.RawMessage, error) {
var doc map[string]any
if err := json.Unmarshal(raw, &doc); err != nil {
@@ -58,6 +62,7 @@ func positionMemberDrop(raw json.RawMessage, positions map[string]memberDropPosi
return json.Marshal(doc)
}
// UnmarshalJSON 只接受两个非 null 数值字段;范围与有限性由 validMemberDropPositions 继续检查。
func (p *memberDropPosition) UnmarshalJSON(raw []byte) error {
var fields map[string]json.RawMessage
if err := json.Unmarshal(raw, &fields); err != nil {
+3
View File
@@ -1,3 +1,4 @@
// 成员拖放纯文档回归,复用子图 fixture 验证来源坐标只转换一次。
package platform
import (
@@ -6,6 +7,8 @@ import (
"testing"
)
// TestMemberDropPositions 先更新来源局部位置,再执行跨子图移动,断言目标坐标为 (140,250)。
// 另覆盖缺失成员、不匹配 ID 集合、非有限/越界坐标及缺字段或 null 的严格解码。
func TestMemberDropPositions(t *testing.T) {
raw := memberFixture(t)
source := "11111111-1111-4111-8111-111111111111"
+9
View File
@@ -1,3 +1,4 @@
// 项目可配置的首次引导:账号资料、工作区、可选邀请和问卷在一个事务内完成。
package platform
import (
@@ -9,10 +10,13 @@ import (
"strings"
)
// Question 引用 surveyTypes 中的固定题目键,Required 决定缺省或空白答案是否允许。
type Question struct {
Key string `json:"key"`
Required bool `json:"required"`
}
// OnboardingConfig 按项目配置必需工作区及问题清单,缺省配置允许空引导。
type OnboardingConfig struct {
RequireWorkspace bool `json:"require_workspace"`
Questions []Question `json:"questions"`
@@ -23,6 +27,7 @@ var surveyTypes = map[string]string{
"previous_use": "boolean", "purpose": "string", "company_size": "string",
}
// ParseOnboarding 启动时严格解析配置,拒绝未配置项目、未知题目和重复键。
func ParseOnboarding(raw string, callbacks map[string]string) (map[string]OnboardingConfig, error) {
configs := map[string]OnboardingConfig{}
if strings.TrimSpace(raw) == "" {
@@ -51,6 +56,7 @@ func ParseOnboarding(raw string, callbacks map[string]string) (map[string]Onboar
return configs, nil
}
// validAnswers 先验证提交键与类型,再检查必答题;必答布尔 false 合法,null 与空白必答文本不合法。
func validAnswers(config OnboardingConfig, answers map[string]json.RawMessage) bool {
questions := map[string]Question{}
for _, question := range config.Questions {
@@ -89,6 +95,7 @@ func validAnswers(config OnboardingConfig, answers map[string]json.RawMessage) b
return true
}
// onboarding GET 返回配置和已完成状态;POST 锁账户后检查既有结果,防止并发创建重复工作区。
func (s *service) onboarding(w http.ResponseWriter, r *http.Request, project, account string) error {
config := s.onboardingConfigs[project]
if config.Questions == nil {
@@ -143,6 +150,7 @@ func (s *service) onboarding(w http.ResponseWriter, r *http.Request, project, ac
}
var prior json.RawMessage
err = tx.QueryRowContext(r.Context(), "SELECT result FROM onboarding_responses WHERE project=$1 AND account_id=$2", project, account).Scan(&prior)
// 已完成直接返回已存 result;邀请明文不落库,所以重复请求不会重新返回 invite_url。
if err == nil {
reply(w, 200, response{"completed": true, "result": prior, "already_completed": true})
return nil
@@ -178,6 +186,7 @@ VALUES($1,$2,$3,'viewer',$4,now()+interval '7 days') RETURNING id::text
invitation = s.origin + "/s/" + token
}
}
// 结果只保存工作区和邀请 ID;明文 URL 仅随首次成功提交返回。
answers, _ := json.Marshal(input.Answers)
resultJSON, _ := json.Marshal(result)
_, err = tx.ExecContext(r.Context(), "INSERT INTO onboarding_responses(project,account_id,answers,result) VALUES($1,$2,$3,$4)", project, account, answers, resultJSON)
+12
View File
@@ -1,3 +1,4 @@
// 邀请链接分离公开点击与登录后兑换:点击只记录来源,兑换才增加角色和使用次数。
package platform
import (
@@ -14,17 +15,21 @@ import (
var linkTokenPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{22}$`)
// newLinkToken 产生十六随机字节的公开邀请凭据及落库摘要;明文仅在创建响应中给出。
func newLinkToken() (string, string) {
var raw [16]byte
rand.Read(raw[:])
value := base64.RawURLEncoding.EncodeToString(raw[:])
return value, linkDigest(value)
}
// linkDigest 与 newLinkToken/shortLink/redeemShare 共用相同摘要格式,数据库不保存邀请明文。
func linkDigest(token string) string {
sum := sha256.Sum256([]byte(token))
return base64.RawURLEncoding.EncodeToString(sum[:])
}
// shareInput 可邀请加入整个工作区或单个素材;单素材不能授予 admin,缺省有效期七天。
type shareInput struct {
Role string `json:"role"`
MaterialID *string `json:"material_id"`
@@ -32,6 +37,7 @@ type shareInput struct {
MaxUses *int `json:"max_uses"`
}
// shares 仅供工作区 admin 列表或创建邀请;列表返回统计和链接 ID,不可还原原始 token。
func (s *service) shares(w http.ResponseWriter, r *http.Request, project, account string) error {
workspace := r.PathValue("workspace")
if r.Method != http.MethodPost && r.Method != http.MethodGet {
@@ -110,6 +116,7 @@ VALUES($1,$2,$3,$4,$5,$6,now()+$7*interval '1 second',$8) RETURNING id::text,exp
return nil
}
// revokeShare 设置首次撤销时间,重复撤销保留时间;只阻止未来兑换,不回收已授予角色。
func (s *service) revokeShare(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
@@ -150,6 +157,7 @@ UPDATE share_links SET revoked_at=COALESCE(revoked_at,now()) WHERE project=$1 AN
// A public short link records only a referring origin and redirects to a fixed
// frontend. The fragment carries the invitation, never a login session.
// shortLink 是无需会话的公开入口,只记录 Referer 的 origin,邀请 token 放入固定前端回调 fragment。
func (s *service) shortLink(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Cache-Control", "no-store")
w.Header().Set("Referrer-Policy", "no-referrer")
@@ -202,6 +210,7 @@ SELECT project FROM click
http.Redirect(w, r, destination.String(), 302)
}
// redeemShare 按工作区再链接的顺序加锁,原子校验有效期、容量与既往兑换记录。
func (s *service) redeemShare(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -243,6 +252,7 @@ FROM share_links WHERE project=$1 AND workspace_id=$2 AND token_hash=$3 FOR UPDA
if err != nil {
return err
}
// 已兑换者可在容量耗尽后重复读取结果,但链接过期或撤销后仍不可兑换。
if !allowed || (!capacity && !redeemed) {
reject(w, 410, "share_unavailable")
return nil
@@ -257,6 +267,7 @@ INSERT INTO share_redemptions(project,workspace_id,link_id,account_id) VALUES($1
if err != nil {
return err
}
// 唯一兑换记录插入成功才提升角色并计数;重复请求不重复消耗额度,也不降低原有更高角色。
if n > 0 {
if material == nil {
_, err = tx.ExecContext(r.Context(), `
@@ -287,6 +298,7 @@ ON CONFLICT(project,workspace_id,material_id,account_id) DO UPDATE SET role=CASE
return nil
}
// shareClicks 仅 admin 可读,按递减点击 ID 做游标分页,多取一条判断 next_before。
func (s *service) shareClicks(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
+2
View File
@@ -1,3 +1,4 @@
// 资源别名使用小写连字符格式,避免与受保护路由可直接接受的 UUID 引用发生歧义。
package platform
import "regexp"
@@ -7,6 +8,7 @@ var slugPattern = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
var uuidSlugPattern = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`)
// Slugs remain stable across renames unless explicitly changed by an authorized edit.
// validSlug 的 nil 表示创建时由数据库生成或更新时保留原值;非 nil 必须非空、最多百字节且非 UUID。
func validSlug(slug *string) bool {
return slug == nil || (len(*slug) <= 100 && slugPattern.MatchString(*slug) && !uuidSlugPattern.MatchString(*slug))
}
@@ -1,3 +1,4 @@
// 节点迁移/解散时修复上一层祖先端口;外层 port ID 保持稳定,因此更高层链路无需全部重写。
package platform
import (
@@ -9,7 +10,10 @@ import (
"strings"
)
// ancestorPortChange 保存受影响外层端口 ID 及其原始真实节点、handle 与方向。
type ancestorPortChange struct{ PortID, NodeID, Handle, Direction string }
// ancestorPortRepair 描述需加入版本事务的祖先画布、对应 frame 和最小端口修改集。
type ancestorPortRepair struct {
Ancestor, Frame string
Changes []ancestorPortChange
@@ -17,6 +21,7 @@ type ancestorPortRepair struct {
// A parent keeps stable port IDs. Updating that one boundary also preserves all
// higher ancestor chains, which continue to reference the same frame/port pair.
// planAncestorPortRepair 只制定计划:读取父级所属关系与祖先快照,选出直接或经 source frame 暴露的移动节点。
func planAncestorPortRepair(r *http.Request, tx *sql.Tx, project, workspace, parent, source, account string, nodeIDs []string, before json.RawMessage) (*ancestorPortRepair, error) {
relation, err := readSubgraphRelation(r, tx, project, workspace, parent)
if err == sql.ErrNoRows {
@@ -56,6 +61,7 @@ func planAncestorPortRepair(r *http.Request, tx *sql.Tx, project, workspace, par
handle := port["handle"].(string)
direction := port["direction"].(string)
affected := source == parent && selected[node]
// 来源是孩子时再解开一层 port:<id>,确定祖先端口实际引用的移动成员。
if !affected && source != parent {
data := parentNodes[node]
sub, _ := data["subgraph"].(map[string]any)
@@ -82,6 +88,9 @@ func planAncestorPortRepair(r *http.Request, tx *sql.Tx, project, workspace, par
}
return result, nil
}
// applyAncestorPortRepair 对副本补齐目标 frame 内端口,再在祖先中保留原 PortID 只换指向。
// target==parent 表示节点已展开到父级,可直接指向真实节点,无需新的中间端口。
func applyAncestorPortRepair(repair *ancestorPortRepair, parent, target string, documents map[string]json.RawMessage) error {
if repair == nil {
return nil
@@ -157,6 +166,7 @@ func applyAncestorPortRepair(repair *ancestorPortRepair, parent, target string,
return errGraphOwnership
}
}
// 父和祖先都重新规范化后写回结果映射;数据库版本推进与提交仍由外层命令负责。
for board, doc := range map[string]map[string]any{parent: parentDoc, repair.Ancestor: ancestorDoc} {
encoded, _ := json.Marshal(doc)
normalized, ok := normalizeCanvas(encoded)
+6
View File
@@ -1,3 +1,4 @@
// 子图解散的纯文档变换:把孩子内容还原到父坐标,移除 frame,并将孩子文档清空。
package platform
import (
@@ -5,6 +6,7 @@ import (
"errors"
)
// 领域错误由 HTTP 层分别映射为所有权冲突或图预算超限。
var errGraphOwnership = errors.New("ownership_conflict")
var errGraphCapacity = errors.New("graph_limit_exceeded")
@@ -12,6 +14,7 @@ var errGraphCapacity = errors.New("graph_limit_exceeded")
// ownership changes atomically after checking every participating version.
// An empty child document is returned so the archived board does not remain a
// second live owner of the nodes restored to the parent.
// dissolveDocuments 对父子文档副本操作;节点/边 ID 冲突整体拒绝,不能改名或保留双重活跃所有者。
func dissolveDocuments(parentRaw, childRaw json.RawMessage, frameID string) (json.RawMessage, json.RawMessage, error) {
var parent, child map[string]any
if err := json.Unmarshal(parentRaw, &parent); err != nil {
@@ -50,6 +53,7 @@ func dissolveDocuments(parentRaw, childRaw json.RawMessage, frameID string) (jso
scale = value
}
}
// 位置按 frame 内容偏移与缩放映回父画布,节点固有尺寸、文本和嵌套缩放保持原值。
childKinds := map[string]string{}
for _, v := range childNodes {
n := v.(map[string]any)
@@ -73,6 +77,7 @@ func dissolveDocuments(parentRaw, childRaw json.RawMessage, frameID string) (jso
ports[p["id"].(string)] = p
}
}
// 父边经过旧 frame 端口还原到真实孩子节点;孩子内部边迁入父文档时须检查边 ID 冲突。
edges := parent["edges"].([]any)
edgeIDs := map[string]bool{}
for _, v := range edges {
@@ -128,6 +133,7 @@ func dissolveDocuments(parentRaw, childRaw json.RawMessage, frameID string) (jso
return normalized, empty, nil
}
// projectEdgePath 对绝对 knot 做缩放和平移,对端点控制及 in/out 相对向量只缩放。
func projectEdgePath(e map[string]any, scale, x, y float64) {
data, _ := e["data"].(map[string]any)
path, _ := data["path"].(map[string]any)
@@ -1,3 +1,4 @@
// 解散事务:归档直接孩子、提升嵌套孩子的父级、展开文档并修复祖先端口,保留可撤销记录。
package platform
import (
@@ -7,6 +8,7 @@ import (
"time"
)
// dissolveSubgraph 在 v2 编辑权限下收集父/孩子/嵌套孩子及必要祖先,要求所有参与者版本一致。
func (s *service) dissolveSubgraph(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -64,6 +66,7 @@ func (s *service) dissolveSubgraph(w http.ResponseWriter, r *http.Request, proje
if err != nil {
return err
}
// 孩子保留关系恢复记录但设为归档;其直接嵌套孩子会迁到当前父画布而不是一并归档。
archivedRelation := relation
archivedRelation.Archived = true
changes := []subgraphRelationChange{{Before: relation, After: archivedRelation}}
@@ -108,6 +111,7 @@ func (s *service) dissolveSubgraph(w http.ResponseWriter, r *http.Request, proje
for node := range canvasNodeData(childBefore.Document) {
members = append(members, node)
}
// 祖先若引用将被展开的成员,修复计划保持原外层端口 ID,只更新其逻辑节点/handle。
repair, err := planAncestorPortRepair(r, tx, project, workspace, board, child, account, members, parentBefore.Document)
if err != nil {
return err
@@ -172,11 +176,13 @@ func (s *service) dissolveSubgraph(w http.ResponseWriter, r *http.Request, proje
snapshots[child] = childSnapshot
// Reparent nested children first. The archived child keeps a recovery record,
// while live ownership immediately follows the nodes flattened into the parent.
// 先重挂嵌套关系再归档当前孩子,避免活跃所有权暂时落在已归档父级下。
for i := len(changes) - 1; i >= 0; i-- {
if err = writeSubgraphRelation(r, tx, project, workspace, changes[i].After); err != nil {
return err
}
}
// 即使部分参与者文档未变也推进版本,使所有权变化对客户端的版本向量可见。
updated := []canvasSnapshot{}
versions := map[string]int64{}
for _, id := range participants {
@@ -1,3 +1,4 @@
// 子图解散纯算法回归,将旧图先迁移再展开,验证数据恢复与失败输入不变。
package platform
import (
@@ -6,6 +7,7 @@ import (
"testing"
)
// TestMigrateDissolveRestoresContentAndEdges 比对节点和边的语义对象;去掉旧 frameId 后应恢复内容/几何,孩子节点和边清空。
func TestMigrateDissolveRestoresContentAndEdges(t *testing.T) {
raw := json.RawMessage(legacyMigrationFixture)
parent, children, err := migrateLegacyDocument(raw, map[string]string{"f": "11111111-1111-4111-8111-111111111111", "empty": "22222222-2222-4222-8222-222222222222"})
@@ -47,6 +49,8 @@ func TestMigrateDissolveRestoresContentAndEdges(t *testing.T) {
t.Fatal("archived child duplicates live content")
}
}
// canvasNodesByID 将测试快照索引为节点对象,供跨文件几何和所有权断言复用。
func canvasNodesByID(raw json.RawMessage) map[string]map[string]any {
var doc map[string]any
_ = json.Unmarshal(raw, &doc)
@@ -57,6 +61,8 @@ func canvasNodesByID(raw json.RawMessage) map[string]map[string]any {
}
return out
}
// TestDissolveRejectsNodeCollisionWithoutMutatingInputs 将孩子节点改为父节点同名,要求所有权冲突而非覆盖,且源父 JSON 不变。
func TestDissolveRejectsNodeCollisionWithoutMutatingInputs(t *testing.T) {
parent, children, err := migrateLegacyDocument(json.RawMessage(legacyMigrationFixture), map[string]string{"f": "11111111-1111-4111-8111-111111111111", "empty": "22222222-2222-4222-8222-222222222222"})
if err != nil {
+14
View File
@@ -1,3 +1,4 @@
// 成员跨父/子或兄弟子画布移动的纯变换,先解析真实逻辑端点,再按新所有者重建边界。
package platform
import (
@@ -7,8 +8,13 @@ import (
"sort"
)
// canvasCoordinateSpace 表示相对于协调父画布的内容原点与展示缩放,不包含 viewport。
type canvasCoordinateSpace struct{ X, Y, Scale float64 }
// memberLogicalEndpoint 用原画布/节点复合 Key 保留身份,避免不同画布同名节点被错误合并。
type memberLogicalEndpoint struct{ Key, Handle string }
// memberLogicalEdge 保留原边对象、来源坐标空间和解析后的真实端点,供重新选择边所有者。
type memberLogicalEdge struct {
OriginalBoard string
Data map[string]any
@@ -17,6 +23,7 @@ type memberLogicalEdge struct {
// All documents are copied before transforming them. Each node/edge retains its
// ID; collisions in a destination reject the entire operation instead of renaming.
// moveMembersDocuments 只修改新解码副本,保留节点/边 ID;任何目标 ID 冲突都整体拒绝,不自动改名。
func moveMembersDocuments(parent, source, target string, nodeIDs []string, raw map[string]json.RawMessage) (map[string]json.RawMessage, error) {
if source == target || source == "" || target == "" || len(nodeIDs) == 0 {
return nil, errGraphOwnership
@@ -35,6 +42,7 @@ func moveMembersDocuments(parent, source, target string, nodeIDs []string, raw m
if docs[parent] == nil || docs[source] == nil || docs[target] == nil {
return nil, errGraphOwnership
}
// 允许 parent 和其直接子画布间变换;内容偏移为 frame 原点加 (24,36),再应用 contentScale。
spaces := map[string]canvasCoordinateSpace{parent: {Scale: 1}}
frames := map[string]map[string]any{}
childForFrame := map[string]string{}
@@ -92,6 +100,7 @@ func moveMembersDocuments(parent, source, target string, nodeIDs []string, raw m
if targetFrame := frames[target]; targetFrame != nil && source == parent && id == targetFrame["id"] {
return nil, errGraphOwnership
}
// 先映到父坐标再映到目标局部坐标;节点固有宽高不随 presentation 缩放被破坏性重写。
owner[key] = target
p := n["position"].(map[string]any)
from, to := spaces[source], spaces[target]
@@ -99,6 +108,7 @@ func moveMembersDocuments(parent, source, target string, nodeIDs []string, raw m
p["y"] = (from.Y + from.Scale*p["y"].(float64) - to.Y) / to.Scale
delete(n["data"].(map[string]any), "frameId")
}
// 将父边的 frame port 展开为孩子真实端点,再决定迁移后边归哪个画布所有。
resolve := func(board, node, handle string) (memberLogicalEndpoint, error) {
if board == parent {
if child := childForFrame[node]; child != "" {
@@ -143,6 +153,7 @@ func moveMembersDocuments(parent, source, target string, nodeIDs []string, raw m
}
// Remove ports whose target changed ownership. Rebuild only the boundaries
// still needed by logical edges; stable endpoint hashes deduplicate retries.
// 删除已转移节点对应的旧端口,保留未移动端点的稳定端口 ID。
for child, frame := range frames {
data := frame["data"].(map[string]any)
ports, _ := data["ports"].([]any)
@@ -170,6 +181,7 @@ func moveMembersDocuments(parent, source, target string, nodeIDs []string, raw m
outputNodes[destination] = append(outputNodes[destination], n)
}
}
// 边留在父画布而端点在孩子时,复用或补齐该孩子 frame 的端口;同画布直接引用真实节点。
endpoint := func(value memberLogicalEndpoint, edgeBoard, direction string) (string, string, error) {
board := owner[value.Key]
n := nodes[value.Key]
@@ -201,6 +213,7 @@ func moveMembersDocuments(parent, source, target string, nodeIDs []string, raw m
data["ports"] = append(ports, map[string]any{"id": id, "nodeId": node, "handle": handle, "direction": direction})
return frame["id"].(string), "port:" + id, nil
}
// 两端新所有者相同时边下沉,否则留在父画布;曲线位置/向量一起按对应空间转换。
for _, edge := range logical {
destination := parent
if owner[edge.Source.Key] == owner[edge.Target.Key] {
@@ -236,6 +249,7 @@ func moveMembersDocuments(parent, source, target string, nodeIDs []string, raw m
projectEdgePath(e, from.Scale/to.Scale, (from.X-to.X)/to.Scale, (from.Y-to.Y)/to.Scale)
outputEdges[destination] = append(outputEdges[destination], e)
}
// 所有输出重新规范化后才返回;调用方负责原子保存,不能逐张提前提交。
result := map[string]json.RawMessage{}
for _, board := range boards {
doc := docs[board]
@@ -1,3 +1,4 @@
// 成员移动事务把文档重分配、嵌套孩子重挂、祖先端口修复和回执组合为一个原子操作。
package platform
import (
@@ -7,6 +8,7 @@ import (
"time"
)
// moveSubgraphMembers 要求源/目标至少一侧是路径 frame 的孩子,另一侧只能是父或其直接孩子。
func (s *service) moveSubgraphMembers(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -81,6 +83,7 @@ func (s *service) moveSubgraphMembers(w http.ResponseWriter, r *http.Request, pr
reject(w, 409, "ownership_conflict")
return nil
}
// 参与集合首先包括协调父、源与目标;移动嵌套 frame 时还需加入其所有后代以校验版本和权限。
participants := map[string]bool{parent: true, input.Source: true, input.Target: true}
for _, board := range []string{input.Source, input.Target} {
if board == parent {
@@ -99,6 +102,7 @@ func (s *service) moveSubgraphMembers(w http.ResponseWriter, r *http.Request, pr
if err != nil {
return err
}
// frame 节点移动保留子画布 ID,只改变关系的 Parent;不可移到自己或后代内部形成循环。
sourceNodes := canvasNodeData(sourceSnapshot.Document)
changes := []subgraphRelationChange{}
for _, node := range input.Nodes {
@@ -155,6 +159,7 @@ func (s *service) moveSubgraphMembers(w http.ResponseWriter, r *http.Request, pr
if err != nil {
return err
}
// 若父画布对外暴露了被移动节点,还要将上一层祖先加入事务,保持端口链可解析。
repair, err := planAncestorPortRepair(r, tx, project, workspace, parent, input.Source, account, input.Nodes, parentSnapshot.Document)
if err != nil {
return err
@@ -162,6 +167,7 @@ func (s *service) moveSubgraphMembers(w http.ResponseWriter, r *http.Request, pr
if repair != nil {
participants[repair.Ancestor] = true
}
// 要求版本表完整且不夹带额外项,防止只确认局部版本就改写更大所有权子树。
if len(input.Expected) != len(participants) {
reject(w, 428, "version_required")
return nil
@@ -199,6 +205,7 @@ func (s *service) moveSubgraphMembers(w http.ResponseWriter, r *http.Request, pr
before = append(before, snapshot)
}
raw := map[string]json.RawMessage{parent: snapshots[parent].Document, input.Source: snapshots[input.Source].Document, input.Target: snapshots[input.Target].Document}
// 可选落点先写到来源局部文档,再交纯算法做一次空间转换,不能提前写成目标坐标。
if input.Positions != nil {
positioned, err := positionMemberDrop(raw[input.Source], input.Positions)
if err != nil {
@@ -222,6 +229,7 @@ func (s *service) moveSubgraphMembers(w http.ResponseWriter, r *http.Request, pr
return err
}
}
// 写关系、保存所有参与快照并记录 before/after 版本,同一事务出错即回滚。
for _, change := range changes {
if err = writeSubgraphRelation(r, tx, project, workspace, change.After); err != nil {
return err
@@ -1,3 +1,4 @@
// 跨兄弟子图和父级的成员移动回归,复用迁移结果作为真实端口/边界结构输入。
package platform
import (
@@ -6,6 +7,7 @@ import (
"testing"
)
// memberFixture 生成父、非空孩子和空孩子三份 JSON 快照,所有用例得到独立副本。
func memberFixture(t *testing.T) map[string]json.RawMessage {
t.Helper()
parent, children, err := migrateLegacyDocument(json.RawMessage(legacyMigrationFixture), map[string]string{"f": "11111111-1111-4111-8111-111111111111", "empty": "22222222-2222-4222-8222-222222222222"})
@@ -14,6 +16,8 @@ func memberFixture(t *testing.T) map[string]json.RawMessage {
}
return map[string]json.RawMessage{"parent": parent, "11111111-1111-4111-8111-111111111111": children["f"], "22222222-2222-4222-8222-222222222222": children["empty"]}
}
// TestMembersMoveSiblingsAndRestoreParent 先后将边两端移到另一孩子,检查内部边随所有者下沉;再移回父级恢复原坐标和三条边。
func TestMembersMoveSiblingsAndRestoreParent(t *testing.T) {
raw := memberFixture(t)
a, b := "11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222"
@@ -60,6 +64,8 @@ func TestMembersMoveSiblingsAndRestoreParent(t *testing.T) {
t.Fatal("duplicate content after move")
}
}
// TestMembersRejectCollisionCyclesAndCapacity 实际覆盖框移入自身、重复成员和满父画布;容量拒绝后输入孩子 JSON 必须字节不变。
func TestMembersRejectCollisionCyclesAndCapacity(t *testing.T) {
raw := memberFixture(t)
child := "11111111-1111-4111-8111-111111111111"
+11
View File
@@ -1,3 +1,4 @@
// 显式 legacy frameId 成员迁移为独立子画布的纯算法;不读写数据库,不按几何重叠推断成员。
package platform
import (
@@ -10,12 +11,15 @@ import (
// A plan contains only explicit legacy memberships. Coordinates are local to
// the containing canvas; the viewport is never part of this transformation.
// legacyFramePlan 按框列出成员节点、内部边和边界边,供 dry-run 解释实际迁移范围。
type legacyFramePlan struct {
FrameID string `json:"frame_id"`
NodeIDs []string `json:"node_ids"`
InternalEdges []string `json:"internal_edges"`
BoundaryEdges []string `json:"boundary_edges"`
}
// legacyMigrationPlan 将计划绑定项目/工作区/父 ID、版本和源文档摘要,防止按陈旧预览执行。
type legacyMigrationPlan struct {
PlanID string `json:"plan_id"`
ParentVersion int64 `json:"parent_version"`
@@ -25,6 +29,7 @@ type legacyMigrationPlan struct {
Issues []string `json:"issues"`
}
// legacyPlan 从已校验快照提取尚未拥有 subgraph 的框,排序框/成员以稳定展示和计划身份。
func legacyPlan(project, workspace string, parent canvasSnapshot) legacyMigrationPlan {
var doc map[string]any
_ = json.Unmarshal(parent.Document, &doc)
@@ -76,6 +81,7 @@ func legacyPlan(project, workspace string, parent canvasSnapshot) legacyMigratio
// migrateLegacyDocument mutates only a freshly decoded snapshot. Boundary edges
// stay in the parent and are redirected through stable, deduplicated ports.
// migrateLegacyDocument 解码复制后按 frame→child ID 映射拆分文档;每个输出都经过 normalizeCanvas。
func migrateLegacyDocument(raw json.RawMessage, children map[string]string) (json.RawMessage, map[string]json.RawMessage, error) {
var doc map[string]any
if err := json.Unmarshal(raw, &doc); err != nil {
@@ -94,6 +100,7 @@ func migrateLegacyDocument(raw json.RawMessage, children map[string]string) (jso
childDocs[id] = map[string]any{"schema_version": 2, "nodes": []any{}, "edges": []any{}, "viewport": map[string]any{"x": 0, "y": 0, "zoom": 1}}
}
}
// 子节点坐标减去框原点及内容内边距 (24,36),同时去掉旧 frameId,父文档保留框。
parentNodes := []any{}
for _, v := range nodes {
n := v.(map[string]any)
@@ -117,6 +124,7 @@ func migrateLegacyDocument(raw json.RawMessage, children map[string]string) (jso
d["ports"] = []any{}
d["presentation"] = map[string]any{"collapsed": false, "contentScale": 1, "expandedSize": map[string]any{"width": f["width"], "height": f["height"]}, "collapsedSize": map[string]any{"width": 240, "height": 140}}
}
// 同一孩子内的边随节点移动;跨边界边留在父画布,通过按逻辑端点派生的稳定端口连接。
parentEdges := []any{}
for _, v := range edges {
e := v.(map[string]any)
@@ -134,6 +142,7 @@ func migrateLegacyDocument(raw json.RawMessage, children map[string]string) (jso
if frame == "" {
continue
}
// 旧边缺 handle 时按源右/目标左补缺省,再由方向、节点与 handle 去重端口。
handle, _ := e[end+"Handle"].(string)
if handle == "" {
if end == "source" {
@@ -183,6 +192,8 @@ func migrateLegacyDocument(raw json.RawMessage, children map[string]string) (jso
}
return parent, result, nil
}
// translateEdgeKnots 仅平移绝对 knot 位置,端点控制与 knot in/out 是相对向量,不受纯平移影响。
func translateEdgeKnots(e map[string]any, x, y float64) {
data, _ := e["data"].(map[string]any)
path, _ := data["path"].(map[string]any)
@@ -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 {
@@ -1,3 +1,4 @@
// 旧 frameId 迁移纯算法回归:检查唯一所有权、边界端口和坐标转换,不创建真实数据库子素材。
package platform
import (
@@ -6,6 +7,8 @@ import (
"testing"
)
// legacyMigrationFixture 同时包含显式成员、空框、仅几何重叠的非成员、内部边和共享端点的边界边。
// viewport 刻意设为非零,用于发现错误地将屏幕变换应用到持久坐标。
const legacyMigrationFixture = `{"schema_version":1,"nodes":[
{"id":"f","type":"frame","position":{"x":100,"y":200},"width":640,"height":400,"data":{"kind":"frame","title":"Frame","text":"","labelMode":"fixed"}},
{"id":"empty","type":"frame","position":{"x":0,"y":0},"width":400,"height":300,"data":{"kind":"frame","title":"Empty","text":""}},
@@ -14,6 +17,8 @@ const legacyMigrationFixture = `{"schema_version":1,"nodes":[
{"id":"outside","type":"material","position":{"x":160,"y":270},"data":{"kind":"text","title":"Not a member","text":"overlaps frame"}}
],"edges":[{"id":"internal","source":"a","target":"b","sourceHandle":"right","targetHandle":"left"},{"id":"boundary","source":"b","target":"outside","sourceHandle":"right","targetHandle":"left"},{"id":"boundary-2","source":"b","target":"outside","sourceHandle":"right","targetHandle":"top"}],"viewport":{"x":2000,"y":3000,"zoom":2}}`
// TestLegacyMigrationOwnershipAndBoundary 检查空框也进入计划、只有显式成员迁入孩子、重复逻辑端点复用一个端口。
// 并验证计划随版本变化,迁移后的已关联框不会再次被计划迁移。
func TestLegacyMigrationOwnershipAndBoundary(t *testing.T) {
parent := canvasSnapshot{BoardID: "parent", Version: 5, Document: json.RawMessage(legacyMigrationFixture)}
plan := legacyPlan("p", "w", parent)
@@ -78,6 +83,7 @@ func TestLegacyMigrationOwnershipAndBoundary(t *testing.T) {
}
}
// TestMigrationPreservesBezierGeometry 对内部边检查 knot 平移到子局部坐标,而相对控制向量不平移。
func TestMigrationPreservesBezierGeometry(t *testing.T) {
var doc map[string]any
_ = json.Unmarshal([]byte(legacyMigrationFixture), &doc)
+8
View File
@@ -1,3 +1,4 @@
// 子画布所有权关系读写,统一循环/深度约束与 AI 子树失效处理,供移动、解散及撤销复用。
package platform
import (
@@ -6,22 +7,28 @@ import (
"net/http"
)
// subgraphRelation 以 Child 唯一标识关系,Parent/Frame 定位其当前拥有者,Archived 控制活跃可见性。
type subgraphRelation struct {
Parent string `json:"parent_board_id"`
Frame string `json:"frame_id"`
Child string `json:"child_board_id"`
Archived bool `json:"archived"`
}
// subgraphRelationChange 保存前后关系;撤销前检查当前仍等于 After,再恢复 Before。
type subgraphRelationChange struct {
Before subgraphRelation `json:"before"`
After subgraphRelation `json:"after"`
}
// readSubgraphRelation 在调用方事务内锁住关系行,避免基于已变更父级编排事务。
func readSubgraphRelation(r *http.Request, tx *sql.Tx, project, workspace, child string) (subgraphRelation, error) {
result := subgraphRelation{Child: child}
err := tx.QueryRowContext(r.Context(), `SELECT parent_board_id::text,frame_id,archived_at IS NOT NULL FROM canvas_subgraphs WHERE project=$1 AND workspace_id=$2 AND child_board_id=$3 FOR UPDATE`, project, workspace, child).Scan(&result.Parent, &result.Frame, &result.Archived)
return result, err
}
// writeSubgraphRelation 发生真实关系变更时检查新活跃位置并失效 AI 子树,再写父级/框及归档状态。
func writeSubgraphRelation(r *http.Request, tx *sql.Tx, project, workspace string, relation subgraphRelation) error {
before, err := readSubgraphRelation(r, tx, project, workspace, relation.Child)
if err != nil {
@@ -45,6 +52,7 @@ func writeSubgraphRelation(r *http.Request, tx *sql.Tx, project, workspace strin
var errSubgraphCycle = errors.New("subgraph_cycle")
var errSubgraphDepth = errors.New("subgraph_depth_exceeded")
// validateSubgraphPlacement 同查父方祖先与孩子后代;拒绝成环,合并后最大路径深度不得超过八。
func validateSubgraphPlacement(r *http.Request, tx *sql.Tx, project, workspace, parent, child string) error {
var cycle bool
var depth int
+8
View File
@@ -1,3 +1,4 @@
// 子图创建事务与共享快照读取;父 frame、子素材、关系和撤销回执必须一起提交。
package platform
import (
@@ -9,18 +10,21 @@ import (
"time"
)
// canvasSnapshot 使用独立 canvas_version,与素材标题/内容的 version 区分,Document 保留完整 JSON。
type canvasSnapshot struct {
BoardID string `json:"board_id"`
Version int64 `json:"version"`
Document json.RawMessage `json:"document"`
}
// loadCanvas 读取并锁定素材行,旧 board 无快照时投影为空 v1 文档;调用方先做类型和权限检查。
func loadCanvas(r *http.Request, tx *sql.Tx, project, workspace, board string) (canvasSnapshot, error) {
result := canvasSnapshot{BoardID: board}
err := tx.QueryRowContext(r.Context(), `SELECT canvas_version,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, board).Scan(&result.Version, &result.Document)
return result, err
}
// createSubgraph 要求 v2、幂等 UUID 和父 If-Match;创建空 v2 子画布并在父文档加对应 frame。
func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -78,6 +82,7 @@ func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project
reject(w, 403, "forbidden")
return nil
}
// 取得工作区锁后先重放历史回执,再检查当前版本,因此丢响应重试不会因版本已推进而失败。
var previousHash string
var previous json.RawMessage
var status int
@@ -121,6 +126,7 @@ func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project
reject(w, 413, "graph_limit_exceeded")
return nil
}
// 子素材先在未提交事务中创建;后续深度/父文档校验失败时 defer 回滚,不留下孤儿孩子。
var childID, slug string
err = tx.QueryRowContext(r.Context(), `INSERT INTO materials(project,workspace_id,kind,title,created_by,canvas_document) VALUES($1,$2,'board',$3,$4,'{"schema_version":2,"nodes":[],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}') RETURNING id::text,slug`, project, workspace, f.Title, account).Scan(&childID, &slug)
if err != nil {
@@ -150,6 +156,7 @@ func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project
reject(w, 400, "invalid_canvas")
return nil
}
// before 只包含原父快照;撤销时据此识别本次新建的孩子,将其归档保留恢复记录。
before := parent
parent.Document = normalized
parent.Version++
@@ -167,6 +174,7 @@ func (s *service) createSubgraph(w http.ResponseWriter, r *http.Request, project
if err != nil {
return err
}
// 回执记录父子版本与七天撤销期限,和所有文档/关系同事务持久化,成功提交后才响应。
result := response{"transaction_id": transaction, "frame_id": f.ID, "child_board": response{"id": childID, "slug": slug, "workspace_id": workspace}, "parent": parent, "child": child, "undo_receipt": response{"transaction_id": transaction, "valid_for_seconds": 604800, "expires_at": receiptExpiry}}
encoded, _ := json.Marshal(result)
savedBefore, _ := json.Marshal([]canvasSnapshot{before})
+7
View File
@@ -1,3 +1,4 @@
// 工作区标签目录与素材标签关联;素材关联替换使用乐观版本,目录删除会使相关素材版本失效。
package platform
import (
@@ -8,6 +9,7 @@ import (
var colorPattern = regexp.MustCompile(`^#[0-9A-Fa-f]{6}$`)
// tags 允许成员列表,editor/admin 创建;名称去空白,颜色可为空或六位十六进制。
func (s *service) tags(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet && r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -70,6 +72,8 @@ func (s *service) tags(w http.ResponseWriter, r *http.Request, project, account
reply(w, 201, response{"id": id, "name": input.Name, "color": input.Color})
return nil
}
// deleteTag 先递增所有引用素材版本,再删除标签及级联关联,整个过程共用工作区锁与事务。
func (s *service) deleteTag(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
@@ -105,6 +109,8 @@ UPDATE materials m SET version=version+1,modified_at=now() WHERE project=$1 AND
reply(w, 204, nil)
return nil
}
// materialTags 用提交列表整体替换素材关联;先以 If-Match 推进版本,后续任一坏引用会回滚全部修改。
func (s *service) materialTags(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -154,6 +160,7 @@ func (s *service) materialTags(w http.ResponseWriter, r *http.Request, project,
if err != nil {
return err
}
// 重复标签通过 ON CONFLICT 去重;跨工作区或不存在的标签交给外键约束拒绝。
for _, tag := range input.Tags {
_, err = tx.ExecContext(r.Context(), "INSERT INTO material_tags(project,workspace_id,material_id,tag_id) VALUES($1,$2,$3,$4) ON CONFLICT DO NOTHING", project, workspace, material, tag)
if err != nil {
+8
View File
@@ -1,3 +1,4 @@
// 工作区与成员管理:所有成员/角色写入先锁工作区,使撤销和后续业务权限检查按同一顺序串行化。
package platform
import (
@@ -7,6 +8,7 @@ import (
"strings"
)
// workspaces 列出本人所属工作区,或在单个事务中创建工作区和所有者 admin 成员。
func (s *service) workspaces(w http.ResponseWriter, r *http.Request, project, account string) error {
switch r.Method {
case http.MethodGet:
@@ -73,6 +75,7 @@ WHERE m.project=$1 AND m.account_id=$2 ORDER BY lower(w.name),w.id LIMIT 200
return nil
}
// createWorkspace 同时供普通创建和 onboarding 使用;调用方负责提交,使所有者与成员记录原子落库。
func createWorkspace(ctx context.Context, tx *sql.Tx, project, account, name string) (string, error) {
var id string
err := tx.QueryRowContext(ctx, `
@@ -87,6 +90,7 @@ INSERT INTO workspace_members(project,workspace_id,account_id,role) VALUES($1,$2
return id, err
}
// lockWorkspace 先锁工作区再读调用者角色;等待并发撤销完成后读取,避免沿用旧成员权限。
func lockWorkspace(ctx context.Context, tx *sql.Tx, project, workspace, account string) (string, string, error) {
var owner, role string
err := tx.QueryRowContext(ctx, `
@@ -102,6 +106,7 @@ SELECT role FROM workspace_members WHERE project=$1 AND workspace_id=$2 AND acco
return owner, role, err
}
// workspace 允许成员读取,admin 改名/slug,仅 owner 能删除;读取分支结束由 defer 回滚释放锁。
func (s *service) workspace(w http.ResponseWriter, r *http.Request, project, account string) error {
workspace := r.PathValue("workspace")
tx, err := s.db.BeginTx(r.Context(), nil)
@@ -159,6 +164,7 @@ func (s *service) workspace(w http.ResponseWriter, r *http.Request, project, acc
return nil
}
// members 仅在调用方也是成员时返回列表;空结果按不可见资源处理,不披露工作区存在性。
func (s *service) members(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -194,6 +200,7 @@ ORDER BY m.joined_at,m.account_id LIMIT 200
return nil
}
// member 管理单个成员:owner 身份不可降级/删除;普通成员只能删除自己,admin 可管理他人。
func (s *service) member(w http.ResponseWriter, r *http.Request, project, account string) error {
workspace, target := r.PathValue("workspace"), r.PathValue("account")
if r.Method != http.MethodPatch && r.Method != http.MethodDelete {
@@ -209,6 +216,7 @@ func (s *service) member(w http.ResponseWriter, r *http.Request, project, accoun
if err != nil {
return err
}
// owner 必须始终留在成员表,不能通过退出或修改角色破坏工作区管理入口。
if owner == target {
reject(w, 409, "owner_membership_required")
return nil