docs: require local HTML prototype snapshots (#21)

.gitea/issue_template/task.md

@@ -59,13 +59,15 @@
 
 - 修改类型：纯显示文案 / 小范围 UI / 新组件 / 新页面或独立用户功能 / 重大交互或导航 / 非 UI / 恢复既有行为的 Bug
 - 所需设计证据：无 / 标注截图 / 低保真图 / 已确认原型 / 架构、API、数据、状态或流程设计 / 原设计或复现证据
-- 证据链接、Git 路径或事实来源：
+- 可编辑设计源链接、版本或事实来源：
+- 本地 HTML 审核快照路径和版本（不适用时说明原因）：
+- 本地浏览方式和资源完整性检查：
 - 版本、revision 或确认日期：
 - 状态：无 / 草稿 / 已确认 / 已废弃
 - 确认人、确认时间和覆盖范围：
 - 无需 UI 原型或无需任何原型的原因：
 
-<!-- 新页面、独立用户功能、重大交互或导航变化：原型和文字需求未确认前不得编写生产代码。 -->
+<!-- 新页面、独立用户功能、重大交互或导航变化：先生成 prototypes/<工单号>/<版本>/index.html 审核快照；原型和文字需求未确认前不得编写生产代码。 -->
 
 ## 文档影响
 

AGENTS.md

@@ -54,11 +54,14 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明
 
 - 纯界面显示文案只有在不改变业务含义、流程、权限、状态、接口、数据、法律/安全/支付/单位等高风险含义、国际化键、程序标识符、布局和可访问性，且没有任何不确定时，才免工单和原型；修改后执行最小界面检查。
 - 新页面、独立用户功能、重大交互或导航变化，必须先用 Quant-UX 或其他合适工具制作可审阅原型；用户确认原型、文字需求和覆盖范围后，才能建立或放行实现工单并编写生产代码。
+- 上述完整原型形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照，保存到 `prototypes/<工单号>/<版本>/index.html`；版本目录内资源使用相对路径。可编辑设计源仍在原设计工具，Git HTML 是版本化审核证据，Wiki 和工单只保存索引。
+- 已确认的 HTML 快照不得原位覆盖；页面结构、流程、状态、权限、异常处理或验收结果变化时，使用新版本目录重新导出并重新确认。提交审核前检查入口、主要交互和资源完整性，并删除凭据、账号、个人信息和生产数据。
 - 现有界面的小范围样式或布局调整使用标注截图、低保真图或明确复用的现有规范；新组件记录状态、错误和边界。两者只要不符合纯文案豁免就必须建单。
 - 后端、接口、数据处理和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计；恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。
 - 需要设计证据的工单记录链接或路径、版本/revision 或日期、状态、确认人、确认时间和覆盖范围；没有 UI 原型时记录替代技术设计或原因。
 - 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，必须更新原型或文字需求并重新确认后再继续正式编码。
 - 草稿原型可以用于讨论；写入 Git/Wiki、多人协作或单独实施时建立设计任务。草稿和经明确授权的隔离技术验证都不得直接作为生产实现。
+- 设计工具无法生成可用 HTML 时，在工单记录限制并停止审核，等待用户确认等效的本地可浏览方案；不得只保留难以访问的线上链接后直接编码。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML。
 
 ### 自然语言快捷指令
 

dev_scripts/check_harness.py

@@ -57,6 +57,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "## 工单与设计证据双门禁",
         "### 先判断是否需要工单",
         "### 再判断设计证据",
+        "### 本地 HTML 审核快照",
         "### 记录和重新确认",
         "## 面向初级维护者的修改边界",
         "## 每个任务的文档影响",
@@ -133,6 +134,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "## 登记规则",
         "## 原型与设计资产",
         "### 原型门禁",
+        "### 本地 HTML 审核快照",
         "### 原型确认记录",
         "## 状态规则",
         "## 更新时机",
@@ -264,7 +266,9 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None:
         "## 设计与原型门禁",
         "- 修改类型：纯显示文案 / 小范围 UI / 新组件 / 新页面或独立用户功能 / 重大交互或导航 / 非 UI / 恢复既有行为的 Bug",
         "- 所需设计证据：无 / 标注截图 / 低保真图 / 已确认原型 / 架构、API、数据、状态或流程设计 / 原设计或复现证据",
-        "- 证据链接、Git 路径或事实来源：",
+        "- 可编辑设计源链接、版本或事实来源：",
+        "- 本地 HTML 审核快照路径和版本（不适用时说明原因）：",
+        "- 本地浏览方式和资源完整性检查：",
         "- 版本、revision 或确认日期：",
         "- 状态：无 / 草稿 / 已确认 / 已废弃",
         "- 确认人、确认时间和覆盖范围：",
@@ -305,6 +309,8 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
         "提交只包含当前工单相关文件",
         "### 工单与设计证据双门禁",
         "新页面、独立用户功能、重大交互或导航变化",
+        "`prototypes/<工单号>/<版本>/index.html`",
+        "已确认的 HTML 快照不得原位覆盖",
         "代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案",
         "### 自然语言快捷指令",
         "`只分析`",

docs/01-workflow.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Development-Workflow
 wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Development-Workflow.-
-wiki_revision: 8483fab908adc0d5d016290776968ac7e692207a
-synchronized_at: 2026-08-17T03:24:26Z
+wiki_revision: bf6874586d026dfa70a243323f485e7fddbe68a2
+synchronized_at: 2026-08-17T06:50:32Z
 <!-- gitea-wiki-mirror:end -->
 
 # 开发工作流
@@ -57,6 +57,17 @@ Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地
 
 采用最低成本、足以让用户确认的证据，不为了形式制作高保真原型。草稿原型可以用于需求讨论；草稿需要写入 Git/Wiki、多人协作或单独实施时，应建立设计任务。草稿原型和临时技术验证都不能直接作为生产实现。
 
+### 本地 HTML 审核快照
+
+新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照：
+
+- 可编辑设计源仍保存在 Quant-UX 或原设计工具；Git 中的 HTML 只是与需求和代码版本绑定的审核证据，Wiki 和工单只保存索引与确认记录。
+- 快照放入 `prototypes/<工单号>/<版本>/index.html`；图片、样式、脚本和字体使用该版本目录内的相对路径。需要网络资源才能显示时，不得标记为可离线浏览。
+- 用户通过 `index.html` 审核；浏览器限制直接打开时，在工单记录最小本地静态服务命令和访问地址，不新增项目专用服务脚本。
+- 提交或请求审核前检查入口可打开、主要页面和交互可访问、图片和字体不缺失，并删除令牌、账号、个人信息和生产数据。
+- 页面结构、主要流程、状态、权限、异常处理或验收结果发生变化时，在新版本目录重新导出并重新确认；不得覆盖已经确认的版本。
+- 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML；仍使用双门禁表规定的最低证据。
+- 设计工具无法生成可用 HTML 时必须在工单说明限制并停止审核，由用户确认等效的本地可浏览原型方案；不得只保留难以访问的线上链接后直接编码。
 ### 记录和重新确认
 
 需要设计证据的工单必须记录：

docs/09-product-requirements-overview.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Product-Requirements-Overview
 wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Product-Requirements-Overview.-
-wiki_revision: 36af67197fae307430a7c65b489332608cbb5c98
-synchronized_at: 2026-08-17T03:33:10Z
+wiki_revision: 234c9c458f0052fb125bc4f819303a4a175101f5
+synchronized_at: 2026-08-17T06:51:06Z
 <!-- gitea-wiki-mirror:end -->
 
 # 产品需求总览
@@ -33,7 +33,7 @@ synchronized_at: 2026-08-17T03:33:10Z
 |---|---|---|---|---|---|---|---|
 | 文档事实来源与需求追溯 | 负责人和 Agent 需要从需求到实现、验收可追溯 | 已交付（Wiki 初始化门禁） | 模板核心 | [开发工作流](Development-Workflow.-) | [#1](https://git.ilapage.cn/OPC/dev_harness/issues/1)、[#10](https://git.ilapage.cn/OPC/dev_harness/issues/10)、[#14](https://git.ilapage.cn/OPC/dev_harness/issues/14)、[#20](https://git.ilapage.cn/OPC/dev_harness/issues/20) | 无（流程文档） | [#1 归档](Task-1-Wiki-文档主源)、[#10 归档](Task-10-需求记录与流转规则)、[#14 归档](Task-14-任务归档按需导出)、[#20 归档](Task-20-Gitea-Wiki首页初始化硬门禁) |
 | 初级维护者文档 | 初级程序员需要理解项目并处理简单修改 | 已交付 | 模板核心 | [项目档案](Project-Profile.-)、[代码地图](Architecture-and-Code-Map.-)、[常见修改](Common-Changes.-) | [#2](https://git.ilapage.cn/OPC/dev_harness/issues/2)、[#3](https://git.ilapage.cn/OPC/dev_harness/issues/3) | 无（流程文档） | [#2 归档](Task-2-Junior-Maintainer-Docs)、[#3 归档](Task-3-Dev-Scripts-Rename) |
-| Agent 范围、效率和 Claude 协作 | Agent 按确认范围实施并选择合适模型 | 已交付（原型门禁） | 模板核心 | [开发工作流](Development-Workflow.-)、仓库 `AGENTS.md` 和 `CLAUDE.md` | [#4](https://git.ilapage.cn/OPC/dev_harness/issues/4)–[#9](https://git.ilapage.cn/OPC/dev_harness/issues/9)、[#19](https://git.ilapage.cn/OPC/dev_harness/issues/19) | 无（流程文档） | 对应 `Task-4` 至 `Task-9` Wiki 归档；[#19 归档](Task-19-UI原型确认与文字修改双门禁) |
+| Agent 范围、效率和 Claude 协作 | Agent 按确认范围实施并选择合适模型 | 开发中（原型 HTML 快照） | 模板核心 | [开发工作流](Development-Workflow.-)、仓库 `AGENTS.md` 和 `CLAUDE.md` | [#4](https://git.ilapage.cn/OPC/dev_harness/issues/4)–[#9](https://git.ilapage.cn/OPC/dev_harness/issues/9)、[#19](https://git.ilapage.cn/OPC/dev_harness/issues/19)、[#21](https://git.ilapage.cn/OPC/dev_harness/issues/21) | 无（流程文档） | 对应 `Task-4` 至 `Task-9` Wiki 归档；[#19 归档](Task-19-UI原型确认与文字修改双门禁) |
 | 交付文档 | 其他岗位和客户需要与版本匹配的使用、部署或支持说明 | 待验收 | 模板核心 | [交付文档指南](Delivery-Documentation-Guide.-)、[岗位文档模板](Audience-Document-Template.-) | [#11](https://git.ilapage.cn/OPC/dev_harness/issues/11) | 无（文档模板） | [#11 归档](Task-11-交付文档指南与岗位文档模板) |
 | 已有项目和多交付单元接入 | 维护者需要在保留历史和项目规则的前提下接入 DevHarness | 已交付 | 模板核心 | [已有项目接入指南](Existing-Project-Adoption-Guide.-) | [#12](https://git.ilapage.cn/OPC/dev_harness/issues/12)、[#13](https://git.ilapage.cn/OPC/dev_harness/issues/13) | 无（流程文档） | [#12 归档](Task-12-已有项目接入DevHarness指南)、[#13 归档](Task-13-多子项目与独立交付单元) |
 | 建设基线与后续升级 | 新项目和已有项目需要选择、记录并升级可复现的 DevHarness 或开源基线 | 待验收（升级规范） | 模板核心 | [新项目文档初始化](New-Project-Documentation-Setup.-)、[已有项目接入指南](Existing-Project-Adoption-Guide.-) | [#15](https://git.ilapage.cn/OPC/dev_harness/issues/15)、[#16](https://git.ilapage.cn/OPC/dev_harness/issues/16) | 无（流程文档） | [#15 归档](Task-15-开源建设基线评估)、[#16 归档](Task-16-DevHarness-后续升级与基线记录) |
@@ -74,6 +74,13 @@ synchronized_at: 2026-08-17T03:33:10Z
 
 新增页面、独立用户功能、重大交互或导航变化的顺序固定为：确认文字需求 → 制作可审阅原型 → 用户确认原型和覆盖范围 → 建立或放行实现工单 → 编写生产代码。原型发生影响页面结构、主要流程、状态、权限、异常处理或验收结果的变化时，必须重新确认。
 
+### 本地 HTML 审核快照
+
+需要完整原型门禁的新页面、独立用户功能、重大交互或导航变化，在用户审核前把 Quant-UX 或等效设计源的待审核版本生成到 `prototypes/<工单号>/<版本>/index.html`。版本目录内的资源使用相对路径，快照应在本地可浏览；如果必须启动静态服务，在工单记录最小启动命令。可编辑设计源仍以原设计工具为准，Git HTML 是不可覆盖的版本化审核证据，Wiki 和工单负责索引。
+
+已确认快照不得原位覆盖。页面结构、流程、状态、权限、异常处理或验收结果变化时创建新版本目录、重新导出并重新确认。审核前检查页面、交互和资源完整性，并删除凭据、账号、个人信息和生产数据。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML。
+
+设计工具无法生成可用 HTML 时，工单记录限制并停止审核，等待用户确认等效的本地可浏览方案；不能把难以访问的线上链接直接当作已确认原型。
 ### 原型确认记录
 
 原型或替代设计证据至少记录链接/路径、版本/revision或确认日期、状态、确认人、确认时间和覆盖范围。外部原型需要保留可追溯版本；重要已确认版本按需保存快照。没有 UI 原型时，记录采用的技术设计或无需原型的原因。

tests/test_harness_docs.py

@@ -69,6 +69,7 @@ class CoreDocumentTests(unittest.TestCase):
         self.assertIn("## 当前需求索引", required)
         self.assertIn("## 原型与设计资产", required)
         self.assertIn("### 原型门禁", required)
+        self.assertIn("### 本地 HTML 审核快照", required)
         self.assertIn("### 原型确认记录", required)
         self.assertIn("## 更新时机", required)
 
@@ -77,6 +78,7 @@ class CoreDocumentTests(unittest.TestCase):
         self.assertIn("## 工单与设计证据双门禁", required)
         self.assertIn("### 先判断是否需要工单", required)
         self.assertIn("### 再判断设计证据", required)
+        self.assertIn("### 本地 HTML 审核快照", required)
         self.assertIn("### 记录和重新确认", required)
 
     def test_workflow_requires_online_wiki_initialization_gate(self) -> None:
@@ -163,7 +165,15 @@ class TaskTemplateTests(unittest.TestCase):
             check_task_template(errors, root)
         self.assertIn("单元任务模板缺少：## 设计与原型门禁", errors)
         self.assertIn(
-            "单元任务模板缺少：- 证据链接、Git 路径或事实来源：",
+            "单元任务模板缺少：- 可编辑设计源链接、版本或事实来源：",
+            errors,
+        )
+        self.assertIn(
+            "单元任务模板缺少：- 本地 HTML 审核快照路径和版本（不适用时说明原因）：",
+            errors,
+        )
+        self.assertIn(
+            "单元任务模板缺少：- 本地浏览方式和资源完整性检查：",
             errors,
         )