PRD 需求标注到 HTML 原型图

概述

本技能将 PRD 需求文档标注到 HTML 原型图文件中，在原型上叠加一层需求标注系统，将 PRD 中的功能需求逐条映射到原型图对应的 UI 元素上，实现"点击标注→查看需求详情"的交互能力。标注系统不破坏原有原型功能，所有新增代码内联到原型 HTML 文件中。

触发条件

当出现以下情况时使用此技能：
- 用户提供 PRD 需求文档和 HTML 原型图文件，要求将需求标注到原型上
- 用户要求给已有原型图添加 PRD 需求说明
- 用户要求在原型上标注需求点，实现点击查看详情
- 用户说"把需求文档标注到原型图"、"给原型添加 PRD 标注"、"在原型上标注需求"、"PRD 标注到原型"等

输入要求

1. PRD 需求文档：HTML 格式，含功能详情章节，每个功能点有 6 个维度（功能说明、用户场景、业务规则、页面交互说明、展示字段/操作项、异常处理）
2. HTML 原型图文件：单文件，自包含，离线可运行
3. 语言要求：所有输出（标注文案、UI 文案、代码注释）均使用中文

工作流程

第一步：解析 PRD 与原型

1. 解析 PRD 文档：
   - 提取第四章「功能详情」中的所有功能点
   - 记录每个功能点的 6 个维度内容：功能说明、用户场景、业务规则、页面/交互说明、展示字段/操作项/列表筛选项、异常处理
   - 记录每个功能点的 PRD 章节编号、优先级、所属模块
2. 分析原型图文件：
   - 读取原型 HTML 文件，理解页面结构和 UI 元素
   - 识别每个 UI 元素的 CSS 选择器，用于后续锚点定位
   - 确认原型的容器结构和定位方式

第二步：建立标注映射

遍历 PRD 第四章「功能详情」的每个功能点，按以下规则映射到原型 UI 元素：

1. 元素匹配：为每个功能点识别原型图中对应的 UI 元素（通过 CSS 选择器匹配）
2. 详情提取：从 PRD 的 6 个维度中提取关键规则，浓缩为卡片详情
3. 数值保留：详情中必须包含具体数值参数（如"100ms 刷新""1.01x-100.00x"）、业务规则分支、交互状态流转
4. 合并标注：一个 UI 元素可能对应多个 PRD 章节（如按钮同时涉及"投注提交"和"手动领取"），合并为一条标注
5. 后端逻辑映射：后端逻辑模块（如状态机、随机倍率系统）无直接 UI 元素时，标注到最相关的展示区域

第三步：生成标注数据

每个标注点为 JS 对象，包含字段：

{
  id: 1,                    // 编号
  prd: 'PRD 4.1',           // PRD 章节引用
  priority: 'P0',           // 优先级 P0/P1/P2
  section: '游戏首页展示',    // 所属功能模块
  title: '顶部用户信息栏',    // 标注标题
  target: '.top-bar',       // 目标元素 CSS 选择器
  detail: '...'             // 需求详情（HTML 格式）
}

第四步：在原型中追加标注系统

在原型图 HTML 文件中追加以下组件，保持原有原型功能不变：

1. 顶部工具栏（固定定位）

• 左侧：产品名称 + PRD 版本号标签
• 右侧：「标注列表」按钮 + 「显示标注」开关（toggle）
• 高度 40px，深色背景，z-index 999
• 原型内容整体下移 40px 避让

2. 标注锚点（编号气泡）

• 每个需求点对应一个圆形编号锚点（24×24px，蓝色背景，白色数字）
• 锚点定位在对应 UI 元素的右上角（使用 CSS 选择器定位）
• 默认隐藏，开启「显示标注」开关后显示
• 点击锚点 → 自动打开标注面板并高亮对应卡片
• 激活态锚点变为橙色
• z-index 设为 60，确保不被原型内容遮挡

3. 锚点定位防遮挡逻辑（关键）

必须实现以下边界检测和防重叠算法：

• 右边界检测：锚点超出容器右边界时，自动翻转到元素左上角
• 左边界检测：锚点超出左边界时，贴左对齐
• 上边界检测：锚点超出顶部时，下移到安全区（margin 6px）
• 下边界检测：锚点超出底部时，上移到安全区
• 防重叠：多个锚点位置重叠时，自动向下偏移，最多尝试 8 次
• 定期重定位（每秒 1 次），适配动态内容变化

参考实现：

function positionPins(){
  var app = document.querySelector('.app'); // 原型主容器
  var appRect = app.getBoundingClientRect();
  var appW = app.offsetWidth;
  var appH = app.offsetHeight;
  var pinSize = 24;
  var margin = 6;
  var placed = []; // 记录已放置锚点位置，防止重叠

  annotations.forEach(function(a){
    var el = document.querySelector(a.target);
    if(!el) return;
    var rect = el.getBoundingClientRect();

    // 默认放在元素右上角
    var x = rect.left - appRect.left + rect.width - pinSize/2;
    var y = rect.top - appRect.top - pinSize/2 + 4;

    // 右边界检测：超出右侧改放左上角
    if(x + pinSize > appW - margin){
      x = rect.left - appRect.left - pinSize/2;
    }
    // 左边界检测
    if(x < margin){
      x = rect.left - appRect.left + 4;
    }
    // 下边界检测
    if(y + pinSize > appH - margin){
      y = appH - pinSize - margin;
    }
    // 上边界检测
    if(y < margin){
      y = margin;
    }
    // 防重叠：与已放置锚点距离过近时偏移
    for(var attempt=0; attempt<8; attempt++){
      var overlap = false;
      for(var k=0; k<placed.length; k++){
        var p = placed[k];
        var dx = x - p.x, dy = y - p.y;
        if(Math.abs(dx) < pinSize && Math.abs(dy) < pinSize){
          overlap = true; break;
        }
      }
      if(!overlap) break;
      y += pinSize;
      if(y + pinSize > appH - margin){ y = margin; x += pinSize; }
      if(x + pinSize > appW - margin){ x = margin; }
    }
    placed.push({x:x, y:y});

    var pin = document.getElementById('anno-pin-' + a.id);
    if(!pin){
      pin = document.createElement('div');
      pin.className = 'anno-pin';
      pin.id = 'anno-pin-' + a.id;
      pin.innerHTML = '<span>' + a.id + '</span>';
      pin.onclick = function(){
        toggleAnnoPanel();
        highlightAnno(a.id);
      };
      app.appendChild(pin);
    }
    pin.style.left = x + 'px';
    pin.style.top = y + 'px';
    pin.classList.toggle('show', annoEnabled);
  });
}

