pessimistcamellia/proto-note

原型变更标注层（proto-note）

在单文件 HTML 原型上叠加「研发视角变更导览」：右侧固定深色批注栏（模块勾选 + 批注卡）↔ 页面编号锚点 + canvas 连线；双向悬停/点击定位；批注卡带 SDD 深链。

安装与目录

# 个人 skill（推荐）
git clone https://github.com/pessimistcamellia/proto-note.git ~/.cursor/skills/proto-note

# 或项目内
git clone https://github.com/pessimistcamellia/proto-note.git .cursor/skills/proto-note

也可拷贝整个目录到上述路径。目录结构：

proto-note/
├── SKILL.md
├── assets/diff-annotator.js      # 标注引擎（整段内联到原型，勿改逻辑）
├── references/changeset-schema.md
├── docs/screenshots/             # README 效果图
└── scripts/deploy_github.sh      # GitHub Pages 备选部署

环境依赖

能力	工具	缺失时
技术栈/源码定位	codewiki MCP（或等价代码检索）	用线上 URL + 源码仓 + 浏览器 DOM 还原
SDD 深链	lark-cli（飞书）	手填文档 URL 与章节 blockId；非飞书则链到对应章节锚点
像素级校准	浏览器 DevTools / chrome-devtools MCP	手工打开线上页对照
部署	内网静态托管（优先）	个人 GitHub Pages（deploy_github.sh，需 gh 授权）

团队若另有前端规范 skill（如选型白名单、组件库用法），制作前按需读取；没有则以目标仓库源码与团队文档为准。

默认方案：组件库与发布优先级

按优先级执行；前序不可用时才落到下一级，最后一档为默认兜底：

1. 组件库 / 规范（优先）：使用目标线上系统真实在用的组件库与组件规范（对照源码 / DOM / 团队规范 skill），禁止无依据换库。
2. 发布地址（优先）：有内网现成静态托管（或团队约定的内网地址）时，优先发到内网。
3. 默认兜底：若拿不到真实组件库/规范，或因权限、网络、内网不可达等原因无法使用 → 组件可按通用方案自选（仍保持单文件可交互 HTML）；发布到用户个人 GitHub 仓库（Pages）。部署前须确认 gh 授权，未授权先与用户沟通，禁止未同意推私人仓。

产品铁律

1. 变更三级 + 类型：页面 / 模块 / 字段；类型区分新增、文案、枚举口径、逻辑、流程、删除，禁止笼统标「新增」。
2. 默认隐藏、模块勾选：打开时不展示标注；按 page::module 勾选；状态进 localStorage。新增模块的缺失 key 默认 true（可见），禁止用「曾关过任一开关」继承隐藏；脏状态靠升级 LS_KEY 版本清除。
3. 只联动 SDD，不展示 PRD：批注卡用 SDD文档URL#blockId。
4. 信息精简：批注栏无版本号/基线/操作说明；desc 只写结论。
5. 可点必有效：勾选模块即切视图 + 滚动 + 脉冲定位。
6. 评审态只在批注栏：正常/空态/错误态等放 demoControls；真实业务 Tab 留在业务页。
7. 输入分支给可复现示例：examples 与 fixture 一致，禁止占位假值。
8. 批注栏不挡内容：不压缩业务布局；靠 spacer 扩展 scrollWidth，水平滚动看全右侧。禁止只加 body padding-right 或改业务根宽度。
9. 组件库与规范优先真实线上：能还原则必须还原（见「默认方案」第 1 档）。同款组件库不等于还原——骨架、列集/列宽、冻结列、单元格结构、操作列布局、自定义类名与关键样式须对照线上 DOM/源码；交付前逐屏截图比对。仅在无法取得真实组件库/规范时，才允许通用组件兜底。
10. 发布优先内网，否则个人 GitHub：有内网地址优先用；不可用时发个人 GitHub Pages（见「默认方案」第 2–3 档）。
11. 「前」= 线上现状：新增写「无此页面/模块/功能/字段」；禁止写成相对上一版 demo 的差异；线上新增点不得漏标。
12. 无 UI 落点不连线：纯流程/链路 target: null，无锚点；卡片入「流程与链路 · 页面不可见」，且排在 changes 末尾。
13. 弹窗内变更：点批注卡须经 DIFF_HOOKS.locate 打开弹窗再连线；锚点/连线 z-index 高于弹窗（引擎用 9000 段）。
14. 弹窗随页面横纵滚动：批注栏开启时，弹窗容器随 (-scrollX,-scrollY) 平移（引擎已处理）；禁止锁死滚动回避。
15. 可下载物真格式：模板/回执与真实业务同格式同结构（如双 sheet 须真 .xlsx），禁止用 CSV 冒充。
16. 多端分别制作并联动：运营后台、C 端等按系统边界分 HTML；统一菜单标明「端 · 页面」；有跨页数据则模拟写入/读取/启停/异常。
17. 批注卡必须可跳转 SDD：有 SDD 时每条变更（或所在功能点）配置 sdd.section + blockId，卡片渲染深链；点击应打开对应章节，而非只写章节名。

展示层规范（引擎已内置，勿回退）

