DLG-73 原型组件标注系统 + 公开发布集成 — UAT V1.0 → V1.1¶
日志编号：DLG-73 日期：2026-08-17 触发人：用户指令「对所有页面进行编号和页面功能组件进行编号，通过特殊事件（例如：ctrl+鼠标停留）可以显示编号+业务需求编号，然后通过这些编号，与需求文档建立关联。上述任务完成后，进行文档公开发布，前面完成的大部分文档都增加纳入发布范围，包括这份完整的原型，都可以发布页面直接操作。」 执行人：听写助手（DT） 前置条件：DLG-72 完成人机协作关系优化（PMG V9.1），UAT V1.0 全套静态 HTML 功能原型（五端 50 页）已完成（DLG-71 后续） 关联文档：PMG V9.5、UAT V1.1、UAT-MAP、UAT-PROTO
一、任务背景¶
1.1 触发场景¶
DLG-71 完成 UAT V1.0 全套静态 HTML 功能原型（五端 50 页 + 26 用例 + 11 账号）后，用户在本次会话中提出两项深化需求：
- 原型组件级标注系统：对所有页面编号 + 所有页面功能组件编号；通过 Ctrl+鼠标悬停特殊事件显示「组件编号 + 业务需求编号」；通过编号建立原型与需求文档的双向关联（在需求文档中描述功能实现的位置）。
- 公开发布集成：上述任务完成后，将业务测试目录、DIP1 文档及原型纳入公开发布范围，使原型可在发布站点直接操作。
1.2 任务目标¶
- 建立
<pageId>.<AREA>.<NN>组件编号体系，覆盖五端 50 页全部功能组件 - 实现 Ctrl+Hover Tooltip 标注交互，支持动态渲染元素
- 建立原型↔需求双向追溯：原型侧通过
data-req-ids反查需求；需求侧通过 SPEC 表格「原型位置」列反查组件 - 扩展 MkDocs 站点结构，新增 UAT 区块（13 个 slug），原型通过 iframe 嵌入发布站点
- 全部工作纳入 Git 版本控制并部署至 Cloudflare Pages
二、执行步骤 12 阶段¶
阶段 1：方案设计与基础设施 ✅¶
设计文档 .trae/documents/原型编号系统与公开发布方案.md，明确：
| 设计点 | 方案 |
|---|---|
| 页面编号 | <END>-<SHORTID>，如 OPR-DASH-01（OPR 端 DASH-01 页） |
| 组件编号 | <pageId>.<AREA>.<NN>，如 OPR-DASH-01.KPI.01 |
| AREA 枚举 | NAV / TAB / KPI / POOL / TREND / REC / TODO / FORM / LIST / DTL / BTN / ACT / FTG / CHART / CARD / STEP / MODAL / MISC |
| Ctrl+Hover 实现 | 事件委托监听 Control 键状态 + 动态 Tooltip + WV.annotate(selector, mapper) API |
| 双向映射 | pageMeta.json + reqIndex.json + 11-原型需求映射.md + SPEC「原型位置」列 |
阶段 2：标注基础设施 3 件套 ✅¶
| 文件 | 类型 | 关键内容 |
|---|---|---|
| assets/js/annotate.js | 新建 | Ctrl 键监听 + Tooltip 渲染 + WV.annotate API + 事件委托支持动态元素 |
| assets/css/common.css | 修改 | 追加 .wv-annotate-mode（虚线轮廓高亮）+ .wv-tooltip（浮层样式） |
| assets/js/data.js | 修改 | renderWebSidebar / renderPhoneTabBar 等函数为导航菜单/TabBar 自动注入 data-comp-id / data-comp-desc / data-req-ids；oprMenu / mfrMenu / wkrTabs / cstTabs / lgpTabs 所有菜单项新增 reqIds 字段 |
阶段 3：HTML 标注 50 页全量覆盖 ✅¶
采用 6 个 subagent 并行标注（按端+复杂度分组）：
| 组 | 端 | 页面数 | 组件数 | 备注 |
|---|---|---|---|---|
| 组1 | OPR 简单页 | 8 | 65 | login/admin/buildings/customers/leads 等 |
| 组2 | OPR 复杂页 | 11 | 115 | dashboard/orders-board/quotes 等含 KPI/LIST/CHART |
| 组3 | MFR 全部 | 8 | 70 | 后期重试 5 个文件（48 组件）补齐 |
| 组4 | WKR 全部 | 8 | 67 | today-orders/install-process/earnings 等 |
| 组5 | CST 全部 | 8 | 61 | home/inquiry/order-detail/review 等 |
| 组6 | LGP 6 + 入口 1 | 7 | 56 | pending/in-progress/completed/waybill-detail 等 |
| 合计 | 五端+入口 | 50 | 434 | 唯一 compId 434 个 |
阶段 4：扫描脚本与元数据生成 ✅¶
- 扫描 50 个 HTML 文件，提取
data-page-id/data-comp-id/data-comp-desc/data-req-ids - 生成 pageMeta.json（50 页 / 434 组件元数据）
- 生成 reqIndex.json（26 需求反向索引）
运行结果：
===== 扫描结果 =====
页面总数: 50
组件总数: 434
被引用需求数: 26
按端分布:
CST (客户端 App): 8 页 / 61 组件
LGP (物流端 App): 6 页 / 48 组件
MFR (生产商门户): 8 页 / 70 组件
OPR (运营后台): 19 页 / 180 组件
PORTAL (原型入口): 1 页 / 8 组件
WKR (师傅端 App): 8 页 / 67 组件
阶段 5：双向映射文档生成 ✅¶
新建 scripts/gen-prototype-mapping.js，生成 11-原型需求映射.md（90 KB）：
| 章节 | 内容 |
|---|---|
| 一、文档元数据 | 文档编号 DOC-U11 / UAT-MAP / V1.0 |
| 二、整体统计 | 50 页 / 434 组件 / 26 需求 / 25.5% 覆盖率 |
| 三、正向映射（页面→组件→需求） | 按端分组，每页列出组件清单+关联需求 |
| 四、反向映射（需求→组件→页面） | 按 SPEC 章节分组，每需求列出组件+页面 |
| 五、未覆盖需求清单 | 70 个需求未在原型标注（多为后端逻辑） |
| 六、Ctrl+Hover 使用说明 | 操作步骤 / 视觉提示 / 常见问题 |
阶段 6：SPEC 反向追溯列自动追加 ✅¶
新建 scripts/fill-spec-prototype.py V1.1：
- 读取
reqIndex.json反向索引 - 为 DIP1-SPEC 所有 §3.x 章节功能点表格追加「原型位置」列
- 修复 V1.0 中的列分隔符 bug（
append_col_to_row函数正确处理末尾|） - 74 行功能点全部追加原型组件编号（如
OPR-QSV-01.FORM.01; OPR-QSV-01.BTN.01）
阶段 7：校验工具与完整性验证 ✅¶
新建 scripts/verify-annotate.js：
===== 原型标注校验 =====
① 共发现 50 个 HTML 文件
② 校验每个 HTML 的标注完整性:
✅ 50/50 HTML 有 data-page-id
✅ 50/50 HTML 引入了 annotate.js
✅ 共 434 个唯一 compId
✅ 共 26 个被引用的 F-XXX-NNN
③ 校验 pageMeta.json / reqIndex.json:
✅ pageMeta.json: 50 页
✅ reqIndex.json: 26 需求
④ 校验需求覆盖（SPEC ↔ reqIndex）:
✅ SPEC 中包含 94 个 F-XXX-NNN
⚠️ reqIndex 中有 2 个需求不在 SPEC 中（F-OPS-015/F-SYS-002，经核查为校验脚本误报——这两个 ID 在 SPEC 范围 F-OPS-001~022 / F-SYS-001~014 内，只是 SPEC 文本使用简写形式）
ℹ️ SPEC 中有 70 个需求未在原型中标注（部分后端逻辑无前端原型，属正常）
✅ 原型覆盖率: 25.5% (24/94)
===== 汇总 =====
错误: 0
警告: 1
信息: 1
阶段 8：MkDocs 发布集成配置 ✅¶
8.1 URL 映射扩展¶
MANUAL_MAP新增 13 个 UAT slug 映射：
"docs/业务测试/README.md": "uat",
"docs/业务测试/01-测试账号清单.md": "uatacct",
"docs/业务测试/02-C端标准流程用例.md": "uatcst1",
"docs/业务测试/03-C端异常流程用例.md": "uatcst2",
"docs/业务测试/04-B2B2C本地配送用例.md": "uatloc",
"docs/业务测试/05-B2B2C跨境配送用例.md": "uatxbd",
"docs/业务测试/06-物流配送专项用例.md": "uatlgp",
"docs/业务测试/07-MFR生产商专项用例.md": "uatmfr",
"docs/业务测试/08-运营管理与派调用例.md": "uatopr",
"docs/业务测试/09-数据初始化方案.md": "uatinit",
"docs/业务测试/10-测试执行计划.md": "uatplan",
"docs/业务测试/11-原型需求映射.md": "uatmap",
"docs/业务测试/原型入口.md": "uatproto",
NAV_STRUCTURE新增「业务测试 UAT」导航区块（13 条目）
8.2 原型入口页¶
新建 docs/业务测试/原型入口.md（DOC-U12 / UAT-PROTO / V1.0）：
- 通过 iframe 嵌入静态 HTML 原型（保留 Ctrl+Hover 标注能力）
- 提供三种访问方式：iframe 内嵌 / 新窗口打开 / 按端直达
- Ctrl+Hover 使用说明 + 编号体系说明 + 常见问题 FAQ
阶段 9：AGENTS.md 版本升级 V9.4 → V9.5 ✅¶
修改 AGENTS.md：
- 顶部版本号 V9.4 → V9.5，最后更新 2026-08-18
- 文档导航表第 7 条「UAT」版本 V1.0 → V1.1，新增「V1.1 新增原型组件标注系统（Ctrl+Hover 显示组件编号+需求 ID）+ 11-原型需求映射.md 双向追溯 + MkDocs 公开发布集成」描述
- 修订记录新增 V9.5 条目（详细记录标注基础设施 / 双向追溯 / 校验工具 / MkDocs 集成 5 大模块）
阶段 10：Git 提交与站点构建 ✅¶
10.1 Git 提交¶
8ea932c—docs: V9.5 原型组件标注系统 + 公开发布集成 + DT后门 + MFR/LGP干系方（216 文件，整合 V9.1~V9.5 全部变更）d447628—fix: build-site.py 添加原型 HTML 复制到 uatproto slug 目录的后处理步骤（14 行新增）eeb480a—fix: 排除 ops/tmp/ 目录避免 APK 文件超过 Cloudflare Pages 25MB 限制（3 行新增 2 行修改）
10.2 build-site.py 修复¶
发现两个构建期问题并修复：
| 问题 | 原因 | 修复 |
|---|---|---|
| 原型 HTML 不在 uatproto slug 目录 | MkDocs 将 md 转为 site/uatproto/index.html，但原型 HTML 保留在 site/业务测试/原型/，iframe src 期望在 site/uatproto/原型/ |
步骤 10.6 新增 shutil.copytree 复制 55 个原型文件到正确位置 |
| APK 文件超过 Cloudflare Pages 25MB 限制 | ops/tmp/ 下 4 个 APK 文件各约 68.6 MiB |
EXCLUDE_PREFIXES 新增 "ops/tmp/"，非 md 文件从 103 降至 84 |
10.3 站点构建结果¶
✓ 跟踪文件: 189 md + 84 非 md (已排除 ops/private + ops/worklog + ops/deploy + ops/tmp)
✓ URL 映射表: 172 个 slug
✓ 复制 Markdown（slug 扁平化）: 190 个文件
✓ 复制非 Markdown: 84 个文件
✓ 复制原型 HTML 到 uatproto/原型/: 55 个文件（iframe 嵌入支持）
✓ 站点已构建: D:\AC\TF\hk2026\site
阶段 11：Cloudflare Pages 部署 ✅¶
用户执行 powershell -File D:\AC\TF\hk2026\scripts\deploy-site.ps1 -SkipBuild 完成部署，站点发布至 https://hk2026-docs.pages.dev。
部署后可访问的关键路径：
| 路径 | 内容 |
|---|---|
/uat/ |
UAT 目录索引 |
/uatproto/ |
功能原型入口（iframe 嵌入原型） |
/uatmap/ |
原型需求映射文档（双向追溯） |
/uatacct/ |
测试账号清单 |
/uatcst1/ /uatcst2/ |
C 端标准+异常流程用例 |
/uatloc/ /uatxbd/ |
B2B2C 本地+跨境配送用例 |
/uatlgp/ /uatmfr/ /uatopr/ |
物流/MFR/运营专项用例 |
/uatinit/ /uatplan/ |
数据初始化+测试执行计划 |
阶段 12：部署后验证 ✅¶
- ✅
site/uatproto/index.html存在，iframe src 正确指向原型/index.html - ✅
site/uatproto/原型/index.html存在（PORTAL 入口页） - ✅
site/uatproto/原型/opr-admin/login.html存在（OPR 登录页） - ✅
site/uatproto/原型/assets/js/annotate.js存在（标注脚本） - ✅
site/uatmap/index.html存在（映射文档） - ✅ 13 个 UAT 目录全部生成
- ✅ 站点中无超过 10 MiB 的文件
三、交付物清单¶
3.1 新建文档（4 份）¶
| 文档 | 编号 | 位置 |
|---|---|---|
| 原型需求映射 | UAT-MAP / DOC-U11 | docs/业务测试/11-原型需求映射.md |
| 功能原型入口 | UAT-PROTO / DOC-U12 | docs/业务测试/原型入口.md |
| 实施方案 | — | .trae/documents/原型编号系统与公开发布方案.md |
| 本工作日志 | DLG-73 | docs/工作日志/对话记录/20260817_听写助手对话记录73_原型标注系统与公开发布集成.md |
3.2 新建脚本（4 份）¶
| 脚本 | 作用 |
|---|---|
| scripts/scan-prototype.js | 扫描 HTML 生成 pageMeta.json + reqIndex.json |
| scripts/gen-prototype-mapping.js | 生成 11-原型需求映射.md 双向映射文档 |
| scripts/fill-spec-prototype.py | 为 SPEC 表格追加「原型位置」列 |
| scripts/verify-annotate.js | 校验标注完整性（0 错误） |
3.3 新建前端资源（2 份）¶
| 文件 | 作用 |
|---|---|
| docs/业务测试/原型/assets/js/annotate.js | Ctrl+Hover Tooltip 核心逻辑 + WV.annotate API |
| docs/业务测试/原型/assets/js/pageMeta.json + reqIndex.json | 元数据 JSON（运行时加载） |
3.4 修改文件（6 份）¶
| 文件 | 变更 |
|---|---|
| docs/业务测试/原型/assets/css/common.css | 追加 .wv-annotate-mode + .wv-tooltip 样式 |
| docs/业务测试/原型/assets/js/data.js | render 函数注入 data-* + menu reqIds 字段 |
| dip1/docs/DIP1-SPEC-需求规格说明书.md | 74 行功能点追加「原型位置」列 |
| scripts/build-site.py | 新增步骤 10.6 原型复制 + ops/tmp/ 排除 |
| scripts/url_map.py | 新增 13 个 UAT slug + 导航区块 |
| AGENTS.md | V9.4 → V9.5 修订记录 |
3.5 修改 HTML（50 份）¶
五端 50 页原型 HTML 全部添加：
<body data-page-id="...">页面编号<script src="../assets/js/annotate.js"></script>标注脚本引入- 组件级
data-comp-id/data-comp-desc/data-req-ids属性（共 434 个组件）
四、关键里程碑¶
- 本次完成日期：2026-08-17
- 里程碑意义：UAT 从 V1.0（原型可用）升级至 V1.1（原型可追溯+公开发布），原型与 SPEC 需求建立双向追溯链路，发布站点可直接操作原型并查看组件级需求关联，为真实用户测试提供标准化操作入口
- 下一关键节点：真实用户联调测试启动后，测试人员可通过 Ctrl+Hover 快速定位每个组件对应的需求编号，反向查询 SPEC 验收标准；测试中发现的 bug 可通过组件编号精准上报
五、后续待办¶
| 序号 | 待办 | 负责人 |
|---|---|---|
| 1 | 听码（WDE）实施听写后门功能代码（F-DT-001~006） | WDE |
| 2 | 数据库迁移脚本编写（dt_backdoor_audit 表） | WDE |
| 3 | 真实用户联调测试启动（使用 UAT V1.1 原型作为操作参考） | DT |
| 4 | 测试中发现的 bug 通过组件编号精准定位需求→代码 | DT → WDE |
| 5 | 根据测试反馈补充未覆盖需求的原型标注（当前覆盖率 25.5%） | DT |
六、Git 提交记录¶
| Commit | 类型 | 描述 | 文件数 |
|---|---|---|---|
8ea932c |
docs | V9.5 原型组件标注系统 + 公开发布集成 + DT后门 + MFR/LGP干系方 | 216 |
d447628 |
fix | build-site.py 添加原型 HTML 复制到 uatproto slug 目录的后处理步骤 | 1 |
eeb480a |
fix | 排除 ops/tmp/ 目录避免 APK 文件超过 Cloudflare Pages 25MB 限制 | 1 |
本日志记录 UAT V1.0 → V1.1 原型组件标注系统与公开发布集成的完整过程。相关文档见 PMG V9.5 / UAT V1.1 / UAT-MAP / UAT-PROTO。