Skip to content

fix(app-shell)!: converge flow node geometry to spec FlowNode.position (#3172) - #3294

Merged
xuyushun441-sys merged 1 commit into
mainfrom
claude/issue-3172-flow-position-canonical
Aug 3, 2026
Merged

fix(app-shell)!: converge flow node geometry to spec FlowNode.position (#3172)#3294
xuyushun441-sys merged 1 commit into
mainfrom
claude/issue-3172-flow-position-canonical

Conversation

@xuyushun441-sys

@xuyushun441-sysxuyushun441-sys commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

这是什么

按维护者裁决（2026-08-03）与 PM 审计报告，把流程设计器的节点几何收敛到 spec 已声明的 FlowNode.position，退役 objectui 本地拼写 ui: {x, y}。改动面全部落在 @object-ui/app-shell；packages/spec、objectstack 仓、plugin-designer、types/react/components/fields（#3233 在飞）零改动。

它同时是一个行为修复，不只是改名。 spec 17 的 FlowNodeSchema 自 objectstack#4001 起是 .strict()，ui 会产出 unrecognized_keys：客户端实时校验飘红、服务端保存 422。也就是说今天在设计器里拖一个节点，这份 flow 就存不进去。审计里这条是静态推导，本 PR 把它跑成了断言（见下「实机验证」）。

触点清销（对照审计的 5 文件 ~15 处）

写侧 3 处 —— 一律产出 position，永不写 ui：

  • FlowCanvas.tsxpersistPosition（拖拽落点）
  • FlowCanvas.tsxaddNode（带 at 的新增）
  • FlowCanvas.tsxinsertOnEdge（边上插入）

读侧 2 处 —— position 优先、ui 仅作遗留回退，保留「x/y 同时有限」判据：

  • flow-canvas-layout.tshasManualPosition（现委托给新的单一读点 manualPosition()）
  • flow-canvas-layout.ts 布局覆盖（positions.set(...)，同时去掉了 n.ui!.x! 那对非空断言）

类型 3 处 —— 几何按引用派生自 spec，不再手写形状：

  • FlowNodeUI → FlowNodePosition = NonNullable< SpecFlowNode['position'] >（import type，仍是零运行时依赖）
  • FlowDesignerNode 挂载 position?: FlowNodePosition；ui?: LegacyFlowNodeUI 保留但标 @deprecated 只读
  • FlowPreview.tsx:52 的形状拷贝消灭，改 type FlowNode = FlowDesignerNode（与它早已这么做的 edge 对齐）

夹具 / 文档：

  • flow-canvas-layout.test.ts 两条夹具改 position，并新增一条同点位的 legacy ui 夹具（兼容读继续被覆盖）
  • README.md 布局段落改写；FlowCanvas.tsx 头注释改写
  • changeset（minor，按 AGENTS.md「changeset 不声明 major，破坏性语义写正文」）

不变量与证明

  1. 写侧只出 position —— 三条写路径各一条回归测试。
  2. 离开设计器的 draft 必须 ui-free —— 抬升点选在画布输入边界（FlowCanvas 用 withCanonicalGeometry(storedNodes) 归一后再 useMemo），而不是塞进 persistPosition。理由：FlowCanvas 有 5 条会重发 nodes 数组的 patch 路径（拖拽、新增、边插入、revise loop、删除），只补写侧会漏掉后两条——它们不写几何，却会把遗留 ui 原样带回 draft，闸门照样 422。归一在入口，则任何现有或将来的 patch 都从已规范化的数组构造，结构上不可能再发出 ui。测试里专门有一条「删除节点也 ui-free」钉住这一点。
  3. 读侧兼容旧数据 —— manualPosition() 是唯一读点：position 优先、ui 回退；一条测试把两种拼写各布一次局并比对整张 map 相等。
  4. 几何类型 ≡ spec —— spec-symbol-parity.test.ts 新增正向 parity（编译期：与 NonNullable< SpecFlowNode['position'] > 互等、input 与 parsed 一致、x/y 均必填、半个坐标不可表示；运行期：spec 仍拼作 position 且拒收 ui）。既有的 FlowCanvasNode / FlowCanvasEdge 反向防撞 pin 原样保留。
  5. 索引签名兜底 —— FlowDesignerNode 带 [k: string]: unknown，编译器抓不到漏掉的 ui 读写点，因此收工做了全仓 grep：写形态 ui: { x|y|... } 在生产代码中零命中（仅剩注释与故意造遗留数据的测试夹具）；读形态 ui?.x / ui.y 零命中，唯一的 node.ui 读点就是 manualPosition() 里那条有文档的遗留回退。

验证

  • 单测：pnpm exec vitest run 三个受影响文件 → 80 passed；app-shell 全量 → 266 files / 2311 passed / 1 skipped。
  • turbo run type-check --filter=@object-ui/app-shell 通过（含 tsconfig.typetests.json，编译期断言真的被编译）；lint 0 errors（新增告警仅 _legacy 解构丢弃一处，与本包既有 _-前缀写法一致）。
  • 每条新测试都做了 sabotage 验证（改坏见红、还原见绿）：把 persistPosition 改回写 ui → 2 红；绕过入口归一 → 5 红；删掉 legacy 读回退 → 9 红；抬升时不删 ui 键 → 10 红；破坏同引用返回 → 1 红；把 spec 拒收断言喂合法节点 → 1 红；把 FlowNodePosition 改成 { x: number; y?: number } → typetests 4 处 TS2344 报红。还原后 80/80 绿。

实机验证（浏览器，无后端）

用仓内 verify 技能的 preview gallery（Playwright 驱动，console dev server 起在自选端口 5197，用完按 PID 关掉，临时插桩已 git checkout 还原）：把 flow 样本的 find 节点临时种成 ui: {x: 520, y: 40}，实测：

  • 遗留节点渲染在钉位：left: 520px / top: 40px（兼容读活着）。
  • 拖动另一个节点 start 后，真实 patch 载荷为
    [{"id":"start","position":{"x":290,"y":88}},{"id":"find","position":{"x":520,"y":40}}, …]，
    JSON.stringify(patch).includes('"ui"') === false —— 遗留节点在同一个 patch 里自愈了。
  • 拖后的节点停在落点（说明写进去的 position 又被读了回来，不是靠自动布局巧合）。
  • 闸门实测：设计器产出的这份 draft FlowSchema.safeParse(draft).success === true；把同一份 draft 换回 ui 拼写则 REJECTED，issue 正是审计里那条
    {"code":"unrecognized_keys","keys":["ui"],"path":["nodes",0]}。审计中「今天拖一个节点就存不进去」的静态推导由此变成执行过的证据。

未实机覆盖的部分：真实后端 POST /metadata 的 422 未走真机（本次验证不带后端），但服务端用的就是同一份 FlowSchema，上面的 safeParse 即该链路的判定函数；真实环境存量数据的规模仓内无法回答（仓内 examples/fixtures 既无 ui 也无 position），不过因为 strict 闸门，带 ui 的行今天本就写不进去，存量面大概率接近空集。

范围外发现

无（本次没有踩到与本单无关的缺陷，故未新开 issue）。

Closes#3172

Generated by Claude Code

@claude
fix(app-shell)!: converge flow node geometry to spec `FlowNode.positi…
a199748
…on` (#3172)
The flow designer wrote node geometry as its own `ui: { x, y }` while
`@objectstack/spec` has modelled the same object as `FlowNode.position` all
along. Since objectstack#4001 the spec's node schema is `.strict()`, so `ui` is
an `unrecognized_keys` error: dragging a node made the flow fail live client
validation and be rejected on save with a 422. Converging the spelling is
therefore a behaviour fix, not a rename.
- All three write paths (drag / add-at-point / insert-on-edge) emit
`position: { x, y }`.
- The canvas migrates on write: `withCanonicalGeometry` lifts a stored `ui`
onto `position` and strips the key at the canvas's input boundary, so every
patch it emits is `ui`-free — including patches unrelated to geometry.
- Reading stays backwards-compatible: `manualPosition()` prefers `position` and
falls back to a legacy `ui`, keeping the "x and y both finite" predicate.
- The geometry type is derived from the spec by reference
(`FlowNodePosition`), the shape-copy in `FlowPreview.tsx` is gone, and
`spec-symbol-parity.test.ts` gains a positive parity pin plus a runtime
assertion that the spec rejects the retired spelling.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NVPjPzmmAJ2Ngtvgg5MSRa
@vercel

vercelBot commented Aug 3, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
ProjectDeploymentActionsUpdated (UTC)
objectuiIgnoredIgnoredAug 3, 2026 12:52pm

Request Review

@github-actionsgithub-actionsBot added documentation Improvements or additions to documentation tests labels Aug 3, 2026
@github-actions

github-actionsBot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

✅ Console Performance Budget

MetricValueBudget
Main entry (gzip)28.1 KB350 KB
Entry fileindex-DYI_jXU1.js—
StatusPASS—

📦 Bundle Size Report

PackageSizeGzipped
app-shell (index.js)8.47KB3.09KB
app-shell (runtime-config.js)7.42KB2.32KB
app-shell (types.js)0.01KB0.04KB
app-shell (urlParams.js)7.57KB2.97KB
auth (AuthContext.js)0.31KB0.24KB
auth (AuthGuard.js)1.17KB0.53KB
auth (AuthProvider.js)22.10KB4.37KB
auth (AuthShell.js)3.49KB1.40KB
auth (ForgotPasswordForm.js)12.21KB3.45KB
auth (LoginForm.js)18.13KB5.39KB
auth (PreviewBanner.js)0.90KB0.50KB
auth (RegisterForm.js)6.64KB2.21KB
auth (SocialSignInButtons.js)9.60KB3.89KB
auth (UserMenu.js)3.40KB1.22KB
auth (auth-gate-events.js)1.29KB0.66KB
auth (authStyles.js)5.04KB1.72KB
auth (createAuthClient.js)35.76KB9.11KB
auth (createAuthenticatedFetch.js)4.37KB1.69KB
auth (index.js)2.35KB1.07KB
auth (org-roles.js)6.66KB2.78KB
auth (phone-identifier.js)1.11KB0.66KB
auth (types.js)0.59KB0.35KB
auth (useAuth.js)4.91KB0.87KB
auth (useIsWorkspaceAdmin.js)1.61KB0.85KB
collaboration (CommentThread.js)18.38KB4.49KB
collaboration (LiveCursors.js)3.17KB1.27KB
collaboration (PresenceAvatars.js)3.65KB1.42KB
collaboration (PresenceProvider.js)2.79KB1.13KB
collaboration (index.js)1.25KB0.53KB
collaboration (useCommentSearch.js)1.98KB0.88KB
collaboration (useConflictResolution.js)7.75KB1.86KB
collaboration (useMentionNotifications.js)1.81KB0.68KB
collaboration (usePresence.js)6.33KB1.84KB
collaboration (useRealtimeSubscription.js)7.91KB2.01KB
components (index.js)476.47KB104.64KB
core (index.js)2.25KB0.80KB
create-plugin (index.js)9.28KB2.98KB
data-objectstack (index.js)136.23KB34.75KB
fields (index.js)223.48KB54.76KB
i18n (LocalizationContext.js)1.76KB0.96KB
i18n (currency.js)1.22KB0.64KB
i18n (i18n.js)4.32KB1.77KB
i18n (index.js)2.46KB0.96KB
i18n (pickLocalized.js)1.70KB0.83KB
i18n (provider.js)5.37KB1.72KB
i18n (useObjectLabel.js)26.14KB6.07KB
i18n (useSafeTranslation.js)3.26KB1.44KB
layout (index.js)37.96KB10.54KB
mobile (MobileProvider.js)0.92KB0.49KB
mobile (ResponsiveContainer.js)0.94KB0.38KB
mobile (breakpoints.js)1.51KB0.70KB
mobile (createOfflineDataSource.js)5.61KB1.74KB
mobile (index.js)1.50KB0.62KB
mobile (offlineQueue.js)3.91KB1.35KB
mobile (pwa.js)0.97KB0.49KB
mobile (serviceWorker.js)1.48KB0.62KB
mobile (serviceWorkerSource.js)3.41KB1.48KB
mobile (useBreakpoint.js)1.54KB0.65KB
mobile (useGesture.js)6.96KB1.98KB
mobile (useOfflineSync.js)1.99KB0.72KB
mobile (usePullToRefresh.js)2.53KB0.85KB
mobile (useResponsive.js)0.71KB0.42KB
mobile (useResponsiveConfig.js)1.36KB0.63KB
mobile (useSpecGesture.js)4.05KB1.53KB
mobile (useTouchTarget.js)1.01KB0.54KB
permissions (MePermissionsProvider.js)8.75KB3.06KB
permissions (PermissionContext.js)0.31KB0.25KB
permissions (PermissionGuard.js)0.89KB0.45KB
permissions (PermissionProvider.js)3.67KB1.12KB
permissions (evaluator.js)4.41KB1.44KB
permissions (index.js)0.91KB0.41KB
permissions (store.js)0.91KB0.42KB
permissions (useFieldPermissions.js)1.28KB0.52KB
permissions (usePermissions.js)1.55KB0.71KB
plugin-ai (index.js)15.71KB3.79KB
plugin-calendar (index.js)44.98KB12.37KB
plugin-charts (index.js)60.54KB17.13KB
plugin-chatbot (index.js)180.09KB42.72KB
plugin-dashboard (index.js)112.01KB28.86KB
plugin-designer (index.js)210.51KB42.51KB
plugin-detail (index.js)230.56KB56.80KB
plugin-editor (index.js)2.46KB1.10KB
plugin-form (index.js)111.49KB26.95KB
plugin-gantt (index.js)162.25KB39.55KB
plugin-grid (index.js)185.08KB49.04KB
plugin-kanban (index.js)47.89KB13.18KB
plugin-list (index.js)104.94KB25.32KB
plugin-map (index.js)16.81KB5.24KB
plugin-markdown (index.js)13.72KB4.69KB
plugin-report (index.js)40.55KB10.59KB
plugin-timeline (index.js)25.76KB7.33KB
plugin-tree (index.js)8.34KB2.82KB
plugin-view (index.js)83.67KB20.43KB
providers (DataSourceProvider.js)0.75KB0.39KB
providers (MetadataProvider.js)1.37KB0.59KB
providers (ThemeProvider.js)1.90KB0.85KB
providers (UploadProvider.js)11.71KB3.53KB
providers (index.js)0.44KB0.22KB
providers (types.js)0.01KB0.04KB
react-runtime (index.js)5.67KB2.37KB
react (LazyPluginLoader.js)3.77KB1.33KB
react (SchemaRenderer.js)19.28KB6.38KB
react (data-invalidation.js)5.05KB2.08KB
react (index.js)1.02KB0.55KB
react (spec-input.js)0.20KB0.18KB
sdui-parser (codegen.js)4.09KB1.74KB
sdui-parser (index.js)4.47KB2.03KB
sdui-parser (parse.js)10.04KB2.82KB
sdui-parser (types.js)0.29KB0.24KB
sdui-parser (validate.js)4.69KB1.48KB
types (ai.js)0.20KB0.17KB
types (api-types.js)0.20KB0.18KB
types (app.js)2.87KB0.99KB
types (base.js)0.20KB0.18KB
types (blocks.js)0.20KB0.18KB
types (complex.js)0.20KB0.18KB
types (crud.js)0.20KB0.18KB
types (data-display.js)0.20KB0.18KB
types (data-protocol.js)0.20KB0.19KB
types (data.js)0.20KB0.18KB
types (designer.js)1.87KB0.85KB
types (disclosure.js)0.20KB0.18KB
types (error-code.js)1.54KB0.88KB
types (feedback.js)0.20KB0.18KB
types (field-types.js)0.20KB0.18KB
types (form.js)0.20KB0.18KB
types (http-retry.js)4.32KB2.02KB
types (index.js)2.46KB1.21KB
types (layout.js)0.20KB0.18KB
types (managed-by.js)0.19KB0.18KB
types (mobile.js)0.20KB0.18KB
types (navigation.js)0.20KB0.18KB
types (objectql.js)0.20KB0.18KB
types (overlay.js)0.20KB0.18KB
types (permissions.js)0.20KB0.18KB
types (plugin-scope.js)0.20KB0.18KB
types (record-components.js)0.20KB0.19KB
types (record-semantics.js)1.28KB0.67KB
types (registry.js)0.20KB0.18KB
types (reports.js)0.20KB0.18KB
types (spec-report.js)5.05KB1.93KB
types (system-fields.js)3.33KB1.54KB
types (theme.js)0.20KB0.18KB
types (ui-action.js)3.40KB1.71KB
types (views.js)0.20KB0.18KB
types (widget.js)0.20KB0.18KB

Size Limits

  • ✅ Core packages should be < 50KB gzipped
  • ✅ Component packages should be < 100KB gzipped
  • ⚠️ Plugin packages should be < 150KB gzipped

@xuyushun441-sys
xuyushun441-sys marked this pull request as ready for review August 3, 2026 12:56
@xuyushun441-sys
xuyushun441-sys added this pull request to the merge queueAug 3, 2026
Merged via the queue into main with commit 6e794a1Aug 3, 2026
17 checks passed
@xuyushun441-sys
xuyushun441-sys deleted the claude/issue-3172-flow-position-canonical branch August 3, 2026 12:57
This was referenced Aug 5, 2026
Closed
Merged
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentationImprovements or additions to documentationtests

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Flow 节点几何有三种拼写(ui:{x,y} / spec 的 FlowNode.position / FlowCanvasNode)—— 需要定一种并收敛

2 participants

@xuyushun441-sys@claude