dev_harness/docs/09-product-requirements-overview.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Product-Requirements-Overview wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Product-Requirements-Overview.- wiki_revision: 60a169e4e8e3c396c4c4c35544be48a17548d19c synchronized_at: 2026-09-02T02:14:07Z

产品需求总览

本页用途

本页是产品需求的统一导航入口，帮助项目负责人、Agent 和初级维护者快速回答：项目有哪些长期需求、当前状态是什么、详细规则和实施证据在哪里。

本页只保存稳定摘要、状态和链接，不复制完整工单、主题文档或聊天内容。需求详情仍在对应事实来源维护，避免形成两份不一致的正式需求。

事实来源边界

信息	唯一事实来源	本页怎样记录
项目目标、用户、范围和技术基线	Project-Profile	链接和一句话摘要
长期功能需求、业务规则和系统边界	对应 Wiki 主题页	需求领域和详情链接
单次实现范围、变化和验收标准	Gitea 单元任务工单	工单编号和当前状态
单次任务方案、实现、测试、遗留问题和验收	Gitea 单元任务工单	工单链接；专项 Wiki 快照仅按需附加
与版本绑定的原型、设计图或交互稿	Git 中的 design/ 或 prototypes/	路径、版本和确认状态
外部原型	原型平台	链接、版本或确认日期；重要版本保留可追溯快照

不保存完整聊天记录、Agent 内部推理、密码、令牌、个人数据或生产数据。

当前需求索引

需求领域	用户与场景	状态	版本 / MVP	详细说明	实施工单	原型	验收入口
文档事实来源与需求追溯	负责人和 Agent 需要从需求到实现、验收可追溯且不重复归档	已交付	模板核心	开发工作流	#1、#10、#14、#20、#25、#26	无（流程文档）	#25、#26、迁移边界快照；旧 Wiki 归档保留为历史证据
初级维护者文档	初级程序员需要理解项目并处理简单修改	已交付	模板核心	项目档案、代码地图、常见修改	#2、#3	无（流程文档）	#2 归档、#3 归档
Agent 范围、效率和 Claude 协作	Agent 按确认范围实施并选择合适模型	已交付	模板核心	开发工作流、仓库 AGENTS.md 和 CLAUDE.md	#4–#9、#19、#21、#27	无（流程文档）	对应 Task-4 至 Task-9 Wiki 归档；#19 归档、#21 归档、#27
交付文档	其他岗位和客户需要与版本匹配的使用、部署或支持说明	已交付	模板核心	交付文档指南、岗位文档模板	#11	无（文档模板）	#11 归档
已有项目和多交付单元接入	维护者需要在保留历史和项目规则的前提下接入 DevHarness	已交付	模板核心	已有项目接入指南	#12、#13	无（流程文档）	#12 归档、#13 归档
建设基线与后续升级	新项目和已有项目需要选择、记录并升级可复现的 DevHarness 或开源基线	已交付	模板核心	新项目文档初始化、已有项目接入指南	#15、#16	无（流程文档）	#15 归档、#16 归档
产品需求与原型索引	负责人、Agent 和初级维护者需要从一个入口找到需求和证据	已交付	模板核心	本页	#18	无（当前任务没有产品界面）	#18 归档
服务部署文档	有常驻服务的项目需要可复现的部署、运维和回滚说明	已交付	模板核心	部署文档模板	#24	无（文档模板）	#24 归档

基础设施迁移、一次性排错和普通小缺陷不作为长期产品需求单独占一行；只有它们改变长期能力、边界或使用方式时，才更新对应需求领域。

登记规则

每一行代表一项长期需求或稳定需求领域，不代表一个普通 Bug。至少填写：

• 清楚、稳定的需求名称；
• 谁在什么场景下需要它；
• 当前状态和所属版本、MVP 或发布范围；
• 唯一的详细 Wiki 页面；
• 当前或主要实施工单；
• 原型状态或明确写“无”；
• 已交付时的 Gitea 工单验收入口。

需求正文、接口细节、业务规则和验收标准只在各自事实来源修改。本页使用一至两句话摘要并链接过去，不复制大段内容。

原型与设计资产

原型门禁

先选择最低成本、足以确认需求的设计证据：