• 右侧批注栏：深海军蓝、宽 360px，可收起为浮动入口。
• 横向滚动：用 document.body.scrollWidth 测业务宽（spacer 为 absolute，不进该值）；勿先隐藏 spacer 再测。恢复滚动用 behavior:"instant"，避免与 scroll-behavior:smooth 打架。
• 锚点：文档坐标 position:absolute，钉目标左上角；禁止 fixed+滚动追帧；遮挡用 elementFromPoint 隐藏。
• 连线：平时无线；悬停/固定只画一条；固定态优先于悬停态；起点取实时 rect。
• 批注卡：编号 + 标题 + 类型·层级 + 结论 + 前/后 + SDD；可含 examples。
• 演示区：批注栏顶部 segmented control → DIFF_HOOKS.setDemoState。

技术栈还原（Step 0）

按「默认方案」执行：能还原则还原；不能则记录原因后走自由选型兜底。

1. 用户未给线上 URL → 先提醒；仍无则自行检索系统/路由/源码。
2. 用 codewiki（或源码检索）确认：框架、组件库、路由→页面文件、关键模板片段；需要时查索引新鲜度，并用线上 DOM 校准。
3. 优先用目标仓真实组件库与规范；新增控件沿用该页既有类型/尺寸/排列。同款组件库不等于还原——骨架、列集/列宽、冻结列、单元格结构、操作列布局、自定义类名须对照线上 DOM/源码。
4. 有团队规范 skill 则遵循；否则跟目标仓与文档。
5. 像素级或检索不足时：打开线上页抓挂载方式、组件类名、表格列宽/冻结列、操作列结构、自定义 computed style。
6. 产出仍为单文件 HTML；能 CDN 引入同款框架/组件库则引入。整页无法还原时，自由选用常见组件库完成可交互原型，并在交付说明中注明「未还原原因」。
7. 发布：有内网静态地址则优先上传；否则在取得用户 GitHub 授权后用 deploy_github.sh 发个人仓。

高频坑：勿给外层设超宽 min-width 撑死表格（会丢掉内部横滚与 fixed 列）；统一菜单顶栏用 position:fixed，避免宽页横滚顶栏断口。

多页面 / 多端与数据联动

1. 先列矩阵：端/系统 → 页面 → 关键状态 → 上下游数据；不同技术栈分文件，不强行合并。
2. 统一菜单：「端 · 页面」命名，当前页高亮；菜单不做变更批注。
3. 同源同目录部署，保证 localStorage 共享。
4. 共享状态 key：proto-note:<requirement-slug>:state:v1；读写后同页派发事件，跨标签听 storage。
5. URL 只带业务 ID；正文在共享状态。非同源优先改同源，否则 postMessage 且校验 origin。
6. 内置 fixture +「重置演示数据」；上下游状态与异常可复现。

工作流

0. Step 0 技术栈还原。
1. 从 PRD 提取变更清单、端/页面矩阵、输入分支与跨页数据关系 → 见 references/changeset-schema.md。
2. 取 SDD blockId，写入每条 sdd。
3. 按端制作原型；多端配菜单与共享状态并验联动。
4. 接入标注层：
   • 容器加 data-diff-page；落点补 id；实现 DIFF_HOOKS.locate / setDemoState。
   • 评审 Tab 迁入 meta.demoControls。
   • 分支写入 examples（与 fixture 一致）。
   • </body> 前内联 DIFF_CHANGESET，再整段复制最新 assets/diff-annotator.js（勿沿用过期拷贝）。
5. 部署与自检：

   • 优先内网：有现成内网静态托管则上传；对象键不覆盖则换新路径（-v2 等），以返回 URL + md5 为准。

   • 兜底 GitHub Pages：内网不可用时发个人仓。先 gh auth status；无权限则沟通并完成 gh auth login，禁止未授权推私人仓：

     bash ~/.cursor/skills/proto-note/scripts/deploy_github.sh <slug> ./index.html
     

自检清单

• 能还原时已用线上真实组件库/规范；不能还原时已注明原因并走自由选型兜底
• 发布优先内网；内网不可用时已授权后发个人 GitHub
• 与线上逐屏比对（若有线上页：列宽、冻结列、操作列、分页、顶栏）
• 初始无锚点/连线；模块未勾选；新增模块对老访客默认可见
• 勾选模块仅显示对应卡/锚点/线，并自动定位；弹窗内变更可自动开窗且线在弹窗之上
• 滚动无锚点漂移；平时无线，固定/悬停仅一条线；固定态不被 hover 抢走
• 批注栏开着可横滚看全右侧；横滚位置不因 DOM 更新弹回；弹窗随底页横纵滚动
• target:null 无锚点，卡片在「流程与链路」且靠后；「前」均为线上现状、无漏标
• 批注卡 SDD 深链可打开并定位到对应章节
• 演示态只在批注栏；examples 可复现；下载物格式正确
• 多端菜单可达；跨原型读写/刷新/跨标签/重置一致
• 收起批注栏干净；业务交互不受影响

参考

• 本仓库 README.md（效果截图、Live demo、默认方案说明）
• Live demo：https://pessimistcamellia.github.io/non-ecommerce-thirdparty-order-prototype/admin-upload.html