docs: require confirmed prototypes for major UI work (#19)

.gitea/issue_template/task.md

@@ -53,6 +53,20 @@
 |---|---|---|---|
 | | | | 是 / 否 |
 
+## 设计与原型门禁
+
+<!-- 先判断是否属于纯显示文案豁免，再选择最低成本、足以确认的设计证据。 -->
+
+- 修改类型：纯显示文案 / 小范围 UI / 新组件 / 新页面或独立用户功能 / 重大交互或导航 / 非 UI / 恢复既有行为的 Bug
+- 所需设计证据：无 / 标注截图 / 低保真图 / 已确认原型 / 架构、API、数据、状态或流程设计 / 原设计或复现证据
+- 证据链接、Git 路径或事实来源：
+- 版本、revision 或确认日期：
+- 状态：无 / 草稿 / 已确认 / 已废弃
+- 确认人、确认时间和覆盖范围：
+- 无需 UI 原型或无需任何原型的原因：
+
+<!-- 新页面、独立用户功能、重大交互或导航变化：原型和文字需求未确认前不得编写生产代码。 -->
+
 ## 文档影响
 
 <!-- 至少选择一项；不影响长期文档时必须写明原因。 -->

AGENTS.md

@@ -24,8 +24,9 @@
 - 只做格式化、导入排序或不跨文件的内部变量改名；
 - 补充类型标注或文档字符串且不改变行为；
 - 删除已经确认无人使用的死代码。
+- 只修改用户看到的界面显示文案，并且满足本文件“工单与设计证据双门禁”的全部豁免条件。
 
-只要涉及接口、数据库、状态、权限、安全、并发、用户界面，或者无法确定是否改变行为，就必须建工单。
+除严格符合界面显示文案豁免的修改外，只要涉及接口、数据库、状态、权限、安全、并发、用户界面，或者无法确定是否改变行为，就必须建工单。代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案，不适用豁免。
 
 ## 3. 需求到实施
 
@@ -41,6 +42,16 @@
 
 Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。
 
+### 工单与设计证据双门禁
+
+- 纯界面显示文案只有在不改变业务含义、流程、权限、状态、接口、数据、法律/安全/支付/单位等高风险含义、国际化键、程序标识符、布局和可访问性，且没有任何不确定时，才免工单和原型；修改后执行最小界面检查。
+- 新页面、独立用户功能、重大交互或导航变化，必须先用 Quant-UX 或其他合适工具制作可审阅原型；用户确认原型、文字需求和覆盖范围后，才能建立或放行实现工单并编写生产代码。
+- 现有界面的小范围样式或布局调整使用标注截图、低保真图或明确复用的现有规范；新组件记录状态、错误和边界。两者只要不符合纯文案豁免就必须建单。
+- 后端、接口、数据处理和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计；恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。
+- 需要设计证据的工单记录链接或路径、版本/revision 或日期、状态、确认人、确认时间和覆盖范围；没有 UI 原型时记录替代技术设计或原因。
+- 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，必须更新原型或文字需求并重新确认后再继续正式编码。
+- 草稿原型可以用于讨论；写入 Git/Wiki、多人协作或单独实施时建立设计任务。草稿和经明确授权的隔离技术验证都不得直接作为生产实现。
+
 ### 自然语言快捷指令
 
 快捷指令只是本工作流的自然语言别名，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收：

dev_scripts/check_harness.py

@@ -53,6 +53,10 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "## 环境、配置与凭据",
     ),
     "docs/01-workflow.md": (
+        "## 工单与设计证据双门禁",
+        "### 先判断是否需要工单",
+        "### 再判断设计证据",
+        "### 记录和重新确认",
         "## 面向初级维护者的修改边界",
         "## 每个任务的文档影响",
         "## 需求记录与流转",
@@ -126,6 +130,8 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "## 当前需求索引",
         "## 登记规则",
         "## 原型与设计资产",
+        "### 原型门禁",
+        "### 原型确认记录",
         "## 状态规则",
         "## 更新时机",
         "## 最小验收清单",
@@ -253,6 +259,14 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None:
         "- 关键原话或脱敏摘要：",
         "## 需求变化记录",
         "| 日期 | 变化内容 | 原因 | 用户确认 |",
+        "## 设计与原型门禁",
+        "- 修改类型：纯显示文案 / 小范围 UI / 新组件 / 新页面或独立用户功能 / 重大交互或导航 / 非 UI / 恢复既有行为的 Bug",
+        "- 所需设计证据：无 / 标注截图 / 低保真图 / 已确认原型 / 架构、API、数据、状态或流程设计 / 原设计或复现证据",
+        "- 证据链接、Git 路径或事实来源：",
+        "- 版本、revision 或确认日期：",
+        "- 状态：无 / 草稿 / 已确认 / 已废弃",
+        "- 确认人、确认时间和覆盖范围：",
+        "- 无需 UI 原型或无需任何原型的原因：",
         "## 文档影响",
         "- [ ] 不影响长期文档，原因：",
         "- [ ] 更新架构与代码地图",
@@ -284,6 +298,9 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
         "用户没有明确验收通过前不得关闭",
         "长期核心文档必须先修改 Wiki",
         "提交只包含当前工单相关文件",
+        "### 工单与设计证据双门禁",
+        "新页面、独立用户功能、重大交互或导航变化",
+        "代码组件名、类名、变量、国际化键、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: 3f50238b637bc2f896ceab6caa5ab8ab1ded2a4b
+wiki_revision: 3fa437209777476101dc709444c4fe7a0015b76a
-synchronized_at: 2026-08-16T11:18:52Z
+synchronized_at: 2026-08-17T02:17:54Z
 <!-- gitea-wiki-mirror:end -->
 
 # 开发工作流
@@ -15,6 +15,48 @@ synchronized_at: 2026-08-16T11:18:52Z
 - Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
 - 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。
 
+## 工单与设计证据双门禁
+
+开始正式实现前依次判断“是否需要工单”和“需要什么设计证据”。原型确认不能代替方案、工单、安全检查或技术验证；工单存在也不能绕过原型确认。
+
+### 先判断是否需要工单
+
+只有纯界面显示文案同时满足以下全部条件时，才可以免工单、免原型：
+
+- 只修改用户看到的组件显示名称、按钮文字、标题、提示语或其他文案；
+- 不改变业务含义、操作流程、权限、状态、接口、数据和验收结果；
+- 不涉及法律条款、安全提示、支付、金额、单位或其他高风险含义；
+- 不修改国际化键、代码组件名、类名、变量、API 字段、数据库字段或其他程序标识符；
+- 不造成明显布局、截断、换行、可访问性或支持平台问题；
+- 有任何不确定时不使用豁免。
+
+豁免修改只执行与受影响界面相称的最小检查，确认文字正确且没有明显布局或可访问性问题，然后停止。只要任一条件不满足，或涉及用户行为、样式布局、交互和导航，就建立单元任务工单。
+
+### 再判断设计证据
+
+| 修改类型 | 最低设计证据 | 正式编码门禁 |
+|---|---|---|
+| 纯显示文案且满足全部豁免条件 | 无原型 | 完成最小界面检查即可 |
+| 现有界面的小范围样式或布局调整 | 标注截图或低保真线框图；没有设计不确定性时说明复用的现有规范 | 工单确认设计证据后编码 |
+| 新组件但复用现有设计体系 | 组件状态、错误和边界说明；按需提供低保真图 | 工单确认状态和复用边界后编码 |
+| 新页面、独立用户功能、重大交互或导航变化 | Quant-UX 或其他合适工具制作的可审阅原型 | 用户确认原型和文字需求后才能编写生产代码 |
+| 后端、接口、数据处理或定时任务 | 架构、API、数据、状态或流程设计 | 用户确认技术方案后编码，不制作无意义的 UI 原型 |
+| 恢复既有确认行为的 Bug | 原设计、已确认截图、复现步骤或现有验收证据 | 确认是恢复而不是改变行为后修复 |
+
+采用最低成本、足以让用户确认的证据，不为了形式制作高保真原型。草稿原型可以用于需求讨论；草稿需要写入 Git/Wiki、多人协作或单独实施时，应建立设计任务。草稿原型和临时技术验证都不能直接作为生产实现。
+
+### 记录和重新确认
+
+需要设计证据的工单必须记录：
+
+- 原型或设计的链接、Git 路径或对应事实来源；
+- 版本、revision 或确认日期；
+- 状态：无、草稿、已确认或已废弃；
+- 确认人和确认时间；
+- 本次确认覆盖的页面、组件、流程和边界；
+- 不需要 UI 原型时采用的技术设计，或无需任何原型的原因。
+
+页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新原型或文字需求并重新确认，再继续正式编码。只读技术检查可以在确认前进行；确需可行性代码验证时，必须由用户明确同意，隔离为不可进入生产的技术验证，不得悄悄扩展成正式实现。
 ## 一次任务怎样完成
 
 ### 1. 讨论

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: 560f97d976efa8699bc63fff50f469aac56e9367
+wiki_revision: b0f7e4bba7678adfc58b327bd05e3631dcd7fcbd
-synchronized_at: 2026-08-17T02:02:46Z
+synchronized_at: 2026-08-17T02:18:21Z
 <!-- gitea-wiki-mirror:end -->
 
 # 产品需求总览
@@ -33,7 +33,7 @@ synchronized_at: 2026-08-17T02:02:46Z
 |---|---|---|---|---|---|---|---|
 | 文档事实来源与需求追溯 | 负责人和 Agent 需要从需求到实现、验收可追溯 | 已交付 | 模板核心 | [开发工作流](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) | 无（流程文档） | [#1 归档](Task-1-Wiki-文档主源)、[#10 归档](Task-10-需求记录与流转规则)、[#14 归档](Task-14-任务归档按需导出) |
 | 初级维护者文档 | 初级程序员需要理解项目并处理简单修改 | 已交付 | 模板核心 | [项目档案](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) | 无（流程文档） | 对应 `Task-4` 至 `Task-9` Wiki 归档 |
+| 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 实施中 |
 | 交付文档 | 其他岗位和客户需要与版本匹配的使用、部署或支持说明 | 待验收 | 模板核心 | [交付文档指南](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-后续升级与基线记录) |
@@ -57,6 +57,27 @@ synchronized_at: 2026-08-17T02:02:46Z
 
 ## 原型与设计资产
 
+### 原型门禁
+
+先选择最低成本、足以确认需求的设计证据：
+
+| 修改类型 | 是否建单 | 原型或替代证据 |
+|---|---|---|
+| 纯界面显示文案，且不改变语义、流程、权限、状态、接口、高风险文字、国际化键、程序标识符、布局或可访问性 | 否 | 无原型，只做最小界面检查 |
+| 现有界面的小范围样式或布局调整 | 是 | 标注截图、低保真图或明确复用的现有规范 |
+| 新组件但沿用现有设计体系 | 是 | 组件状态和边界说明，按需提供低保真图 |
+| 新页面、独立用户功能、重大交互或导航变化 | 是 | Quant-UX 或其他工具制作并经用户确认的可审阅原型 |
+| 后端、接口、数据或定时任务 | 是 | 架构、API、数据、状态或流程设计，不强制 UI 原型 |
+| 恢复既有确认行为的 Bug | 是 | 原设计、截图、复现步骤或已有验收证据 |
+
+“文字豁免”只指用户看到的显示文案，不包括代码组件名、类名、变量、API 字段、数据库字段或国际化键。任何条件不明确时都要建单。
+
+新增页面、独立用户功能、重大交互或导航变化的顺序固定为：确认文字需求 → 制作可审阅原型 → 用户确认原型和覆盖范围 → 建立或放行实现工单 → 编写生产代码。原型发生影响页面结构、主要流程、状态、权限、异常处理或验收结果的变化时，必须重新确认。
+
+### 原型确认记录
+
+原型或替代设计证据至少记录链接/路径、版本/revision或确认日期、状态、确认人、确认时间和覆盖范围。外部原型需要保留可追溯版本；重要已确认版本按需保存快照。没有 UI 原型时，记录采用的技术设计或无需原型的原因。
+
 - 与代码版本绑定的图片、HTML 交互稿和设计源文件放入 Git 的 `design/` 或 `prototypes/`，不要手工放入 Wiki 镜像目录 `docs/`。
 - 外部 Figma 等原型记录可访问链接、版本或确认日期、负责人和适用需求；重要的已确认版本保留可追溯快照。
 - 原型必须标记“草稿、已确认、已废弃”之一。草稿不能作为正式实现依据；已废弃原型保留状态和替代入口，不让 Agent 误用。

tests/test_harness_docs.py

@@ -67,8 +67,17 @@ class CoreDocumentTests(unittest.TestCase):
         required = CORE_DOCUMENT_REQUIREMENTS[path]
         self.assertIn("## 当前需求索引", required)
         self.assertIn("## 原型与设计资产", required)
+        self.assertIn("### 原型门禁", required)
+        self.assertIn("### 原型确认记录", required)
         self.assertIn("## 更新时机", required)
 
+    def test_workflow_requires_ticket_and_design_evidence_gates(self) -> None:
+        required = CORE_DOCUMENT_REQUIREMENTS["docs/01-workflow.md"]
+        self.assertIn("## 工单与设计证据双门禁", required)
+        self.assertIn("### 先判断是否需要工单", required)
+        self.assertIn("### 再判断设计证据", required)
+        self.assertIn("### 记录和重新确认", required)
+
     def test_existing_project_adoption_requires_upgrade_process(self) -> None:
         required = CORE_DOCUMENT_REQUIREMENTS[
             "docs/08-existing-project-adoption.md"
@@ -135,6 +144,20 @@ class TaskTemplateTests(unittest.TestCase):
             errors,
         )
 
+    def test_task_template_requires_design_and_prototype_gate(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            template = root / ".gitea" / "issue_template" / "task.md"
+            template.parent.mkdir(parents=True)
+            template.write_text("## 基本信息\n", encoding="utf-8")
+            errors: list[str] = []
+            check_task_template(errors, root)
+        self.assertIn("单元任务模板缺少：## 设计与原型门禁", errors)
+        self.assertIn(
+            "单元任务模板缺少：- 证据链接、Git 路径或事实来源：",
+            errors,
+        )
+
     def test_task_template_requires_subproject_impact(self) -> None:
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)