原型需求说明层 产品 PRD
状态：原型准备就绪
产品 PRD 版本：1.3
当前变更：CR-20260824-004
交付包：prd-package.json
本 PRD 的页面结构、交互方式、组件行为、权限控制与状态定义，均遵循《UI 交互规范主文件》；未单独说明者，默认按该规范执行。
0. 初始化动作与输出策略
| 项目 | 内容 |
|---|
| 用户选择 | 方案 B：正式需求随版本发布，评审意见服务端保存 |
| 交互约束 | 标注工具不得默认遮挡或抢占业务原型操作；默认进入纯净操作态，用户主动查看标注后才显示说明层。 |
| 产品方向 | 在可分享的原型交付地址中提供页面标注和非页面逻辑 HTML 文档 |
| 输出节奏 | 分段高保真；用户已于 2026-08-24 明确“开始搭建” |
| 当前阶段 | Phase 4：已确认决策进入实施 |
| 下一步进入条件 | PRD 准备度通过后实施原型与服务端 |
1. 背景与目标
1.1 业务场景
| 维度 | 内容 |
|---|
| 当前业务场景 | 产品通过 PRD 和可交互原型向开发、测试交付需求。 |
| 触发问题 | PRD 文字量大，开发难以快速识别页面改动点；只看原型又容易遗漏规则、字段、异常和权限。 |
| 现有处理方式 | PRD Markdown、前端契约、原型分开阅读；本地 annotate.js 只保存个人走查反馈。 |
| 当前痛点 | 需求与页面缺少直观双向定位；本地标注无法随分享链接展示；非页面逻辑没有统一阅读入口。 |
| 不做的代价 | 开发漏实现、测试漏验收、不同设备看到不同信息、需求版本难以追溯。 |
| 受影响对象 | 产品负责人、开发人员、测试人员、原型交付生成器、Cloudflare 评审服务。 |
| 已知约束 | Markdown 保持权威；正式业务原型不得混入调试控件；不批量迁移历史原型；未授权不得发布。 |
1.2 假设前提
| 假设 ID | 假设内容 | 影响范围 | 风险等级 | 验证方式 | 当前状态 |
|---|
| A-001 | 线上正式阅读权限沿用原型分享地址的访问范围。 | 权限、发布 | 中 | 发布前由用户确认是否增加 Cloudflare Access | 待确认 |
| A-002 | 评论与回复仅允许钉钉扫码识别的本企业员工；页面不要求使用者额外输入凭证。 | 权限、审计 | 高 | OAuth 回调返回 corpId 与目标企业一致，用户身份由服务端接口回读 | 已确认；已复用小汪智能助理并完成真实企业员工扫码与写入，非本企业账号拒绝待专项验收 |
| A-003 | 未来原型可为所有已确认功能提供稳定 data-requirement-id。 | 原型、门禁 | 低 | 自动扫描原型 DOM/源码 | 已有项目基线支持 |
1.3 目标与成功标准
| 类型 | 指标 / 目标 | 口径 | 当前基线 | 目标值 | 验收方式 |
|---|
| 业务目标 | 已确认页面需求可直接定位 | 已确认且需页面实现的功能 ID 中存在可定位锚点的比例 | 尚无统一统计 | 100% | 交付一致性检查 |
| 用户目标 | 分享后所有设备看到相同标注 | 同一 URL、同一版本的标注数量与内容一致 | 本地标注不可共享 | 100% 一致 | 清缓存、无痕窗口、第二浏览器验证 |
| 北极星指标 | 未映射已确认功能数 | 已确认、状态为“实现”的功能 ID 未出现在标注或逻辑文档的数量 | 无门禁 | 0 | 自动门禁 |
| 数据目标 | 共享数据不依赖本地存储 | 正式标注及评审意见读取是否依赖 localStorage/sessionStorage | 当前本地标注依赖 localStorage | 0 项依赖 | 静态检查与浏览器验证 |
2. 用户与场景
2.1 目标用户
| 角色 | 主要任务 | 使用频率 | 数据范围 | 权限边界 | 备注 |
|---|
| 产品负责人 | 编排正式需求标注、确认评审意见、发布版本 | 中频 | 当前项目全部需求 | 可维护权威 PRD；发布需单独授权 | 正式内容作者 |
| 开发人员 | 查看页面改动、规则、字段和待确认项；提交评审意见 | 高频 | 被分享项目 | 默认可读；写入需评审权限 | 主要阅读者 |
| 测试人员 | 从标注跳转到验收规则和异常分支 | 高频 | 被分享项目 | 默认可读；写入需评审权限 | 主要验收者 |
| 只读评审者 | 查看原型和逻辑文档 | 低频 | 被分享项目 | 未登录或非本企业员工不可评论、回复 | 外部协作者 |
2.2 用户故事 / JTBD
| 用户故事 ID | 作为 | 我希望 | 以便 | 优先级 | 验收方式 |
|---|
| US-001 | 开发人员 | 在原型上直接看到本次需求标注 | 快速理解要改哪里 | P0 | 点击标注双向定位 |
| US-002 | 开发人员 | 在同一地址查看非页面逻辑 HTML | 不遗漏状态、接口、权限和异常 | P0 | 切换逻辑文档页签 |
| US-003 | 产品负责人 | 分享后所有人看到相同版本 | 避免本地数据造成信息差 | P0 | 跨浏览器一致性测试 |
| US-004 | 评审人员 | 在线提交并跟踪意见 | 让意见跨设备保存且可审计 | P0 | D1 写入与回读测试 |
| US-005 | 测试人员 | 从功能 ID 回溯 PRD 和验收条款 | 验证实现没有静默删减 | P0 | 来源链接与门禁测试 |
2.3 典型场景
| 场景 ID | 场景名称 | 前置条件 | 触发动作 | 当前痛点 | 理想结果 |
|---|
| S-001 | 开发阅读本次改动 | 已获得交付地址 | 打开原型与标注 | 需在长 PRD 中搜索 | 首屏看到变更 ID、标注数量和页面位置 |
| S-002 | 查看跨页面逻辑 | 规则无单一页面锚点 | 切换逻辑文档 | 原型无法表达 | HTML 目录定位对应 PRD 章节 |
| S-003 | 提交评审意见 | 用户具备写权限 | 在标注卡片或页面级入口提交 | 本地意见无法共享 | 服务端保存并在其他设备回读 |
| S-004 | 原型版本升级 | 新版本已生成 | 打开新版本 | 旧意见可能串入 | 默认只显示当前版本意见，旧意见可追溯但不混入 |
3. 产品方案
3.1 核心价值主张
| 对象 | 价值主张 | 为什么重要 | 不这么做的影响 |
|---|
| 开发与测试 | 页面改动可定位，非页面逻辑同地址可读 | 减少遗漏和跨文档搜索 | 实现和验收只覆盖可见 UI |
| 产品负责人 | 正式需求、评审意见和版本边界清晰 | 防止评论直接污染已确认规格 | 同一条反馈被误当成正式需求 |
| 交付系统 | 自动检查功能 ID、锚点和版本 | 把完整性从人工记忆变成门禁 | 仍依赖口头提醒和人工抽查 |
3.2 MVP 范围
| 范围项 | 本期是否包含 | 优先级 | 纳入 / 排除理由 | 依赖 | 备注 |
|---|
| 可分享的原型与标注页签 | 是 | P0 | 核心问题 | 交付生成器、稳定锚点 | 正式标注只读 |
| 逻辑文档 HTML 页签 | 是 | P0 | 承载非页面逻辑 | 现有 Markdown 渲染 | 保留目录和来源 |
| 服务端评审意见 | 是 | P0 | 消除本地保存 | Worker + D1 | 版本绑定 |
| 版本与锚点门禁 | 是 | P0 | 防止错误交付 | delivery check | 失败即阻止交付 |
| 历史原型批量迁移 | 否 | P2 | 用户明确排除 | 无 | 未来改动时增量接入 |
| 在线编辑正式 PRD | 否 | P2 | 避免双重权威源 | 无 | 继续修改 Markdown |
| 实时多人光标和富文本协同 | 否 | P3 | 超出解决问题所需 | 无 | 不建设通用文档平台 |
3.3 成功指标
| KPI ID | 指标名称 | 指标定义 | 计算口径 | 数据来源 | 目标值 | 观察周期 |
|---|
| KPI-001 | 页面需求锚点覆盖率 | 有稳定锚点的已确认页面功能占比 | 锚点功能数 / 页面实现功能数 | 前端契约与标注清单 | 100% | 每次交付 |
| KPI-002 | 共享一致率 | 跨设备读取相同版本内容一致的测试通过率 | 通过场景 / 总场景 | 浏览器验收 | 100% | 每次交付 |
| KPI-003 | 版本串场数 | 当前版本默认视图出现其他版本意见的数量 | 不匹配记录数 | API 回读 | 0 | 每次交付 |
| KPI-004 | 未归属评审意见数 | 缺少原型 ID 或版本的意见数量 | 非法记录数 | D1 约束与接口校验 | 0 | 持续 |
3.4 核心流程
flowchart LR
A["产品 PRD 与前端契约"] --> B["生成正式标注索引"]
B --> C{"版本与锚点检查"}
C -- "通过" --> D["生成原型标注与逻辑文档 HTML"]
C -- "失败" --> E["停止交付并返回缺失项"]
D --> F["开发与测试打开共享地址"]
F --> G["在线提交评审意见"]
G --> H["Worker 鉴权与校验"]
H --> I["D1 保存意见与审计事件"]
I --> J["产品确认后同步 PRD 并发布新版本"]
4. 功能范围
4.1 本期范围
| 范围 ID | 功能 / 能力 | 业务价值 | 覆盖用户 | 优先级 | 验收结果 |
|---|
| R-001 | 共享交付外壳 | 一个地址阅读原型、标注和逻辑文档 | 全部角色 | P0 | 页签真实切换 |
| R-002 | 正式标注与稳定锚点 | 把功能 ID 定位到页面区域 | 开发、测试 | P0 | 双向定位、分类筛选 |
| R-003 | HTML 逻辑文档 | 承载非页面规则 | 开发、测试 | P0 | 目录与来源链接 |
| R-004 | 服务端评审意见 | 跨设备保存和追踪 | 产品、开发、测试 | P0 | 创建、回读、解决、重开 |
| R-005 | 一致性与权限门禁 | 防止版本串场和越权写入 | 产品、系统 | P0 | 自动测试和错误反馈 |
4.2 非本期范围
| 排除 ID | 不做内容 | 排除原因 | 是否后续候选 | 若误做的风险 |
|---|
| OOS-001 | 历史原型批量补标 | 用户明确只覆盖未来 | 否 | 大量无当前价值迁移 |
| OOS-002 | 浏览器内修改正式需求 | PRD 必须保持权威源 | 否 | 形成双重事实源 |
| OOS-003 | 评论附件和图片上传 | MVP 先验证文本闭环 | 是 | 引入对象存储和敏感文件风险 |
| OOS-004 | 实时多人编辑 | 非必要 | 是 | 复杂状态同步和冲突处理 |
| OOS-005 | 未经授权的线上发布 | 外部影响需单独授权 | 否 | 暴露内部需求或产生费用 |
5. 功能设计与业务规则
5.1 正式需求标注与共享阅读
5.1.1 功能定义
| 优先级 | 角色 | 功能点 | 触发条件 | 前置条件 | 业务结果 |
|---|
| P0 | 开发、测试、产品 | F-001 共享交付外壳 | 打开未来原型的交付地址 | 模块存在交付清单 | 显示原型与标注、逻辑文档两个页签；默认以纯净操作态展示原型 |
| P0 | 开发、测试 | F-002 正式标注双向定位 | 打开原型与标注页签 | 标注清单和稳定锚点通过检查 | 标注点、说明卡片、分类筛选互相联动 |
5.1.1.1 外部 API 对接与字段映射
| 业务功能 | API 名称与文档地址 | 已核验生产地址 / 方法 | 平台入参（类型 / 来源） | 返参字段与本地记录 | 回读 / 错误 / 未核验门禁 |
|---|
| 正式标注读取 | 本次不涉及外部 API | 静态同源 annotations.json / GET | 原型 ID、版本由交付清单生成 | 标注数组，不写浏览器存储 | 文件缺失、版本不一致或结构非法时显示错误并停止交付 |
5.1.2 字段取值逻辑
| 字段名称 | 类型 | 必填 | 默认值 | 取值逻辑 | 枚举值 | 校验规则 | 空值 / 异常显示 |
|---|
| 标注 ID | string | 是 | 无 | 模块内唯一 | ANN-数字 | 不可重复 | 缺失阻止交付 |
| 功能 ID | string | 是 | 无 | 对应前端契约覆盖矩阵 | F-数字或业务前缀 | 必须存在于覆盖矩阵 | 缺失阻止交付 |
| 锚点 ID | string | 条件必填 | 无 | 页面需求使用 data-requirement-id | 功能 ID | 当前原型必须可匹配 | 非页面逻辑明确进入文档 |
| 分类 | enum | 是 | page | 标注主阅读维度 | page、interaction、rule、field、pending | 只允许枚举值 | 非法阻止生成 |
| 状态 | enum | 是 | confirmed | 正式性状态 | confirmed、pending、superseded | 待确认不得显示为已确认 | 未知状态显示异常 |
| 来源引用 | string | 是 | 无 | 指向生成 HTML 的章节锚点 | URL fragment | 必须同源且可解析 | 不可定位时标记来源异常 |
5.1.3 交互说明
| 场景 | Ant Design / ProComponents 组件 | 触发动作 | 前端交互 | 后端逻辑 | 错误处理 |
|---|
| 切换阅读面 | Tabs | 点击页签 | 保留当前原型滚动和已选标注 | 不涉及 | 文档加载失败使用 Result 并允许重试 |
| 进入标注阅读 | Button、Badge、Tag、Drawer、Collapse | 点击“查看标注” | 宽屏以不覆盖画布的并列面板显示标注；窄屏按需打开 Drawer | 不涉及 | 锚点不存在显示“该需求未找到页面位置” |
| 查看标注 | Badge、Tag、Collapse | 点击数字点或卡片 | 高亮外壳中的目标区域、滚动定位、展开详情；高亮层不接收业务点击 | 不涉及 | 锚点不存在显示“该需求未找到页面位置” |
| 分类筛选 | Tabs、Badge | 点击分类 | 仅过滤说明层，不修改业务原型 | 不涉及 | 无结果显示 Empty 并保留清空筛选入口 |
| 操作原型 / 关闭标注 | Button | 点击 | 同时隐藏点位、目标高亮和说明面板，恢复完整画布；业务原型状态不重置 | 不涉及 | 覆盖层必须 pointer-events:none，不得残留透明拦截区 |
5.1.4 功能阐述
| 路径类型 | 步骤 | 用户动作 | 系统行为 | 用户感知 | 结果 |
|---|
| 正向 | 1 | 打开共享地址 | 加载版本、标注和原型，标注层保持关闭 | 首屏是完整可操作原型 | 可先完成业务交互 |
| 正向 | 2 | 点击“查看标注”后选择卡片或数字点 | 定位对应功能锚点并闪烁提示 | 原型位置与说明同时高亮 | 完成双向定位 |
| 异常 | 1 | 打开缺少标注文件的地址 | 拒绝伪造空列表 | Result 显示文件缺失和重试入口 | 交付不可误判为“无需求” |
| 边界 | 1 | 多个标注落在同一区域 | 聚合数量并在点击后展开 | 页面不被大量气泡遮挡 | 可逐条阅读 |
5.1.5 逆向流程搭建
| 逆向场景 | 触发角色 | 触发条件 | 数据影响 | 状态回退 / 修正规则 | 限制条件 | 审计要求 |
|---|
| 标注废弃 | 产品负责人 | 对应需求被新版本替代 | 旧标注保留在历史版本 | 新版本状态设为 superseded，不删除旧版本证据 | 不允许浏览器直接修改正式清单 | 由 Git 和变更日志审计 |
5.1.6 功能权限清单
| 角色 | 页面权限 | 按钮权限 | 字段权限 | 数据范围 | 审批 / 二次确认 | 无权反馈 |
|---|
| 所有被分享用户 | 可见 | 可切换、筛选、定位 | 正式标注只读 | 当前分享项目与版本 | 否 | 不展示正式内容编辑入口 |
| 产品负责人 | 可见 | 同上；正式内容通过仓库流程维护 | 浏览器只读 | 当前项目全部版本 | 发布需二次确认 | 提示“请在权威 PRD 中修改并重新生成” |
5.1.7 上线前历史数据处理方案
| 数据对象 | 数据来源 | 是否迁移 | 迁移 / 清洗规则 | 默认值策略 | 历史状态处理 | 回滚方案 | 验证方式 |
|---|
| 历史原型标注 | localStorage、旧截图 | 否 | 用户已确认不批量迁移 | 无 | 历史原型保持原状 | 删除新模块即可回退 | 检查历史原型文件未改 |
5.2 逻辑文档与来源回溯
5.2.1 功能定义
| 优先级 | 角色 | 功能点 | 触发条件 | 前置条件 | 业务结果 |
|---|
| P0 | 开发、测试、产品 | F-003 非页面逻辑 HTML 阅读 | 切换逻辑文档页签 | PRD Markdown 已生成 HTML | 状态机、接口、权限、历史数据可在同一地址阅读 |
5.2.1.1 外部 API 对接与字段映射
| 业务功能 | API 名称与文档地址 | 已核验生产地址 / 方法 | 平台入参（类型 / 来源） | 返参字段与本地记录 | 回读 / 错误 / 未核验门禁 |
|---|
| 文档读取 | 本次不涉及外部 API | 同源生成 HTML / GET | 文档 ID 与章节锚点 | HTML 阅读视图 | 源 Markdown 变化但 HTML 未刷新时一致性检查失败 |
5.2.2 字段取值逻辑
| 字段名称 | 类型 | 必填 | 默认值 | 取值逻辑 | 枚举值 | 校验规则 | 空值 / 异常显示 |
|---|
| 文档 ID | enum | 是 | prd | 来自交付清单 | prd、frontend-contract、build-notes、delivery-summary | 目标文件必须存在 | 缺失显示 Result |
| 章节锚点 | string | 否 | 文档顶部 | 由 Markdown 标题生成 | 本次不涉及 | 页面内唯一 | 无锚点时打开文档顶部 |
5.2.3 交互说明
| 场景 | Ant Design / ProComponents 组件 | 触发动作 | 前端交互 | 后端逻辑 | 错误处理 |
|---|
| 切换文档 | Tabs、Menu | 点击 | 保留左侧目录和当前章节 | 不涉及 | 404 显示“文档尚未生成” |
| 从标注查看来源 | Button、Tooltip | 点击“查看完整文档” | 切换逻辑文档并定位章节 | 不涉及 | 锚点失效时打开文档顶部并警告 |
5.2.4 功能阐述
| 路径类型 | 步骤 | 用户动作 | 系统行为 | 用户感知 | 结果 |
|---|
| 正向 | 1 | 点击逻辑文档 | 加载 PRD HTML 和目录 | 同一交付外壳内阅读 | 不离开项目上下文 |
| 异常 | 1 | 打开过期生成文件 | 一致性门禁在交付前发现 | 不产生错误线上交付 | 返回源文件需刷新 |
5.2.5 逆向流程搭建
| 逆向场景 | 触发角色 | 触发条件 | 数据影响 | 状态回退 / 修正规则 | 限制条件 | 审计要求 |
|---|
| 文档版本回退 | 产品负责人 | 新版本需要回退 | 回退 PRD 与交付清单后重新生成 | 不手改生成 HTML | 需遵循 Git 回滚和发布授权 | Git 与变更日志记录 |
5.2.6 功能权限清单
| 角色 | 页面权限 | 按钮权限 | 字段权限 | 数据范围 | 审批 / 二次确认 | 无权反馈 |
|---|
| 被分享用户 | 可见 | 可切换和定位 | 全部只读 | 当前项目 | 否 | 无编辑入口 |
5.2.7 上线前历史数据处理方案
| 数据对象 | 数据来源 | 是否迁移 | 迁移 / 清洗规则 | 默认值策略 | 历史状态处理 | 回滚方案 | 验证方式 |
|---|
| 既有交付 HTML | 现有 delivery 目录 | 否 | 保持兼容；没有标注清单的模块继续原交付首页 | 原交付模式 | 不主动改变旧链接 | 可关闭新清单字段 | 回归现有交付测试 |
5.3 在线评审意见与服务端保存
5.3.1 功能定义
| 优先级 | 角色 | 功能点 | 触发条件 | 前置条件 | 业务结果 |
|---|
| P0 | 本企业员工 | F-004 创建、查看、回复评审意见 | 在当前版本提交文本 | 钉钉扫码登录成功且服务端确认所属企业 | 意见保存到 D1 并可跨设备回读 |
| P0 | 产品负责人 / 发布者 | 回复、解决或重开意见 | 意见状态需要变化 | 服务端发布会话有效，携带当前 revision | 无需重复扫码，但每次操作仍可审计地归属到发布者 |
5.3.1.1 外部 API 对接与字段映射
| 业务功能 | API 名称与文档地址 | 已核验生产地址 / 方法 | 平台入参（类型 / 来源） | 返参字段与本地记录 | 回读 / 错误 / 未核验门禁 |
|---|
| 查询意见 | Cloudflare D1 Worker Binding API | 待部署地址 / GET /api/reviews | prototypeId、prototypeVersion、annotationId 可选 | items、count；浏览器不持久化副本 | API 未配置时显示“在线评审尚未启用”，不伪造成功 |
| 钉钉登录授权 | 获取登录用户的访问凭证 | GET https://login.dingtalk.com/oauth2/auth | redirect_uri、client_id、scope=openid corpid、签名 state；桌面端由钉钉页面展示二维码 | 回调 authCode、原样返回 state | 回调域名必须与应用安全设置一致；state 无效、过期或来源不合法时拒绝 |
| 换取用户 token | 获取用户 token | POST https://api.dingtalk.com/v1.0/oauth2/userAccessToken | AppKey、AppSecret、authCode、grantType=authorization_code | accessToken、refreshToken、expireIn、corpId | corpId 必须等于服务端 DINGTALK_CORP_ID，否则 403；密钥只存 Worker Secret |
| 回读员工身份 | 获取用户通讯录个人信息 | GET https://api.dingtalk.com/v1.0/contact/users/me | Header 携带个人 accessToken；应用需 Contact.User.Read | nick、openId、unionId、avatarUrl | 作者只取服务端响应；缺权限或用户不存在时拒绝创建会话 |
| 创建 / 回复意见 | D1 prepared statements | https://prototype-review-worker.wanggeng826.workers.dev / POST /api/reviews、POST /api/reviews/:id/replies | 版本、标注 ID、内容；作者仅取服务端会话 | comment / reply、revision | 401 未登录；403 非本企业员工；422 字段错误 |
| 更新状态 | D1 batch | https://prototype-review-worker.wanggeng826.workers.dev / PATCH /api/reviews/:id | status、revision；actor 取服务端会话 | 更新后的 comment | revision 冲突返回 409，客户端刷新后重试 |
5.3.2 字段取值逻辑
| 字段名称 | 类型 | 必填 | 默认值 | 取值逻辑 | 枚举值 | 校验规则 | 空值 / 异常显示 |
|---|
| 意见 ID | string | 是 | 服务端生成 UUID | crypto.randomUUID() | 本次不涉及 | 唯一 | 缺失视为服务端错误 |
| 原型 ID | string | 是 | 无 | 当前交付清单 | 小写字母、数字、连字符 | 1–80 字符 | 非法返回 422 |
| 原型版本 | string | 是 | 无 | 当前交付清单 | 语义版本或构建版本 | 1–40 字符 | 非法返回 422 |
| 标注 ID | string | 否 | null | 绑定卡片时写入 | ANN-数字 | 当前清单存在时才接受 | 空值表示页面级意见 |
| 分类 | enum | 是 | interaction | 用户选择 | page、interaction、rule、field、pending | 只允许枚举 | 非法返回 422 |
| 内容 | string | 是 | 无 | 用户输入 | 本次不涉及 | 去首尾空格，1–2000 字符 | 空值禁止提交 |
| 作者身份 | object | 是 | 无 | 服务端从钉钉员工会话或发布会话解析 | employee、publisher | 客户端不可上传或覆盖作者姓名 / ID | 会话无效返回 401/403 |
| 状态 | enum | 是 | open | 服务端状态机 | open、resolved | 只允许 open↔resolved | 未知值返回 422 |
| revision | int | 是 | 1 | 每次状态更新加 1 | 正整数 | 必须匹配当前值 | 冲突返回 409 |
| 员工会话 | 短期 bearer + HttpOnly cookie 兼容回退 | 是 | 无 | OAuth 成功后服务端生成随机令牌，仅在 D1 保存哈希；令牌通过 URL fragment 一次性交付并立即移入页面内存 | employee | 不使用 localStorage/sessionStorage；兼容跨站 Cookie 被拦截的移动浏览器；短期有效、可撤销 | 刷新后重新扫码；过期返回 401，不在浏览器存储评审正文 |
| 发布者会话 | 短期 bearer + HttpOnly cookie 兼容回退 | 条件必填 | 无 | 可信发布流程生成短期一次性签名声明，Worker 验签后换取页面内存会话 | publisher | 绑定 prototypeId、prototypeVersion、发布者与有效期；nonce 只能使用一次 | 无法证明真实发布链路时不得授予发布者权限 |
5.3.3 交互说明
| 场景 | Ant Design / ProComponents 组件 | 触发动作 | 前端交互 | 后端逻辑 | 错误处理 |
|---|
| 加载意见 | Skeleton、Spin、Alert | 打开面板 | 正式标注先显示，意见异步加载 | 按原型 ID+版本查询 | 失败不影响正式标注，Alert 支持重试 |
| 提交意见 / 回复 | Drawer、Form、Input.TextArea、Button、Message | 点击评论或回复 | 未登录时引导钉钉扫码；已登录时直接校验并提交 | 从服务端会话取作者、校验 corpId、写 comment/reply 与审计事件 | 401 引导登录；403 明确非本企业成员；网络错误不伪造成功 |
| 解决意见 | Popconfirm、Tag、Message | 点击解决 | 二次确认后提交 revision | batch 原子更新状态与事件 | 409 提示内容已变化并刷新 |
| 重开意见 | Button、Message | 点击重开 | 状态恢复 open | 同上 | 同上 |
5.3.4 功能阐述
| 路径类型 | 步骤 | 用户动作 | 系统行为 | 用户感知 | 结果 |
|---|
| 正向 | 1 | 提交有效意见 | API 校验后写入 D1 | Message“评审意见已保存” | 其他设备可回读 |
| 异常 | 1 | 无写权限提交 | 返回 401，不写数据 | Message“没有评审意见写入权限” | 输入仍在当前表单内 |
| 异常 | 2 | revision 已过期 | 返回 409 | Notification 提示刷新后重试 | 不覆盖他人状态 |
| 边界 | 1 | API 不可用 | 正式标注与文档正常展示 | Alert“在线评审暂不可用” | 核心阅读不被阻断 |
5.3.5 逆向流程搭建
| 逆向场景 | 触发角色 | 触发条件 | 数据影响 | 状态回退 / 修正规则 | 限制条件 | 审计要求 |
|---|
| 重开意见 | 有写权限用户 | 已解决意见仍需跟进 | status 变 open，revision +1 | 不删除原解决事件 | 必须携带当前 revision | 写 reopen 事件 |
| 撤销误提交 | 产品负责人 | 内容错误或敏感 | MVP 不物理删除，新增纠正意见并解决旧意见 | 保留原始证据 | 物理删除不在本期 | 全部事件保留 |
5.3.6 功能权限清单
| 角色 | 页面权限 | 按钮权限 | 字段权限 | 数据范围 | 审批 / 二次确认 | 无权反馈 |
|---|
| 只读用户 | 可见意见 | 新增、解决、重开隐藏或禁用 | 只读 | 当前项目版本 | 否 | 提示需写权限 |
| 本企业员工 | 可见 | 可新增、回复 | 可编辑新意见，不可改历史正文 | 当前项目版本 | 首次需钉钉扫码 | 非本企业成员返回 403 |
| 产品负责人 / 发布者 | 可见 | 可回复、解决、重开 | 正式性仍需回写 PRD | 发布会话绑定的项目版本 | 由可信发布流程的一次性签名链接换取会话；不要求扫码，发布仍需单独授权 | 链接过期、转发后已使用或会话失效时要求重新生成 |
5.3.7 上线前历史数据处理方案
| 数据对象 | 数据来源 | 是否迁移 | 迁移 / 清洗规则 | 默认值策略 | 历史状态处理 | 回滚方案 | 验证方式 |
|---|
| 既有 localStorage 走查反馈 | 浏览器本地 | 否 | 不自动上传，避免将个人草稿误当共享需求 | 无 | 保持原工具独立 | 不影响现有工具 | 清空浏览器后共享数据仍存在 |
5.4 版本一致性与交付门禁
5.4.1 功能定义
| 优先级 | 角色 | 功能点 | 触发条件 | 前置条件 | 业务结果 |
|---|
| P0 | 产品、交付系统 | F-005 版本与锚点检查 | 刷新或检查交付 | PRD 包、标注清单和原型存在 | 不一致时停止交付并列出错误 |
| P0 | 全部角色 | F-006 状态与权限反馈 | 加载、无数据、异常或无权 | 进入对应状态 | 用户明确知道原因和下一步 |
5.4.1.1 外部 API 对接与字段映射
| 业务功能 | API 名称与文档地址 | 已核验生产地址 / 方法 | 平台入参（类型 / 来源） | 返参字段与本地记录 | 回读 / 错误 / 未核验门禁 |
|---|
| 一致性检查 | 本次不涉及外部 API | 本地脚本 | PRD 版本、变更 ID、功能 ID、锚点、指纹 | 通过或错误清单 | 任一 P0 错误阻止交付 |
5.4.2 字段取值逻辑
| 字段名称 | 类型 | 必填 | 默认值 | 取值逻辑 | 枚举值 | 校验规则 | 空值 / 异常显示 |
|---|
| 原型版本 | string | 是 | 无 | PRD 包版本与标注清单相同 | 本次不涉及 | 完全一致 | 不一致阻止交付 |
| 变更 ID | string | 是 | 无 | PRD 包 lastChangeId | CR-YYYYMMDD-NNN | 清单最新记录相同 | 不一致阻止交付 |
| API 基础地址 | string | 条件必填 | 空 | 启用在线评审时配置 | HTTPS URL | 生产必须 HTTPS | 空值显示未启用，不伪造可用 |
5.4.3 交互说明
| 场景 | Ant Design / ProComponents 组件 | 触发动作 | 前端交互 | 后端逻辑 | 错误处理 |
|---|
| 初次加载 | Skeleton、Spin | 打开 | 保持布局稳定 | 并行加载静态标注和在线意见 | 任何单项失败分区反馈 |
| 无标注 | Empty、Alert | 筛选或清单为空 | 区分“筛选无结果”和“未配置” | 不涉及 | 未配置视为交付异常，不显示普通空态 |
| 无权限 | Result、Tooltip | 写操作 | 隐藏或禁用并解释 | API 返回 401/403 | 不反复弹窗 |
| 部分可用 | Alert、Notification | API 失败 | 正式内容照常可读 | 记录结构化错误日志 | 提供重试，不把意见写入本地兜底 |
5.4.4 功能阐述
| 路径类型 | 步骤 | 用户动作 | 系统行为 | 用户感知 | 结果 |
|---|
| 正向 | 1 | 刷新交付 | 校验全部来源和锚点 | 返回通过清单 | 允许本地交付 |
| 异常 | 1 | 功能 ID 无锚点 | 输出明确缺失 ID | 交付命令失败 | 不产生错误分享地址 |
| 边界 | 1 | 模块无标注清单 | 使用旧交付模式 | 历史模块不受影响 | 保持向后兼容 |
5.4.5 逆向流程搭建
| 逆向场景 | 触发角色 | 触发条件 | 数据影响 | 状态回退 / 修正规则 | 限制条件 | 审计要求 |
|---|
| 关闭增强交付 | 项目维护者 | 新功能导致回归 | 移除模块 annotationManifest 配置 | 回到既有交付首页 | 不删除 PRD 或评审数据库 | Git 记录变更 |
5.4.6 功能权限清单
| 角色 | 页面权限 | 按钮权限 | 字段权限 | 数据范围 | 审批 / 二次确认 | 无权反馈 |
|---|
| 项目维护者 | 可运行检查 | 可刷新本地交付 | 可读错误清单 | 全部模块 | 发布另行授权 | 无发布授权时只输出本地结果 |
| 普通评审者 | 不可运行治理命令 | 不展示 | 不展示 | 当前分享项目 | 否 | 不暴露内部路径和堆栈 |
5.4.7 上线前历史数据处理方案
| 数据对象 | 数据来源 | 是否迁移 | 迁移 / 清洗规则 | 默认值策略 | 历史状态处理 | 回滚方案 | 验证方式 |
|---|
| 旧 delivery-publication.json | 已有业务模块 | 否 | annotationManifest 保持可选 | 无配置走旧模式 | 历史链接不变 | 回退生成器变更 | 全部现有交付测试通过 |
6. 数据与口径
| 数据项 / 指标 | 定义 | 计算口径 | 数据来源 | 刷新规则 | 权限影响 | 缺失 / 异常处理 |
|---|
| 正式标注数量 | 当前版本非 superseded 标注数 | 按 annotation ID 去重 | 静态 annotations.json | 随发布 | 全部可读 | 文件缺失不是 0，显示错误 |
| 待确认数量 | 当前版本 status=pending 的标注数 | 按标注状态统计 | 静态 annotations.json | 随发布 | 全部可读 | 显示 0 |
| 开放意见数量 | 当前版本 status=open 的评审意见数 | 按 comment ID 去重 | D1 | 实时查询 | 按分享范围可读 | API 失败显示不可用，不显示 0 |
| 锚点覆盖率 | 页面实现功能中有稳定锚点的比例 | 有锚点功能数 / 页面实现功能数 | 前端契约、原型、标注清单 | 每次交付 | 项目维护者 | 低于 100% 阻止交付 |
7. 权限、状态与异常
7.1 状态机
stateDiagram-v2
[*] --> open: 创建评审意见
open --> resolved: 解决
resolved --> open: 重开
open --> superseded: 新版本已替代
resolved --> superseded: 新版本已替代
7.2 状态与异常矩阵
| 状态 / 异常 | 触发条件 | 用户可见文案 | 可执行操作 | 数据影响 | 恢复方式 |
|---|
| 正常 | 静态标注与文档加载成功 | 显示当前版本与数量 | 阅读、筛选、定位 | 无写入 | 不适用 |
| 在线评审未配置 | reviewApi.baseUrl 为空 | 在线评审尚未启用 | 阅读正式内容 | 无 | 配置并部署 API |
| 在线评审加载失败 | API 超时或 5xx | 在线评审暂不可用，正式需求仍可查看 | 重试 | 不写本地兜底 | 恢复 API 后重试 |
| 无写权限 | 401/403 | 没有评审意见写入权限 | 继续只读 | 无 | 获取权限后重试 |
| 版本冲突 | revision 不匹配 | 该意见已被其他人更新，请刷新后重试 | 刷新 | 不覆盖 | 读取最新 revision |
| 锚点缺失 | anchorId 不存在 | 该需求未找到页面位置 | 查看逻辑文档 | 交付前应阻断 | 修正原型或清单 |
8. 前端功能限制
| 限制 ID | 限制内容 | 适用页面 / 功能 | 触发条件 | 前端处理 | 后端兜底 |
|---|
| FL-001 | 正式标注不得写入 localStorage 或 sessionStorage | 全部共享页面 | 任意读取与筛选 | 只从发布 JSON 读取 | 不涉及 |
| FL-002 | 评审正文 1–2000 字符 | 意见表单 | 输入 | 实时计数和校验 | 再次校验 |
| FL-003 | 一次只突出一个标注 | 原型与标注 | 点击 | 清除上一高亮 | 不涉及 |
| FL-004 | 标注层关闭后不得拦截业务原型点击 | 原型与标注 | 关闭 | 卸载点位和面板交互层 | 不涉及 |
| FL-005 | API 未配置时不得假装保存成功 | 在线评审 | 提交 | 禁用提交并说明 | 无地址不接受请求 |
| FL-006 | 生产 API 必须 HTTPS 且限制允许来源 | 在线评审 | 发布 | 拒绝非 HTTPS 配置 | CORS 白名单 |
| FL-007 | 正式标注正文不得复制完整 PRD | 标注卡片 | 生成 | 只展示摘要、要点和来源 | 生成检查长度 |
9. 业务验收标准
| Scenario | Given 前置条件 | When 触发动作 | Then 预期结果 | And 附加预期 |
|---|
| S-001 共享读取 | 已生成增强交付 | 在第二浏览器或无痕窗口打开同一 URL | 标注数量、内容、版本一致 | 清空本地存储不影响结果 |
| S-002 双向定位 | 标注存在有效锚点 | 点击标注卡片 | 原型滚动并高亮对应区域 | 点击数字点展开同一说明 |
| S-003 逻辑文档 | 需求无页面锚点 | 打开逻辑文档并点击来源 | 定位对应 HTML 章节 | 不要求伪造页面标注 |
| S-004 服务端保存 | API 可用且用户有写权限 | 提交合法意见 | D1 保存并返回 revision=1 | 第二浏览器可读取同一意见 |
| S-005 无写权限 | 用户无写权限 | 尝试提交 | 返回 401/403 且界面说明原因 | 数据库无新增记录 |
| S-006 并发冲突 | 两个客户端持有相同 revision | 后提交者更新状态 | 返回 409 | 不覆盖先提交结果 |
| S-007 锚点门禁 | 清单引用不存在锚点 | 运行交付检查 | 命令失败并列出 annotationId、requirementId、anchorId | 不生成可宣称完成的交付 |
| S-008 历史兼容 | 旧模块没有 annotationManifest | 运行整站交付测试 | 继续生成原有交付目录 | 旧 URL 和文档不丢失 |
10. 风险与未决问题
| 类型 | 问题 / 风险 | 影响范围 | 阻塞程度 | 当前策略 | 责任方 | 期望处理时间 |
|---|
| 部分验收通过 | 复用已发布的“「小汪智能助理」”企业内部应用、Contact.User.Read 与 HTTPS 回调 | 权限、发布 | 员工扫码、写入和跨浏览器回读已通过；非本企业账号与发布者会话仍待验收 | 权限、回调、Worker、Secrets、亚太 D1 和增强交付页已上线 | Freddy、项目维护者 | 发布者与非本企业账号专项验收时 |
| 风险 | VPN、家庭网络与移动办公导致出口 IP 和链路变化 | 登录、评审写入 | 高 | 钉钉应用不启用固定 IP 白名单；回调与评审 API 使用公网 HTTPS；GET 弱网自动重试一次，写请求不自动重放；失败明确提示未保存并在本页保留草稿 | Worker、交付页 | 持续 |
| 风险 | 发布者免登录链接属于短期 bearer credential，被转发可能导致冒用 | 权限、审计 | 高 | 一次性 nonce、短有效期、绑定项目版本、换取页面内存会话后立即失效 | 发布流程、Worker | 持续 |
| 风险 | 原型结构变更导致锚点消失 | 原型、交付 | 高 | 使用功能 ID 并加入交付门禁 | 前端、产品 | 每次交付 |
| 风险 | 正式标注与 PRD 重复维护 | 产品、数据 | 高 | 标注清单只保存摘要、锚点和 sourceRef，不承载唯一业务事实 | 产品、生成器 | 持续 |
| 风险 | 在线意见被误当成已确认需求 | 产品、开发 | 高 | 意见默认 open，确认后必须回写 PRD 并重新发布 | 产品负责人 | 持续 |
| 风险 | API 失败诱导用户以为意见已保存 | 交互、数据 | 高 | 失败保留当前表单内容但不做本地持久化，明确提示未保存 | 前端 | 持续 |
11. 全局一致性锚点
| 类别 | 内容 | 来源 / 引用 | 当前状态 |
|---|
| 术语表 | 正式标注=随版本发布的只读需求索引；评审意见=服务端保存但尚未成为正式需求；逻辑文档=由权威 Markdown 生成的 HTML 阅读视图 | 用户确认、PRD §5 | 已确认 |
| 目标与指标 | 跨设备一致、页面功能 100% 锚点覆盖、0 版本串场、0 本地共享数据依赖 | PRD §1.3、§3.3 | 已确认 |
| 范围边界 | 做未来需求、共享外壳、标注、HTML 文档、服务端意见和门禁；不迁移历史、不在线编辑 PRD、不擅自发布 | PRD §4 | 已确认 |
| 关键约束 | PRD 权威；业务原型纯净；评审写入鉴权；生产 API HTTPS；发布独立授权 | PRD §8、§10 | 已确认，Access 选型待发布前决定 |
| 已确认决策 Decision Log | 2026-08-24：采用方案 B；只覆盖未来；PRD 继续作为权威源；功能完成后再由 V2-00 接入验收 | 用户确认 / CR-20260824-001 | 已确认 |
| 已确认决策 Decision Log | 2026-08-24：标注工具不得影响原型交互；默认纯净操作，主动查看时再显示标注 | 用户确认 / CR-20260824-002 | 已确认 |
| 已确认决策 Decision Log | 2026-08-24：员工通过钉钉扫码登录后评论、回复；发布者不重复登录，但通过服务端发布会话验证身份 | 用户确认 / CR-20260824-002 | 已确认 |
| 已确认决策 Decision Log | 2026-08-24：钉钉登录复用已发布的“「小汪智能助理」”企业内部应用，不再新建独立评审应用 | 用户确认 / CR-20260824-003 | 已确认；线上权限、回调与真实员工联调已完成 |
| 已核验事实 | 钉钉 OAuth 授权支持 scope=openid corpid；用户 token 响应含 corpId；个人信息接口返回 nick/openId/unionId 且需要 Contact.User.Read | 钉钉开放平台官方文档 / CR-20260824-003 | 已核验 |
| 已确认实现 | Worker、亚太 D1、Secrets、Contact.User.Read、钉钉 HTTPS 回调与增强交付页已上线；会话使用页面内存 bearer 兼容移动端跨站 Cookie 限制 | 用户“替我完成” / CR-20260824-003 | 真实企业员工扫码、评论写入及未登录第二浏览器回读已通过；发布者回复与非本企业账号拒绝待验收 |
11.1 文档维护规则
| 规则 | 要求 |
|---|
| 后续修改 | 任何业务、交互、数据、权限或验收变化同步本 PRD、前端契约、标注清单和全局一致性锚点。 |
| 阶段推进 | 当前已获“开始搭建”授权；本地完成后单独报告发布与 V2-00 接入条件。 |
| 规格同步 | 标注展示、文档页签、评审意见状态或错误反馈变化必须同步前端契约。 |
| 知识沉淀 | 用户已确认的平台交付原则写入项目工作流；不把未确认 Access 选型写成长期事实。 |