原型需求说明 · Build Notes

产品 PRD 版本：1.3

前端实施契约版本：1.3

来源变更：CR-20260824-004

本次变更覆盖

变更编号	用户修改	产品 PRD 落点	前端契约落点	原型落点
CR-20260824-001	用标注点直观呈现页面改动，并用 HTML 页签承载页面外逻辑	F-001～F-003	P-001、P-002；F-001～F-003	分享阅读页、标注侧栏、逻辑文档页签
CR-20260824-001	分享给开发后仍能看到标注与评审内容，不能只存在本地	F-004～F-006、数据模型、权限与验收	F-004～F-006、服务契约与失败状态	静态正式标注清单、Cloudflare Worker + D1 评审服务、版本门禁
CR-20260824-002	标注工具不能影响业务原型交互	F-001、F-002 默认纯净操作和按需说明态	C-002、7.1、视觉与验收契约	默认关闭说明层；宽屏面板并列不遮挡，窄屏按需打开；关闭后清空点位、面板和高亮；复合功能 ID 可定位
CR-20260824-003	员工扫码评论回复；发布者无需重复登录但必须验证身份	F-004～F-006、权限与审计	C-006、C-007、7.2、状态矩阵	钉钉 OAuth + corpId 硬校验；D1 会话、评论、回复与审计；一次性发布者签名链接
CR-20260824-004	记录线上员工评论与跨浏览器回读验收结果，不把未验证的发布者与非本企业边界写成已完成	A-002、风险与一致性锚点	发布与身份验收边界	v1.3 状态文案、标注清单、交付摘要与验收记录

已实现

正式需求标注随交付版本生成 annotations.json，分享链接不依赖当前电脑。
review.html 在同一地址内提供“原型与标注 / 逻辑文档”页签、筛选、双向定位与来源回溯。
当前阅读器只从服务端 API 回读意见，浏览器不使用 localStorage 或 sessionStorage 保存共享内容。
D1 数据结构已包含原型版本、标注点、评论、回复、短期会话、一次性发布者声明、修订号与审计事件。
Worker 已移除共享写入令牌：员工走钉钉 OAuth，token 响应 corpId 与目标企业不一致时拒绝；作者从个人身份接口回读。员工与发布者会话通过 URL fragment 一次性交付并只保存在页面内存，兼容移动端跨站 Cookie 限制。
阅读器已实现登录态、评论、回复、发布者解决/重开、401/403/409 和服务异常反馈；未配置 API 时不显示假保存入口。
交付一致性指纹覆盖标注源、生成清单、阅读页、样式与脚本。
默认以完整业务原型进入；只有用户主动点击“查看标注”才渲染点位和说明面板，点击“操作原型”或 Escape 后全部说明层退出。
业务前缀功能 ID（如 F-VIS-102）和空格分隔的复合 data-requirement-id 使用 token 匹配；选中目标由外壳高亮，不改写业务原型 DOM。

边界与待确认

亚太 D1、生产密钥、评审 Worker 与增强交付页均已上线；正式分享地址为 https://erp-prototypes.pages.dev/prototype/prototype-requirement-hub/delivery/review。
已复用“「小汪智能助理」”并开通 Contact.User.Read，公网 HTTPS 回调已保存；为兼容 VPN 和移动办公，不启用固定出口 IP 白名单。
2026-08-24 已用真实企业员工“汪耕”完成扫码登录与页面级测试评论写入，并在未登录第二浏览器回读同一评论，确认数据来自服务端。
发布者免登录回复与非本企业账号拒绝仍待线上专项验收，不能据此宣称全部身份边界验收完成。
PRD 仍是业务权威源；标注清单只保存定位和摘要，不复制新的独立业务规则。
未迁移历史原型；未来新需求及发生改动的页面使用该能力。

检查

[x] PRD 准备度
[x] TypeScript / antd 6 / ProComponents 生产构建
[x] Worker 钉钉员工会话、评论/回复、发布者会话与移动端 bearer 单元测试（12/12）
[x] D1 本地迁移（10 条语句）与 Wrangler 4.125 本地运行：GET /health 200、当前版本 GET /api/reviews 200 回读空列表
[x] 发布者链接生成脚本实测；签名声明位于 fragment，输出验证时已脱敏
[x] prototype:guard（0 error；原型示意页仍有原始色值 warning）
[x] 交互干扰复验：默认无面板/点位/高亮，业务按钮命中链路直达 iframe；打开后 6 个点位，ANN-002 卡片/点位/目标高亮一致；关闭后全部移除
[x] 1440×900、1280×720、1024×720 真实浏览器复验：无横向溢出；1440/1280 面板与画布边界相接不重叠；1024 切为按需抽屉
[x] 无注入隔离 Chrome 的顶层页和 iframe 均无运行时异常；内置浏览器仍会报 MutationObserver.observe 空目标，但页面世界对 MutationObserver.prototype.observe 的诊断包装无法拦截该调用，可确认调用发生在浏览器控制的隔离世界，不是交付页脚本执行链
[x] change:sync（base: main）
[x] delivery:check
[x] 本地交付页 v1.2 浏览器走查：默认标注关闭；打开后 6 个点位与右侧面板；未发布 API 时只读且登录按钮禁用；关闭后面板隐藏、点位为 0、iframe pointer-events:auto
[x] 真实钉钉员工扫码、企业身份评论写入及未登录第二浏览器跨设备回读
[ ] 非本企业账号拒绝与发布者免登录回复线上验收
[ ] 用户视觉验收

知识影响

该能力属于项目长期 PRD / 原型交付规范，已同步 docs/prd-driven-workflow.md、docs/prototype-hosting.md 与 prd/_TEMPLATE/；没有把未确认的线上权限方案写成既定事实。