// 定期重定位，适配动态内容
setInterval(positionPins, 1000);

4. 标注侧边面板（右侧滑出）

• 宽度 360px，移动端全宽
• 面板头部：标题 + 标注总数徽标 + 关闭按钮
• 面板主体：可滚动的标注卡片列表
• 点击面板外区域或关闭按钮收起

5. 标注卡片（每个需求点一张）

每张卡片包含：

• 编号：圆形数字徽标（与锚点编号对应）
• 标题：UI 元素名称（如"投注金额输入框"）
• PRD 引用：蓝色标签，标注对应 PRD 章节（如"PRD 4.2"）
• 所属模块：灰色文字（如"投注金额"）
• 优先级标签：P0 红色 / P1 橙色 / P2 蓝色
• 需求详情：从 PRD 中提取的业务规则、交互规则、字段说明、数据参数，使用 HTML 列表和加粗排版
• 点击卡片 → 高亮对应锚点（橙色）

第五步：质量检查

生成完成后，对照以下清单检查：

• [ ] 所有标注锚点不被遮挡、不超出可视区域
• [ ] 锚点编号与面板卡片编号一一对应
• [ ] 点击锚点 → 面板自动打开并高亮卡片
• [ ] 点击卡片 → 对应锚点高亮为橙色
• [ ] 「显示标注」开关可正常切换显示/隐藏
• [ ] 原有原型功能（游戏循环、投注、领取、动画等）不受影响
• [ ] 无 JS 控制台报错
• [ ] 移动端面板全宽适配正常
• [ ] 防遮挡逻辑覆盖上下左右四个边界
• [ ] 定期重定位正常工作，动态内容变化后锚点位置正确

技术约束

• 单文件原则：所有新增 CSS 和 JS 内联到原型 HTML 文件中，不产生外部依赖
• 零网络请求：不引入任何 CDN 或外部资源
• 不破坏原有功能：原型已有的游戏逻辑、动画、交互必须保持正常
• 语义化 HTML：使用 <div> <button> 等语义标签
• 锚点 z-index 设为 60，确保不被原型内容遮挡
• 工具栏 z-index 设为 999，确保始终可见
• 面板 z-index 设为 500，确保浮于内容之上

标注映射规则

1. 遍历 PRD 第四章「功能详情」的每个功能点
2. 为每个功能点识别原型图中对应的 UI 元素（通过 CSS 选择器匹配）
3. 从 PRD 的 6 个维度中提取关键规则，浓缩为卡片详情
4. 详情中必须包含：具体数值参数（如"100ms 刷新""1.01x-100.00x"）、业务规则分支、交互状态流转
5. 一个 UI 元素可能对应多个 PRD 章节（如按钮同时涉及"投注提交"和"手动领取"），合并为一条标注
6. 后端逻辑模块（如状态机、随机倍率系统）无直接 UI 元素时，标注到最相关的展示区域

优先级标注规则

• P0：核心功能，必须有，影响主流程（红色标签）
• P1：重要功能，提升体验（橙色标签）
• P2：次要功能，可后续迭代（蓝色标签）

迭代修改指引

后续用户要求修改时：

• 标注遗漏：若用户指出某功能点未标注，补充对应标注点并重新定位锚点
• 锚点位置不对：调整 CSS 选择器或定位逻辑，确保锚点准确定位
• 详情不完整：从 PRD 中补充提取更多规则到卡片详情
• 新增页面标注：若原型新增页面，按相同规则添加标注
• 每次修改后重新执行质量检查清单

交付物

1. 追加了标注系统的完整 HTML 原型文件（单文件，自包含）

使用示例

用户：请将这份 PRD 需求文档标注到原型图文件中
助手：我先解析 PRD 的功能详情章节和原型图的 UI 结构，建立标注映射关系...

用户：给这个原型添加 PRD 标注
助手：我来读取 PRD 和原型文件，为每个功能点创建标注锚点和详情卡片...

用户：有些标注被遮挡了
助手：我检查锚点定位逻辑，调整边界检测和防重叠算法...

注意事项

1. 不得破坏原型已有的任何功能和交互
2. 所有新增代码必须内联，不产生外部依赖
3. 防遮挡逻辑是核心，必须覆盖上下左右四个边界和防重叠场景
4. 定期重定位必须启用，适配动态内容变化
5. 标注详情必须包含 PRD 中的具体数值参数，禁止模糊表述
6. 一个 UI 元素对应多个 PRD 章节时，合并为一条标注