Skip to content

docs(design): record create/edit/subtable surface + return-flow model (#2604) - #2614

Closed
os-zhuang wants to merge 1 commit into
mainfrom
claude/record-surface-design-ftuljs
Closed

os-zhuang wants to merge 1 commit into
mainfrom
claude/record-surface-design-ftuljs

Conversation

@os-zhuang

Copy link
Copy Markdown
Contributor

概述

落地 #2604(#2578 的后续)的设计文档:docs/design/record-surface-return-flows.md。对 issue 中的三个待决问题给出决定,并把返回流(return flow)写成可实现、可浏览器验证的契约。纯文档,空 changeset,不发包。

三个决定

  1. D1 — Create / Edit 一律是 overlay,永不走路由。 表面大小仍复用 字段多的对象:自适应呈现表面 + 语义 field span(auto/full)+ 表单布局防呆 lint(AI-authored,ADR-0085 对齐) #2578 的派生:field-heavy(派生 'page')→ 全屏 modal(size: 'full'),轻对象 → drawer。这正是 RecordSurface 类型里 'modal' 存在的意义。深链接属于"状态"(详情路由,已上线),不属于"临时任务"——刷新即丢草稿的 URL 是虚假承诺。
  2. D2 — 详情 → 编辑 = 同一个编辑 overlay 盖在详情之上(issue 中的选项 b)。全平台只有一个编辑表面(列表行编辑 / 详情编辑 / 子表子记录编辑同一条代码路径、同一个返回契约)。就地(字段级 inline)编辑是正交增强,推迟而非否决。
  3. D3 — 子表子记录新建/编辑 = 盖在父详情上的 overlay,永不独立路由(确认 issue 推荐)。子 overlay 的大小按子对象自己的字段数派生;保存后只 refetch 子表,父详情的滚动/选中 tab 原样保留。

返回流契约(文档 §4)

  • 取消不变式:Cancel / X / Esc / Back → 回到原地,分毫不动,不 refetch。
  • 保存不变式:编辑不挪人;新建落到新纪录上;子任务不离开父记录。 即:list→New 保存后进新记录详情(轻对象是列表之上的 drawer,列表上下文天然保留;重对象进路由,已有 "← 所有记录" 回程);编辑保存回原地并 refetch;子记录保存只刷子表。
  • 脏表单守卫 + 全屏 modal 压一条 history(Back = 关闭而不是丢上下文)——嵌套层层弹栈,浏览器就是 return stack,不自建。

实现计划(文档 §5)

  • Step 1(framework,可独立合):record-surface.ts 增加 deriveRecordFlowSurface(def, flow, opts) —— 把上面的映射做成 ADR-0085 §5 的"one shared derivation",纯函数 + 单测 + minor changeset。
  • Step 2(objectui):ObjectView.tsx 的 create/edit 换掉硬编码大 modal;详情 Edit 按钮、related-list 子记录接同一 helper;脏守卫 + history 集成;spec pin 未含 Step 1 前照 字段多的对象:自适应呈现表面 + 语义 field span(auto/full)+ 表单布局防呆 lint(AI-authored,ADR-0085 对齐) #2578 先例本地镜像 + TODO。
  • Step 3:浏览器验证矩阵(field_zoo 57 字段 / product 6 字段 + 带 relatedList 的父子),覆盖 issue 验收清单的每一条返回路径。

零元数据授权

不加任何新 key(recordSurface / returnTo / afterSave 均过不了 ADR-0085 §2 准入测试),不开新 ADR;显式覆盖仍是既有的 navigation.mode/size、FormView.type/modalSize、assigned Page。

Refs #2604 · #2578 · ADR-0085 · #2595 · #2599

🤖 Generated with Claude Code

https://claude.ai/code/session_019zKcAtbtxuF9SXYgSzjk9v


Generated by Claude Code

…#2604)

Decides the three open questions from #2604 (follow-up to #2578):

- D1: create/edit are ALWAYS overlays, never routes — the derived 'page'
  surface maps to a full-screen modal (size 'full'); light objects keep a
  drawer. Deep-linkability belongs to state (detail route, shipped), not to
  transient tasks.
- D2: detail → edit reuses the same edit overlay over the detail route —
  one edit surface everywhere; in-place field editing deferred, not rejected.
- D3: subtable child create/edit = overlay over the parent detail, never a
  route; size derived from the CHILD object's own field count.

Specifies the return-flow contract (cancel invariant, save invariant —
edit never moves you, create lands on the record, child tasks never leave
the parent — dirty guard, full-screen-modal history integration), the
Step 1 spec helper deriveRecordFlowSurface as the one shared derivation
(ADR-0085 §5), the objectui wiring plan, and the browser-verification
matrix. Zero new authorable keys (ADR-0085 §2); docs-only, empty changeset.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019zKcAtbtxuF9SXYgSzjk9v
@vercel

vercel Bot commented Jul 5, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
spec Ready Ready Preview, Comment Jul 5, 2026 2:49am

Request Review

Copy link
Copy Markdown
Contributor Author

按维护者要求,设计结论改为直接更新到 issue 评论(#2604 (comment)),不再以仓库文档形式落地 —— 关闭本 PR。


Generated by Claude Code

This branch was successfully deployed

1 active deployment
Preview — 1439cec5 Deployed Jul 5, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/m tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants