原型需求说明层前端实施契约

状态：原型准备就绪

产品 PRD 版本：1.3

前端实施契约版本：1.3

来源变更：CR-20260824-004

确认依据：Freddy 于 2026-08-24 确认方案 B、未来增量范围和 PRD 权威边界，并明确“开始搭建”

交付包：prd-package.json

本文件是给前端工程师、交付生成器和评审服务实现者的实施输入。产品事实以 prd.md 为准；本契约只细化页面、组件、状态、数据交换和门禁。

1. 来源与范围

项目	内容
产品 PRD	`prd.md` v1.3
本次变更	CR-20260824-004
PRD 工作流阶段	Phase 1–4 已完成，进入本地实施
全局一致性锚点	已同步
覆盖页面	P-001 原型与标注；P-002 逻辑文档
覆盖服务	评审意见 Worker + D1、本地和生成一致性门禁
不覆盖页面	历史原型；正式 PRD 在线编辑器；实时多人协同编辑

2. 页面清单

页面 ID	页面名称	页型	核心任务	原型路径
P-001	原型与标注	OperationsWorkbenchPage / delivery shell	在同一上下文阅读原型、定位需求并查看或提交评审意见	`prototype/prototype-requirement-hub/index.html`
P-002	逻辑文档	DocumentationView / delivery shell	阅读非页面逻辑并回溯产品 PRD、前端契约和验收记录	`prototype/prototype-requirement-hub/index.html#documents`

3. 产品功能覆盖矩阵

功能 ID	页面/表面	PRD 来源	已确认产品功能	实现目标	状态	排除依据
F-001	P-001 顶部与主画布	PRD 5.1	可分享的共享交付外壳	Tabs 切换原型与标注、逻辑文档；显示版本和变更 ID；默认纯净操作态	实现	—
F-002	P-001 原型画布与右侧面板	PRD 5.1	正式标注双向定位与分类筛选	稳定功能锚点、编号点、筛选、聚合、目标外框高亮；关闭后不残留拦截层	实现	—
F-003	P-002 文档阅读区	PRD 5.2	非页面逻辑 HTML 阅读	文档目录、内容 iframe、来源章节定位	实现	—
F-004	P-001 评审意见区	PRD 5.3	在线意见跨设备保存	创建、加载、解决、重开；D1 持久化；不使用 localStorage	实现	—
F-005	交付生成与检查	PRD 5.4	版本、功能 ID、锚点和来源一致性门禁	扩展生成器与 delivery:check	实现	—
F-006	P-001、P-002 全状态	PRD 5.4	加载、空、异常、禁用和无权反馈	Skeleton、Spin、Empty、Alert、Result、Message、Notification	实现	—

3A. 研发级 PRD 到前端契约映射

PRD 维度	前端契约承接位置	必须说明
功能定义	页面清单、覆盖矩阵、页面设计决策	阅读面、标注面板、评审服务和门禁边界
字段取值逻辑	普通控件、复杂控件、数据展示契约	分类、状态、版本、锚点、正文和 revision
交互说明	复杂控件、交互与反馈	页签、双向定位、提交、解决、重开、失败重试
功能阐述	页面-区域-组件映射、状态与权限矩阵	正向、异常、部分可用和恢复方式
逆向流程搭建	复杂控件、状态矩阵	废弃、重开、版本替代和回滚
功能权限清单	状态与权限矩阵、前端验收清单	只读、写入、发布授权三层分离
上线前历史数据处理	来源追踪、门禁和兼容回归	旧模块不迁移、无清单走原交付模式

4. 页面设计决策

候选画像工具错误匹配到 ApprovalPage；本页面不包含审批对象或通过/驳回，因此不采用该候选。结合两个平级阅读面、持续可见的版本上下文、原型画布和评审面板，确定使用 OperationsWorkbenchPage 的结构原则，并明确它是交付工具外壳而非 ERP 业务页面。

P-001 原型与标注

产品范式：研发需求交付与评审工作台
页面基线：Ant Design Pro PageContainer + Tabs 工作台模式；右侧说明使用 Ant Design Drawer/固定辅助面板心智
页面母版：OperationsWorkbenchPage
页面目标：让开发和测试不离开原型上下文即可识别、定位并讨论本次需求改动
主用户任务：按分类扫描标注、在原型定位、阅读详情并查看或提交评审意见
信息优先级：一级当前版本、变更 ID 与正式标注；二级原型锚点和需求摘要；三级规则详情、来源和评审意见
主操作：默认“查看标注”，进入说明态后切换为“操作原型”；评审写入是面板内次级任务，不与业务操作竞争
密度策略：compact
视觉强调：decision-first
视觉强调对象：本次改动点、待确认项、版本边界和未解决意见
动效策略：minimal
动效说明：只保留页签切换、锚点定位闪烁、抽屉/折叠展开和保存反馈
推荐组件：PageContainer、Tabs、Badge、Tag、Drawer、Collapse、Form、Input.TextArea、Select、Button、Popconfirm、Skeleton、Spin、Empty、Alert、Result、message、notification
常驻信息：模块标题、产品 PRD 版本、变更 ID、两个阅读页签、显示标注开关、正式标注总数
渐进呈现：标注详细规则和来源进入 Collapse；意见列表进入右侧面板；用户只在主动评论或回复时进入钉钉扫码和评审表单
页面结构预算：单一 PageContainer；顶部紧凑元信息；默认主体为完整原型画布；宽屏说明态使用画布 + 360px 并列辅助面板，窄屏按需 Drawer；不叠加业务摘要卡
禁止冗余：禁止重复页面标题、重复变更摘要、装饰性指标卡、演示角色切换器、正式标注编辑器和页面内发布按钮
必须避免：把评审意见显示成已确认需求；把本地保存成功冒充服务端保存；标注遮挡原型主操作；关闭标注后仍拦截点击

P-002 逻辑文档

产品范式：研发规格阅读工作台
页面基线：Ant Design Pro PageContainer + Tabs 文档阅读模式；目录遵循 Ant Design Anchor 心智
页面母版：DocumentationView
页面目标：让无法绑定页面的状态、接口、权限、异常和历史规则在同一分享地址可读
主用户任务：选择交付文档、通过目录定位章节、从来源链接回溯完整规则
信息优先级：一级当前文档和章节；二级本次变更相关规则；三级构建、验收与发布信息
主操作：切换文档；文档阅读页不设置保存或编辑主按钮
密度策略：standard
视觉强调：data-first
视觉强调对象：标题目录、表格、状态机和来源引用
动效策略：minimal
动效说明：仅文档切换和章节定位平滑滚动
推荐组件：PageContainer、Tabs、Anchor、Alert、Result、Skeleton、Button、Tooltip
常驻信息：模块标题、版本、变更 ID、主阅读页签和当前文档标题
渐进呈现：发布指纹与构建信息折叠；长表格在内容区横向滚动；文档目录在宽屏粘性显示
页面结构预算：单一 PageContainer；文档选择栏 + 目录 + 正文；不复制文档正文成说明卡
禁止冗余：禁止同一章节在标注卡和正文双份完整展示；禁止业务原型导航混入文档页
必须避免：源 Markdown 已变但仍展示旧 HTML；章节来源链接失效无提示；生成 HTML 被当作第二权威源

5. 页面-区域-组件映射

页面 ID	区域	业务目的	组件或片段	数据来源	状态	备注
P-001	顶部上下文	明确项目与版本	PageContainer header、Tag、Badge	PRD 包、标注清单	默认/加载/版本异常	版本异常使用 Alert
P-001	主阅读页签	切换原型和文档	Tabs	固定两项	默认	切换保留原型上下文
P-001	原型画布	承载纯净业务原型	同源 iframe	`../index.html`	loading/error	标注层位于外壳，不修改 iframe 业务 DOM
P-001	标注覆盖层	显示编号和高亮	Badge 心智的绝对定位按钮	annotations.json + iframe 锚点矩形	默认/聚合/缺锚点	使用 iframe 同源 DOM 读取
P-001	标注面板	筛选和阅读需求	Tabs、Tag、Collapse	annotations.json	loading/empty/error	360px 宽，窄屏切 Drawer
P-001	评审意见	查看、评论和回复	Alert、List、Form、Input.TextArea、Button、Popconfirm、钉钉扫码登录	review API + 钉钉会话	loading/empty/error/unauthenticated/non-employee	API 失败不阻断正式内容
P-002	文档选择	选择 PRD/契约/验收材料	Tabs	delivery-publication documents	默认	只读
P-002	文档内容	阅读生成 HTML	同源 iframe / Anchor 心智	生成 HTML	loading/error	来源锚点通过 URL fragment 定位

6. 普通控件契约

控件 ID	所在区域	组件	值与默认态	校验与限制	状态反馈	规则来源
C-001	顶部	Tabs	默认 `prototype`；另有 `documents`	仅两个平级阅读面	当前项高亮	PRD 5.1、5.2
C-002	顶部	Button	默认“查看标注”；说明态显示“操作原型”	不保存浏览器偏好；每次打开默认关闭说明层	切换即时生效；关闭后面板、点位和高亮全部移除	PRD 5.1
C-003	标注面板	Tabs	默认 all	all、page、interaction、rule、field、pending	Badge 显示数量	PRD 5.1
C-004	评审表单	Input.TextArea	空；showCount	1–2000 字符，去首尾空格	字段错误贴近输入框	PRD 5.3
C-005	评审表单	Select	默认 interaction	page、interaction、rule、field、pending；可清空=false	非法值禁止提交	PRD 5.3
C-006	评审入口	Button + 钉钉扫码登录	未登录跳转钉钉 OAuth 页面；桌面端展示官方二维码；已登录直接打开表单	Worker 使用 `scope=openid corpid`，换 token 后硬校验目标 corpId；随机会话令牌经 fragment 一次性交付并只保存在页面内存；客户端不提交作者身份	401 引导重新登录；403 提示仅限本企业员工；缺权限时拒绝建会话	PRD 5.3、10
C-007	发布者回复	Button + 服务端发布会话	可信发布链接首次打开后换取会话，不要求扫码或输入共享令牌	一次性签名声明绑定发布者、原型、版本、nonce 和有效期；消费后写审计并失效	已使用、过期、转发后抢先消费或会话撤销时要求重新生成	PRD 5.3、10

