diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py index c7e0793..36f5fa9 100644 --- a/dev_scripts/check_harness.py +++ b/dev_scripts/check_harness.py @@ -27,6 +27,9 @@ CORE_PAGE_PATHS = { "Existing-Project-Adoption-Guide": ( "docs/08-existing-project-adoption.md" ), + "Product-Requirements-Overview": ( + "docs/09-product-requirements-overview.md" + ), "Delivery-Documentation-Guide": "docs/delivery/README.md", "Audience-Document-Template": ( "docs/delivery/audience-document-template.md" @@ -91,6 +94,7 @@ CORE_DOCUMENT_REQUIREMENTS = { ), "docs/07-new-project-documentation-setup.md": ( "## 初始化顺序", + "#### 需求总览启用条件", "### 2. 选择建设基线", "#### 判断案例", "### 3. 识别子项目与交付单元", @@ -116,6 +120,16 @@ CORE_DOCUMENT_REQUIREMENTS = { "## 最小验收清单", "## 回退原则", ), + "docs/09-product-requirements-overview.md": ( + "## 本页用途", + "## 事实来源边界", + "## 当前需求索引", + "## 登记规则", + "## 原型与设计资产", + "## 状态规则", + "## 更新时机", + "## 最小验收清单", + ), "docs/delivery/README.md": ( "## 什么时候需要交付文档", "## 受众与文档选择", diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index 657ff59..d58800e 100644 --- a/docs/00-project-profile.md +++ b/docs/00-project-profile.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Project-Profile.- -wiki_revision: 33232aab59d7106c73a5d573054b82ce2db184eb -synchronized_at: 2026-08-16T12:34:06Z +wiki_revision: ad8b8d6e893e426fdfd6c11ee9d5ff7e1dfb5f80 +synchronized_at: 2026-08-17T01:57:47Z # 项目档案 @@ -61,6 +61,7 @@ synchronized_at: 2026-08-16T12:34:06Z ## 阅读入口 - 新人入口:Home。 +- 产品需求入口:[产品需求总览](Product-Requirements-Overview.-)。 - 代码入口:[架构与代码地图](Architecture-and-Code-Map.-)。 - 业务边界:[业务规则与术语](Business-Rules-and-Glossary.-)。 - 运行验证:[本地开发与验证](Local-Development-and-Verification.-)。 diff --git a/docs/07-new-project-documentation-setup.md b/docs/07-new-project-documentation-setup.md index b984da4..31a9117 100644 --- a/docs/07-new-project-documentation-setup.md +++ b/docs/07-new-project-documentation-setup.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件) wiki_page: New-Project-Documentation-Setup wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/New-Project-Documentation-Setup.- -wiki_revision: 864d81b515b420d17fa4ff0fc7f528109b1a3d99 -synchronized_at: 2026-08-16T11:38:04Z +wiki_revision: 8c70a393a0537b94091224d00363fc61edadb1b6 +synchronized_at: 2026-08-17T01:58:11Z # 新项目文档初始化 @@ -26,6 +26,10 @@ synchronized_at: 2026-08-16T11:38:04Z 把项目专用红线写入根目录或子目录 `AGENTS.md`。 +#### 需求总览启用条件 + +从模板创建项目时保留 Product-Requirements-Overview 这一核心页面。仅有探索性想法时可以只记录已确认目标和待确认项;形成 MVP、长期需求超过少量工单或开始制作原型时,必须建立并持续维护需求索引,把需求领域、状态、主题 Wiki、工单、原型和验收入口关联起来。不要复制完整工单或聊天记录。 + ### 2. 选择建设基线 确定技术方案前,优先评估是否存在功能和架构匹配、持续维护、许可证兼容且工程流程完善的开源项目。这里要求的是“先评估”,不是强制采用开源项目,也不能只根据知名度、Star 数量或演示效果决定。 @@ -139,15 +143,16 @@ Agent 只读检查: 1. Home; 2. Project-Profile; -3. Architecture-and-Code-Map; -4. Business-Rules-and-Glossary; -5. Local-Development-and-Verification; -6. Common-Changes; -7. Troubleshooting; -8. Development-Workflow; -9. Delivery-Documentation-Guide; -10. Audience-Document-Template; -11. Task-Archive-Template。 +3. Product-Requirements-Overview; +4. Architecture-and-Code-Map; +5. Business-Rules-and-Glossary; +6. Local-Development-and-Verification; +7. Common-Changes; +8. Troubleshooting; +9. Development-Workflow; +10. Delivery-Documentation-Guide; +11. Audience-Document-Template; +12. Task-Archive-Template。 Home 给出建议阅读顺序;每个命令必须有预期结果;代码地图必须指出入口和测试位置。具体岗位文档仅按第 7 步确认的受众创建。 @@ -178,6 +183,7 @@ python -m unittest discover -s tests -v 初级程序员应能仅依靠 Home 和链接页面回答: - 项目解决什么问题; +- 当前有哪些长期需求、状态如何,详细规则、工单、原型和验收入口在哪里; - 怎样启动和运行测试; - 常用功能从哪个目录和入口开始读; - 一个简单修改通常要改哪里、验证什么; diff --git a/docs/09-product-requirements-overview.md b/docs/09-product-requirements-overview.md new file mode 100644 index 0000000..9def974 --- /dev/null +++ b/docs/09-product-requirements-overview.md @@ -0,0 +1,97 @@ + +generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件) +wiki_page: Product-Requirements-Overview +wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Product-Requirements-Overview.- +wiki_revision: 54b2c60c0d914c7744b0c64e627d0687eee33e71 +synchronized_at: 2026-08-17T01:58:16Z + + +# 产品需求总览 + +## 本页用途 + +本页是产品需求的统一导航入口,帮助项目负责人、Agent 和初级维护者快速回答:项目有哪些长期需求、当前状态是什么、详细规则和实施证据在哪里。 + +本页只保存稳定摘要、状态和链接,不复制完整工单、主题文档或聊天内容。需求详情仍在对应事实来源维护,避免形成两份不一致的正式需求。 + +## 事实来源边界 + +| 信息 | 唯一事实来源 | 本页怎样记录 | +|---|---|---| +| 项目目标、用户、范围和技术基线 | Project-Profile | 链接和一句话摘要 | +| 长期功能需求、业务规则和系统边界 | 对应 Wiki 主题页 | 需求领域和详情链接 | +| 单次实现范围、变化和验收标准 | Gitea 单元任务工单 | 工单编号和当前状态 | +| 已完成方案、测试和遗留问题 | Wiki 任务归档 | 验收入口 | +| 与版本绑定的原型、设计图或交互稿 | Git 中的 `design/` 或 `prototypes/` | 路径、版本和确认状态 | +| 外部原型 | 原型平台 | 链接、版本或确认日期;重要版本保留可追溯快照 | + +不保存完整聊天记录、Agent 内部推理、密码、令牌、个人数据或生产数据。 + +## 当前需求索引 + +| 需求领域 | 用户与场景 | 状态 | 版本 / MVP | 详细说明 | 实施工单 | 原型 | 验收入口 | +|---|---|---|---|---|---|---|---| +| 文档事实来源与需求追溯 | 负责人和 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 归档 | +| 交付文档 | 其他岗位和客户需要与版本匹配的使用、部署或支持说明 | 待验收 | 模板核心 | [交付文档指南](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-后续升级与基线记录) | +| 产品需求与原型索引 | 负责人、Agent 和初级维护者需要从一个入口找到需求和证据 | 进行中 | 模板核心 | 本页 | [#18](https://git.ilapage.cn/OPC/dev_harness/issues/18) | 无(当前任务没有产品界面) | #18 待验收后补充归档状态 | + +基础设施迁移、一次性排错和普通小缺陷不作为长期产品需求单独占一行;只有它们改变长期能力、边界或使用方式时,才更新对应需求领域。 + +## 登记规则 + +每一行代表一项长期需求或稳定需求领域,不代表一个普通 Bug。至少填写: + +- 清楚、稳定的需求名称; +- 谁在什么场景下需要它; +- 当前状态和所属版本、MVP 或发布范围; +- 唯一的详细 Wiki 页面; +- 当前或主要实施工单; +- 原型状态或明确写“无”; +- 已交付时的任务归档或验收入口。 + +需求正文、接口细节、业务规则和验收标准只在各自事实来源修改。本页使用一至两句话摘要并链接过去,不复制大段内容。 + +## 原型与设计资产 + +- 与代码版本绑定的图片、HTML 交互稿和设计源文件放入 Git 的 `design/` 或 `prototypes/`,不要手工放入 Wiki 镜像目录 `docs/`。 +- 外部 Figma 等原型记录可访问链接、版本或确认日期、负责人和适用需求;重要的已确认版本保留可追溯快照。 +- 原型必须标记“草稿、已确认、已废弃”之一。草稿不能作为正式实现依据;已废弃原型保留状态和替代入口,不让 Agent 误用。 +- 原型只表达界面和交互意图,不能代替文字业务规则、安全边界、异常处理和验收标准。 +- 没有原型时写“无”和原因,不创建空图片、空目录或占位原型。 +- 原型包含账号、个人信息或生产数据时必须先脱敏;凭据不得进入原型或截图。 + +## 状态规则 + +需求状态使用:待确认、已确认、开发中、待验收、已交付、已停止。 + +- 方案未确认时为“待确认”;用户确认后才能进入“已确认”。 +- 开始执行单元任务后为“开发中”;实现完成并等待用户确认时为“待验收”。 +- 用户明确验收后改为“已交付”。 +- 需求取消或被替代时改为“已停止”,并链接原因和替代需求,不删除历史记录。 +- 一个需求领域包含多个任务时,以尚未完成的关键任务决定状态,并在状态中简短说明。 + +## 更新时机 + +以下情况必须更新本页: + +1. 用户确认新的长期产品需求或新需求领域; +2. 需求进入开发、待验收、已交付或已停止; +3. 需求的正式 Wiki、主要工单、原型或验收入口变化; +4. 原型从草稿变为已确认或已废弃; +5. MVP、版本范围或用户场景发生变化。 + +普通内部重构、小缺陷和不改变长期能力的任务只保留在工单,不必进入本页。 + +## 最小验收清单 + +- [ ] 新成员能从本页找到每项长期需求的详细说明。 +- [ ] 状态与相关 Gitea 工单一致。 +- [ ] 每项已交付需求具有验收入口。 +- [ ] 原型具有路径或链接、版本和确认状态,或者明确写“无”。 +- [ ] 本页没有复制完整工单或主题文档。 +- [ ] 草稿原型没有被描述为正式需求。 +- [ ] 不包含凭据、个人数据或生产数据。 diff --git a/docs/README.md b/docs/README.md index 9dd69ba..135c0da 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件) wiki_page: Home wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Home -wiki_revision: c1c1f27f33bd8d413787921e6a04b9ea32d80286 -synchronized_at: 2026-08-16T12:37:05Z +wiki_revision: a71a7309c9298b63946d5b784322659171c2e984 +synchronized_at: 2026-08-17T01:57:45Z # DevHarness 文档中心 @@ -15,12 +15,13 @@ DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期 建议按以下顺序,用 10~20 分钟建立整体认识: 1. [项目档案](Project-Profile.-):项目目标、环境、命令和目录边界。 -2. [架构与代码地图](Architecture-and-Code-Map.-):功能从哪里开始读、测试在哪里。 -3. [业务规则与术语](Business-Rules-and-Glossary.-):重要名词、状态和不能破坏的规则。 -4. [本地开发与验证](Local-Development-and-Verification.-):怎样运行、测试和排错。 -5. [常见修改指南](Common-Changes.-):简单修改的步骤和停止条件。 -6. [故障排查](Troubleshooting):遇到错误时按什么顺序检查。 -7. [开发工作流](Development-Workflow.-):完整建单、实施、验收和归档流程。 +2. [产品需求总览](Product-Requirements-Overview.-):长期需求、状态、原型和验收入口。 +3. [架构与代码地图](Architecture-and-Code-Map.-):功能从哪里开始读、测试在哪里。 +4. [业务规则与术语](Business-Rules-and-Glossary.-):重要名词、状态和不能破坏的规则。 +5. [本地开发与验证](Local-Development-and-Verification.-):怎样运行、测试和排错。 +6. [常见修改指南](Common-Changes.-):简单修改的步骤和停止条件。 +7. [故障排查](Troubleshooting):遇到错误时按什么顺序检查。 +8. [开发工作流](Development-Workflow.-):完整建单、实施、验收和归档流程。 从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-);向已有项目增量接入本流程时阅读[已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)。需要为客户或其他岗位准备说明时,阅读[交付文档指南](Delivery-Documentation-Guide.-),再按需使用[岗位文档模板](Audience-Document-Template.-)。 @@ -49,6 +50,7 @@ python dev_scripts/sync_wiki_docs.py --check | 想做什么 | 先读哪里 | 主要验证 | |---|---|---| | 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 | +| 查看或更新产品需求 | Product-Requirements-Overview、对应主题 Wiki 和工单 | 状态、链接和事实来源核对 | | 接入已有项目 | Existing-Project-Adoption-Guide | 只读盘点、差异确认和分阶段验证 | | 准备交付文档 | Delivery-Documentation-Guide、Audience-Document-Template | 目标岗位验证和 Wiki 同步检查 | | 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 | @@ -63,6 +65,7 @@ python dev_scripts/sync_wiki_docs.py --check | 信息 | 事实来源 | |---|---| | 任务状态、讨论、阻塞、验收过程 | Gitea 工单 | +| 长期产品需求的统一导航和状态 | Gitea Wiki 的 Product-Requirements-Overview | | 架构、业务规则、开发规范、操作手册、交付文档、任务归档 | Gitea Wiki | | 源码和与特定代码版本强绑定的文档 | Git 仓库 | | 核心长期文档的离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 | @@ -73,6 +76,7 @@ python dev_scripts/sync_wiki_docs.py --check ## 项目入口 - [Gitea 工单](https://git.ilapage.cn/OPC/dev_harness/issues) +- [产品需求总览](Product-Requirements-Overview.-) - [代码仓库](https://git.ilapage.cn/OPC/dev_harness) - [已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-) - [交付文档指南](Delivery-Documentation-Guide.-) diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 1eeae90..5b5928d 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -58,6 +58,17 @@ class CoreDocumentTests(unittest.TestCase): self.assertIn(path, CORE_DOCUMENT_REQUIREMENTS) self.assertIn("## 可复制 Agent 指令", CORE_DOCUMENT_REQUIREMENTS[path]) + def test_product_requirements_overview_is_core_document(self) -> None: + path = "docs/09-product-requirements-overview.md" + self.assertEqual( + CORE_PAGE_PATHS.get("Product-Requirements-Overview"), + path, + ) + required = CORE_DOCUMENT_REQUIREMENTS[path] + 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" @@ -77,6 +88,7 @@ class CoreDocumentTests(unittest.TestCase): self.assertIn("### 2. 选择建设基线", required) self.assertIn("#### 判断案例", required) self.assertIn("### 3. 识别子项目与交付单元", required) + self.assertIn("#### 需求总览启用条件", required) def test_missing_or_wrong_core_mapping_is_reported(self) -> None: errors = core_mapping_errors({"Home": "docs/wrong.md"}) diff --git a/wiki-docs.json b/wiki-docs.json index 9040467..9cbd4c4 100644 --- a/wiki-docs.json +++ b/wiki-docs.json @@ -44,6 +44,10 @@ "page": "Existing-Project-Adoption-Guide", "path": "docs/08-existing-project-adoption.md" }, + { + "page": "Product-Requirements-Overview", + "path": "docs/09-product-requirements-overview.md" + }, { "page": "Delivery-Documentation-Guide", "path": "docs/delivery/README.md"