修改类型	轻量模式	最低设计证据
文案、局部样式或布局、复用现有规范的组件调整	可直接实施	现有界面、一句话或按需标注截图；不制作完整原型
预期行为明确的小 Bug	可直接实施	复现步骤、原设计或已有验收证据
不改变接口、数据结构、权限和安全边界的单模块低风险调整	可直接实施	明确目标和最小验证方法
完整独立需求、新页面或跨模块功能	建单	先用文字确认；有明显交互不确定性、返工成本显著或用户要求时才制作可审阅原型
API、数据结构、权限、安全、迁移或其他中高风险任务	建单并按风险升级	必要的架构、数据、权限、状态、回退或验证设计；不强制无意义的 UI 原型

标准模式对新功能、缺陷修复、重构和用户可感知行为变化建单；新页面、独立用户功能和重大交互使用可审阅原型。高风险模式的正式行为变化必须建单并等待人工确认。

原型只在足以降低真实不确定性时建立。已确认设计发生影响页面结构、主要流程、状态、权限、异常处理或验收结果的变化时才重新确认；轻量直接实施项一旦扩展为完整需求或中高风险变化，先建单再继续。

线上原型与按需 HTML 快照

需要完整原型的新页面、独立用户功能、重大交互或导航变化，默认直接通过 Quant-UX 或等效设计工具的线上版本审核。可编辑设计源仍以原设计工具为准，工单记录可访问链接、版本/revision、复制版本或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围。

线上链接无法访问或无法区分审核版本时停止审核，等待用户确认等效方案；不能为了节省时间把不稳定链接直接当作已确认原型。页面结构、流程、状态、权限、异常处理或验收结果变化时更新线上版本并重新确认。

只有用户明确要求 导出原型 #N、导出全部原型，或项目专用规则要求离线交付时，才把确认版本导出到 prototypes/<工单号>/<版本>/index.html。资源使用相对路径，导出后检查入口、主要交互和资源完整性；已确认快照不得原位覆盖，新版本使用新目录。导出不自动提交，也不顺带扩大到未请求的原型。

设计工具无法生成用户明确要求的可用 HTML 时，工单记录限制并停止该导出或离线交付，等待用户确认等效方案；只要线上原型仍可访问且版本明确，不因此阻塞线上审核。已有本地快照继续作为历史审核证据，不反向替代可编辑设计源。

原型确认记录

原型或替代设计证据至少记录线上链接、访问检查、版本/revision、复制版本或确认日期、审核版本识别方式、状态、确认人、确认时间和覆盖范围。只有显式导出时才记录本地路径、版本和资源检查结果。没有 UI 原型时，记录采用的技术设计或无需原型的原因。

• 与代码版本绑定的图片、HTML 交互稿和设计源文件放入 Git 的 design/ 或 prototypes/，不要手工放入 Wiki 镜像目录 docs/。
• 外部 Quant-UX、Figma 等原型记录可访问链接、审核版本识别方式、负责人和适用需求；只有用户或项目专用规则明确要求时才保存本地快照。
• 原型必须标记“草稿、已确认、已废弃”之一。草稿不能作为正式实现依据；已废弃原型保留状态和替代入口，不让 Agent 误用。
• 原型只表达界面和交互意图，不能代替文字业务规则、安全边界、异常处理和验收标准。
• 没有原型时写“无”和原因，不创建空图片、空目录或占位原型。
• 原型包含账号、个人信息或生产数据时必须先脱敏；凭据不得进入原型或截图。

状态规则

需求状态使用：待确认、已确认、开发中、待验收、已交付、已停止。

• 方案未确认时为“待确认”；用户确认后才能进入“已确认”。
• 开始执行单元任务后为“开发中”；实现完成并等待用户确认时为“待验收”。
• 用户明确验收后改为“已交付”。
• 需求取消或被替代时改为“已停止”，并链接原因和替代需求，不删除历史记录。
• 一个需求领域包含多个任务时，以尚未完成的关键任务决定状态，并在状态中简短说明。

更新时机

以下情况必须更新本页：

1. 用户确认新的长期产品需求或新需求领域；
2. 需求进入开发、待验收、已交付或已停止；
3. 需求的正式 Wiki、主要工单、原型或验收入口变化；
4. 原型从草稿变为已确认或已废弃；
5. MVP、版本范围或用户场景发生变化。

普通内部重构、小缺陷和不改变长期能力的任务只保留在工单，不必进入本页。

最小验收清单

• 新成员能从本页找到每项长期需求的详细说明。
• 状态与相关 Gitea 工单一致。
• 每项已交付需求具有验收入口。
• 原型具有路径或链接、版本和确认状态，或者明确写“无”。
• 本页没有复制完整工单或主题文档。
• 草稿原型没有被描述为正式需求。
• 不包含凭据、个人数据或生产数据。