7. 复杂控件契约

7.1 标注双向定位

契约项	规则
锚点来源	仅以 `data-requirement-id` 匹配；正式交付不得使用 localStorage 中的 CSS selector。
点位位置	读取目标元素 `getBoundingClientRect()`，相对 iframe 视口投影到覆盖层；滚动和 resize 使用 requestAnimationFrame 重算。
多功能 ID	DOM 属性允许空格分隔多个功能 ID；每个标注按 requirementId 匹配。
聚合	点位中心距离小于 24px 时显示聚合数量；点击后在面板中列出组内标注。
选中	一次只允许一个 annotationId 选中；选中点、卡片和目标区域同时高亮。
定位	点击卡片后调用目标元素 `scrollIntoView({block:'center'})`；完成后重算点位。
缺失	运行时显示错误标记；构建/检查阶段将缺锚点作为阻断错误。
默认态	首次打开不渲染点位和目标高亮，面板 `display:none`，iframe 占满主内容区。
关闭	关闭后清空点位和目标高亮，面板隐藏，覆盖层 `pointer-events:none`，iframe 业务操作不受影响。

7.2 评审意见状态更新

契约项	规则
加载键	prototypeId + prototypeVersion；annotationId 为可选过滤。
创建	提交成功才清空正文；网络失败保留内存中的表单值，不落 localStorage/sessionStorage。
解决	使用 Popconfirm；请求必须携带当前 revision。
重开	仅 resolved 可操作；请求必须携带当前 revision。
冲突	409 后刷新当前列表并 Notification 提示，不自动重放状态变更。
审计	每次 create、resolve、reopen 与 comment 记录在同一 D1 batch 中提交。

7.3 文档来源跳转

契约项	规则
来源格式	`<target>.html#<heading-id>`；生成器统一创建 heading id。
触发	点击“查看完整文档”切换 P-002，并设置文档 iframe src。
回退	fragment 不存在时打开文档顶部并显示一次 warning message。
权威边界	文档页不允许编辑；所有修改回到 Markdown 源。

8. 表格与数据展示契约

数据面	展示规则	排序与筛选	空值	溢出与性能
正式标注列表	编号、标题、分类、状态、摘要、详情、来源	正式序号升序；分类 Tabs 过滤	不允许把文件缺失显示成空列表	详情 Collapse；只渲染当前分类
评审意见列表	状态、分类、作者、正文、更新时间、关联标注	open 优先，其次更新时间倒序	无意见使用 Empty“暂无当前版本评审意见”	正文换行；超过 50 条使用分页或分批读取
文档正文表格	保留 Markdown 表头和单元格	不在阅读层重排序	`—`	容器横向滚动，不压缩到不可读

9. 状态与权限矩阵

角色/状态	可见	可操作	禁用原因	反馈
只读 / 正常	正式标注、文档、已有评审意见	切换、筛选、定位	无写权限	不显示正式内容编辑入口
本企业员工 / 正常	同上 + 评审表单	新增、回复	无	Message 成功反馈
发布者 / 发布会话有效	同上 + 评审表单	回复、解决、重开	无需重复扫码	操作仍写入发布者审计记录
任意 / API 未配置	正式标注、文档	阅读	在线评审未启用	Alert；不显示假保存按钮
任意 / API 异常	正式标注、文档	阅读、重试 API	服务不可用	Alert + 重试
未登录 / 鉴权失败	正式内容和表单当前输入	钉钉扫码或重试	401；403 表示非本企业员工	不展示人工凭证输入；明确说明身份边界
写入 / revision 冲突	最新列表	刷新后重试	记录已变化	Notification；不覆盖
任意 / 锚点缺失	标注卡、文档来源	查看文档	页面位置不存在	错误 Tag；交付检查失败

10. 交互与反馈

