From 6435579e090e336833c8c7aff165052bdd581d58 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Mon, 17 Aug 2026 10:19:34 +0800 Subject: [PATCH] docs: require confirmed prototypes for major UI work (#19) --- .gitea/issue_template/task.md | 14 ++++++++ AGENTS.md | 13 ++++++- dev_scripts/check_harness.py | 17 +++++++++ docs/01-workflow.md | 46 ++++++++++++++++++++++-- docs/09-product-requirements-overview.md | 27 ++++++++++++-- tests/test_harness_docs.py | 23 ++++++++++++ 6 files changed, 134 insertions(+), 6 deletions(-) diff --git a/.gitea/issue_template/task.md b/.gitea/issue_template/task.md index 423b407..a0f21e7 100644 --- a/.gitea/issue_template/task.md +++ b/.gitea/issue_template/task.md @@ -53,6 +53,20 @@ |---|---|---|---| | | | | 是 / 否 | +## 设计与原型门禁 + + + +- 修改类型：纯显示文案 / 小范围 UI / 新组件 / 新页面或独立用户功能 / 重大交互或导航 / 非 UI / 恢复既有行为的 Bug +- 所需设计证据：无 / 标注截图 / 低保真图 / 已确认原型 / 架构、API、数据、状态或流程设计 / 原设计或复现证据 +- 证据链接、Git 路径或事实来源： +- 版本、revision 或确认日期： +- 状态：无 / 草稿 / 已确认 / 已废弃 +- 确认人、确认时间和覆盖范围： +- 无需 UI 原型或无需任何原型的原因： + + + ## 文档影响 diff --git a/AGENTS.md b/AGENTS.md index 519e403..7c97b20 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,8 +24,9 @@ - 只做格式化、导入排序或不跨文件的内部变量改名； - 补充类型标注或文档字符串且不改变行为； - 删除已经确认无人使用的死代码。 +- 只修改用户看到的界面显示文案，并且满足本文件“工单与设计证据双门禁”的全部豁免条件。 -只要涉及接口、数据库、状态、权限、安全、并发、用户界面，或者无法确定是否改变行为，就必须建工单。 +除严格符合界面显示文案豁免的修改外，只要涉及接口、数据库、状态、权限、安全、并发、用户界面，或者无法确定是否改变行为，就必须建工单。代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案，不适用豁免。 ## 3. 需求到实施 @@ -41,6 +42,16 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。 +### 工单与设计证据双门禁 + +- 纯界面显示文案只有在不改变业务含义、流程、权限、状态、接口、数据、法律/安全/支付/单位等高风险含义、国际化键、程序标识符、布局和可访问性，且没有任何不确定时，才免工单和原型；修改后执行最小界面检查。 +- 新页面、独立用户功能、重大交互或导航变化，必须先用 Quant-UX 或其他合适工具制作可审阅原型；用户确认原型、文字需求和覆盖范围后，才能建立或放行实现工单并编写生产代码。 +- 现有界面的小范围样式或布局调整使用标注截图、低保真图或明确复用的现有规范；新组件记录状态、错误和边界。两者只要不符合纯文案豁免就必须建单。 +- 后端、接口、数据处理和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计；恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。 +- 需要设计证据的工单记录链接或路径、版本/revision 或日期、状态、确认人、确认时间和覆盖范围；没有 UI 原型时记录替代技术设计或原因。 +- 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，必须更新原型或文字需求并重新确认后再继续正式编码。 +- 草稿原型可以用于讨论；写入 Git/Wiki、多人协作或单独实施时建立设计任务。草稿和经明确授权的隔离技术验证都不得直接作为生产实现。 + ### 自然语言快捷指令 快捷指令只是本工作流的自然语言别名，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收： diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py index 36f5fa9..6eab498 100644 --- a/dev_scripts/check_harness.py +++ b/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 字段和数据库字段不是显示文案", "### 自然语言快捷指令", "`只分析`", "`建工单`", diff --git a/docs/01-workflow.md b/docs/01-workflow.md index fe681ca..fb678e1 100644 --- a/docs/01-workflow.md +++ b/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 -synchronized_at: 2026-08-16T11:18:52Z +wiki_revision: 3fa437209777476101dc709444c4fe7a0015b76a +synchronized_at: 2026-08-17T02:17:54Z # 开发工作流 @@ -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. 讨论 diff --git a/docs/09-product-requirements-overview.md b/docs/09-product-requirements-overview.md index dd996f9..601816b 100644 --- a/docs/09-product-requirements-overview.md +++ b/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 -synchronized_at: 2026-08-17T02:02:46Z +wiki_revision: b0f7e4bba7678adfc58b327bd05e3631dcd7fcbd +synchronized_at: 2026-08-17T02:18:21Z # 产品需求总览 @@ -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 误用。 diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 5b5928d..4d67a1e 100644 --- a/tests/test_harness_docs.py +++ b/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)