diff --git a/.env.example b/.env.example index f79d8e6..1a1dbab 100644 --- a/.env.example +++ b/.env.example @@ -1,12 +1,16 @@ +# 示例值供部署配置参考,真实 .env/凭据不得提交。公共地址必须是 HTTPS 根 origin。 PUBLIC_ORIGIN=https://api.example.com DATABASE_URL=postgresql://foundry:replace-me@postgres.internal:5432/foundry_auth GOOGLE_CLIENT_ID=replace-me.apps.googleusercontent.com GOOGLE_CLIENT_SECRET=replace-me +# 项目→固定前端回调白名单;生产 HTTPS,开发仅允许回环 HTTP,不能由请求任意指定。 FOUNDRY_PROJECTS='{"notes":"http://localhost:3000/auth/callback","board":"http://localhost:3001/auth/callback"}' +# 默认监听回环,容器发布时 release.sh 显式改为 0.0.0.0;PORT 仅决定内部 HTTP 监听。 HOST=127.0.0.1 PORT=8080 # Optional email verification through TLS SMTP. +# 邮件配置整组缺省可关闭,部分填写会启动失败;此示例只接受隐式 TLS 465。 SMTP_HOST=smtpdm.aliyun.com SMTP_PORT=465 SMTP_USERNAME=noreply@notice.entroia.com @@ -14,6 +18,7 @@ SMTP_PASSWORD=replace-me SMTP_FROM=noreply@notice.entroia.com # Optional Sign in with Slack. +# Slack 客户端 ID 与 Secret 必须成对配置,回调 URL 由 PUBLIC_ORIGIN 派生。 SLACK_CLIENT_ID=replace-me SLACK_CLIENT_SECRET=replace-me diff --git a/.gitea/workflows/check.yml b/.gitea/workflows/check.yml index 088ddd4..ff52e99 100644 --- a/.gitea/workflows/check.yml +++ b/.gitea/workflows/check.yml @@ -1,8 +1,10 @@ +# 分支推送和 PR 检查:格式/编译、隔离数据库回归、固定版本 headless 客户端以及 HTTP smoke。 name: Foundry Go checks on: [push, pull_request] jobs: check: + # 所有构建在此远程 runner 执行;脚本中的 Docker 挂载路径也基于它的工作区。 runs-on: ces-control # Cold toolchain installation can exceed ten minutes on the existing runner. timeout-minutes: 30 @@ -18,6 +20,7 @@ jobs: test -z "$(gofmt -l cmd internal)" go test -mod=readonly ./... go build -mod=readonly -o bin/foundry ./cmd/foundry + # 仅 push 可使用已配置秘密做占位码探测,不能替代真实用户 OAuth 登录。 - name: Check Slack OAuth configuration and endpoint if: gitea.event_name == 'push' env: @@ -69,6 +72,7 @@ jobs: print("Negative control result:", control if control in known else "unclassified") sys.exit("Slack client preflight could not verify the configured credentials") PYSLACK + # 固定客户端提交避免服务端回归随外部默认分支漂移,下载不使用用户本机凭据。 - name: Fetch pinned headless HTTP integration client env: HEADLESS_CLIENT_REVISION: dcbbdad25de7c3b1d6bee317df6074da2c0642eb @@ -82,6 +86,7 @@ jobs: printf 'Pinned Endoleap client: %s\n' "$HEADLESS_CLIENT_REVISION" - name: Verify schema migration and real headless HTTP client in an isolated database run: HEADLESS_CLIENT_SOURCE="$PWD/.headless-client" bash deploy/check-schema.sh + # smoke 不依赖可连接数据库:healthz 只检查进程,缺 bearer 的 me 必须先返回 401。 - name: Smoke test HTTP routes env: PUBLIC_ORIGIN: https://api.example.com diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml index 928e4f3..5bd714c 100644 --- a/.gitea/workflows/deploy.yml +++ b/.gitea/workflows/deploy.yml @@ -1,3 +1,4 @@ +# 仅 main 的相关路径变更触发发布;工作分支验证不应运行此生产切换。 name: Deploy Foundry Core on: push: @@ -11,6 +12,7 @@ on: - 'db/**' - '.gitea/workflows/deploy.yml' +# 发布串行排队且不取消正在进行的路由/数据库操作。 concurrency: group: foundry-core-main-deploy cancel-in-progress: false @@ -26,12 +28,14 @@ jobs: with: go-version-file: go.mod cache: false + # 在远程 runner 生成无 CGO 二进制,供只读 slim 容器执行。 - name: Verify and build run: | set -eu test -z "$(gofmt -l cmd internal)" go test -mod=readonly ./... CGO_ENABLED=0 go build -mod=readonly -o bin/foundry ./cmd/foundry + # secrets 仅注入进程环境,项目/引导 JSON 来自 Actions Variables,release 再检查内容。 - name: Deploy and verify backend readiness env: GOOGLE_CLIENT_ID: ${{ secrets.GOOGLE_CLIENT_ID }} diff --git a/.gitignore b/.gitignore index db3643f..56e78a8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +# 本地配置可能含凭据,构建/文档生成目录不作为源码提交。 .env /bin/ /api-docs/ diff --git a/README.md b/README.md index 2253a25..c614c8b 100644 --- a/README.md +++ b/README.md @@ -636,3 +636,7 @@ not migrate it or cause an implicit PATCH. #### Atomic member drop positions `POST B/subgraphs/{frame}/members` additionally accepts optional `positions`, an object with exactly one `{x,y}` entry for each `node_ids` item, expressed in the **source board's local coordinates**. Both coordinates are required, finite and within ±1,000,000. Capabilities advertise `subgraphs.member_positions: true`. Omission preserves legacy behavior. Positions, ownership, edge/port conversion, versions and undo receipt commit in one transaction; no preceding coordinate PATCH is needed. Validation failures or stale versions perform zero writes. The positions participate in the idempotency payload digest; retries must keep the entire body and key unchanged. Undo restores the pre-drop snapshot, including original positions. + +## 源码阅读注释 + +Go 实现、测试与部署脚本内的中文注释说明调用关系、事务、版本、身份和资源生命周期。历史 `db/*.sql` 由部署校验和锁定,逐迁移、逐表及约束说明集中在 [数据库注释索引](docs/database-comments.sql),保留历史 SQL 字节以兼容已部署数据库。`go.sum` 和协议 JSON fixture 保留机器可读原文,不插入注释。 diff --git a/cmd/foundry/main.go b/cmd/foundry/main.go index 32d4196..2de3f2a 100644 --- a/cmd/foundry/main.go +++ b/cmd/foundry/main.go @@ -1,3 +1,4 @@ +// Foundry 进程装配入口:HTTP 服务连接认证、平台、研究库和 Codex Unix socket。 package main import ( @@ -18,6 +19,7 @@ import ( "github.com/jackc/pgx/v5/stdlib" ) +// env 将空环境变量视为缺省;仅用于允许默认值的配置项。 func env(key, fallback string) string { if value := os.Getenv(key); value != "" { return value @@ -25,10 +27,12 @@ func env(key, fallback string) string { return fallback } +// main 支持独立 codex-worker 模式,其余启动方式进入 HTTP API 服务。 func main() { if len(os.Args) == 2 && os.Args[1] == "codex-worker" { log.Fatal(codex.ServeWorker("/run/foundry-codex/worker.sock")) } + // 公共 origin 只允许 HTTPS 根地址,回调路径由程序拼接,避免配置夹带查询或用户信息。 origin, err := url.Parse(os.Getenv("PUBLIC_ORIGIN")) if err != nil || origin.Scheme != "https" || origin.Hostname() == "" || origin.User != nil || (origin.Path != "" && origin.Path != "/") || origin.RawQuery != "" || origin.Fragment != "" { @@ -46,12 +50,14 @@ func main() { if err != nil { log.Fatal("Invalid DATABASE_URL") } + // OpenDB 创建连接池,实际连接按需建立;HTTP 就绪检查再验证主库可用性。 db := stdlib.OpenDB(*config) defer db.Close() email, err := auth.EmailConfigFromEnv() if err != nil { log.Fatal(err) } + // nil 邮件配置会直接返回;此后台任务使用进程级上下文,没有单独的优雅停机取消。 go email.Run(context.Background(), db) slack, err := auth.SlackConfigFromEnv(origin.ResolveReference(&url.URL{Path: "/auth/slack/callback"}).String()) if err != nil { @@ -62,6 +68,7 @@ func main() { log.Fatal(err) } mux := http.NewServeMux() + // 研究数据使用可选、独立且只读的连接池;配置后必须在五秒启动探测内可访问。 var papers research.Repository if researchDSN := os.Getenv("FOUNDRY_RESEARCH_DATABASE_URL"); researchDSN != "" { researchConfig, err := pgx.ParseConfig(researchDSN) @@ -88,6 +95,7 @@ func main() { } papers = repository } + // 先注册具体业务路径,最后的根处理器承接认证及健康探测请求。 research.Register(mux, papers, callbacks) if err := codex.Register(mux, callbacks, os.Getenv("FOUNDRY_CODEX_SOCKET"), os.Getenv("FOUNDRY_CODEX_GRANTS")); err != nil { log.Fatal(err) @@ -98,6 +106,7 @@ func main() { } platform.Register(mux, db, callbacks, origin.Scheme+"://"+origin.Host, onboarding, codex.NewCanvasClient(os.Getenv("FOUNDRY_CODEX_SOCKET"))) mux.Handle("/", handler) + // HOST 默认只监听回环,容器部署显式覆盖;较长写超时用于耗时业务响应。 server := &http.Server{ Addr: net.JoinHostPort(env("HOST", "127.0.0.1"), env("PORT", "8080")), Handler: mux, ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 10 * time.Second, diff --git a/deploy/check-canvas-real.sh b/deploy/check-canvas-real.sh index eaa68d0..62914cc 100644 --- a/deploy/check-canvas-real.sh +++ b/deploy/check-canvas-real.sh @@ -1,5 +1,6 @@ #!/usr/bin/env bash # Explicit remote-runner opt-in: invokes real models using the dedicated CLI login. +# 此脚本会编译测试并实际调用模型;只用于明确授权的专用远程 runner,普通检查不自动运行。 set -euo pipefail umask 077 binary=$(realpath "$1") @@ -9,6 +10,7 @@ login=${FOUNDRY_REAL_CODEX_HOME:-/opt/endoleap-infra/foundry/codex/home} test -x "$binary" test -s "$login/auth.json" test -s "$login/models_cache.json" +# 随机命名 worker/数据库和临时 socket 目录,退出时一并清理,不复用生产队列。 suffix=$(openssl rand -hex 8) database=foundry-real-db-$suffix worker=foundry-real-worker-$suffix @@ -24,6 +26,7 @@ docker exec "$database" psql -X -U postgres -v ON_ERROR_STOP=1 -c 'CREATE ROLE f python3 deploy/migrate.py --container "$database" --database postgres --role foundry_fixture # Only the CLI container sees the login. Core/tests receive the private socket, # never the login, runtime configuration or Docker socket. +# 只有 CLI 容器只读读取专用登录和模型缓存,测试容器仅挂 socket,不能访问登录或 Docker socket。 docker run -d --name "$worker" --init --network bridge --user 1000:1000 \ --cap-drop ALL --security-opt no-new-privileges --read-only --pids-limit 128 --memory 1g \ --tmpfs /tmp:rw,nosuid,nodev,size=128m --tmpfs /work:ro,nosuid,nodev \ @@ -38,6 +41,7 @@ docker run -d --name "$worker" --init --network bridge --user 1000:1000 \ node:24-bookworm-slim /opt/foundry codex-worker >/dev/null for attempt in {1..30}; do if [[ -S "$scratch/run/worker.sock" ]]; then break; fi; sleep 1; done test -S "$scratch/run/worker.sock" +# 先等私有 socket 出现,再在 runner 编译并仅运行真实 worker 专项用例;与普通单元测试开关分离。 CGO_ENABLED=0 go test -mod=readonly -c -o bin/platform-real-tests ./internal/platform docker run --rm --network "container:$database" --user 1000:1000 \ --read-only --cap-drop ALL --security-opt no-new-privileges \ diff --git a/deploy/check-schema.sh b/deploy/check-schema.sh index 629e098..ff497ac 100644 --- a/deploy/check-schema.sh +++ b/deploy/check-schema.sh @@ -1,6 +1,8 @@ #!/usr/bin/env bash +# 远程 runner 的数据库/集成检查,会编译测试二进制并运行容器;不能在未授权本地环境执行。 set -euo pipefail +# 随机隔离数据库容器不映射宿主端口,EXIT 时销毁;trust 认证只用于该临时网络命名空间。 container=foundry-schema-$(openssl rand -hex 8) cleanup() { docker rm -f "$container" >/dev/null 2>&1 || true; } trap cleanup EXIT @@ -12,6 +14,7 @@ for attempt in {1..30}; do sleep 1 done psql() { docker exec -i "$container" psql -X -U postgres -v ON_ERROR_STOP=1; } +# 先安装最早认证版本并植入有效/过期旧会话,模拟部署前已有用户数据。 psql < db/001-auth.sql psql <<'SQL' INSERT INTO project_accounts(project,id,google_subject,email) @@ -23,8 +26,10 @@ SQL psql <<'SQLROLE' CREATE ROLE foundry_fixture LOGIN; SQLROLE +# 连续跑两次真实迁移器,验证旧基线接管和校验和重放,而不是仅验证全新数据库建表。 python3 deploy/migrate.py --container "$container" --database postgres --role foundry_fixture python3 deploy/migrate.py --container "$container" --database postgres --role foundry_fixture +# SQL 断言旧 Google 绑定保留、过期会话不复活、绝对期限添加,再在回滚事务中验证资源与跨项目外键。 psql <<'SQL' DO $$ BEGIN @@ -68,6 +73,7 @@ ROLLBACK; SQL printf 'Migration preserved existing logins and enforced project isolation.\n' psql < internal/research/testdata/corpus.sql +# runner 编译 Linux 静态测试程序,随后在同数据库网络空间用最小权限容器运行,源码不挂入测试容器。 for package in platform auth research; do CGO_ENABLED=0 go test -mod=readonly -c -o "bin/$package-tests" "./internal/$package" docker run --rm --network "container:$container" --user 1000:1000 \ @@ -81,6 +87,7 @@ done # Run the actual pinned Endoleap runtime against this build's authenticated HTTP # routes and the same disposable database. Only this remote container needs Node. +# 可选 pinned Endoleap 客户端需要 Node,额外运行一次真实 HTTP 客户端集成;未提供时跳过该阶段。 if [[ -n "${HEADLESS_CLIENT_SOURCE:-}" ]]; then test -f "$HEADLESS_CLIENT_SOURCE/tests/headless/foundry.integration.mjs" docker run --rm --network "container:$container" --user 1000:1000 \ diff --git a/deploy/codex-worker.sh b/deploy/codex-worker.sh index ec5b7b5..26325d5 100644 --- a/deploy/codex-worker.sh +++ b/deploy/codex-worker.sh @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# 远程私有 worker 启动器;使用与 Core 同一二进制的 codex-worker 模式,CLI 和登录目录由运维预先提供。 set -euo pipefail base=/opt/endoleap-infra @@ -7,14 +8,18 @@ binary=$(realpath "$1") test -x "$binary" test -s "$dir/home/auth.json" test -s "$dir/grants/projects.json" +# socket 目录归容器 uid 1000,socket 本身由服务设为 0600;不公布宿主 TCP 端口。 install -d -m 700 "$dir/run" chown 1000:1000 "$dir/run" +# 可选目录声明已验证图片输出后端;没有此名单时不根据图片输入能力推测图片生成能力。 canvas_env=() if [[ -s "$dir/canvas.env" ]]; then canvas_env=(--env-file "$dir/canvas.env"); fi # The host operator supplies an isolated Codex home and starts a single worker. # The Docker default bridge supplies egress independently of Foundry's network. +# 单 worker 使用独立 bridge 出网,根文件系统只读;临时任务写 /tmp,登录目录需允许 CLI 自身状态更新。 +# CLI/二进制只读挂载,Core 只看到 socket,不共享本登录目录。 docker run -d --name foundry-codex-worker --restart unless-stopped --init \ --network bridge --user 1000:1000 --cap-drop ALL --security-opt no-new-privileges \ --read-only --pids-limit 128 --memory 1g --tmpfs /tmp:rw,nosuid,nodev \ diff --git a/deploy/migrate.py b/deploy/migrate.py index d1ff616..20ae6b7 100644 --- a/deploy/migrate.py +++ b/deploy/migrate.py @@ -1,5 +1,7 @@ #!/usr/bin/env python3 """Apply checked migrations atomically from the trusted deployment runner.""" +# 部署 runner 入口:组合所有尚未执行的迁移及授权为单个外层事务,失败整体回滚。 +# db/*.sql 的校验和覆盖原始注释;历史文件不可仅为加注释而改写,中文对象说明见 docs/database-comments.sql。 import argparse import hashlib import os @@ -7,6 +9,7 @@ from pathlib import Path import re import subprocess +# 数据库/角色会插入 SQL 标识符,先严格限制为小写标识;container 通过 argv 传给 docker。 parser = argparse.ArgumentParser() parser.add_argument("--container", default=os.environ.get("FOUNDRY_POSTGRES_CONTAINER", "foundry-postgres")) parser.add_argument("--database", default="foundry_auth") @@ -19,6 +22,7 @@ migrations = sorted((Path(__file__).resolve().parent.parent / "db").glob("[0-9]* if not migrations: raise SystemExit("No migrations found") +# psql 遇错立即退出,固定 advisory 事务锁串行化同库部署,lock_timeout 防止无限等锁。 script = [ "\\set ON_ERROR_STOP on", "BEGIN;", @@ -33,6 +37,7 @@ for index, path in enumerate(migrations): name = path.name if not re.fullmatch(r"[0-9]+-[a-z0-9-]+\.sql", name): raise SystemExit("Invalid migration name") + # 原文 SHA-256 与已执行记录逐字匹配,禁止同名历史迁移在部署后被静默修改。 checksum = hashlib.sha256(source.encode()).hexdigest() tables.update(re.findall(r"CREATE TABLE ([a-z_]+)", source)) # The first deployed version predates migration tracking. @@ -55,6 +60,7 @@ for index, path in enumerate(migrations): "\\endif", "\\else", ]) + # 每份源文件显式 BEGIN/COMMIT;去除内层边界后放入外层统一事务,而非逐文件部分提交。 source = source.strip() if not source.startswith("BEGIN;") or not source.endswith("COMMIT;"): raise SystemExit("Migration must have explicit transaction boundaries") @@ -63,12 +69,14 @@ for index, path in enumerate(migrations): f"INSERT INTO foundry_schema_migrations(name,checksum) VALUES('{name}','{checksum}');", "\\endif", ]) +# 从受信任源码的 CREATE TABLE 清单补应用 DML 权限;identity 序列另授予使用/读取权限。 for table in sorted(tables): script.append(f'GRANT SELECT,INSERT,UPDATE,DELETE ON TABLE "{table}" TO "{args.role}";') script.extend([ f'GRANT USAGE,SELECT ON SEQUENCE link_clicks_id_seq TO "{args.role}";', "COMMIT;", ]) +# SQL 经标准输入交给容器内 psql,不把数据库密码或整段 SQL 拼成 shell 命令参数。 subprocess.run( ["docker", "exec", "-i", args.container, "sh", "-c", 'exec psql -X -U "${POSTGRES_USER:-postgres}" -d "$1" -v ON_ERROR_STOP=1', "sh", args.database], diff --git a/deploy/release.sh b/deploy/release.sh index b75658c..e57cb6d 100644 --- a/deploy/release.sh +++ b/deploy/release.sh @@ -1,4 +1,6 @@ #!/usr/bin/env bash +# 由 main 部署工作流在远程基础设施主机执行,参数一必须是已构建的 Foundry 二进制。 +# 本脚本会迁移数据库、替换 worker 并启动候选服务,不能当作本地静态检查执行。 set -euo pipefail umask 077 @@ -8,6 +10,7 @@ origin=https://api.foundry.entroia.com candidate=foundry-core-candidate network=endoleap-dev_default +# 必需凭据仅从环境传入,拒绝换行以保持容器环境参数边界,日志不打印值。 for name in GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET; do value=${!name-} if [[ -z "$value" || "$value" == *$'\n'* || "$value" == *$'\r'* ]]; then @@ -16,6 +19,7 @@ for name in GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET; do fi done # Accept formatted JSON from Actions Variables and never print its contents. +# 将 Actions 中可多行排版的 JSON 压为单行;这里只校验映射形状,URL 协议由服务启动继续验证。 FOUNDRY_PROJECTS=$(python3 - <<'PYCONFIG' import json import os @@ -44,11 +48,14 @@ test -s "$foundry/database.env" ca_bundle=/etc/ssl/certs/ca-certificates.crt test -s "$ca_bundle" docker network inspect "$network" >/dev/null +# 先运行全事务迁移及角色授权,迁移失败立即终止,不让新服务在半升级 schema 上启动。 python3 "$(dirname "$0")/migrate.py" +# 每次发布使用独立二进制目录供只读挂载;本脚本不清除旧 release 目录。 release=$(mktemp -d "$foundry/release.XXXXXXXX") install -m 755 "$1" "$release/foundry" export HOST=0.0.0.0 PORT=8080 PUBLIC_ORIGIN="$origin" +# 邮件/研究配置可选且从受保护文件加载;Slack 优先 Actions 环境,缺省才回退服务器文件。 mail_env=() if [[ -s "$foundry/mail.env" ]]; then mail_env=(--env-file "$foundry/mail.env") @@ -73,6 +80,7 @@ elif [[ -s "$foundry/slack.env" ]]; then fi codex_mounts=() codex_dir=$foundry/codex +# 存在 worker 配置才启用 IPC;worker 必须先与当前 Core 二进制协议对齐,启动失败恢复旧 worker。 if [[ -d "$codex_dir" ]]; then # Core and its private worker must speak the same Canvas artifact protocol. # Keep the previous container definition for exact startup rollback. @@ -107,6 +115,7 @@ if [[ -d "$codex_dir" ]]; then printf 'Canvas worker startup/catalog verification failed; previous worker restored.\n' >&2 exit 1 fi + # 目录探测成功后删除旧 worker 定义;后续候选/路由失败不会再恢复该 worker,回滚范围需据此理解。 if [[ -n "$worker_backup" ]]; then docker rm "$worker_backup" >/dev/null; fi for attempt in {1..20}; do [[ ! -S "$codex_dir/run/worker.sock" ]] || break @@ -122,6 +131,7 @@ if [[ -d "$codex_dir" ]]; then ) fi +# Core 只挂载 IPC/授权表,不挂载 CLI 登录;以非 root、只读根文件系统和裁剪能力运行。 docker run -d --name "$candidate" "${codex_mounts[@]}" "${mail_env[@]}" "${slack_env[@]}" "${research_env[@]}" --network "$network" \ --env-file "$foundry/database.env" -e HOST -e PORT -e PUBLIC_ORIGIN \ -e GOOGLE_CLIENT_ID -e GOOGLE_CLIENT_SECRET -e FOUNDRY_PROJECTS -e FOUNDRY_ONBOARDING \ @@ -132,11 +142,13 @@ docker run -d --name "$candidate" "${codex_mounts[@]}" "${mail_env[@]}" "${slack --mount "type=bind,source=$release/foundry,target=/opt/foundry,readonly" \ node:24-bookworm-slim /opt/foundry >/dev/null +# 候选或路由失败时删除本次新 Core;旧 Core 由 route 成功探测后才停止。 cleanup_candidate() { docker rm -f "${live:-$candidate}" >/dev/null 2>&1 || true } trap cleanup_candidate EXIT +# 容器内 smoke 只验证 CA 文件、数据库就绪及匿名请求被拒,不执行真实 OAuth 或付费模型。 docker exec "$candidate" node -e ' const assert = require("node:assert/strict"); const fs = require("node:fs"); @@ -166,6 +178,7 @@ docker exec "$candidate" node -e ' # Keep the previous running container until the new candidate has passed checks. # Traefik reads the route atomically from its watched config directory. +# 使用容器 ID 前缀命名新 live,route.sh 负责原子路由写入、外部就绪检查和失败恢复路由。 id=$(docker inspect -f '{{.Id}}' "$candidate") live=foundry-core-${id:0:12} docker rename "$candidate" "$live" diff --git a/deploy/research/query-indexes.sql b/deploy/research/query-indexes.sql index 314cf06..fb99d0c 100644 --- a/deploy/research/query-indexes.sql +++ b/deploy/research/query-indexes.sql @@ -1,3 +1,5 @@ +-- 运维手动索引步骤:对已发布 research schema 执行,不能由只读服务角色调用,也不能包进事务。 +-- 不属于 db/ 版本迁移;CREATE INDEX CONCURRENTLY 需要独立顶层语句,避免长时间阻塞语料读取。 -- Manual operator step against the published Paper Atlas schema, outside a -- transaction. Core's SELECT-only runtime role must never execute this file. -- These indexes support the actual author search and exact category filter; @@ -6,8 +8,10 @@ SET lock_timeout = '2s'; SET statement_timeout = '20min'; SET maintenance_work_mem = '32MB'; SET max_parallel_maintenance_workers = 0; +-- (tag_id,paper_id) 支持纯主题页直接走关联索引,在 LIMIT 前避免读所有宽论文行。 CREATE INDEX CONCURRENTLY IF NOT EXISTS paper_tags_tag_paper ON research.paper_tags(tag_id,paper_id); +-- simple 配置匹配作者查询的表达式,不对姓名做 english 词干化;索引表达式须与查询一致。 CREATE INDEX CONCURRENTLY IF NOT EXISTS papers_authors_search_gin ON research.papers USING gin(to_tsvector('simple'::regconfig,authors_json)); -- After an interrupted concurrent build, inspect pg_index.indisvalid before diff --git a/deploy/route.sh b/deploy/route.sh index 5a7c29b..9ac3f44 100644 --- a/deploy/route.sh +++ b/deploy/route.sh @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# 远程部署的路由切换阶段,参数必须是本次已通过内部就绪检查的 Core 容器名。 set -euo pipefail umask 077 cd /opt/endoleap-infra @@ -8,12 +9,14 @@ live=$1 install -d -m 700 dev/foundry-edge edge=dev/foundry-edge route=$edge/foundry.yml +# 从现有动态配置提取旧容器;仅在新路由完成 HTTPS 探测后才停止它。 previous= if [[ -f "$route" ]]; then previous=$(sed -n 's@.*url: http://\(foundry-core-[a-f0-9]\{12\}\):8080.*@\1@p' "$route") fi backup=$(mktemp) if [[ -f "$route" ]]; then cp "$route" "$backup"; fi +# EXIT trap 只恢复动态路由文件或删除新路由,不回滚已执行的数据库迁移/worker/Compose 配置。 rollback() { if [[ -s "$backup" ]]; then cp "$backup" "$edge/.restore" @@ -25,6 +28,7 @@ rollback() { } trap rollback EXIT +# ACME 文件保存证书状态,限制权限;动态路由先写隐藏临时文件再 mv,避免 watcher 读到半文件。 touch "$edge/acme.json" chmod 600 "$edge/acme.json" cat > "$edge/.foundry.yml" < foundry-edge.yml <<'YAML' services: traefik: @@ -68,11 +73,13 @@ services: YAML docker compose -p endoleap-dev --env-file dev/env -f compose.yml -f dev.yml -f foundry-edge.yml up -d --no-deps traefik +# --resolve 在本机回环命中 Traefik,同时保留公开域名 Host/TLS 验证,探测真正的 HTTPS 路由。 curl --fail --silent --show-error --output /dev/null --max-time 6 \ --retry 15 --retry-delay 4 --retry-all-errors \ --resolve api.foundry.entroia.com:443:127.0.0.1 \ https://api.foundry.entroia.com/readyz +# HTTPS 就绪后解除回滚并删除备份;旧容器停止失败仅提示手工清理,不能误报新路由失败。 trap - EXIT rm -f "$backup" if [[ "$previous" =~ ^foundry-core-[a-f0-9]{12}$ && "$previous" != "$live" ]]; then diff --git a/docs/database-comments.sql b/docs/database-comments.sql new file mode 100644 index 0000000..090f5d2 --- /dev/null +++ b/docs/database-comments.sql @@ -0,0 +1,115 @@ +-- Foundry 数据库源码阅读注释索引(仅注释,不执行迁移)。 +-- 历史 db/*.sql 的 SHA-256 由 deploy/migrate.py 原文计算并记录;即使只改注释, +-- 已部署库也会拒绝同名文件的新校验和。因此按迁移文件与对象名在此维护中文说明。 +-- 顺序:001 认证 → 002 平台 → 003 快照 → 004 会话期限 → 005 子图事务 → +-- 006 资产 → 007 AI 队列 → 008 canonical 模型 → 009–011 AI 身份/回执/位置。 + +-- db/001-auth.sql:四张基础认证表在一个事务中安装。 +-- project_accounts:账户身份以 (project,id) 为主键,Google subject 在项目内唯一。 +-- 同一 Google 用户可在不同项目有不同账户,邮箱是可空资料,不作为跨提供方自动合并依据。 +-- oauth_attempts:十分钟 OAuth 尝试;state/browser 保存摘要,frontend_challenge 绑定 +-- 前端兑换证明,google_verifier 原文用于服务器向 Google 兑换 PKCE 授权码。 +-- 回调通过 DELETE ... RETURNING 原子消费,外部兑换失败也不会恢复已消费尝试。 +-- login_grants:一分钟一次性交换码只存 token_hash,复合外键保证账户属于同一项目。 +-- project_sessions:bearer 明文只交客户端,数据库仅存摘要和期限;删除账户级联清会话。 +-- 三个 expires_at 索引提供过期定位能力,本文件本身不创建定时清理任务。 + +-- db/002-platform.sql:扩展身份提供方与协作资源,保留旧 Google 账户/会话。 +-- project_accounts:google_subject 放宽可空;username 在项目内按 lower 唯一, +-- display_name/avatar_url 是可由用户维护的资料,updated_at 由应用更新。 +-- oauth_attempts.provider 默认 google 兼容已有行;Slack 增加 oidc_nonce 防止 ID token 重放。 +-- account_identities:以项目/提供方/subject 唯一定位账户,迁入既有 Google subject; +-- 项目/提供方/account 唯一约束限定同一账户每提供方只有一个绑定。 +-- email_credentials:已验证邮箱凭据,邮箱须小写,password_hash 是 bcrypt; +-- 项目/email 主键及项目/account 唯一性不允许多个凭据冒用同一邮箱或账户。 +-- email_registrations:未验证注册单独保存密码摘要和验证码摘要,未确认前不建立账户; +-- 重发注册由应用在邮箱级事务锁下替换待验证记录及过期时间。 +-- email_outbox:邮件与注册同事务写入,available_at/attempts 控制重试;lease_id/ +-- lease_until 使后台 worker 可认领并在租约失效后恢复,sent_at 标成功。 +-- 发送成功后应用清空 body;SMTP 成功与数据库标记不原子,不能宣称严格只投递一次。 +-- auth_rate_limits:仅保存限频键摘要,固定窗口过期后由应用 upsert 重置次数。 +-- onboarding_responses:项目/账户唯一完成记录,answers/result 必须 JSON 对象; +-- 配合账户行锁,使并发首次引导只能创建一次工作区并重放已存结果。 +-- workspaces:所有者外键指向同项目账户;工作区行锁是角色/所有权变更共享的串行点。 +-- workspace_members:每人每工作区一个角色,admin/editor/viewer 的写权限由应用解释; +-- owner 必须保留 admin 成员的规则由服务控制,表约束没有单独自动生成该成员。 +-- materials:按项目/工作区隔离的可复用内容对象,kind 为受限类型;version 是素材 +-- 内容/元数据的乐观版本,后续新增 canvas_version 与它分离。 +-- material_modified/material_created/material_alphabetical:对应列表排序的复合索引。 +-- material_opens:账户级最近打开时间,可反复 upsert,不修改素材正文;专用索引支持最近打开。 +-- tags/material_tags:标签名在工作区内忽略大小写唯一;双复合外键阻止跨工作区关联, +-- 标签/素材删除级联清关联,应用负责让受影响素材版本递增。 +-- board_layouts:旧布局引用可复用素材,位置/尺寸与内容独立;禁止引用自身, +-- “必须 board 且不可嵌套 board”及每板最多 2000 条由服务检查。 +-- material_grants:显式 editor/viewer 素材权限,不存在素材级 admin 授予; +-- 根画布继承和归档祖先检查由 lockMaterial 的递归查询决定。 +-- share_links:仅保存邀请摘要;可指工作区或单素材,单素材不允许 admin; +-- max_uses/use_count 是额度,expires_at/revoked_at 控制之后的兑换资格。 +-- share_redemptions:同账户同链接只兑换一次;应用在持锁事务内插入成功后才加额度并提升角色。 +-- link_clicks:公开点击独立于兑换计数,仅存 Referer origin,避免收集路径、查询和令牌。 +-- bigint identity 支持递减 ID 分页;应用角色需单独授予序列 USAGE/SELECT。 + +-- db/003-canvas.sql:为 board 增加独立 canvas_version 和可空 canvas_document。 +-- canvas_board_only 禁止非 board 保存快照;旧空文档在读取时投影为初始空 v1 图。 +-- workspaces/materials 的 slug 先按名称/标题加 UUID 回填,再设 NOT NULL 和作用域唯一。 +-- foundry_default_slug:仅 INSERT 且未给 slug 才派生值,名字更改不会隐式改 URL。 +-- label 规范化并限长,空结果回退 canvas;触发器在两个表共享,因此区分 name/title。 + +-- db/004-session-lifetime.sql:加入 created_at 和九十天 absolute_expires_at 缺省。 +-- 旧会话原始发行时间未知,绝对上限从迁移时开始,但原 expires_at 完全不变, +-- 已闲置过期的旧会话不会被此迁移复活。应用续期取 min(三十天后,绝对期限)。 + +-- db/005-canvas-subgraphs.sql:持久唯一所有权与多画布事务恢复信息。 +-- canvas_subgraphs:Child 是主键中的唯一所有者身份,活跃 Parent/Frame 受部分唯一索引限制; +-- archived_at 保留恢复关系但从活跃树移除;migration_source 保存旧框迁移证据。 +-- 父/子外键均 RESTRICT,不能删掉素材而留下无法解释的所有权记录。 +-- foundry_check_subgraph:先锁工作区,确认两端是 board,再递归算祖先和后代, +-- 拒绝循环与深度超八;数据库触发器也保护绕过 HTTP 的维护写入。 +-- canvas_transactions:账户/画布/动作/幂等键唯一,payload_hash 防止同键换体。 +-- response_status/body 冻结重放结果;before_state、after_versions、relation_changes +-- 支持条件撤销;expires_at 七天及 undone_at 控制撤销有效性,不会自动倒退当前版本。 + +-- db/006-canvas-assets.sql:编码原图 bytea 与绑定同库事务提交,URL 与存储后端解耦。 +-- canvas_assets:限制格式和二十 MiB 编码预算,上传者/工作区/幂等键唯一,digest 为原图摘要; +-- 完整像素预算与解码有效性由应用在写入前检查,不能只依赖 MIME 字符串。 +-- canvas_asset_bindings:资产可被多个画布引用,主键去重;删除画布级联清绑定, +-- 有绑定资产不能直接删除。可读性按当前绑定画布授权判断,缓存字节不能作为权限证明。 + +-- db/007-canvas-ai.sql:run/step/event 与旧取消/显式应用回执。 +-- canvas_ai_runs:冻结 plan/create_response,保存队列时间、取消位、租约与单调 last_seq; +-- pending 部分索引服务认领,active 索引服务活跃列表;expires_at 表示三十天保留期限。 +-- canvas_ai_steps:每 run 的拓扑 ordinal、冻结输入、目标指纹、输出与应用版本; +-- 局部 board/node 活跃部分唯一索引防止同目标同时重复生成。 +-- canvas_ai_events:以 run/seq 主键保证重放顺序;appendAIEvent 用同一 SQL 推进 last_seq。 +-- canvas_ai_mutations:旧协议按 run/账户/动作/键冻结应用和取消结果;不同于 run 生成重试。 +-- 租约过期不证明模型尚未执行,恢复把未知执行标为中断,只有明确 codex_busy 才允许回队。 + +-- db/008-canvas-model.sql:只安装 canonical schema,不自动迁移已有用户快照。 +-- canvas_model_projects:每根显式迁移身份屏障,记录源版本表与 migration_id。 +-- canvas_model_canvases:树关系、入口元素、独立版本及 archived;父/入口同时可空, +-- 无父只能是根;延迟外键允许入口元素与孩子关系在同批创建,提交时再验证。 +-- canvas_model_active_entry 部分唯一索引防止一个活跃入口拥有多个子画布。 +-- canvas_model_elements:主键 (project,element_id) 使身份跨工作区/树不可被抢占; +-- record 的 id/owner/incarnation 必须与索引列相符,删除记录保留 deleted_incarnation。 +-- owner 外键延迟验证,支持同事务移动所有权;应用验证整个最终树和连接共同祖先。 +-- canvas_model_identity_map:保留来源画布/结构/旧 ID 到稳定元素 ID 的完整一次性映射。 +-- canvas_model_requests:账户作用域请求键、动作、摘要、状态与冻结回执,确定拒绝也可恢复。 +-- canvas_model_operations:逻辑 ID 独立于传输 request_id 去重,外键延迟到同事务回执落库; +-- 只有应用成功才消费逻辑身份,拒绝前缀不能把其中操作标为已执行。 +-- foundry_guard_canonical_canvas:已迁入树的 canvas_document/version 改写需事务内 +-- foundry.canonical_writer=on,阻止旧写入路径覆盖权威身份。此标志是应用协作约定,不替代数据库角色权限。 + +-- db/009-canvas-ai-operations.sql:为 run 增加可空 logical_operation_id,旧行保持 NULL。 +-- 部分唯一索引限定项目/工作区/账户下同逻辑操作只能准入一个 run,换传输键不能重复付费执行。 + +-- db/010-canvas-ai-receipts.sql:把传输回执从执行保留周期中分离。 +-- canvas_ai_requests:允许 run.start/cancel/apply,保存 applied/not-applied 与原始请求身份; +-- 不以 run 外键级联删除,使 run 清理后仍可判定已知结果,工作区删除则整体清理。 +-- applied 逻辑操作部分唯一:确定零效果拒绝可显式用新键重计划,已应用操作不能再次执行。 +-- INSERT ... SELECT 从旧 canonical run 回填 accepted 回执,ON CONFLICT 保留已有记录。 +-- 回执缺失只能回答 unknown,不能证明历史付费调用从未发生。 + +-- db/011-canvas-ai-target-location.sql:分离冻结来源与实际应用位置。 +-- applied_board_id:结果写到 owner 移动后的目标画布,旧已应用行按原 board_id 回填。 +-- canvas_ai_canonical_target_busy:按根/稳定节点/代数而非原 board 唯一限制活跃步骤, +-- owner-only 移动不能逃过 node_busy,再次删除/恢复的新代则由生命周期检查单独处理。 diff --git a/go.mod b/go.mod index 150984c..41b4c89 100644 --- a/go.mod +++ b/go.mod @@ -1,12 +1,16 @@ +// Foundry Go 模块身份,internal 包的导入前缀必须与此一致。 module gitea.entroia.com/Zayden-Jung/foundry-core +// CI 从此读取工具链版本,避免开发和远程构建使用不同语言契约。 go 1.25.0 +// 直接依赖提供 PostgreSQL 驱动/事务与图片解码缩放能力。 require ( github.com/jackc/pgx/v5 v5.7.6 golang.org/x/image v0.25.0 ) +// 以下保留 Go 模块图要求的间接依赖;版本校验摘要由 go.sum 管理。 require ( github.com/jackc/pgpassfile v1.0.0 // indirect github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect diff --git a/internal/auth/auth.go b/internal/auth/auth.go index 6149651..230d0f5 100644 --- a/internal/auth/auth.go +++ b/internal/auth/auth.go @@ -1,3 +1,4 @@ +// Package auth 管理项目隔离的登录:提供方回调产生 grant,前端凭 verifier 换取 bearer 会话。 package auth import ( @@ -19,9 +20,11 @@ import ( "time" ) +// 项目名限制为可用于路由的短标识;令牌格式对应 32 随机字节的无填充 base64url。 var projectName = regexp.MustCompile(`^[a-z][a-z0-9-]*$`) var tokenPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{43}$`) +// service 共享数据库、回调白名单和外部 HTTP 客户端;passwordSlots 限制 bcrypt 并发。 type service struct { db *sql.DB projects map[string]*url.URL @@ -33,13 +36,16 @@ type service struct { slack *SlackConfig } +// New 由进程入口调用,验证项目回调并返回独立认证路由;db 的关闭由调用方负责。 func New(db *sql.DB, callbacks map[string]string, redirectURI, id, secret string, email *EmailConfig, slack *SlackConfig) (http.Handler, error) { + // 未注册邮箱也执行同成本密码比对,减少通过响应耗时区分账号存在性的差异。 dummy, err := bcrypt.GenerateFromPassword([]byte("foundry-invalid-login-placeholder"), bcrypt.DefaultCost) if err != nil { return nil, err } s := &service{db: db, email: email, slack: slack, passwordSlots: make(chan struct{}, 4), dummyPassword: dummy, projects: make(map[string]*url.URL), redirectURI: redirectURI, clientID: id, secret: secret, google: &http.Client{Timeout: 10 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}} + // 回调固定在配置白名单,生产要求 HTTPS,开发仅允许回环主机使用 HTTP。 for name, raw := range callbacks { u, err := url.Parse(raw) if err != nil { @@ -52,6 +58,7 @@ func New(db *sql.DB, callbacks map[string]string, redirectURI, id, secret string } s.projects[name] = u } + // healthz 仅说明进程可响应;readyz 查询账户表,覆盖连接与基础 schema 就绪性。 mux := http.NewServeMux() mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) { reply(w, 200, payload{"status": "ok"}) }) mux.HandleFunc("GET /readyz", s.wrap(func(w http.ResponseWriter, r *http.Request) error { @@ -73,8 +80,10 @@ func New(db *sql.DB, callbacks map[string]string, redirectURI, id, secret string }), nil } +// payload 是小型 JSON 响应对象,nil 响应体用于 204 等无内容结果。 type payload map[string]any +// reply 必须在尚未写响应时调用;编码/网络错误当前由调用链忽略。 func reply(w http.ResponseWriter, status int, body payload) { if body != nil { w.Header().Set("Content-Type", "application/json") @@ -85,11 +94,13 @@ func reply(w http.ResponseWriter, status int, body payload) { } } +// reject 已写出预期业务错误并返回 nil,避免 wrap 再次将它改写为 503。 func reject(w http.ResponseWriter, status int, code string) error { reply(w, status, payload{"error": code}) return nil } +// wrap 将未处理依赖错误统一返回 503,日志仅记录类型,避免泄露凭据和提供方响应。 func (s *service) wrap(handle func(http.ResponseWriter, *http.Request) error) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { if err := handle(w, r); err != nil { @@ -99,17 +110,20 @@ func (s *service) wrap(handle func(http.ResponseWriter, *http.Request) error) ht } } +// token 生成可放入 Cookie、URL fragment 或请求头的随机凭据。 func token() string { var value [32]byte rand.Read(value[:]) return base64.RawURLEncoding.EncodeToString(value[:]) } +// digest 用于凭据落库摘要和 S256 challenge;不用于密码存储,密码使用 bcrypt。 func digest(value string) string { sum := sha256.Sum256([]byte(value)) return base64.RawURLEncoding.EncodeToString(sum[:]) } +// project 先校验项目,再分派登录与会话动作;Origin 缺省的服务端请求仍可进入认证。 func (s *service) project(w http.ResponseWriter, r *http.Request) error { project, action := r.PathValue("project"), r.PathValue("action") frontend := s.projects[project] @@ -150,11 +164,14 @@ func (s *service) project(w http.ResponseWriter, r *http.Request) error { return nil } +// oauthCookie 以随机 state 区分并行登录,__Host- 前缀配合 Secure、根路径和无 Domain。 func oauthCookie(state, value string, maxAge int) *http.Cookie { return &http.Cookie{Name: "__Host-foundry-oauth-" + state, Value: value, Path: "/", MaxAge: maxAge, Secure: true, HttpOnly: true, SameSite: http.SameSiteLaxMode} } +// start 保存十分钟 OAuth 尝试;browser 绑定浏览器,verifier 用于 Google 端 PKCE。 +// 前端 challenge 是另一层兑换证明,最终与 login_grants 绑定。 func (s *service) start(w http.ResponseWriter, r *http.Request, project string) error { challenge := r.URL.Query().Get("challenge") if !tokenPattern.MatchString(challenge) { @@ -177,6 +194,7 @@ func (s *service) start(w http.ResponseWriter, r *http.Request, project string) return nil } +// googleJSON 同时用于 Google 和 Slack;客户端拒绝重定向,响应解码最多读取 1 MiB。 func (s *service) googleJSON(ctx context.Context, method, endpoint string, form url.Values, bearer string, result any) error { var body io.Reader if form != nil { @@ -203,6 +221,7 @@ func (s *service) googleJSON(ctx context.Context, method, endpoint string, form return json.NewDecoder(io.LimitReader(res.Body, 1<<20)).Decode(result) } +// callback 原子删除 OAuth 尝试后换取 Google 身份;后续网络失败也不能重放该 state。 func (s *service) callback(w http.ResponseWriter, r *http.Request) error { ctx := r.Context() query := r.URL.Query() @@ -232,6 +251,7 @@ func (s *service) callback(w http.ResponseWriter, r *http.Request) error { } http.SetCookie(w, oauthCookie(state, "", -1)) + // 复制共享 URL 后再写 fragment,避免并发请求改动项目白名单;交换码不放查询参数。 destination := *frontend code := query.Get("code") if code == "" || query.Has("error") { @@ -278,6 +298,7 @@ func (s *service) callback(w http.ResponseWriter, r *http.Request) error { return nil } +// exchange 在同一 SQL 中消费一次性 grant 并建会话;项目、challenge、期限必须全部匹配。 func (s *service) exchange(w http.ResponseWriter, r *http.Request, project string) error { code, verifier := r.Header.Get("X-Foundry-Code"), r.Header.Get("X-Foundry-Verifier") if !tokenPattern.MatchString(code) || !tokenPattern.MatchString(verifier) { @@ -307,6 +328,7 @@ func (s *service) exchange(w http.ResponseWriter, r *http.Request, project strin return nil } +// account 的 me 分支校验并续期,logout 按项目删除摘要且允许重复注销返回 204。 func (s *service) account(w http.ResponseWriter, r *http.Request, project string, logout bool) error { token, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ") if !ok || !tokenPattern.MatchString(token) { diff --git a/internal/auth/email.go b/internal/auth/email.go index 4855335..92367ca 100644 --- a/internal/auth/email.go +++ b/internal/auth/email.go @@ -1,3 +1,4 @@ +// 邮箱登录链路:注册写待验证记录和 outbox,确认链接才创建账户;登录直接校验 bcrypt。 package auth import ( @@ -13,11 +14,14 @@ import ( "golang.org/x/crypto/bcrypt" ) +// emailAddress 统一大小写并拒绝显示名形式,只接受最多 254 字节的纯邮箱地址。 func emailAddress(value string) (string, bool) { value = strings.ToLower(strings.TrimSpace(value)) address, err := mail.ParseAddress(value) return value, err == nil && address.Address == value && len(value) <= 254 } + +// emailBody 限制 16 KiB、拒绝未知字段及尾随 JSON;失败时已经写出 400。 func emailBody(w http.ResponseWriter, r *http.Request, input any) bool { decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 16384)) decoder.DisallowUnknownFields() @@ -28,6 +32,7 @@ func emailBody(w http.ResponseWriter, r *http.Request, input any) bool { return true } +// rateLimit 将键摘要计入数据库十五分钟固定窗口,过期后第一次访问重新计数。 func (s *service) rateLimit(ctx context.Context, key string, limit int) (bool, error) { var count int err := s.db.QueryRowContext(ctx, ` @@ -40,6 +45,7 @@ RETURNING attempts return count <= limit, err } +// emailAction 由 project 路由调用;先限频,再以非阻塞信号量限制密码哈希占用。 func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, action string) error { if action == "verify-email" { return s.verifyEmail(w, r, project) @@ -70,6 +76,7 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a w.Header().Set("Retry-After", "900") return reject(w, 429, "rate_limited") } + // 四个槽位都忙时立即返回 429,不让昂贵 bcrypt 请求无限排队。 select { case s.passwordSlots <- struct{}{}: defer func() { <-s.passwordSlots }() @@ -87,6 +94,7 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a return err } passwordHash := []byte(hash) + // 不存在的账户使用启动时生成的 dummy 哈希,但无论密码比对结果如何均拒绝登录。 if missing { passwordHash = s.dummyPassword } @@ -102,6 +110,8 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a return nil } +// registerEmail 在邮箱级事务锁下更新三十分钟验证记录,邮件与记录共同提交。 +// 已注册邮箱不写新邮件,仍返回相同 202,避免从此响应枚举账号。 func (s *service) registerEmail(w http.ResponseWriter, r *http.Request, project, email, password string) error { hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost) if err != nil { @@ -147,6 +157,8 @@ INSERT INTO email_outbox(project,recipient,subject,body,expires_at) VALUES($1,$2 return nil } +// verifyEmail 先定位邮箱再加同一事务锁,随后删除并返回有效记录以保证验证码一次性消费。 +// 账户、邮箱凭据、会话都成功后才提交,任何失败交由 defer 回滚。 func (s *service) verifyEmail(w http.ResponseWriter, r *http.Request, project string) error { var input struct { Token string `json:"token"` diff --git a/internal/auth/email_test.go b/internal/auth/email_test.go index b2b3227..6f4739c 100644 --- a/internal/auth/email_test.go +++ b/internal/auth/email_test.go @@ -1,3 +1,4 @@ +// 认证回归:数据库用例需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移的 fixture。 package auth import ( @@ -12,6 +13,7 @@ import ( "testing" ) +// TestConcurrentRegistrationAndVerification 并发重发注册与消费原验证链接,允许任一先取得邮箱锁;最终只能留下一个凭据或一个待验证记录。 func TestConcurrentRegistrationAndVerification(t *testing.T) { dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL") if dsn == "" { @@ -45,6 +47,7 @@ func TestConcurrentRegistrationAndVerification(t *testing.T) { if len(match) != 2 { t.Fatal("missing verification link") } + // 缓冲通道收集两条 goroutine 的结果;这里断言最终数据库一致性,不规定抢锁顺序。 done := make(chan error, 2) go func() { r := httptest.NewRequest("POST", "https://api.example.com/register", nil) diff --git a/internal/auth/identity.go b/internal/auth/identity.go index d4ef1e9..8c9b7fa 100644 --- a/internal/auth/identity.go +++ b/internal/auth/identity.go @@ -1,3 +1,4 @@ +// 本文件把 Google、Slack、邮箱等提供方身份归一为项目账户,并签发一次性交换码。 package auth import ( @@ -8,7 +9,10 @@ import ( "strings" ) +// identityGrant 由已完成提供方验证的登录流程调用;subject 必须是该提供方的稳定身份。 +// challenge 来自前端登录起点,后续 exchange 必须提交对应 verifier 才能换取会话。 func (s *service) identityGrant(ctx context.Context, project, provider, subject string, email *string, name, picture, challenge string) (string, error) { + // 外部资料仅作为初始显示信息:限制姓名长度,头像只接受无用户信息的 HTTPS URL。 name = strings.TrimSpace(name) if len(name) > 160 { name = "" @@ -20,13 +24,15 @@ func (s *service) identityGrant(ctx context.Context, project, provider, subject if err != nil { return "", err } + // 账户、身份关联和短期 grant 同事务提交;任一步失败都不遗留半注册账户。 defer tx.Rollback() - // Serialize first registration for the same provider identity. + // 事务级 advisory lock 串行化同项目、同提供方、同 subject 的首次注册;事务结束即释放。 if _, err = tx.ExecContext(ctx, "SELECT pg_advisory_xact_lock(hashtextextended($1,0))", project+":"+provider+":"+subject); err != nil { return "", err } var account string err = tx.QueryRowContext(ctx, "SELECT account_id::text FROM account_identities WHERE project=$1 AND provider=$2 AND subject=$3", project, provider, subject).Scan(&account) + // 身份不存在才建账户;不会仅凭相同邮箱自动合并不同提供方的身份。 if errors.Is(err, sql.ErrNoRows) { var googleSubject *string if provider == "google" { @@ -44,6 +50,7 @@ SELECT $1,id,$2,$3, } _, err = tx.ExecContext(ctx, "INSERT INTO account_identities(project,provider,subject,account_id) VALUES($1,$2,$3,$4)", project, provider, subject, account) } else if err == nil { + // 老账户保留已有显示名/头像,只补空值;非空提供方邮箱会更新账户邮箱。 _, err = tx.ExecContext(ctx, ` UPDATE project_accounts SET email=COALESCE($3,email), display_name=CASE WHEN display_name='' THEN $4 ELSE display_name END, @@ -55,6 +62,7 @@ UPDATE project_accounts SET email=COALESCE($3,email), if err != nil { return "", err } + // 只落库交换码摘要,明文仅返回给回调方;一分钟期限和前端 challenge 限制兑换。 grant := token() _, err = tx.ExecContext(ctx, "INSERT INTO login_grants VALUES($1,$2,$3,$4,now()+interval '1 minute')", digest(grant), project, account, challenge) if err != nil { diff --git a/internal/auth/mailer.go b/internal/auth/mailer.go index 77efda5..7ab748b 100644 --- a/internal/auth/mailer.go +++ b/internal/auth/mailer.go @@ -1,3 +1,4 @@ +// 邮件发送采用数据库 outbox:登录请求写队列,Run 后台轮询租约并通过 SMTP 投递。 package auth import ( @@ -15,10 +16,12 @@ import ( "time" ) +// EmailConfig 是可选 SMTP 能力配置;Password 仅用于内存中的 SMTP 认证。 type EmailConfig struct { Host, Port, Username, Password, From string } +// EmailConfigFromEnv 允许整组缺省以关闭邮件登录;部分配置或非 465 TLS 配置会启动失败。 func EmailConfigFromEnv() (*EmailConfig, error) { c := &EmailConfig{Host: os.Getenv("SMTP_HOST"), Port: os.Getenv("SMTP_PORT"), Username: os.Getenv("SMTP_USERNAME"), Password: os.Getenv("SMTP_PASSWORD"), From: os.Getenv("SMTP_FROM")} if c.Host == "" && c.Port == "" && c.Username == "" && c.Password == "" && c.From == "" { @@ -31,6 +34,8 @@ func EmailConfigFromEnv() (*EmailConfig, error) { return c, nil } +// send 同步发送一封纯文本邮件;拒绝头部换行,并用 TLS 主机名验证和连接期限约束网络操作。 +// SMTP 调用不接收 context,Run 的取消要等当前发送结束或网络期限到达。 func (c *EmailConfig) send(recipient, subject, body string) error { if strings.ContainsAny(recipient+subject, "\r\n") { return errors.New("invalid mail headers") @@ -69,6 +74,7 @@ func (c *EmailConfig) send(recipient, subject, body string) error { return client.Quit() } +// Run 由进程入口启动;每三秒最多认领一封,nil 配置直接返回,取消上下文停止后续轮询。 func (c *EmailConfig) Run(ctx context.Context, db *sql.DB) { if c == nil { return @@ -86,6 +92,9 @@ func (c *EmailConfig) Run(ctx context.Context, db *sql.DB) { } } } + +// deliver 用 SKIP LOCKED 避开其他 worker 正在认领的行,两分钟租约允许进程失败后重试。 +// SMTP 成功与数据库标记并非同一事务;标记失败时后续可能再次投递。 func (c *EmailConfig) deliver(ctx context.Context, db *sql.DB) error { var id, lease, recipient, subject, body string var attempts int @@ -99,11 +108,14 @@ RETURNING id::text,lease_id::text,recipient,subject,body,attempts if err != nil { return err } + // lease 是本轮所有权标记;回写时匹配它,避免旧 worker 覆盖租约到期后的新认领结果。 sendErr := c.send(recipient, subject, body) if sendErr == nil { + // 成功后清空邮件正文,减少验证码在队列中的保留;收件人和投递记录仍保留。 _, err = db.ExecContext(ctx, "UPDATE email_outbox SET sent_at=now(),body='',lease_until=NULL,lease_id=NULL WHERE id=$1 AND lease_id=$2", id, lease) return err } + // attempts 在认领时递增:第一次失败延迟 60 秒,指数退避最多 3840 秒,最多尝试十次。 delay := 30 * (1 << min(attempts, 7)) _, err = db.ExecContext(ctx, "UPDATE email_outbox SET available_at=now()+$3*interval '1 second',lease_until=NULL,lease_id=NULL WHERE id=$1 AND lease_id=$2", id, lease, delay) if err != nil { diff --git a/internal/auth/session.go b/internal/auth/session.go index 075d8b1..1c1006c 100644 --- a/internal/auth/session.go +++ b/internal/auth/session.go @@ -1,3 +1,4 @@ +// 本文件是认证与 platform/research 路由共享的会话入口:数据库同时检查项目、闲置期限和绝对期限。 package auth import ( @@ -9,11 +10,16 @@ import ( "strings" ) +// SessionIdleSeconds 是每次有效访问可续期的闲置窗口,绝对期限仍由数据库列限制。 const SessionIdleSeconds = 30 * 24 * 60 * 60 + +// SessionExpiryHeader 向客户端返回本次续期后的剩余秒数,供其更新本地会话提示。 const SessionExpiryHeader = "X-Foundry-Session-Expires-In" +// ErrInvalidSession 区分凭据无效与数据库故障,调用方可据此选择 401 或服务错误。 var ErrInvalidSession = errors.New("invalid session") +// Session 只携带项目内账户和剩余有效期;原始 bearer token 不进入返回结构。 type Session struct { AccountID string ExpiresIn int64 @@ -21,11 +27,13 @@ type Session struct { // AuthenticateSession atomically validates and renews a live session, bounded by // its absolute deadline. Expired, revoked and wrong-project tokens never renew. +// AuthenticateSession 在单条 UPDATE 中检查项目、闲置和绝对期限,仅续期仍有效会话并返回剩余秒数。 func AuthenticateSession(ctx context.Context, db *sql.DB, project, authorization string) (Session, error) { value, ok := strings.CutPrefix(authorization, "Bearer ") if !ok || !tokenPattern.MatchString(value) { return Session{}, ErrInvalidSession } + // 单条 UPDATE 完成校验和续期,避免先查后写把已经撤销或过期的会话重新激活。 var session Session err := db.QueryRowContext(ctx, ` UPDATE project_sessions @@ -33,17 +41,20 @@ SET expires_at=LEAST(now()+interval '30 days',absolute_expires_at) WHERE project=$1 AND token_hash=$2 AND expires_at>now() AND absolute_expires_at>now() RETURNING account_id::text,GREATEST(0,FLOOR(EXTRACT(EPOCH FROM (expires_at-now()))))::bigint `, project, digest(value)).Scan(&session.AccountID, &session.ExpiresIn) + // 无匹配行包含错误项目、已注销、闲置过期和绝对过期,统一隐藏具体原因。 if errors.Is(err, sql.ErrNoRows) { return Session{}, ErrInvalidSession } return session, err } +// WriteSessionHeaders 由 HTTP 调用方在写出响应体前执行;它本身不校验或续期。 func WriteSessionHeaders(w http.ResponseWriter, session Session) { w.Header().Set(SessionExpiryHeader, strconv.FormatInt(session.ExpiresIn, 10)) } // Authenticate preserves the existing API for clients that only need an account ID. +// Authenticate 供只需账户 ID 的旧调用方使用,同样会触发 AuthenticateSession 的续期。 func Authenticate(ctx context.Context, db *sql.DB, project, authorization string) (string, error) { session, err := AuthenticateSession(ctx, db, project, authorization) return session.AccountID, err diff --git a/internal/auth/session_test.go b/internal/auth/session_test.go index 71b36fe..1ec4999 100644 --- a/internal/auth/session_test.go +++ b/internal/auth/session_test.go @@ -1,3 +1,4 @@ +// 认证回归:数据库用例需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移的 fixture。 package auth import ( @@ -14,6 +15,7 @@ import ( _ "github.com/jackc/pgx/v5/stdlib" ) +// sessionFixture 建随机项目账户,通过 t.Cleanup 级联删除相关数据并关闭连接池。 func sessionFixture(t *testing.T) (*sql.DB, string, string) { t.Helper() dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL") @@ -33,6 +35,7 @@ func sessionFixture(t *testing.T) (*sql.DB, string, string) { return db, project, account } +// TestSessionIdleAndAbsoluteExpiry 覆盖闲置/绝对过期与续期上限;过期记录的时间戳不得被认证请求更新。 func TestSessionIdleAndAbsoluteExpiry(t *testing.T) { db, project, account := sessionFixture(t) for _, test := range []struct { @@ -85,6 +88,7 @@ func TestSessionIdleAndAbsoluteExpiry(t *testing.T) { } } +// TestSessionIsolationRevocationAndConcurrentRenewal 检查错误项目与坏凭据拒绝、四个并发续期受绝对期限限制、删除后不能重新续期。 func TestSessionIsolationRevocationAndConcurrentRenewal(t *testing.T) { db, project, account := sessionFixture(t) value := token() @@ -116,6 +120,7 @@ func TestSessionIsolationRevocationAndConcurrentRenewal(t *testing.T) { } } +// TestOAuthExchangeIssuesLongLivedSessionAndMeReturnsRemainingLifetime 从真实 grant 兑换会话,检查三十天闲置/九十天绝对期限,以及 me 响应的续期头。 func TestOAuthExchangeIssuesLongLivedSessionAndMeReturnsRemainingLifetime(t *testing.T) { db, project, account := sessionFixture(t) code, verifier := token(), token() diff --git a/internal/auth/slack.go b/internal/auth/slack.go index 1a94da6..86e2125 100644 --- a/internal/auth/slack.go +++ b/internal/auth/slack.go @@ -1,3 +1,4 @@ +// Slack OIDC 登录验证独立 ID token,再复用 identityGrant 和前端 grant 兑换协议。 package auth import ( @@ -18,6 +19,7 @@ import ( "time" ) +// SlackConfig 保存可选客户端凭据以及由 mu 保护的签名公钥缓存。 type SlackConfig struct { ClientID, Secret, RedirectURI string mu sync.Mutex @@ -25,6 +27,7 @@ type SlackConfig struct { fetchedAt time.Time } +// SlackConfigFromEnv 允许整组缺省以关闭 Slack;只配置一半会阻止服务启动。 func SlackConfigFromEnv(redirect string) (*SlackConfig, error) { id, secret := os.Getenv("SLACK_CLIENT_ID"), os.Getenv("SLACK_CLIENT_SECRET") if id == "" && secret == "" { @@ -36,6 +39,7 @@ func SlackConfigFromEnv(redirect string) (*SlackConfig, error) { return &SlackConfig{ClientID: id, Secret: secret, RedirectURI: redirect}, nil } +// slackClaims 仅在验签、发行方/受众/时间和 nonce 校验后用于账户身份。 type slackClaims struct { Issuer string `json:"iss"` Subject string `json:"sub"` @@ -50,6 +54,7 @@ type slackClaims struct { Picture string `json:"picture"` } +// slackKey 在互斥锁内加载并缓存 JWKS 一分钟;缓存期遇到未知 kid 直接拒绝,避免重复拉取。 func (s *service) slackKey(ctx context.Context, kid string) (*rsa.PublicKey, error) { c := s.slack c.mu.Lock() @@ -73,6 +78,7 @@ func (s *service) slackKey(ctx context.Context, kid string) (*rsa.PublicKey, err if err := s.googleJSON(ctx, "GET", "https://slack.com/openid/connect/keys", nil, "", &document); err != nil { return nil, err } + // 只接收可用于 RS256 签名的 RSA 公钥,并约束模数和指数大小。 keys := map[string]*rsa.PublicKey{} for _, key := range document.Keys { n, nErr := base64.RawURLEncoding.DecodeString(key.N) @@ -93,6 +99,8 @@ func (s *service) slackKey(ctx context.Context, kid string) (*rsa.PublicKey, err } return nil, errors.New("unknown Slack signing key") } + +// verifySlack 限制 token 长度与算法,先验签再信任 payload;nonce 将身份绑定到本次登录。 func (s *service) verifySlack(ctx context.Context, value, nonce string) (slackClaims, error) { var claims slackClaims invalid := errors.New("invalid Slack identity token") @@ -136,6 +144,8 @@ func (s *service) verifySlack(ctx context.Context, value, nonce string) (slackCl } return claims, nil } + +// startSlack 写十分钟尝试和 OIDC nonce,Cookie 采用 SameSite=None 以接收跨站 POST 回调。 func (s *service) startSlack(w http.ResponseWriter, r *http.Request, project string) error { if s.slack == nil { return reject(w, 503, "slack_not_configured") @@ -159,6 +169,8 @@ VALUES($1,$2,$3,$4,'',now()+interval '10 minutes','slack',$5) http.Redirect(w, r, "https://slack.com/openid/connect/authorize?"+query.Encode(), 302) return nil } + +// slackCallback 接受 GET/POST,先一次性消费浏览器绑定的尝试,再向 Slack 兑换 ID token。 func (s *service) slackCallback(w http.ResponseWriter, r *http.Request) error { if s.slack == nil { return reject(w, 503, "slack_not_configured") @@ -216,6 +228,7 @@ RETURNING project,frontend_challenge,oidc_nonce if err != nil { return err } + // 团队和用户共同构成 subject;verifySlack 已拒绝冒号,避免拼接身份产生歧义。 grant, err := s.identityGrant(r.Context(), project, "slack", claims.Team+":"+claims.Subject, claims.Email, claims.Name, claims.Picture, challenge) if err != nil { return err diff --git a/internal/auth/slack_test.go b/internal/auth/slack_test.go index 938f604..0237e50 100644 --- a/internal/auth/slack_test.go +++ b/internal/auth/slack_test.go @@ -1,3 +1,4 @@ +// 认证回归:数据库用例需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移的 fixture。 package auth import ( @@ -21,6 +22,7 @@ import ( _ "github.com/jackc/pgx/v5/stdlib" ) +// signIdentity 为 fixture kid 生成 RS256 JWT;测试公钥缓存在内存,不访问 Slack JWKS。 func signIdentity(t *testing.T, key *rsa.PrivateKey, claims slackClaims) string { t.Helper() header := base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"RS256","kid":"fixture"}`)) @@ -36,6 +38,8 @@ func signIdentity(t *testing.T, key *rsa.PrivateKey, claims slackClaims) string } return value + "." + base64.RawURLEncoding.EncodeToString(sig) } + +// TestSlackIdentityVerification 使用本地 RSA 私钥签发样本,分别破坏发行方、受众、时间、nonce、签名及算法,仅有效样本可通过。 func TestSlackIdentityVerification(t *testing.T) { key, err := rsa.GenerateKey(rand.Reader, 2048) if err != nil { @@ -76,6 +80,8 @@ func TestSlackIdentityVerification(t *testing.T) { }) } } + +// TestSlackCallbackAndExchange 使用临时 HTTP 上游和真实测试库走 Slack 起点、POST 回调、grant 兑换;拒绝回调重放并保留用户已选资料。 func TestSlackCallbackAndExchange(t *testing.T) { dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL") if dsn == "" { @@ -184,8 +190,10 @@ func TestSlackCallbackAndExchange(t *testing.T) { } } +// rewriteTransport 只把测试外部调用改写到本地上游,保留路径和请求上下文。 type rewriteTransport struct{ destination string } +// RoundTrip 克隆请求后改目标,避免修改被测函数持有的原请求对象。 func (t rewriteTransport) RoundTrip(r *http.Request) (*http.Response, error) { cloned := r.Clone(r.Context()) target, _ := url.Parse(t.destination) @@ -193,6 +201,7 @@ func (t rewriteTransport) RoundTrip(r *http.Request) (*http.Response, error) { return http.DefaultTransport.RoundTrip(cloned) } +// TestGoogleIdentityKeepsLegacyAccount 依赖迁移 fixture 的旧 Google 身份与会话,验证新身份归一流程仍使用原账户且不删除旧会话。 func TestGoogleIdentityKeepsLegacyAccount(t *testing.T) { dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL") if dsn == "" { diff --git a/internal/codex/canvas.go b/internal/codex/canvas.go index 68c94c3..6844f0c 100644 --- a/internal/codex/canvas.go +++ b/internal/codex/canvas.go @@ -1,3 +1,4 @@ +// 画布 AI 的私有 IPC 客户端与模型目录:平台侧只看到稳定模型 ID,执行后端保留在 worker 内。 package codex import ( @@ -15,8 +16,10 @@ import ( "time" ) +// CanvasInputLimit 限制提示词字节数;图片另按解码后的总字节限制。 const CanvasInputLimit = 1 << 20 +// CanvasModel 是过滤后的模型能力快照;Backend 不序列化,仅供 worker 启动 CLI。 type CanvasModel struct { ID string `json:"id"` Label string `json:"label"` @@ -32,6 +35,7 @@ type CanvasModel struct { // Only curated catalog fields leave the worker. Raw CLI cache metadata, // local paths, authentication files and backend configuration stay private. +// workerCanvasModels 读取 worker 本地缓存,只公布 list 可见且支持文本/图像输入的条目。 func workerCanvasModels() ([]CanvasModel, error) { raw, err := os.ReadFile("/home/node/.codex/models_cache.json") if err != nil { @@ -53,6 +57,7 @@ func workerCanvasModels() ([]CanvasModel, error) { if entry.Visibility != "list" || entry.Slug == "" || strings.HasPrefix(entry.Slug, "-") || len(entry.Slug) > 128 { continue } + // 稳定散列生成公开 ID;标签可展示,实际 slug 不作为公开 Backend 字段输出。 sum := sha256.Sum256([]byte("codex-cli/" + entry.Slug)) inputs := []string{} for _, value := range entry.Inputs { @@ -72,6 +77,7 @@ func workerCanvasModels() ([]CanvasModel, error) { } result = append(result, CanvasModel{ID: "codex-" + hex.EncodeToString(sum[:16]), Label: label, Provider: "codex-cli", InputModalities: inputs, OutputModalities: []string{"text"}, Available: true, MaxExecutionMS: 90000, MaxInputBytes: CanvasInputLimit, ParametersSchema: map[string]any{"type": "object", "properties": map[string]any{}, "additionalProperties": false}, Backend: entry.Slug}) } + // 图片输出能力必须显式列入已验证后端名单,不能根据支持图片输入推断支持图片生成。 verified := map[string]bool{} for _, id := range strings.Split(os.Getenv("FOUNDRY_CANVAS_IMAGE_MODELS"), ",") { id = strings.TrimSpace(id) @@ -95,8 +101,10 @@ func workerCanvasModels() ([]CanvasModel, error) { return result, nil } +// CanvasClient 通过固定 Unix socket 发送 HTTP;URL 主机名只是协议占位符,不进行 DNS 连接。 type CanvasClient struct{ client *http.Client } +// NewCanvasClient 在未配置 socket 时返回 nil,调用方法会转换为明确的不可用错误。 func NewCanvasClient(socket string) *CanvasClient { if socket == "" { return nil @@ -106,6 +114,8 @@ func NewCanvasClient(socket string) *CanvasClient { }} return &CanvasClient{client: &http.Client{Transport: transport, Timeout: 182 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}} } + +// Models 限制目录响应为 256 KiB,只接受成功状态和完整 JSON,隐藏 worker 内部失败原因。 func (c *CanvasClient) Models(ctx context.Context) ([]CanvasModel, error) { if c == nil { return nil, errors.New("codex_unavailable") @@ -135,6 +145,7 @@ func (c *CanvasClient) Models(ctx context.Context) ([]CanvasModel, error) { return result.Models, nil } +// CanvasTask 在 platform 调度器与 worker 之间传递提示、模型及可选图片;当前参数对象必须为空。 type CanvasTask struct { OutputModality string `json:"output_modality,omitempty"` Images []CanvasImage `json:"images,omitempty"` @@ -143,6 +154,7 @@ type CanvasTask struct { Parameters map[string]any `json:"parameters"` } +// Generate 是只需文本的兼容入口;复用结构化输出校验,并拒绝图片结果。 func (c *CanvasClient) Generate(ctx context.Context, input CanvasTask) (string, error) { output, err := c.GenerateOutput(ctx, input) if err != nil { diff --git a/internal/codex/canvas_artifacts.go b/internal/codex/canvas_artifacts.go index 8bf148d..312f753 100644 --- a/internal/codex/canvas_artifacts.go +++ b/internal/codex/canvas_artifacts.go @@ -1,3 +1,4 @@ +// 画布生成的结构化 IPC 输出;图片以字节传到核心,再由平台资产流程验证和持久化。 package codex import ( @@ -9,13 +10,17 @@ import ( "net/http" ) +// CanvasImageBytesLimit 限制原始图片总字节,响应上限另为 JSON/base64 编码留出空间。 const CanvasImageBytesLimit = 20 << 20 const canvasArtifactResponseLimit = 32 << 20 +// CanvasImage 的 Data 在 JSON 中编码为 base64,仅用于私有 Unix 通道。 type CanvasImage struct { MIME string `json:"mime_type"` Data []byte `json:"data"` } + +// CanvasOutput 用 Kind 区分文本和图片,由 GenerateOutput 再校验形态与请求模态相符。 type CanvasOutput struct { Kind string `json:"kind"` Text string `json:"text,omitempty"` @@ -24,6 +29,7 @@ type CanvasOutput struct { // Encoded image bytes exist only on the private Unix IPC channel. Public Canvas // jobs expose stable asset IDs/URLs and never serialize these bytes to browsers. +// GenerateOutput 先检查输入预算,再发送 IPC;映射稳定错误码,兼容旧 worker 的 result 文本字段。 func (c *CanvasClient) GenerateOutput(ctx context.Context, input CanvasTask) (CanvasOutput, error) { if c == nil { return CanvasOutput{}, errors.New("codex_unavailable") @@ -51,6 +57,7 @@ func (c *CanvasClient) GenerateOutput(ctx context.Context, input CanvasTask) (Ca return CanvasOutput{}, err } defer response.Body.Close() + // 多读一字节区分刚好达到上限与实际超限,防止截断响应被当成成功结果。 raw, err = io.ReadAll(io.LimitReader(response.Body, canvasArtifactResponseLimit+1)) if err != nil || len(raw) > canvasArtifactResponseLimit { return CanvasOutput{}, errors.New("generation_failed") @@ -80,6 +87,7 @@ func (c *CanvasClient) GenerateOutput(ctx context.Context, input CanvasTask) (Ca return CanvasOutput{}, errors.New("generation_failed") } } + // 旧响应只允许回退到文本;图片请求缺少结构化图片时必须失败。 if result.Output == nil { if input.OutputModality == "image" { return CanvasOutput{}, errors.New("generation_failed") diff --git a/internal/codex/canvas_artifacts_test.go b/internal/codex/canvas_artifacts_test.go index 5774a58..325cb1d 100644 --- a/internal/codex/canvas_artifacts_test.go +++ b/internal/codex/canvas_artifacts_test.go @@ -1,3 +1,4 @@ +// 本文件用临时目录和固定事件验证产物隔离及完成判定,不启动 CLI 或真实模型。 package codex import ( @@ -7,6 +8,7 @@ import ( "testing" ) +// TestCanvasArtifactDirectoryIsolation 拒绝目录外图片、多张图片和软链接,只接收生成目录内唯一图片。 func TestCanvasArtifactDirectoryIsolation(t *testing.T) { root := t.TempDir() generated := filepath.Join(root, "generated_images") @@ -48,6 +50,8 @@ func TestCanvasArtifactDirectoryIsolation(t *testing.T) { t.Fatal("symlink escaped job output directory") } } + +// TestCanvasAgentCompletionRequiresSuccessfulTurn 拒绝仅有部分文本或完成后报错的流,接受成功结束的流。 func TestCanvasAgentCompletionRequiresSuccessfulTurn(t *testing.T) { if _, ok := canvasAgentText([]byte("{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",\"text\":\"partial\"}}\n")); ok { t.Fatal("partial generation accepted") diff --git a/internal/codex/canvas_worker.go b/internal/codex/canvas_worker.go index 66a18f0..3c57958 100644 --- a/internal/codex/canvas_worker.go +++ b/internal/codex/canvas_worker.go @@ -1,3 +1,4 @@ +// worker 侧画布执行:每次任务新建临时 CODEX_HOME,按模态启动 CLI 并提取完成结果。 package codex import ( @@ -16,6 +17,7 @@ import ( "time" ) +// executeCanvasTask 由共享执行槽保护;模型已从目录选出,但仍须核对请求模态和输入图片。 func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask, model CanvasModel) { imageOutput := input.OutputModality == "image" if input.OutputModality != "" && input.OutputModality != "text" && !imageOutput { @@ -32,6 +34,7 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask, } ctx, cancel := context.WithTimeout(r.Context(), duration) defer cancel() + // 临时目录承载认证软链接、输入图片和生成产物;成功与所有失败路径都由 defer 删除。 job, err := os.MkdirTemp("", "foundry-canvas-") if err != nil { fail(w, 503, "codex_unavailable") @@ -43,11 +46,13 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask, fail(w, 503, "codex_unavailable") return } + // 关闭 shell、应用、插件等能力;文本模型还关闭图片生成,画布模式忽略用户配置与规则。 args := []string{"--ask-for-approval", "never", "--disable", "shell_tool", "--disable", "apps", "--disable", "plugins", "--disable", "multi_agent", "--disable", "hooks", "--disable", "memories", "-c", `web_search="disabled"`} if !imageOutput { args = append(args, "--disable", "image_generation") } args = append(args, "exec", "--json", "--sandbox", "read-only", "--skip-git-repo-check", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--model", model.Backend) + // 对图片内容嗅探 MIME,而非仅信任传入类型;只允许已知栅格格式并限制总大小。 total := 0 for i, image := range input.Images { total += len(image.Data) @@ -80,6 +85,7 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask, cmd.Dir = "/work" cmd.Env = []string{"PATH=/usr/local/bin:/usr/bin:/bin", "HOME=/home/node", "CODEX_HOME=" + home, "SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt"} cmd.Stdin = strings.NewReader(prompt) + // 独立进程组使请求取消/超时可杀掉 CLI 及其子进程,避免残留后台任务。 cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} cmd.Cancel = func() error { err := syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL) @@ -103,6 +109,7 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask, fail(w, 502, "generation_failed") return } + // CLI 退出零还不够:事件流必须完成且无错误,图片结果还需从专用产物目录读取。 text, completed := canvasAgentText(output.buffer.Bytes()) if !completed { fail(w, 502, "generation_failed") @@ -122,6 +129,8 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask, } writeJSON(w, 200, map[string]any{"output": result}) } + +// canvasAgentText 逐行读取 JSON 事件,保留最后一条 agent_message;任何坏行或失败事件均拒绝。 func canvasAgentText(raw []byte) (string, bool) { result := "" completed := false @@ -148,6 +157,9 @@ func canvasAgentText(raw []byte) (string, bool) { } return result, completed } + +// readCanvasGeneratedImage 只遍历本次 generated_images,拒绝软链接、非常规文件和多张候选图片。 +// 此处只做格式嗅探与字节限制;完整解码和尺寸验证由平台资产接收流程负责。 func readCanvasGeneratedImage(root string) (*CanvasImage, error) { var result *CanvasImage err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error { diff --git a/internal/codex/http.go b/internal/codex/http.go index 45c93a0..c435520 100644 --- a/internal/codex/http.go +++ b/internal/codex/http.go @@ -1,3 +1,4 @@ +// 公开文本生成代理:用项目专属凭据授权后,把受限任务通过 Unix IPC 转发给 worker。 package codex import ( @@ -16,16 +17,19 @@ import ( "time" ) +// 公开请求 32 KiB、返回 512 KiB;worker 执行期限九十秒,IPC 客户端另留两秒收尾。 const ( maxRequest = 32 << 10 maxOutput = 512 << 10 timeout = 90 * time.Second ) +// task 仅允许 prompt,公开调用方不能传 sandbox、工具配置或可执行参数。 type task struct { Prompt string `json:"prompt"` } +// writeJSON 统一输出 JSON 并禁用缓存,内部调用者须在此之前完成状态码选择。 func writeJSON(w http.ResponseWriter, status int, value any) { w.Header().Set("Content-Type", "application/json") w.Header().Set("Cache-Control", "no-store") @@ -33,10 +37,12 @@ func writeJSON(w http.ResponseWriter, status int, value any) { _ = json.NewEncoder(w).Encode(value) } +// fail 将依赖或授权失败转换为稳定错误码,避免向公开 API 泄露本地路径和配置。 func fail(w http.ResponseWriter, status int, code string) { writeJSON(w, status, map[string]string{"error": code}) } +// readTask 限制 JSON 大小、未知字段、尾随值与空白 prompt;失败时已写响应。 func readTask(w http.ResponseWriter, r *http.Request, limit int64) (task, bool) { var input task decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, limit)) @@ -59,6 +65,7 @@ func readTask(w http.ResponseWriter, r *http.Request, limit int64) (task, bool) // Register enables the public endpoint only when both configuration files are supplied. // Each credential digest belongs to exactly one project. +// Register 在两项配置齐备时挂载路由,凭据文件每次请求重新读取以支持撤销。 func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile string) error { if socket == "" && grantsFile == "" { return nil @@ -91,6 +98,7 @@ func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile fail(w, 503, "codex_unavailable") return } + // 凭据是 32 字节十六进制值;将摘要与授权表恒定时间比较,再核对目标项目作用域。 hash := sha256.Sum256(key) var scope string for digest, project := range grants { @@ -113,6 +121,7 @@ func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile if !ok { return } + // IPC 只发送解析后的任务体,不转发公开 Authorization 头;连接目的地固定为配置的 socket。 body, _ := json.Marshal(input) req, err := http.NewRequestWithContext(r.Context(), http.MethodPost, "http://codex/exec", bytes.NewReader(body)) if err != nil { @@ -129,6 +138,7 @@ func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile return } defer resp.Body.Close() + // worker 响应必须在预算内且为合法 JSON;保留其状态与 Retry-After,隐藏传输错误细节。 data, err = io.ReadAll(io.LimitReader(resp.Body, maxOutput+1)) if err != nil || len(data) > maxOutput || !json.Valid(data) { fail(w, 502, "invalid_codex_response") diff --git a/internal/codex/http_test.go b/internal/codex/http_test.go index 718a06c..c9f072d 100644 --- a/internal/codex/http_test.go +++ b/internal/codex/http_test.go @@ -1,3 +1,4 @@ +// 公开代理回归使用临时 Unix socket 假 worker,不访问外部服务或真实 CLI。 package codex import ( @@ -13,6 +14,7 @@ import ( "testing" ) +// TestProjectAuthorizationAndForwarding 检查缺凭据/跨项目拒绝、严格任务体、大小限制及授权文件即时撤销。 func TestProjectAuthorizationAndForwarding(t *testing.T) { dir := t.TempDir() socket := filepath.Join(dir, "worker.sock") @@ -20,6 +22,7 @@ func TestProjectAuthorizationAndForwarding(t *testing.T) { if err != nil { t.Fatal(err) } + // 假 worker 要求代理已移除 Authorization,只回显 prompt,用于确认最小化转发契约。 worker := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { if r.URL.Path != "/exec" || r.Header.Get("Authorization") != "" { fail(w, 500, "unexpected_worker_request") diff --git a/internal/codex/worker.go b/internal/codex/worker.go index 51bfd2e..5c7ead6 100644 --- a/internal/codex/worker.go +++ b/internal/codex/worker.go @@ -1,3 +1,4 @@ +// Package codex 在核心 API 与受限 CLI worker 间通过 Unix socket 通信,隔离公开凭据与本地执行环境。 package codex import ( @@ -15,16 +16,19 @@ import ( "time" ) +// executable 指向部署容器预装 CLI,不从请求或 PATH 选择可执行文件。 const executable = "/opt/codex/node_modules/.bin/codex" var errOutputLimit = errors.New("Codex output limit exceeded") +// outputBuffer 对 CLI stdout 累计限额;超限标记用于进程结束后选择稳定错误响应。 type outputBuffer struct { buffer bytes.Buffer exceeded bool limit int } +// Write 实现 io.Writer,默认使用公共输出限制,画布事件流可另设更大内部预算。 func (b *outputBuffer) Write(p []byte) (int, error) { limit := b.limit if limit == 0 { @@ -37,6 +41,7 @@ func (b *outputBuffer) Write(p []byte) (int, error) { return b.buffer.Write(p) } +// ServeWorker 由 main 的 codex-worker 模式调用,重建 0600 socket,只允许一个生成任务同时执行。 func ServeWorker(socket string) error { syscall.Umask(0077) if err := os.Remove(socket); err != nil && !errors.Is(err, os.ErrNotExist) { @@ -50,6 +55,7 @@ func ServeWorker(socket string) error { if err := os.Chmod(socket, 0600); err != nil { return err } + // 文本 /exec 与 /canvas/exec 共享一个槽位;忙时立即 429,目录读取不占执行槽。 slot := make(chan struct{}, 1) mux := http.NewServeMux() mux.HandleFunc("POST /exec", func(w http.ResponseWriter, r *http.Request) { @@ -87,6 +93,7 @@ func ServeWorker(socket string) error { fail(w, 503, "codex_unavailable") return } + // 仅按公开 ID 匹配当前目录,再在 worker 内取 Backend,调用方不能任意指定 CLI 模型名。 var selected *CanvasModel for _, model := range models { if model.ID == input.ModelID { @@ -112,7 +119,10 @@ func ServeWorker(socket string) error { return server.Serve(listener) } +// execute 为旧文本入口保留默认模型选择,实际进程生命周期集中在 executeModel。 func execute(w http.ResponseWriter, r *http.Request, prompt string) { executeModel(w, r, prompt, "") } + +// executeModel 用请求期限约束 CLI,禁用外部工具能力;失败仅公开错误码,不转发 stderr。 func executeModel(w http.ResponseWriter, r *http.Request, prompt, model string) { ctx, cancel := context.WithTimeout(r.Context(), timeout) defer cancel() @@ -126,6 +136,7 @@ func executeModel(w http.ResponseWriter, r *http.Request, prompt, model string) cmd.Dir = "/work" cmd.Env = []string{"PATH=/usr/local/bin:/usr/bin:/bin", "HOME=/home/node", "CODEX_HOME=/home/node/.codex", "SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt"} cmd.Stdin = strings.NewReader(prompt) + // Setpgid 配合负 PID kill 终止整个进程组;WaitDelay 约束取消后的输出管道等待。 cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} cmd.Cancel = func() error { err := syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL) @@ -146,6 +157,7 @@ func executeModel(w http.ResponseWriter, r *http.Request, prompt, model string) case err != nil: fail(w, 502, "codex_failed") default: + // 只有合法事件流、成功结束事件及非空最终文本才能作为公开生成结果返回。 var result string var completed bool for _, line := range bytes.Split(bytes.TrimSpace(output.buffer.Bytes()), []byte("\n")) { diff --git a/internal/platform/asset_preview.go b/internal/platform/asset_preview.go index 46f9636..36e9c4e 100644 --- a/internal/platform/asset_preview.go +++ b/internal/platform/asset_preview.go @@ -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() diff --git a/internal/platform/asset_preview_test.go b/internal/platform/asset_preview_test.go index bd213fe..d4520e8 100644 --- a/internal/platform/asset_preview_test.go +++ b/internal/platform/asset_preview_test.go @@ -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}) diff --git a/internal/platform/assets.go b/internal/platform/assets.go index 8473046..8cde154 100644 --- a/internal/platform/assets.go +++ b/internal/platform/assets.go @@ -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) diff --git a/internal/platform/assets_test.go b/internal/platform/assets_test.go index ad5c0ab..54c3612 100644 --- a/internal/platform/assets_test.go +++ b/internal/platform/assets_test.go @@ -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}) diff --git a/internal/platform/canvas.go b/internal/platform/canvas.go index 6122529..95e28e3 100644 --- a/internal/platform/canvas.go +++ b/internal/platform/canvas.go @@ -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 } diff --git a/internal/platform/canvas_ai_apply.go b/internal/platform/canvas_ai_apply.go index ba71516..96e0c17 100644 --- a/internal/platform/canvas_ai_apply.go +++ b/internal/platform/canvas_ai_apply.go @@ -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 { diff --git a/internal/platform/canvas_ai_cancel.go b/internal/platform/canvas_ai_cancel.go index 2a5c71a..5f25d23 100644 --- a/internal/platform/canvas_ai_cancel.go +++ b/internal/platform/canvas_ai_cancel.go @@ -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 diff --git a/internal/platform/canvas_ai_config.go b/internal/platform/canvas_ai_config.go index 0066ed2..5666431 100644 --- a/internal/platform/canvas_ai_config.go +++ b/internal/platform/canvas_ai_config.go @@ -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") { diff --git a/internal/platform/canvas_ai_explicit_apply.go b/internal/platform/canvas_ai_explicit_apply.go index 7792f5c..8033eb4 100644 --- a/internal/platform/canvas_ai_explicit_apply.go +++ b/internal/platform/canvas_ai_explicit_apply.go @@ -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") diff --git a/internal/platform/canvas_ai_image_inputs.go b/internal/platform/canvas_ai_image_inputs.go index 1c5c79a..9ef3a69 100644 --- a/internal/platform/canvas_ai_image_inputs.go +++ b/internal/platform/canvas_ai_image_inputs.go @@ -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 != "" { diff --git a/internal/platform/canvas_ai_image_inputs_test.go b/internal/platform/canvas_ai_image_inputs_test.go index 7646aba..5d28ce6 100644 --- a/internal/platform/canvas_ai_image_inputs_test.go +++ b/internal/platform/canvas_ai_image_inputs_test.go @@ -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)) { diff --git a/internal/platform/canvas_ai_images.go b/internal/platform/canvas_ai_images.go index 79fc318..3a19708 100644 --- a/internal/platform/canvas_ai_images.go +++ b/internal/platform/canvas_ai_images.go @@ -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 { diff --git a/internal/platform/canvas_ai_integration_test.go b/internal/platform/canvas_ai_integration_test.go index 52916b0..8bbfe80 100644 --- a/internal/platform/canvas_ai_integration_test.go +++ b/internal/platform/canvas_ai_integration_test.go @@ -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) diff --git a/internal/platform/canvas_ai_invalidate.go b/internal/platform/canvas_ai_invalidate.go index 876c1f7..8757bf7 100644 --- a/internal/platform/canvas_ai_invalidate.go +++ b/internal/platform/canvas_ai_invalidate.go @@ -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 { diff --git a/internal/platform/canvas_ai_list.go b/internal/platform/canvas_ai_list.go index 1bb4ed3..2938c3e 100644 --- a/internal/platform/canvas_ai_list.go +++ b/internal/platform/canvas_ai_list.go @@ -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] diff --git a/internal/platform/canvas_ai_model.go b/internal/platform/canvas_ai_model.go index a088ca1..f7646a4 100644 --- a/internal/platform/canvas_ai_model.go +++ b/internal/platform/canvas_ai_model.go @@ -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 { diff --git a/internal/platform/canvas_ai_model_integration_test.go b/internal/platform/canvas_ai_model_integration_test.go index a5d407a..1f6aec0 100644 --- a/internal/platform/canvas_ai_model_integration_test.go +++ b/internal/platform/canvas_ai_model_integration_test.go @@ -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() diff --git a/internal/platform/canvas_ai_model_test.go b/internal/platform/canvas_ai_model_test.go index 7bfa052..3b51180 100644 --- a/internal/platform/canvas_ai_model_test.go +++ b/internal/platform/canvas_ai_model_test.go @@ -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} diff --git a/internal/platform/canvas_ai_models.go b/internal/platform/canvas_ai_models.go index 7648e17..c86caf8 100644 --- a/internal/platform/canvas_ai_models.go +++ b/internal/platform/canvas_ai_models.go @@ -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{} diff --git a/internal/platform/canvas_ai_plan.go b/internal/platform/canvas_ai_plan.go index 1d07abc..20e0b47 100644 --- a/internal/platform/canvas_ai_plan.go +++ b/internal/platform/canvas_ai_plan.go @@ -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"]} diff --git a/internal/platform/canvas_ai_plan_test.go b/internal/platform/canvas_ai_plan_test.go index 4022468..214d038 100644 --- a/internal/platform/canvas_ai_plan_test.go +++ b/internal/platform/canvas_ai_plan_test.go @@ -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" diff --git a/internal/platform/canvas_ai_query.go b/internal/platform/canvas_ai_query.go index b6d3cfb..20de2c7 100644 --- a/internal/platform/canvas_ai_query.go +++ b/internal/platform/canvas_ai_query.go @@ -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") diff --git a/internal/platform/canvas_ai_reader.go b/internal/platform/canvas_ai_reader.go index 5c3f8e1..f7340b5 100644 --- a/internal/platform/canvas_ai_reader.go +++ b/internal/platform/canvas_ai_reader.go @@ -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) diff --git a/internal/platform/canvas_ai_reader_test.go b/internal/platform/canvas_ai_reader_test.go index a3df085..929e104 100644 --- a/internal/platform/canvas_ai_reader_test.go +++ b/internal/platform/canvas_ai_reader_test.go @@ -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" diff --git a/internal/platform/canvas_ai_real_test.go b/internal/platform/canvas_ai_real_test.go index ff060d1..0eb1d6d 100644 --- a/internal/platform/canvas_ai_real_test.go +++ b/internal/platform/canvas_ai_real_test.go @@ -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, "") diff --git a/internal/platform/canvas_ai_receipts.go b/internal/platform/canvas_ai_receipts.go index 5d1c908..a064485 100644 --- a/internal/platform/canvas_ai_receipts.go +++ b/internal/platform/canvas_ai_receipts.go @@ -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) diff --git a/internal/platform/canvas_ai_requeue.go b/internal/platform/canvas_ai_requeue.go index b2e69a5..6d75dfa 100644 --- a/internal/platform/canvas_ai_requeue.go +++ b/internal/platform/canvas_ai_requeue.go @@ -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 { diff --git a/internal/platform/canvas_ai_runs.go b/internal/platform/canvas_ai_runs.go index 1f3bdf1..f0ed13a 100644 --- a/internal/platform/canvas_ai_runs.go +++ b/internal/platform/canvas_ai_runs.go @@ -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) diff --git a/internal/platform/canvas_ai_scheduler.go b/internal/platform/canvas_ai_scheduler.go index 13f2903..7eb8e99 100644 --- a/internal/platform/canvas_ai_scheduler.go +++ b/internal/platform/canvas_ai_scheduler.go @@ -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 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) } diff --git a/internal/platform/canvas_ai_scheduler_test.go b/internal/platform/canvas_ai_scheduler_test.go index 6e2c195..2ef6b3d 100644 --- a/internal/platform/canvas_ai_scheduler_test.go +++ b/internal/platform/canvas_ai_scheduler_test.go @@ -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}}} diff --git a/internal/platform/canvas_capabilities.go b/internal/platform/canvas_capabilities.go index 305b091..3216994 100644 --- a/internal/platform/canvas_capabilities.go +++ b/internal/platform/canvas_capabilities.go @@ -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}, diff --git a/internal/platform/canvas_connections.go b/internal/platform/canvas_connections.go index 3659779..377a05d 100644 --- a/internal/platform/canvas_connections.go +++ b/internal/platform/canvas_connections.go @@ -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) diff --git a/internal/platform/canvas_connections_integration_test.go b/internal/platform/canvas_connections_integration_test.go index 058458a..1cd7141 100644 --- a/internal/platform/canvas_connections_integration_test.go +++ b/internal/platform/canvas_connections_integration_test.go @@ -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{} diff --git a/internal/platform/canvas_connections_test.go b/internal/platform/canvas_connections_test.go index 363854d..a2012a7 100644 --- a/internal/platform/canvas_connections_test.go +++ b/internal/platform/canvas_connections_test.go @@ -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{}}} diff --git a/internal/platform/canvas_headless_client_integration_test.go b/internal/platform/canvas_headless_client_integration_test.go index de91788..28774cd 100644 --- a/internal/platform/canvas_headless_client_integration_test.go +++ b/internal/platform/canvas_headless_client_integration_test.go @@ -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) } diff --git a/internal/platform/canvas_headless_worker_integration_test.go b/internal/platform/canvas_headless_worker_integration_test.go index 6fe034b..7229a99 100644 --- a/internal/platform/canvas_headless_worker_integration_test.go +++ b/internal/platform/canvas_headless_worker_integration_test.go @@ -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) { diff --git a/internal/platform/canvas_limits.go b/internal/platform/canvas_limits.go index f5ade67..d4a2491 100644 --- a/internal/platform/canvas_limits.go +++ b/internal/platform/canvas_limits.go @@ -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"` diff --git a/internal/platform/canvas_model.go b/internal/platform/canvas_model.go index abd4195..9c527f0 100644 --- a/internal/platform/canvas_model.go +++ b/internal/platform/canvas_model.go @@ -1,3 +1,4 @@ +// Canonical 画布的内存模型与纯事务 reducer:元素稳定身份独立于 owner,跨画布编辑一次校验最终全图。 package platform import ( @@ -9,20 +10,26 @@ import ( "strings" ) +// 文档格式与写入协议独立版本化,前者描述模型视图,后者描述请求/回执契约。 const canvasModelFormat = 1 const canvasModelProtocol = 2 var errCanvasModel = errors.New("invalid_canvas_model") var errModelConflict = errors.New("canvas_model_field_conflict") +// modelParent 用父画布和入口元素描述唯一所有权;不依赖旧 frameId 或投影端口。 type modelParent struct { CanvasID string `json:"canvasId"` EntryElementID string `json:"entryElementId"` } + +// modelCanvas 的根 Parent 为 nil,其他画布必须有唯一且有效的入口节点。 type modelCanvas struct { ID string `json:"id"` Parent *modelParent `json:"parent"` } + +// canvasModel 同时保留活跃对象、删除 incarnation 和死记录;Versions 也保留已移除画布的版本。 type canvasModel struct { Root string Canvases map[string]modelCanvas @@ -32,6 +39,8 @@ type canvasModel struct { DeadRecords map[string]map[string]any Versions map[string]int64 } + +// modelView 为客户端提供完整或参与者局部模型;Removed 明确列出已归档但仍有版本的画布。 type modelView struct { Format int `json:"documentFormatVersion"` ProjectID string `json:"projectId"` @@ -42,10 +51,14 @@ type modelView struct { Complete bool `json:"complete"` Removed []string `json:"removedCanvasIds"` } + +// modelTarget 以 ID+incarnation 定位一代元素,避免删除后恢复的同 ID 被旧操作命中。 type modelTarget struct { ID string `json:"id"` Incarnation int64 `json:"incarnation"` } + +// modelChange 使用 before/after 做比较交换;data 字段的 Present 指针区分缺字段和显式 null。 type modelChange struct { Kind string `json:"kind"` ID string `json:"id,omitempty"` @@ -56,10 +69,14 @@ type modelChange struct { BeforePresent *bool `json:"beforePresent,omitempty"` AfterPresent *bool `json:"afterPresent,omitempty"` } + +// modelOperation 是需跨请求去重的逻辑操作,一次包含若干有序变更。 type modelOperation struct { ID string `json:"id"` Changes []modelChange `json:"changes"` } + +// modelBatch 将多逻辑操作与所有参与画布版本打包;RequestID 必须等于 HTTP 幂等键。 type modelBatch struct { ProtocolVersion int `json:"protocol_version"` RequestID string `json:"request_id"` @@ -67,10 +84,15 @@ type modelBatch struct { Operations []modelOperation `json:"operations"` } +// emptyModel 初始化所有索引,尚无活跃画布,需迁移或构造后通过 validateCanvasModel。 func emptyModel(root string) canvasModel { return canvasModel{Root: root, Canvases: map[string]modelCanvas{}, Elements: map[string]map[string]any{}, Tombstones: map[string]int64{}, TombstoneOwners: map[string]string{}, DeadRecords: map[string]map[string]any{}, Versions: map[string]int64{}} } + +// modelString 只读取已解码 JSON 字符串,类型错误返回空值交由上层验证。 func modelString(value any) string { text, _ := value.(string); return text } + +// modelInt 只接受 JavaScript 安全正整数,防止版本/incarnation 跨端精度丢失。 func modelInt(value any) int64 { number, ok := value.(float64) if !ok || number < 1 || number > 9007199254740991 || math.Trunc(number) != number { @@ -78,6 +100,8 @@ func modelInt(value any) int64 { } return int64(number) } + +// modelJSONSafe 递归限制深度并拒绝非有限浮点或非 JSON 类型,允许未知组件保留合法数据。 func modelJSONSafe(value any, depth int) bool { if depth > 64 { return false @@ -104,6 +128,8 @@ func modelJSONSafe(value any, depth int) bool { } return false } + +// modelEqual 统一到 JSON 值域后比较,使 Go 整数/结构体与解码出的 float64/对象能按语义相等。 func modelEqual(left, right any) bool { // Round-trip numeric Go structs and JSON records to the same JSON value domain. a, ea := json.Marshal(left) @@ -114,6 +140,8 @@ func modelEqual(left, right any) bool { var av, bv any return json.Unmarshal(a, &av) == nil && json.Unmarshal(b, &bv) == nil && reflect.DeepEqual(av, bv) } + +// view 按稳定 ID 排序输出,participants 为 nil 表示完整模型,否则只返回给定画布及其墓碑。 func (model canvasModel) view(participants map[string]int64) modelView { view := modelView{Format: canvasModelFormat, ProjectID: model.Root, Canvases: []modelCanvas{}, Elements: []map[string]any{}, Tombstones: map[string]int64{}, Versions: map[string]int64{}, Complete: participants == nil, Removed: []string{}} for _, id := range sortedKeys(model.Canvases) { @@ -134,6 +162,7 @@ func (model canvasModel) view(participants map[string]int64) modelView { } view.Elements = append(view.Elements, element) } + // 删除代数也必须处于安全整数范围;活跃元素的 incarnation 稍后要求严格高于其墓碑。 for id, incarnation := range model.Tombstones { owner := model.TombstoneOwners[id] if live := model.Elements[id]; live != nil { @@ -159,6 +188,8 @@ func (model canvasModel) view(participants map[string]int64) modelView { } return view } + +// sortedKeys 为模型、投影和回执提供确定顺序,不依赖 Go map 遍历顺序。 func sortedKeys[T any](values map[string]T) []string { keys := make([]string, 0, len(values)) for key := range values { @@ -167,12 +198,16 @@ func sortedKeys[T any](values map[string]T) []string { sort.Strings(keys) return keys } + +// cloneModel 深拷贝 JSON 兼容模型,让 reducer 失败时输入对象及嵌套 data 不被污染。 func cloneModel(model canvasModel) canvasModel { raw, _ := json.Marshal(model) var copy canvasModel _ = json.Unmarshal(raw, ©) return copy } + +// modelAncestors 从当前画布向根遍历,拒绝缺父、循环和超过八层边界的路径。 func modelAncestors(model canvasModel, id string) ([]string, error) { path, seen := []string{}, map[string]bool{} for id != "" { @@ -189,6 +224,8 @@ func modelAncestors(model canvasModel, id string) ([]string, error) { } return path, nil } + +// modelCommonCanvas 从右端最近祖先向上寻找交集,确定连接唯一的最低共同祖先所有者。 func modelCommonCanvas(model canvasModel, left, right string) (string, error) { a, err := modelAncestors(model, left) if err != nil { @@ -209,6 +246,9 @@ func modelCommonCanvas(model canvasModel, left, right string) (string, error) { } return "", errCanvasModel } + +// validateCanvasModel 对最终状态检查唯一根、入口所有权、元素代数、JSON 预算及连接最低共同祖先。 +// 未知组件的合法 data/envelope 字段保留;仅已知 v1 组件追加相应业务数据约束。 func validateCanvasModel(model canvasModel) error { if !uuidSlugPattern.MatchString(model.Root) || len(model.Canvases) == 0 || len(model.Canvases) > 256 || len(model.Elements) > 128000 { return errCanvasModel @@ -310,6 +350,7 @@ func validateCanvasModel(model canvasModel) error { } // Pure transaction reducer. Unknown component data/envelope fields are retained. +// applyModelOperations 在副本依次执行变更,允许批次中间态暂不完整,最后统一验证所有权和引用。 func applyModelOperations(initial canvasModel, operations []modelOperation) (canvasModel, map[string]bool, error) { model, touched, seen := cloneModel(initial), map[string]bool{}, map[string]bool{} if len(operations) == 0 || len(operations) > 2500 { @@ -332,6 +373,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can } switch change.Kind { case "field": + // 字段编辑必须命中同代元素;data. 是单层键,其他字段只允许明确白名单。 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 } diff --git a/internal/platform/canvas_model_atomic_integration_test.go b/internal/platform/canvas_model_atomic_integration_test.go index 4b42fd6..5b045b9 100644 --- a/internal/platform/canvas_model_atomic_integration_test.go +++ b/internal/platform/canvas_model_atomic_integration_test.go @@ -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() diff --git a/internal/platform/canvas_model_guard.go b/internal/platform/canvas_model_guard.go index 37072db..f0e4931 100644 --- a/internal/platform/canvas_model_guard.go +++ b/internal/platform/canvas_model_guard.go @@ -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 diff --git a/internal/platform/canvas_model_http.go b/internal/platform/canvas_model_http.go index 40800bb..3eba0af 100644 --- a/internal/platform/canvas_model_http.go +++ b/internal/platform/canvas_model_http.go @@ -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 diff --git a/internal/platform/canvas_model_integration_test.go b/internal/platform/canvas_model_integration_test.go index 9e3995d..deca5f0 100644 --- a/internal/platform/canvas_model_integration_test.go +++ b/internal/platform/canvas_model_integration_test.go @@ -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) diff --git a/internal/platform/canvas_model_migration.go b/internal/platform/canvas_model_migration.go index 5938634..a22a4fc 100644 --- a/internal/platform/canvas_model_migration.go +++ b/internal/platform/canvas_model_migration.go @@ -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 diff --git a/internal/platform/canvas_model_store.go b/internal/platform/canvas_model_store.go index c8994e1..3d5612d 100644 --- a/internal/platform/canvas_model_store.go +++ b/internal/platform/canvas_model_store.go @@ -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 { diff --git a/internal/platform/canvas_model_stream.go b/internal/platform/canvas_model_stream.go index 8c5cd96..cd7d3d3 100644 --- a/internal/platform/canvas_model_stream.go +++ b/internal/platform/canvas_model_stream.go @@ -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 diff --git a/internal/platform/canvas_model_stream_test.go b/internal/platform/canvas_model_stream_test.go index b6dc281..1e35f7e 100644 --- a/internal/platform/canvas_model_stream_test.go +++ b/internal/platform/canvas_model_stream_test.go @@ -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() diff --git a/internal/platform/canvas_model_test.go b/internal/platform/canvas_model_test.go index 0550d2d..ddafefd 100644 --- a/internal/platform/canvas_model_test.go +++ b/internal/platform/canvas_model_test.go @@ -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)) diff --git a/internal/platform/canvas_operations.go b/internal/platform/canvas_operations.go index 321255b..37540cc 100644 --- a/internal/platform/canvas_operations.go +++ b/internal/platform/canvas_operations.go @@ -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 diff --git a/internal/platform/canvas_operations_http.go b/internal/platform/canvas_operations_http.go index 77a2092..92f2c16 100644 --- a/internal/platform/canvas_operations_http.go +++ b/internal/platform/canvas_operations_http.go @@ -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") diff --git a/internal/platform/canvas_operations_integration_test.go b/internal/platform/canvas_operations_integration_test.go index fefa3ed..3eeece0 100644 --- a/internal/platform/canvas_operations_integration_test.go +++ b/internal/platform/canvas_operations_integration_test.go @@ -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"}) diff --git a/internal/platform/canvas_operations_test.go b/internal/platform/canvas_operations_test.go index 9aac2c6..f1e0e8b 100644 --- a/internal/platform/canvas_operations_test.go +++ b/internal/platform/canvas_operations_test.go @@ -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{ diff --git a/internal/platform/canvas_relations.go b/internal/platform/canvas_relations.go index c217523..ec794d8 100644 --- a/internal/platform/canvas_relations.go +++ b/internal/platform/canvas_relations.go @@ -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:。 func validCanvasPortHandle(value any) bool { if canvasChoice(value, "top", "right", "bottom", "left") { return true diff --git a/internal/platform/canvas_test.go b/internal/platform/canvas_test.go index a11571a..547128d 100644 --- a/internal/platform/canvas_test.go +++ b/internal/platform/canvas_test.go @@ -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 { diff --git a/internal/platform/canvas_undo.go b/internal/platform/canvas_undo.go index 3d6b2f7..fc30418 100644 --- a/internal/platform/canvas_undo.go +++ b/internal/platform/canvas_undo.go @@ -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 { diff --git a/internal/platform/canvas_v2.go b/internal/platform/canvas_v2.go index cb8d8bb..3b649a3 100644 --- a/internal/platform/canvas_v2.go +++ b/internal/platform/canvas_v2.go @@ -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) diff --git a/internal/platform/canvas_v2_test.go b/internal/platform/canvas_v2_test.go index 2778ff5..48ef3d2 100644 --- a/internal/platform/canvas_v2_test.go +++ b/internal/platform/canvas_v2_test.go @@ -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"} { diff --git a/internal/platform/content.go b/internal/platform/content.go index 262f330..91ddf85 100644 --- a/internal/platform/content.go +++ b/internal/platform/content.go @@ -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 diff --git a/internal/platform/content_test.go b/internal/platform/content_test.go index 1cd761c..d9eab88 100644 --- a/internal/platform/content_test.go +++ b/internal/platform/content_test.go @@ -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 diff --git a/internal/platform/grants.go b/internal/platform/grants.go index 6dde717..3fcaffa 100644 --- a/internal/platform/grants.go +++ b/internal/platform/grants.go @@ -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") diff --git a/internal/platform/http.go b/internal/platform/http.go index d963638..9801181 100644 --- a/internal/platform/http.go +++ b/internal/platform/http.go @@ -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 { diff --git a/internal/platform/integration_test.go b/internal/platform/integration_test.go index 42a9535..02bd984 100644 --- a/internal/platform/integration_test.go +++ b/internal/platform/integration_test.go @@ -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 diff --git a/internal/platform/layouts.go b/internal/platform/layouts.go index 4674f1b..4eae28d 100644 --- a/internal/platform/layouts.go +++ b/internal/platform/layouts.go @@ -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 diff --git a/internal/platform/materials.go b/internal/platform/materials.go index c935b01..433308a 100644 --- a/internal/platform/materials.go +++ b/internal/platform/materials.go @@ -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] diff --git a/internal/platform/member_drop.go b/internal/platform/member_drop.go index ef3db4d..5b58b78 100644 --- a/internal/platform/member_drop.go +++ b/internal/platform/member_drop.go @@ -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 { diff --git a/internal/platform/member_drop_test.go b/internal/platform/member_drop_test.go index 6f85c57..da554c7 100644 --- a/internal/platform/member_drop_test.go +++ b/internal/platform/member_drop_test.go @@ -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" diff --git a/internal/platform/onboarding.go b/internal/platform/onboarding.go index c770c46..311fa58 100644 --- a/internal/platform/onboarding.go +++ b/internal/platform/onboarding.go @@ -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) diff --git a/internal/platform/shares.go b/internal/platform/shares.go index 6d5159a..7ec45e7 100644 --- a/internal/platform/shares.go +++ b/internal/platform/shares.go @@ -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") diff --git a/internal/platform/slug.go b/internal/platform/slug.go index eec8d55..5585d9d 100644 --- a/internal/platform/slug.go +++ b/internal/platform/slug.go @@ -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)) } diff --git a/internal/platform/subgraph_ancestor_ports.go b/internal/platform/subgraph_ancestor_ports.go index 0007768..71ef2d2 100644 --- a/internal/platform/subgraph_ancestor_ports.go +++ b/internal/platform/subgraph_ancestor_ports.go @@ -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:,确定祖先端口实际引用的移动成员。 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) diff --git a/internal/platform/subgraph_dissolve.go b/internal/platform/subgraph_dissolve.go index 4e8dcb6..e22773e 100644 --- a/internal/platform/subgraph_dissolve.go +++ b/internal/platform/subgraph_dissolve.go @@ -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) diff --git a/internal/platform/subgraph_dissolve_http.go b/internal/platform/subgraph_dissolve_http.go index 559581a..18ba619 100644 --- a/internal/platform/subgraph_dissolve_http.go +++ b/internal/platform/subgraph_dissolve_http.go @@ -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 { diff --git a/internal/platform/subgraph_dissolve_test.go b/internal/platform/subgraph_dissolve_test.go index b103d6e..83ff0ee 100644 --- a/internal/platform/subgraph_dissolve_test.go +++ b/internal/platform/subgraph_dissolve_test.go @@ -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 { diff --git a/internal/platform/subgraph_members.go b/internal/platform/subgraph_members.go index 900b576..c3e4aee 100644 --- a/internal/platform/subgraph_members.go +++ b/internal/platform/subgraph_members.go @@ -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] diff --git a/internal/platform/subgraph_members_http.go b/internal/platform/subgraph_members_http.go index bb8651f..91b173f 100644 --- a/internal/platform/subgraph_members_http.go +++ b/internal/platform/subgraph_members_http.go @@ -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 diff --git a/internal/platform/subgraph_members_test.go b/internal/platform/subgraph_members_test.go index 2789ebe..078de49 100644 --- a/internal/platform/subgraph_members_test.go +++ b/internal/platform/subgraph_members_test.go @@ -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" diff --git a/internal/platform/subgraph_migration.go b/internal/platform/subgraph_migration.go index e544720..2ced342 100644 --- a/internal/platform/subgraph_migration.go +++ b/internal/platform/subgraph_migration.go @@ -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) diff --git a/internal/platform/subgraph_migration_http.go b/internal/platform/subgraph_migration_http.go index 639b085..dd1311a 100644 --- a/internal/platform/subgraph_migration_http.go +++ b/internal/platform/subgraph_migration_http.go @@ -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 { diff --git a/internal/platform/subgraph_migration_test.go b/internal/platform/subgraph_migration_test.go index 6e255b2..355e5ee 100644 --- a/internal/platform/subgraph_migration_test.go +++ b/internal/platform/subgraph_migration_test.go @@ -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) diff --git a/internal/platform/subgraph_relations.go b/internal/platform/subgraph_relations.go index e7eb4ac..a3e096f 100644 --- a/internal/platform/subgraph_relations.go +++ b/internal/platform/subgraph_relations.go @@ -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 diff --git a/internal/platform/subgraphs.go b/internal/platform/subgraphs.go index c5263d2..5d8109a 100644 --- a/internal/platform/subgraphs.go +++ b/internal/platform/subgraphs.go @@ -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}) diff --git a/internal/platform/tags.go b/internal/platform/tags.go index 32c95ea..7a19cf4 100644 --- a/internal/platform/tags.go +++ b/internal/platform/tags.go @@ -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 { diff --git a/internal/platform/workspaces.go b/internal/platform/workspaces.go index 2062efe..82fe8ee 100644 --- a/internal/platform/workspaces.go +++ b/internal/platform/workspaces.go @@ -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 diff --git a/internal/research/cursor.go b/internal/research/cursor.go index 4efd034..aa7b38b 100644 --- a/internal/research/cursor.go +++ b/internal/research/cursor.go @@ -1,3 +1,4 @@ +// 研究列表的无状态游标:保存排序锚点和查询摘要,不承担身份认证或签名校验。 package research import ( @@ -14,6 +15,8 @@ import ( // Cursors locate a public corpus row, not an account or authentication token. // Binding to normalized filters prevents accidentally paging a different query. +// position 的 ID 用于最近排序;标题排序还需要保留数据库原始 title_key 以稳定处理同名论文。 +// Before 指示向前翻页,Filter 将游标限定在同一筛选条件和页大小内。 type position struct { Version int `json:"v"` ID int64 `json:"id"` @@ -24,6 +27,7 @@ type position struct { var errCursor = errors.New("invalid cursor") +// filterKey 在游标生成与读取两端统一缺省值,把查询条件编码为固定长度摘要。 func filterKey(f Filters) string { sort, search := f.Sort, f.SearchIn if sort == "" { @@ -36,6 +40,8 @@ func filterKey(f Filters) string { sum := sha256.Sum256(data) return hex.EncodeToString(sum[:16]) } + +// encodeCursor 复制锚点并写协议版本、翻页方向;非标题排序删除无用 Key,缩小 URL。 func encodeCursor(f Filters, p position, before bool) string { p.Version, p.Before, p.Filter = 1, before, filterKey(f) if f.Sort != "title" { @@ -44,6 +50,8 @@ func encodeCursor(f Filters, p position, before bool) string { data, _ := json.Marshal(p) return base64.RawURLEncoding.EncodeToString(data) } + +// decodeCursor 将空值视为首页;拒绝过长、额外字段、多 JSON 值或与当前筛选不符的游标。 func decodeCursor(f Filters) (position, error) { var p position if f.Cursor == "" { diff --git a/internal/research/cursor_test.go b/internal/research/cursor_test.go index 4f26d16..40ccfd9 100644 --- a/internal/research/cursor_test.go +++ b/internal/research/cursor_test.go @@ -1,3 +1,4 @@ +// 本文件记录研究 API 的回归契约;测试注释描述实际断言,不代表本次已运行测试。 package research import ( @@ -7,6 +8,7 @@ import ( "testing" ) +// TestCursorValidation 验证最大 int64 ID、含控制字符的标题键和反向游标可往返;同时拒绝非法编码、版本及跨筛选复用。 func TestCursorValidation(t *testing.T) { f := Filters{Query: "graph", Sort: "title", SearchIn: "text", PageSize: 8} f.Cursor = encodeCursor(f, position{ID: 9223372036854775807, Key: "duplicate\x01title"}, true) diff --git a/internal/research/http.go b/internal/research/http.go index 97820b8..5a47336 100644 --- a/internal/research/http.go +++ b/internal/research/http.go @@ -16,12 +16,14 @@ import ( "unicode/utf8" ) +// Source 描述公开来源链接及其外部标识,不含内部数据库记录 ID。 type Source struct { Label string `json:"label"` URL string `json:"url"` ExternalID string `json:"externalId"` } +// Publication 是一次投稿的出版信息与最新决策证据;同一论文可对应多个投稿。 type Publication struct { Venue string `json:"venue"` Year int `json:"year"` @@ -30,6 +32,7 @@ type Publication struct { EvidenceURL string `json:"evidenceUrl,omitempty"` } +// Paper 是公开 API 的论文投影;可空字段保留源数据缺省语义,ID 用字符串避免前端整数精度丢失。 type Paper struct { ID string `json:"id"` Title string `json:"title"` @@ -44,6 +47,7 @@ type Paper struct { Comments *string `json:"comments,omitempty"` } +// Filters 由 parseFilters 验证;Cursor 是相同查询下的排序锚点,不是页码或 OFFSET。 type Filters struct { Query string SearchIn string @@ -53,6 +57,7 @@ type Filters struct { PageSize int } +// Page 同时返回当前项、双向游标和语料主题列表;无后续页面的方向使用空字符串。 type Page struct { Items []Paper `json:"items"` NextCursor string `json:"nextCursor"` @@ -63,11 +68,13 @@ type Page struct { // Repository implementations must use a read-only transaction for each List, // so its metadata and page describe the same database snapshot. +// Repository 将 HTTP 与存储解耦;List 的列表及元数据必须来自同一只读快照。 type Repository interface { List(context.Context, Filters) (Page, error) Get(context.Context, int64) (Paper, error) } +// service 共享公开仓库和项目白名单,以 slots 对整个研究 API 限制并发数据库请求。 type service struct { repository Repository projects map[string]string @@ -77,6 +84,7 @@ type service struct { // Register adds only GET endpoints; no credentials or database errors are sent // to anonymous callers. A nil repository leaves the existing server unchanged. +// Register 由 main 调用;没有研究库配置时不挂载路径,项目认证数据不参与公开语料查询。 func Register(mux *http.ServeMux, repository Repository, projects map[string]string) { if repository == nil { return @@ -86,6 +94,7 @@ func Register(mux *http.ServeMux, repository Repository, projects map[string]str mux.HandleFunc("GET /projects/{project}/research/papers/{id}", s.serve) } +// reply 统一公开 JSON 的缓存和内容嗅探策略,写出后不再向调用方返回编码错误。 func reply(w http.ResponseWriter, status int, value any) { w.Header().Set("Content-Type", "application/json") w.Header().Set("Cache-Control", "no-store") @@ -94,13 +103,16 @@ func reply(w http.ResponseWriter, status int, value any) { _ = json.NewEncoder(w).Encode(value) } +// reject 仅公开稳定错误码,数据库结构和底层错误内容不进入响应。 func reject(w http.ResponseWriter, status int, code string) { reply(w, status, map[string]string{"error": code}) } +// 主题采用受限分类标识,正整数不接受符号或前导零,简化 ID 和页大小的解析。 var topicPattern = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9.-]{0,79}$`) var positiveInteger = regexp.MustCompile(`^[1-9][0-9]*$`) +// parseFilters 严格拒绝重复/未知参数;限制查询字数、词数和页大小后,再验证游标绑定。 func parseFilters(raw string) (Filters, error) { f := Filters{SearchIn: "text", Sort: "recent", PageSize: 8} values, err := url.ParseQuery(raw) @@ -152,6 +164,7 @@ func parseFilters(raw string) (Filters, error) { return f, err } +// serve 在昂贵查询前验证项目与参数;详情不接受筛选参数,列表使用统一 Filters。 func (s *service) serve(w http.ResponseWriter, r *http.Request) { if _, exists := s.projects[r.PathValue("project")]; !exists { reject(w, 404, "not_found") @@ -173,6 +186,7 @@ func (s *service) serve(w http.ResponseWriter, r *http.Request) { reject(w, 400, "invalid_request") return } + // 无空闲槽位时立即返回 429,不排队积累匿名查询;defer 覆盖后续所有退出路径。 select { case s.slots <- struct{}{}: defer func() { <-s.slots }() @@ -193,6 +207,7 @@ func (s *service) serve(w http.ResponseWriter, r *http.Request) { reply(w, 200, result) return } + // SQLSTATE 57014 是数据库取消查询;与请求超时统一映射 504,其余依赖故障为 503。 var state interface{ SQLState() string } switch { case errors.Is(err, sql.ErrNoRows): diff --git a/internal/research/http_test.go b/internal/research/http_test.go index 09873e8..84e8d03 100644 --- a/internal/research/http_test.go +++ b/internal/research/http_test.go @@ -1,3 +1,4 @@ +// 本文件记录研究 API 的回归契约;测试注释描述实际断言,不代表本次已运行测试。 package research import ( @@ -13,6 +14,7 @@ import ( "time" ) +// fixtureRepository 捕获调用参数和次数,并可模拟依赖失败或等到 context 被取消。 type fixtureRepository struct { filters Filters id int64 @@ -21,6 +23,7 @@ type fixtureRepository struct { calls int } +// List 只返回结构化空列表,wait 分支专门验证请求期限与槽位回收。 func (f *fixtureRepository) List(ctx context.Context, filters Filters) (Page, error) { f.calls++ f.filters = filters @@ -31,18 +34,21 @@ func (f *fixtureRepository) List(ctx context.Context, filters Filters) (Page, er return Page{Items: []Paper{}, Topics: []string{}, PageSize: filters.PageSize}, f.err } +// Get 保存请求 ID 并给出固定论文,不访问数据库。 func (f *fixtureRepository) Get(ctx context.Context, id int64) (Paper, error) { f.calls++ f.id = id return Paper{ID: "42", Title: "Original title", Authors: []string{}, Topics: []string{}, Sources: []Source{}}, f.err } +// request 使用内存 recorder 执行路由,不启动监听端口。 func request(handler http.Handler, method, path string) *httptest.ResponseRecorder { w := httptest.NewRecorder() handler.ServeHTTP(w, httptest.NewRequest(method, path, nil)) return w } +// TestAnonymousReadRoutes 通过假仓库验证匿名列表/详情、参数传递、JSON 空值与响应头,并拒绝写方法及未知项目。 func TestAnonymousReadRoutes(t *testing.T) { f := &fixtureRepository{} mux := http.NewServeMux() @@ -70,6 +76,7 @@ func TestAnonymousReadRoutes(t *testing.T) { } } +// TestInvalidQueriesNeverReachRepository 逐项注入重复、未知、超限及非法 Unicode/ID 参数,要求 400 且仓库调用次数保持零。 func TestInvalidQueriesNeverReachRepository(t *testing.T) { queries := []string{"unknown=1", "q=x&q=y", "q=%ff", "q=%00", "q=%zz", "page=0", "page=1001", "page=-1", "page=1.5", "page=01", "pageSize=51", "pageSize=0", "pageSize=9999999999999999999999", "searchIn=sql", "sort=published", "topic=arxiv:cs.LG", "q=" + url.QueryEscape(strings.Repeat("字", 201)), "q=" + url.QueryEscape(strings.Repeat("word ", 21))} for _, query := range queries { @@ -93,6 +100,7 @@ func TestInvalidQueriesNeverReachRepository(t *testing.T) { } } +// TestQueryDefaultsAndUnicode 验证多语言查询只裁剪两端空白,并采用文本搜索、最近排序和八条页大小。 func TestQueryDefaultsAndUnicode(t *testing.T) { f, err := parseFilters("q=" + url.QueryEscape(" 论文 Graph ")) if err != nil || f.Query != "论文 Graph" || f.PageSize != 8 || f.SearchIn != "text" || f.Sort != "recent" { @@ -100,11 +108,16 @@ func TestQueryDefaultsAndUnicode(t *testing.T) { } } +// databaseFailure 让测试模拟驱动 SQLState,同时让 Error 带私密文本以验证脱敏。 type databaseFailure string -func (failure databaseFailure) Error() string { return "private database error" } +// Error 故意返回私密说明,供响应脱敏断言检查。 +func (failure databaseFailure) Error() string { return "private database error" } + +// SQLState 模拟 PostgreSQL 驱动错误分类,不暴露其实际内部消息。 func (failure databaseFailure) SQLState() string { return string(failure) } +// TestStorageErrorsAreRedacted 注入缺行、取消和权限错误,检查状态码映射,同时确保私密数据库内容不会进入响应。 func TestStorageErrorsAreRedacted(t *testing.T) { for _, test := range []struct { err error @@ -126,6 +139,7 @@ func TestStorageErrorsAreRedacted(t *testing.T) { } } +// TestConcurrencyAndTimeoutReleaseSlots 手动占满两个槽验证立即 429,再让假仓库等到超时,验证 504 后槽位被释放。 func TestConcurrencyAndTimeoutReleaseSlots(t *testing.T) { s := &service{repository: &fixtureRepository{wait: true}, projects: map[string]string{"thesisly": "unused"}, slots: make(chan struct{}, 2), timeout: time.Millisecond} mux := http.NewServeMux() @@ -144,6 +158,7 @@ func TestConcurrencyAndTimeoutReleaseSlots(t *testing.T) { } } +// TestInvalidCursorsNeverReachRepository 验证坏编码、过长、筛选不符及重复游标在 HTTP 层拦截,不触发仓库查询。 func TestInvalidCursorsNeverReachRepository(t *testing.T) { f := Filters{Query: "graph", Sort: "recent", SearchIn: "text", PageSize: 8} valid := encodeCursor(f, position{ID: 42}, false) diff --git a/internal/research/postgres.go b/internal/research/postgres.go index feb4898..cb85519 100644 --- a/internal/research/postgres.go +++ b/internal/research/postgres.go @@ -1,3 +1,4 @@ +// PostgreSQL 研究库只读适配器:游标先选窄 ID 集合,再按同一事务快照批量补齐论文元数据。 package research import ( @@ -14,6 +15,7 @@ import ( // The fixed Paper Atlas migration a3b677b preserves business columns as TEXT // and BIGINT and creates the English title/abstract GIN expression below. // No schema creation, indexing or other writes belong to this repository. +// PostgresRepository 的 prefix 仅由已校验 schema 构造;encoded 在启动 Check 成功后确定。 type PostgresRepository struct { db *sql.DB prefix string @@ -23,6 +25,7 @@ type PostgresRepository struct { var schemaName = regexp.MustCompile(`^[a-z][a-z0-9_]{0,35}$`) +// NewPostgresRepository 只构造仓库,不连接或迁移;调用方还需在对外服务前执行 Check。 func NewPostgresRepository(db *sql.DB, schema string) (*PostgresRepository, error) { if db == nil || !schemaName.MatchString(schema) { return nil, errors.New("invalid research database configuration") @@ -30,10 +33,13 @@ func NewPostgresRepository(db *sql.DB, schema string) (*PostgresRepository, erro return &PostgresRepository{db: db, prefix: `"` + schema + `".`, schema: schema}, nil } +// query 只替换受信任的 schema 占位符;搜索词、ID 等业务值始终通过 SQL 参数绑定。 func (r *PostgresRepository) query(value string) string { return strings.ReplaceAll(value, "{schema}", r.prefix) } +// begin 为一次 API 请求建立可重复读、只读事务,并设置事务内的查询时间及内存限制。 +// 设置失败先回滚;成功后由 List/Get/Check 的 defer 负责兜底回收事务。 func (r *PostgresRepository) begin(ctx context.Context) (*sql.Tx, error) { tx, err := r.db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelRepeatableRead, ReadOnly: true}) if err != nil { @@ -51,6 +57,7 @@ func (r *PostgresRepository) begin(ctx context.Context) (*sql.Tx, error) { // Check resolves required columns and SELECT permissions without scanning the // corpus. The migration publishes the complete schema atomically. +// Check 读取 schema 注释识别文本转义协议,用 WHERE false 探测字段和权限而不扫描语料。 func (r *PostgresRepository) Check(ctx context.Context) error { tx, err := r.begin(ctx) if err != nil { @@ -88,6 +95,7 @@ func (r *PostgresRepository) Check(ctx context.Context) error { return nil } +// whereClause 构造可组合筛选片段及对应参数;作者用 simple 全文检索,标题/摘要用 english。 func whereClause(filters Filters) (string, []any) { clauses, values := []string{}, []any{} if filters.Query != "" { @@ -112,8 +120,10 @@ func whereClause(filters Filters) (string, []any) { return " WHERE " + strings.Join(clauses, " AND "), values } +// scanner 让单行 QueryRow 与多行 Rows 共用论文投影读取逻辑。 type scanner interface{ Scan(...any) error } +// scanPaper 先解码数据库文本,再解析作者 JSON;空摘要和发布日期保留为 nil。 func (r *PostgresRepository) scanPaper(row scanner) (Paper, error) { p := Paper{Authors: []string{}, Topics: []string{}, Sources: []Source{}} var id int64 @@ -134,6 +144,7 @@ func (r *PostgresRepository) scanPaper(row scanner) (Paper, error) { return p, err } +// decodeAuthors 兼容直接姓名字符串与 arXiv 元组;交换姓/名展示顺序,忽略第四项所属机构。 func decodeAuthors(raw string) ([]string, error) { var entries []json.RawMessage if err := json.Unmarshal([]byte(raw), &entries); err != nil { @@ -173,6 +184,7 @@ func decodeAuthors(raw string) ([]string, error) { return names, nil } +// positions 只读取 ID 和原始排序键;流式读取或关闭前的错误均交回上层终止本页。 func (r *PostgresRepository) positions(ctx context.Context, tx *sql.Tx, query string, args []any) ([]position, error) { rows, err := tx.QueryContext(ctx, r.query(query), args...) if err != nil { @@ -191,12 +203,14 @@ func (r *PostgresRepository) positions(ctx context.Context, tx *sql.Tx, query st return positions, rows.Err() } +// List 在一个快照中完成锚点选择、详情补全和主题列表;多读一行判定是否还有下一页。 func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, error) { result := Page{Items: []Paper{}, Topics: []string{}, PageSize: filters.PageSize} cursor, err := decodeCursor(filters) if err != nil { return result, err } + // 保留未转义筛选条件来生成游标摘要;仅实际 SQL 绑定值按已发布 schema 的 codec 转义。 original := filters tx, err := r.begin(ctx) if err != nil { @@ -208,6 +222,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e filters.Topic = encodeText(filters.Topic) } where, args := whereClause(filters) + // 最近排序按 ID 倒序,标题按 (title_key,id) 正序;向前翻页同时反转比较和 SQL 排序。 if cursor.ID != 0 { clause := " AND " if where == "" { @@ -253,6 +268,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e } positions := []position{} topicOnly := filters.Sort != "title" && filters.Topic != "" && filters.Query == "" + // 纯主题查询直接走标签关联索引,不必先读取所有匹配论文的宽行。 if topicOnly { // The published paper_tags foreign key guarantees these IDs exist. // Walk the (tag_id,paper_id) index instead of joining all matching @@ -290,6 +306,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e return result, err } } + // 常见搜索词先试 512/4096 的有限 ID 窗口;不足一页加一行时回退完整索引检索,避免漏项。 for _, window := range []int64{512, 4096} { bound, op := int64(0), ">=" if anchor > window { @@ -320,6 +337,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e return result, err } } + // 截去探测行后恢复面向客户端的固定顺序,再按首尾锚点构造可用方向的游标。 more := len(positions) > filters.PageSize if more { positions = positions[:filters.PageSize] @@ -336,6 +354,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e if (!cursor.Before && more) || (cursor.Before && cursor.ID != 0) { result.NextCursor = encodeCursor(original, positions[len(positions)-1], false) } + // ANY 查询不保证输入顺序,先按 ID 收集再依照 positions 重新组装结果。 ids := make([]int64, len(positions)) byID := map[string]Paper{} for i, p := range positions { @@ -389,6 +408,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e return result, tx.Commit() } +// Get 与列表共享解码和 enrich,在同一事务内读取单篇论文及其附属信息。 func (r *PostgresRepository) Get(ctx context.Context, id int64) (Paper, error) { tx, err := r.begin(ctx) if err != nil { @@ -408,11 +428,13 @@ func (r *PostgresRepository) Get(ctx context.Context, id int64) (Paper, error) { // Batch metadata queries avoid per-paper round trips and share the page // snapshot. User values are bound; only the validated schema is interpolated. +// enrich 批量原地填充 papers:主题、来源、DOI、投稿和决策,所有查询复用调用方事务。 func (r *PostgresRepository) enrich(ctx context.Context, tx *sql.Tx, papers []Paper) error { if len(papers) == 0 { return nil } ids := make([]int64, len(papers)) + // 指针指向切片元素,使多组关系查询的追加结果直接回写最终页面。 byID := map[int64]*Paper{} for i := range papers { id, err := strconv.ParseInt(papers[i].ID, 10, 64) @@ -466,6 +488,7 @@ func (r *PostgresRepository) enrich(ctx context.Context, tx *sql.Tx, papers []Pa source.Label = "PMLR" } p.Sources = append(p.Sources, source) + // 按来源记录顺序采用第一个非空元数据;坏 JSON 不阻止来源链接展示。 var fields map[string]json.RawMessage if json.Unmarshal([]byte(metadata), &fields) == nil { for key, target := range map[string]**string{"doi": &p.DOI, "journal-ref": &p.Journal, "comments": &p.Comments} { @@ -501,6 +524,7 @@ func (r *PostgresRepository) enrich(ctx context.Context, tx *sql.Tx, papers []Pa if err != nil { return err } + // 每条投稿通过 LATERAL 选择最新观察到的决策;没有决策时仍保留投稿并标为 unknown。 rows, err = tx.QueryContext(ctx, r.query(`SELECT s.paper_id,v.acronym,e.year,e.track,coalesce(d.status,'unknown'),coalesce(d.evidence_url,'') FROM {schema}submissions s JOIN {schema}editions e ON e.id=s.edition_id JOIN {schema}venues v ON v.id=e.venue_id LEFT JOIN LATERAL (SELECT status,evidence_url FROM {schema}decisions WHERE submission_id=s.id diff --git a/internal/research/postgres_integration_test.go b/internal/research/postgres_integration_test.go index 97ee7e4..1588c58 100644 --- a/internal/research/postgres_integration_test.go +++ b/internal/research/postgres_integration_test.go @@ -1,3 +1,5 @@ +// 真实 PostgreSQL 回归需要 RESEARCH_TEST_DATABASE_URL 指向预装语料 fixture 的可丢弃测试库。 +// 缺少该变量时跳过;测试包含写入拒绝检查,不能指向生产数据库。 package research import ( @@ -14,6 +16,7 @@ import ( _ "github.com/jackc/pgx/v5/stdlib" ) +// integrationRepository 每个用例打开独立连接池并注册关闭及二十秒 context 清理,不创建 fixture schema。 func integrationRepository(t *testing.T) (*PostgresRepository, context.Context) { t.Helper() dsn := os.Getenv("RESEARCH_TEST_DATABASE_URL") @@ -35,6 +38,7 @@ func integrationRepository(t *testing.T) (*PostgresRepository, context.Context) return repository, ctx } +// paperIDs 提取展示顺序,便于断言 SQL 查询和游标返回的 ID 序列。 func paperIDs(papers []Paper) []string { ids := []string{} for _, paper := range papers { @@ -43,6 +47,7 @@ func paperIDs(papers []Paper) []string { return ids } +// TestPostgresPageSearchAndFilters 使用已发布 fixture 验证 SQL 排序、全文与作者检索、主题交集和参数绑定,检查主题命名空间。 func TestPostgresPageSearchAndFilters(t *testing.T) { r, ctx := integrationRepository(t) if err := r.Check(ctx); err != nil { @@ -77,6 +82,7 @@ func TestPostgresPageSearchAndFilters(t *testing.T) { } } +// TestPostgresMetadataPreservesEvidence 验证原文、作者、来源、DOI 优先级与最新决策证据,保留可空字段和缺失论文语义。 func TestPostgresMetadataPreservesEvidence(t *testing.T) { r, ctx := integrationRepository(t) p, err := r.Get(ctx, 1) @@ -111,6 +117,7 @@ func TestPostgresMetadataPreservesEvidence(t *testing.T) { } } +// TestPostgresCorpusIsReadOnlyAndHTTPWorks 检查事务隔离与资源选项;实际尝试写入须被数据库权限拒绝,再经 HTTP 验证真实 SQL 响应。 func TestPostgresCorpusIsReadOnlyAndHTTPWorks(t *testing.T) { r, ctx := integrationRepository(t) tx, err := r.begin(ctx) @@ -153,6 +160,7 @@ func TestPostgresCorpusIsReadOnlyAndHTTPWorks(t *testing.T) { } } +// TestPostgresPublishedTextCodec 通过编码 fixture 检查论文、作者、评论和 HTTP JSON 均还原控制字符,并可继续搜索。 func TestPostgresPublishedTextCodec(t *testing.T) { legacy, ctx := integrationRepository(t) r, err := NewPostgresRepository(legacy.db, "research_encoded_fixture") @@ -182,6 +190,7 @@ func TestPostgresPublishedTextCodec(t *testing.T) { } } +// TestPostgresCursorsTraverseBothDirections 按每页一条遍历两种排序,每步反向读取前页,防止游标循环并拒绝换筛选复用。 func TestPostgresCursorsTraverseBothDirections(t *testing.T) { r, ctx := integrationRepository(t) for _, sort := range []string{"recent", "title"} { @@ -231,6 +240,7 @@ func TestPostgresCursorsTraverseBothDirections(t *testing.T) { } } +// TestPostgresEncodedTitleCursors 在转义标题库中逐页遍历,验证游标保留数据库排序键,不因展示文本解码而改变顺序。 func TestPostgresEncodedTitleCursors(t *testing.T) { legacy, ctx := integrationRepository(t) r, err := NewPostgresRepository(legacy.db, "research_encoded_fixture") @@ -264,6 +274,7 @@ func TestPostgresEncodedTitleCursors(t *testing.T) { } } +// TestPostgresBoundedProbeDoesNotTruncateSparseMatches 用跨越探测窗口的稀疏 ID 和三种页大小验证检索回退不漏项,并检查反向跨空档分页。 func TestPostgresBoundedProbeDoesNotTruncateSparseMatches(t *testing.T) { legacy, ctx := integrationRepository(t) r, err := NewPostgresRepository(legacy.db, "research_sparse_fixture") @@ -310,6 +321,7 @@ func TestPostgresBoundedProbeDoesNotTruncateSparseMatches(t *testing.T) { } } +// TestPostgresTopicCursorSkipsDuplicateEvidence 验证多个来源产生的重复标签证据不会重复返回论文,且主题游标可双向跨页。 func TestPostgresTopicCursorSkipsDuplicateEvidence(t *testing.T) { legacy, ctx := integrationRepository(t) r, err := NewPostgresRepository(legacy.db, "research_sparse_fixture") diff --git a/internal/research/postgres_test.go b/internal/research/postgres_test.go index e1bffb8..ffece02 100644 --- a/internal/research/postgres_test.go +++ b/internal/research/postgres_test.go @@ -1,3 +1,4 @@ +// 本文件记录研究 API 的回归契约;测试注释描述实际断言,不代表本次已运行测试。 package research import ( @@ -8,6 +9,7 @@ import ( "testing" ) +// TestStoredAuthorShapes 覆盖姓名字符串及一到四项作者元组,验证姓名重排、机构忽略、空数组和坏结构拒绝。 func TestStoredAuthorShapes(t *testing.T) { for _, test := range []struct { raw string @@ -35,6 +37,7 @@ func TestStoredAuthorShapes(t *testing.T) { } } +// TestQueryValuesRemainBound 将攻击性文本当作普通搜索词,断言它只进入参数而不拼入 SQL,并检查全文/作者/主题分支。 func TestQueryValuesRemainBound(t *testing.T) { query := `graph'); DROP TABLE papers; -- OR author:*` where, args := whereClause(Filters{Query: query, Topic: "cs.LG", SearchIn: "text"}) @@ -58,6 +61,7 @@ func TestQueryValuesRemainBound(t *testing.T) { } } +// TestSchemaCannotEscapeQualification 验证 schema 名白名单与 nil 连接拒绝,并检查所有占位符都被限定到同一 schema。 func TestSchemaCannotEscapeQualification(t *testing.T) { for _, name := range []string{"", `research";DROP SCHEMA public;--`, "a.b", "Public", strings.Repeat("a", 37)} { if _, err := NewPostgresRepository(&sql.DB{}, name); err == nil { diff --git a/internal/research/testdata/corpus.sql b/internal/research/testdata/corpus.sql index e890668..1216c4f 100644 --- a/internal/research/testdata/corpus.sql +++ b/internal/research/testdata/corpus.sql @@ -1,5 +1,6 @@ -- Synthetic fixture for the disposable, network-isolated CI database only. -- Required columns/types follow Paper Atlas's fixed a3b677b migration. +-- 基础语料覆盖同名标题、可空摘要/日期、多作者形状及原文特殊字符;仅用于可丢弃测试库。 CREATE SCHEMA research_fixture; CREATE TABLE research_fixture.papers ( id bigint PRIMARY KEY, title text NOT NULL, abstract text, title_key text COLLATE "C" NOT NULL, @@ -15,6 +16,7 @@ CREATE TABLE research_fixture.source_records ( ); CREATE TABLE research_fixture.identifiers (scheme text,value text,paper_id bigint REFERENCES research_fixture.papers(id),PRIMARY KEY(scheme,value)); CREATE TABLE research_fixture.tags (id bigint PRIMARY KEY,namespace text,value text,UNIQUE(namespace,value)); +-- evidence_key 允许同论文同标签有多条来源证据,列表和主题分页需去重论文而不是重复返回。 CREATE TABLE research_fixture.paper_tags ( paper_id bigint REFERENCES research_fixture.papers(id),tag_id bigint REFERENCES research_fixture.tags(id), evidence_key text,PRIMARY KEY(paper_id,tag_id,evidence_key) @@ -47,18 +49,21 @@ INSERT INTO research_fixture.paper_tags VALUES(1,1,'first'),(1,1,'second'),(1,2, INSERT INTO research_fixture.venues VALUES(1,'ICLR'),(2,'ICML'); INSERT INTO research_fixture.editions VALUES(7,1,2024,'main'),(8,2,2023,'main'); INSERT INTO research_fixture.submissions VALUES(11,1,7),(12,3,8); +-- 决策优先最新 observed_at,再 decision_date 与 id;旧观察即使声称未来决策日也不能压过新观察。 INSERT INTO research_fixture.decisions VALUES (1,11,'accepted','https://example.test/decision/1','2024-02-01','2024-01-30'), (2,11,'rejected','https://example.test/decision/2','2024-02-01','2024-01-31'), (3,11,'withdrawn','https://example.test/decision/3','2024-02-01','2024-01-31'), (4,11,'accepted','https://example.test/decision/4','2024-01-01','2099-01-01'); +-- 研究运行角色只获 schema USAGE 和表 SELECT,集成测试实际 UPDATE 必须被权限拒绝。 CREATE ROLE foundry_research_fixture LOGIN; REVOKE ALL ON SCHEMA research_fixture FROM PUBLIC; GRANT USAGE ON SCHEMA research_fixture TO foundry_research_fixture; GRANT SELECT ON ALL TABLES IN SCHEMA research_fixture TO foundry_research_fixture; -- Separate encoded schema mirrors the published Paper Atlas nul-soh-v1 format. +-- 复制基础数据并加 codec 标记,用 SOH 转义在 PostgreSQL TEXT 中表达原始 NUL,API 需正确还原。 CREATE SCHEMA research_encoded_fixture; COMMENT ON SCHEMA research_encoded_fixture IS 'paper-atlas:text-codec=nul-soh-v1'; DO $$ @@ -82,6 +87,7 @@ GRANT USAGE ON SCHEMA research_encoded_fixture TO foundry_research_fixture; GRANT SELECT ON ALL TABLES IN SCHEMA research_encoded_fixture TO foundry_research_fixture; -- A large ID gap proves the bounded probe cannot truncate sparse results. +-- 复制语料再加入跨 512/4096 探测窗口的 ID 空档,验证稀疏检索回退不漏匹配及反向分页。 CREATE SCHEMA research_sparse_fixture; DO $$ DECLARE item text; diff --git a/internal/research/text.go b/internal/research/text.go index abebbbb..bba9bcf 100644 --- a/internal/research/text.go +++ b/internal/research/text.go @@ -1,3 +1,4 @@ +// 研究库文本 codec 适配:数据库用 SOH 转义 NUL,API 返回前还原原始文本。 package research import ( @@ -10,6 +11,7 @@ import ( // SOH -> SOH/STX. All other bytes retain their original binary ordering. const textCodec = "nul-soh-v1" +// encodedSchema 仅识别精确协议版本;无标注视为普通文本,未知版本阻止启动,避免错误解码。 func encodedSchema(annotation sql.NullString) (bool, error) { const prefix = "paper-atlas:text-codec=" if !annotation.Valid || !strings.HasPrefix(annotation.String, prefix) { @@ -21,10 +23,12 @@ func encodedSchema(annotation sql.NullString) (bool, error) { return true, nil } +// encodeText 必须先转义 SOH 再转义 NUL,防止第二次替换改写刚生成的转义序列。 func encodeText(value string) string { return strings.ReplaceAll(strings.ReplaceAll(value, "\x01", "\x01\x02"), "\x00", "\x01\x01") } +// decodeText 逐段复制普通字节,仅接受 SOH/SOH 与 SOH/STX;残缺或未知转义立即报错。 func decodeText(value string) (string, error) { if !strings.ContainsRune(value, '\x01') { return value, nil @@ -52,11 +56,13 @@ func decodeText(value string) (string, error) { } } +// textColumn 实现 sql.Scanner,把可选 codec 与目标字段的 NULL 语义集中处理。 type textColumn struct { encoded bool target any } +// Scan 先用 NullString 接收驱动值,再按 schema 解码;非空字符串目标不允许数据库 NULL。 func (column textColumn) Scan(source any) error { var value sql.NullString if err := value.Scan(source); err != nil { @@ -83,6 +89,7 @@ func (column textColumn) Scan(source any) error { return nil } +// text 在 scanPaper/enrich 中包装文本列,避免遗漏对来源元数据或主题的解码。 func (r *PostgresRepository) text(target any) sql.Scanner { return textColumn{encoded: r.encoded, target: target} } diff --git a/internal/research/text_test.go b/internal/research/text_test.go index a972ef2..b95cbcb 100644 --- a/internal/research/text_test.go +++ b/internal/research/text_test.go @@ -1,3 +1,4 @@ +// 本文件记录研究 API 的回归契约;测试注释描述实际断言,不代表本次已运行测试。 package research import ( @@ -6,6 +7,7 @@ import ( "testing" ) +// TestCorpusTextCodecRoundTripAndOrder 对控制字符和 Unicode 两两比较,验证转义既可逆又保留字节排序,并拒绝残缺转义。 func TestCorpusTextCodecRoundTripAndOrder(t *testing.T) { values := []string{"", "\x00", "\x00\x01", "\x01", "\x01\x02", "\x02", "A", "A\x00", "A\x01", "Ada 张三 Ω", "Z\x00\x01\x02尾"} for _, value := range values { @@ -27,6 +29,7 @@ func TestCorpusTextCodecRoundTripAndOrder(t *testing.T) { } } +// TestCorpusTextColumnsRespectCodecAndNulls 验证普通库不解码、编码库还原控制字符,且可空列与必填列保持各自 NULL 约束。 func TestCorpusTextColumnsRespectCodecAndNulls(t *testing.T) { var required string if err := (textColumn{target: &required}).Scan("\x01\x01"); err != nil || required != "\x01\x01" { @@ -50,6 +53,7 @@ func TestCorpusTextColumnsRespectCodecAndNulls(t *testing.T) { } } +// TestCorpusSchemaCodecMarker 验证无标记沿用普通文本、已知标记开启 codec、未知版本明确失败。 func TestCorpusSchemaCodecMarker(t *testing.T) { for _, annotation := range []sql.NullString{{}, {String: "unrelated schema description", Valid: true}} { encoded, err := encodedSchema(annotation)