场景	即时反馈	加载	成功	失败	焦点与恢复
页面初始化	显示框架和版本	Skeleton 覆盖面板，iframe loading	展示标注数量	Result/Alert 分区呈现	重试保持当前页签
点击标注	点位和卡片选中	无	锚点闪烁 1.2 秒	错误 Tag + 查看文档	焦点移到卡片标题
提交意见	Button loading	局部 Spin	message“评审意见已保存”	message/notification 明确未保存	失败保留当前内存输入；成功清空正文
解决意见	Popconfirm	Button loading	message“评审意见已解决”	409 通知刷新	成功后焦点回到意见卡片
加载意见失败	Alert	无循环自动重试	点击重试恢复	“在线评审暂不可用，正式需求仍可查看”	正式标注阅读不受影响

11. 文案

类型	文案
页面标题	原型需求说明
页签	原型与标注；逻辑文档
标注切换	查看标注；操作原型
面板标题	原型标注
分类	全部；页面；交互；规则；字段；待确认
来源操作	查看完整文档
评审标题	在线评审意见
未配置	在线评审尚未启用；正式需求标注和逻辑文档仍可查看。
加载失败	在线评审暂不可用，正式需求仍可查看。
无意见	暂无当前版本评审意见。
保存成功	评审意见已保存。
无权	没有评审意见写入权限。
冲突	该意见已被其他人更新，请刷新后重试。
锚点缺失	该需求未找到页面位置，请查看完整文档。

12. 视觉契约

区域	契约
UI 主入口	`references/ui-review/erp-ui-design-system.md`
技术基线	React 19 + TypeScript + antd 6.5 + ProComponents；正式演示原型使用单一根 ConfigProvider
主题	使用官方 token；主色 `colorPrimary`；不覆盖全局 `.ant-*`
顶部	PageContainer 标题 24px 级；版本与变更用低饱和 Tag；不使用营销 Hero
主体	默认完整画布；大于 1180px 的说明态使用 360px 并列面板且不得覆盖画布；不大于 1180px 时按需 Drawer，关闭后不得残留遮挡或点击拦截
标注点	24px 圆形；页面蓝、交互绿、规则紫、字段橙、待确认红；颜色同时配合分类文字和 aria-label，不作为唯一语义
面板	单一白色表面、1px 边框；卡片之间 12px；详细内容 Collapse，不叠加多层 Card
文档	目录 220px；正文最大 1120px；表格可横向滚动；代码与正文使用现有交付样式
无障碍	所有点位为 button；支持 Tab、Enter/Space；选中状态使用 aria-pressed；焦点环使用 token

13. 来源追踪

实现对象	来源
页签和共享交付外壳	PRD 5.1 / F-001 / 用户确认方案 B
标注分类和双向定位	PRD 5.1 / F-002 / 用户竞品截图
文档 HTML	PRD 5.2 / F-003 / 现有 delivery 渲染机制
服务端保存	PRD 5.3 / F-004 / 用户明确“数据不应该存在本地”
版本门禁	PRD 5.4 / F-005 / 现有 delivery integrity 基线
状态与权限	PRD 5.4 / F-006 / UI 交互规范主文件
Worker 与 D1	Cloudflare 官方 D1 Binding、prepared statements、batch 与 Workers best practices

14. 前端验收清单

[ ] 产品 PRD Phase 1–4 和全局一致性锚点完整
[ ] F-001 至 F-006 均有实现证据
[ ] 原型、标注清单、PRD 和前端契约版本一致
[ ] data-requirement-id 锚点扫描 100% 通过
[ ] 原型与标注、逻辑文档页签真实切换
[ ] 标注点与说明卡片双向定位
[ ] 默认打开时业务原型完整可点、可滚动、可打开自身 Drawer/Modal
[ ] 关闭标注后业务原型点击不受影响
[ ] 清空本地存储后正式标注不丢失
[ ] API 成功时意见跨浏览器回读
[ ] API 失败时不写 localStorage 且不提示保存成功
[ ] 401、409、5xx、空态、加载态均可验证
[ ] 1280×720 与 1440×900 同视口截图通过人工视觉走查
[ ] antd CLI API 查询和 lint 完成
[ ] Worker TypeScript、Wrangler 配置、D1 migration 和本地 API 测试通过
[ ] 旧 delivery-publication 无 annotationManifest 时回归通过
[ ] 未经授权未创建线上 D1、未设置生产密钥、未部署、未发布

15. 待决策

决策	当前处理	阻塞范围
发布者与非本企业账号专项验收	增强交付页、`Contact.User.Read`、HTTPS 回调、Worker、Secrets 与亚太 D1 已上线；真实员工扫码、写入和第二浏览器回读已通过	不阻塞员工评论正式使用；只阻塞发布者免登录回复与企业边界的最终验收结论
VPN 与移动办公网络	不依赖固定出口 IP；GET 请求 12 秒超时后重试一次，POST/PATCH 不自动重放；提交失败保留本页草稿并明确标记未保存	阻塞弱网体验验收，不阻塞静态标注阅读

原型需求说明层 前端实施契约