From 34748704999d54b8e692fcd78468fb00ec770b9b Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Mon, 10 Aug 2026 14:25:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=E6=9C=80=E5=B0=8F?= =?UTF-8?q?=E4=BA=A4=E4=BB=98=E6=96=87=E6=A1=A3=E4=BD=93=E7=B3=BB=20(#11)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/issue_template/task.md | 9 ++ dev_scripts/check_harness.py | 29 +++++++ docs/07-new-project-documentation-setup.md | 34 ++++++-- docs/README.md | 11 ++- docs/delivery/README.md | 80 +++++++++++++++++ docs/delivery/audience-document-template.md | 96 +++++++++++++++++++++ tests/test_harness_docs.py | 31 +++++++ wiki-docs.json | 8 ++ 8 files changed, 285 insertions(+), 13 deletions(-) create mode 100644 docs/delivery/README.md create mode 100644 docs/delivery/audience-document-template.md diff --git a/.gitea/issue_template/task.md b/.gitea/issue_template/task.md index e053beb..275226f 100644 --- a/.gitea/issue_template/task.md +++ b/.gitea/issue_template/task.md @@ -55,6 +55,15 @@ - [ ] 更新常见修改或故障排查 - [ ] 更新其他 Wiki 页面： +## 交付文档影响 + + + +- [ ] 无交付文档影响，原因： +- [ ] 更新已有交付文档，受众与页面： +- [ ] 新增交付文档，受众与页面： +- [ ] 需要目标岗位或客户代表验证：是 / 否；验证方式： + ## 验收标准 - [ ] diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py index 15ce16c..2240c31 100644 --- a/dev_scripts/check_harness.py +++ b/dev_scripts/check_harness.py @@ -24,6 +24,10 @@ CORE_PAGE_PATHS = { "New-Project-Documentation-Setup": ( "docs/07-new-project-documentation-setup.md" ), + "Delivery-Documentation-Guide": "docs/delivery/README.md", + "Audience-Document-Template": ( + "docs/delivery/audience-document-template.md" + ), "Task-Archive-Template": "docs/templates/task-archive.md", } CORE_DOCUMENT_REQUIREMENTS = { @@ -82,8 +86,28 @@ CORE_DOCUMENT_REQUIREMENTS = { ), "docs/07-new-project-documentation-setup.md": ( "## 初始化顺序", + "### 5. 确定交付对象和文档", "## 完成标准", ), + "docs/delivery/README.md": ( + "## 什么时候需要交付文档", + "## 受众与文档选择", + "## 内部文档与交付文档边界", + "## 编写和维护流程", + "## 最小验收清单", + ), + "docs/delivery/audience-document-template.md": ( + "## 文档信息", + "## 目的与适用范围", + "## 前置条件", + "## 操作步骤", + "## 常见错误与恢复", + "## 安全与权限", + "## 已知限制", + "## 支持与升级处理", + "## 版本记录", + "## 交付前检查", + ), } REQUIRED_FILES = ( "AGENTS.md", @@ -178,6 +202,11 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None: "- [ ] 更新架构与代码地图", "- [ ] 更新业务规则与术语", "- [ ] 更新常见修改或故障排查", + "## 交付文档影响", + "- [ ] 无交付文档影响，原因：", + "- [ ] 更新已有交付文档，受众与页面：", + "- [ ] 新增交付文档，受众与页面：", + "- [ ] 需要目标岗位或客户代表验证：是 / 否；验证方式：", ) for section in missing_sections(content, required): errors.append(f"单元任务模板缺少：{section}") diff --git a/docs/07-new-project-documentation-setup.md b/docs/07-new-project-documentation-setup.md index 79b03d4..7c487da 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: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/New-Project-Documentation-Setup.- -wiki_revision: a0eeab23a41671b5dbfc3153e872b71647ea41c7 -synchronized_at: 2026-08-08T01:16:59Z +wiki_revision: 710503a62b7a4ebd3c9d7a1a08dbd398161595d0 +synchronized_at: 2026-08-10T06:23:35Z # 新项目文档初始化 @@ -51,7 +51,19 @@ Agent 只读检查： 区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。 -### 5. 先创建线上 Wiki +### 5. 确定交付对象和文档 + +由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定： + +- 需要完成的工作； +- 所需文档类型； +- 文档可见范围； +- 适用版本、负责人和验证人； +- 不得对外披露的内部信息。 + +按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。 + +### 6. 先创建线上 Wiki 至少创建或填写： @@ -63,11 +75,13 @@ Agent 只读检查： 6. Common-Changes； 7. Troubleshooting； 8. Development-Workflow； -9. Task-Archive-Template。 +9. Delivery-Documentation-Guide； +10. Audience-Document-Template； +11. Task-Archive-Template。 -Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。 +Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 5 步确认的受众创建。 -### 6. 人工确认 +### 7. 人工确认 项目负责人至少确认： @@ -75,9 +89,10 @@ Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图 - 关键业务规则和状态； - 权限、安全和数据边界； - 真实运行、测试和部署命令； -- 哪些修改属于高风险。 +- 哪些修改属于高风险； +- 交付对象、文档可见范围和外部信息边界。 -### 7. 导出镜像并检查 +### 8. 导出镜像并检查 ```powershell python dev_scripts/sync_wiki_docs.py @@ -96,6 +111,7 @@ python -m unittest discover -s tests -v - 怎样启动和运行测试； - 常用功能从哪个目录和入口开始读； - 一个简单修改通常要改哪里、验证什么； -- 哪些情况必须停止并交给 Agent 或负责人。 +- 哪些情况必须停止并交给 Agent 或负责人； +- 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。 回答不了的问题应继续补充主题文档，而不是堆入任务归档。 diff --git a/docs/README.md b/docs/README.md index f5bcdc4..10d6520 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Home wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Home -wiki_revision: f1baf5947fe4e8f08cfc3ccc129946964fbbc3e5 -synchronized_at: 2026-08-08T01:16:46Z +wiki_revision: d7c0df9a900296850ca32296211504c5274c2b26 +synchronized_at: 2026-08-10T06:23:21Z # DevHarness 文档中心 @@ -22,7 +22,7 @@ DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期 6. [故障排查](Troubleshooting)：遇到错误时按什么顺序检查。 7. [开发工作流](Development-Workflow.-)：完整建单、实施、验收和归档流程。 -从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-)。 +从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-)。需要为客户或其他岗位准备说明时，阅读[交付文档指南](Delivery-Documentation-Guide.-)，再按需使用[岗位文档模板](Audience-Document-Template.-)。 ## 五分钟开始 @@ -49,6 +49,7 @@ python dev_scripts/sync_wiki_docs.py --check | 想做什么 | 先读哪里 | 主要验证 | |---|---|---| | 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 | +| 准备交付文档 | Delivery-Documentation-Guide、Audience-Document-Template | 目标岗位验证和 Wiki 同步检查 | | 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 | | 修改同步行为 | `dev_scripts/wiki_docs.py`、Architecture-and-Code-Map | 单元测试和真实 Wiki 检查 | | 增加结构检查 | `dev_scripts/check_harness.py` | 成功与失败测试 | @@ -61,7 +62,7 @@ python dev_scripts/sync_wiki_docs.py --check | 信息 | 事实来源 | |---|---| | 任务状态、讨论、阻塞、验收过程 | Gitea 工单 | -| 架构、业务规则、开发规范、操作手册、任务归档 | Gitea Wiki | +| 架构、业务规则、开发规范、操作手册、交付文档、任务归档 | Gitea Wiki | | 源码和与特定代码版本强绑定的文档 | Git 仓库 | | 离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 | @@ -71,6 +72,8 @@ python dev_scripts/sync_wiki_docs.py --check - [Gitea 工单](http://ilaer.eicp.net:8418/opc/dev_harness/issues) - [代码仓库](http://ilaer.eicp.net:8418/opc/dev_harness) +- [交付文档指南](Delivery-Documentation-Guide.-) +- [岗位文档模板](Audience-Document-Template.-) - [任务归档模板](Task-Archive-Template.-) ## 同步原则 diff --git a/docs/delivery/README.md b/docs/delivery/README.md new file mode 100644 index 0000000..73712be --- /dev/null +++ b/docs/delivery/README.md @@ -0,0 +1,80 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Delivery-Documentation-Guide +wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Delivery-Documentation-Guide.- +wiki_revision: d9de4f8d8abc40630069c67948ca2a5086f90e70 +synchronized_at: 2026-08-10T06:23:38Z + + +# 交付文档指南 + +## 本页用途 + +本页规定项目开发完成后，怎样为客户、最终用户和其他岗位选择、编写、验证及维护交付文档。交付文档面向实际使用产品的人，不替代开发工作流、架构说明和任务归档。 + +最小原则：先确认交付对象，只创建对方完成工作确实需要的文档，不预建空白手册。 + +## 什么时候需要交付文档 + +出现以下任一情况时，应在单元任务工单中评估并更新交付文档： + +- 新增或改变用户可见功能、操作步骤、界面、权限或限制； +- 改变安装、配置、部署、备份、恢复、监控或升级方法； +- 改变外部 API、数据格式、集成条件或兼容范围； +- 改变常见故障的识别、处理或支持方式； +- 发布新版本或交付客户验收。 + +纯内部重构只有在外部行为、操作方式、配置和支持边界均未改变时，才可选择“无交付文档影响”并说明原因。 + +## 受众与文档选择 + +| 交付对象 | 典型文档 | 需要回答的问题 | +|---|---|---| +| 最终用户 | 用户使用说明 | 怎样完成日常操作，失败后怎么办 | +| 管理员 | 管理员指南 | 怎样配置用户、权限和系统参数 | +| 运维人员 | 部署与运维指南 | 怎样安装、启停、监控、备份和恢复 | +| 客服或一线支持 | 支持与排错指南 | 怎样识别问题、收集信息和升级处理 | +| 集成人员 | 接口与集成指南 | 怎样认证、调用接口和处理兼容性 | +| 验收或项目负责人 | 发布、升级与验收说明 | 本次交付了什么，怎样验证和回退 | + +一个项目只选择实际存在的交付对象。多个岗位需要相同内容时可共享一份文档，但必须明确各自可以执行的操作和权限边界。 + +## 内部文档与交付文档边界 + +交付文档可以包含用户完成工作所需的产品地址、公开接口、配置项、操作步骤、结果、限制和支持渠道。 + +面向客户或公开的文档不得包含： + +- 内部工单链接、聊天记录、内部决策过程或任务归档； +- 内部网络地址、仓库路径、无必要的源码模块名和调试细节； +- 密码、令牌、Cookie、私钥、个人数据或生产数据； +- 未经确认的安全实现、漏洞细节或仅供内部使用的恢复手段； +- 未承诺的路线图、期限和功能。 + +交付前必须检查模板中的“可见范围”。同一主题同时存在内部版和客户版时，应分别维护并明确名称，不能依靠读者自行忽略内部内容。 + +## 编写和维护流程 + +1. 在项目初始化或需求确认时识别交付对象、可见范围和所需文档。 +2. 使用[岗位文档模板](Audience-Document-Template.-)按需创建文档，不创建没有明确读者的空页面。 +3. 单元任务在工单“交付文档影响”中选择无影响并说明原因，或列出需要更新的页面和受众。 +4. 功能、配置或流程改变时，代码与对应交付文档在同一任务中更新。 +5. 由熟悉该岗位但未参与实现的人按文档执行关键步骤；不能验证的环境和步骤必须明确标注。 +6. 发布或交付前确认适用版本、最后验证日期、负责人、已知限制和支持渠道。 +7. 长期维护仍遵循 Wiki-first：先修改 Wiki、读取确认，再导出本地 `docs/` 镜像。 + +具体项目创建的岗位文档应增加到 `wiki-docs.json` 的显式映射中。本模板自身的指南和模板镜像位于 `docs/delivery/`。 + +## 最小验收清单 + +- [ ] 文档有明确受众、适用版本、可见范围和负责人。 +- [ ] 前置条件、操作步骤和预期结果完整且可以对应。 +- [ ] 常见失败、恢复方法、安全提示和已知限制已说明。 +- [ ] 关键步骤由目标岗位视角验证，或明确记录未验证项。 +- [ ] 外部版本不含内部链接、敏感数据和无关实现细节。 +- [ ] 本次功能变化涉及的交付文档已更新并与版本一致。 +- [ ] Wiki 已读取确认，本地镜像检查一致。 + +## 不在本页解决的内容 + +开发任务怎样建单、实施和归档见[开发工作流](Development-Workflow.-)；代码结构和维护入口见[架构与代码地图](Architecture-and-Code-Map.-)。本页不规定市场宣传、合同、法务或商务承诺。 diff --git a/docs/delivery/audience-document-template.md b/docs/delivery/audience-document-template.md new file mode 100644 index 0000000..9fdd97d --- /dev/null +++ b/docs/delivery/audience-document-template.md @@ -0,0 +1,96 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Audience-Document-Template +wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Audience-Document-Template.- +wiki_revision: 7a8f38df566fe639094497c9692e0559c9c080e6 +synchronized_at: 2026-08-10T06:23:41Z + + +# 岗位文档模板 + +> 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。 + +## 文档信息 + +| 字段 | 内容 | +|---|---| +| 文档名称 | | +| 适用对象 | 最终用户 / 管理员 / 运维 / 客服 / 集成人员 / 验收人员 / 其他 | +| 适用版本 | | +| 最后验证日期 | YYYY-MM-DD | +| 负责人 | | +| 可见范围 | 内部 / 指定客户 / 公开 | +| 相关产品或模块 | | + +## 目的与适用范围 + +说明读者完成什么工作，以及本文包含和不包含什么。用岗位语言描述结果，不复制内部需求分析。 + +## 前置条件 + +- 所需权限： +- 所需环境或设备： +- 已完成的准备： +- 需要提前获得的信息： + +不得在这里填写真实密码、令牌、个人数据或生产数据。 + +## 操作步骤 + +### 任务一：<明确的操作目标> + +1. <执行动作> +2. <执行动作> +3. <执行动作> + +**预期结果**：<读者可以观察到的成功结果> + +**失败时**：<先检查什么；何时停止并联系支持> + +每个独立任务重复以上结构。命令和界面名称应与适用版本一致；危险或不可逆操作必须在执行前给出醒目警告、影响和回退条件。 + +## 常见错误与恢复 + +| 现象或错误信息 | 可能原因 | 处理步骤 | 何时升级 | +|---|---|---|---| +| | | | | + +只记录经过确认的原因和恢复方法。不要让外部读者执行内部调试、绕过权限或可能扩大损失的操作。 + +## 安全与权限 + +- 本岗位允许执行的操作： +- 明确禁止或需要审批的操作： +- 敏感信息处理规则： +- 数据、日志和截图脱敏要求： +- 删除、发布、迁移或其他高风险操作的确认要求： + +## 已知限制 + +- 支持的环境和版本： +- 当前不支持的场景： +- 兼容性限制： +- 未验证的环境或步骤： + +## 支持与升级处理 + +- 支持渠道： +- 服务时间或响应约定： +- 联系支持前需要收集的信息： +- 不得提交的信息： +- 需要升级到下一岗位或负责人的条件： + +## 版本记录 + +| 日期 | 适用版本 | 变更内容 | 验证人 | +|---|---|---|---| +| | | | | + +## 交付前检查 + +- [ ] 目标岗位能够理解术语和步骤。 +- [ ] 前置条件、步骤与预期结果一一对应。 +- [ ] 关键流程已按目标岗位视角验证。 +- [ ] 常见错误、恢复方法和升级条件清楚。 +- [ ] 没有内部工单、内部地址、敏感数据或无关源码细节。 +- [ ] 适用版本、最后验证日期、负责人和可见范围已填写。 diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index e0b16ce..9c02607 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -57,6 +57,37 @@ class TaskTemplateTests(unittest.TestCase): check_task_template(errors) self.assertEqual(errors, []) + def test_task_template_requires_delivery_document_impact(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" + "- 前置工单：无 / #编号\n" + "- 是否允许与前置工单并行：是 / 否\n" + "- 原因：\n" + "## 原始需求\n" + "- 来源：用户对话 / Gitea / 其他\n" + "- 提出时间：\n" + "- 关键原话或脱敏摘要：\n" + "## 需求变化记录\n" + "| 日期 | 变化内容 | 原因 | 用户确认 |\n" + "## 文档影响\n" + "- [ ] 不影响长期文档，原因：\n" + "- [ ] 更新架构与代码地图\n" + "- [ ] 更新业务规则与术语\n" + "- [ ] 更新常见修改或故障排查\n", + encoding="utf-8", + ) + errors: list[str] = [] + check_task_template(errors, root) + self.assertIn("单元任务模板缺少：## 交付文档影响", errors) + self.assertIn( + "单元任务模板缺少：- [ ] 无交付文档影响，原因：", + errors, + ) + def test_task_template_requires_dependency_fields(self) -> None: with tempfile.TemporaryDirectory() as directory: root = Path(directory) diff --git a/wiki-docs.json b/wiki-docs.json index 4dfec0c..1c07f3a 100644 --- a/wiki-docs.json +++ b/wiki-docs.json @@ -40,6 +40,14 @@ "page": "New-Project-Documentation-Setup", "path": "docs/07-new-project-documentation-setup.md" }, + { + "page": "Delivery-Documentation-Guide", + "path": "docs/delivery/README.md" + }, + { + "page": "Audience-Document-Template", + "path": "docs/delivery/audience-document-template.md" + }, { "page": "Task-Archive-Template", "path": "docs/templates/task-archive.md"