From 4e5c30641d9bcbc69d4c235f33ff89dd47259f63 Mon Sep 17 00:00:00 2001 From: ila Date: Mon, 10 Aug 2026 14:27:45 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E6=88=90=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#11=20=E5=BD=92=E6=A1=A3=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...D%E6%96%87%E6%A1%A3%E6%A8%A1%E6%9D%BF.-.md | 62 ++++++++++++++----- 1 file changed, 46 insertions(+), 16 deletions(-) diff --git a/Task-11-%E4%BA%A4%E4%BB%98%E6%96%87%E6%A1%A3%E6%8C%87%E5%8D%97%E4%B8%8E%E5%B2%97%E4%BD%8D%E6%96%87%E6%A1%A3%E6%A8%A1%E6%9D%BF.-.md b/Task-11-%E4%BA%A4%E4%BB%98%E6%96%87%E6%A1%A3%E6%8C%87%E5%8D%97%E4%B8%8E%E5%B2%97%E4%BD%8D%E6%96%87%E6%A1%A3%E6%A8%A1%E6%9D%BF.-.md index 5d1aa9d..ac09e69 100644 --- a/Task-11-%E4%BA%A4%E4%BB%98%E6%96%87%E6%A1%A3%E6%8C%87%E5%8D%97%E4%B8%8E%E5%B2%97%E4%BD%8D%E6%96%87%E6%A1%A3%E6%A8%A1%E6%9D%BF.-.md +++ b/Task-11-%E4%BA%A4%E4%BB%98%E6%96%87%E6%A1%A3%E6%8C%87%E5%8D%97%E4%B8%8E%E5%B2%97%E4%BD%8D%E6%96%87%E6%A1%A3%E6%A8%A1%E6%9D%BF.-.md @@ -1,9 +1,9 @@ # 11 交付文档指南与岗位文档模板 -- 类型：需求 / 缺陷 / 重构 -- 所属 Epic：# -- 所属 MVP / 版本：# -- 状态：待验收 / 已完成 +- 类型：开发流程优化 +- 所属 Epic：无 +- 所属 MVP / 版本：无 +- 状态：待验收 - 日期：2026-08-10 - Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/11 - Wiki 页面：Task-11-交付文档指南与岗位文档模板 @@ -11,32 +11,62 @@ ## 背景与目标 - +DevHarness 已覆盖开发维护文档，但缺少面向客户、最终用户及其他岗位的交付文档选择、内外边界、编写和验收规则，也没有可以复用的岗位文档模板。 + +本任务以最小范围建立交付文档闭环：只增加一份指南和一份通用模板，并把交付文档影响接入工单和新项目初始化流程，不预建没有明确读者的空白手册。 ## 最终方案 - +- 新增“交付文档指南”，规定适用时机、受众与文档选择、内部与外部信息边界、编写维护流程和最小验收清单。 +- 新增“岗位文档模板”，覆盖文档受众、适用版本、最后验证日期、负责人、可见范围、目的、前置条件、操作步骤、预期结果、常见错误与恢复、安全、限制、支持渠道和版本记录。 +- 明确根据实际受众按需创建用户、管理员、运维、支持、集成或验收文档，不创建没有明确读者的空页面。 +- 单元任务模板增加“交付文档影响”，要求选择无影响并说明原因，或列出新增、更新页面及目标岗位验证方式。 +- 新项目初始化流程增加识别交付对象、可见范围、所需文档和外部信息边界的步骤。 +- Home 增加交付指南和岗位模板入口，并将交付文档纳入 Wiki 长期文档事实来源。 +- 两个新增页面显式映射到 `docs/delivery/`，Harness 将其纳入核心映射和章节检查。 +- 未生成具体岗位手册、PDF、HTML 或发布包，未增加新脚本、框架和第三方依赖。 + +实施结果与已确认方案一致。 ## 修改文件 -- `<文件>`：<改动说明> +- `.gitea/issue_template/task.md`：增加交付文档影响字段。 +- `dev_scripts/check_harness.py`：检查新增核心页面、章节和工单字段。 +- `tests/test_harness_docs.py`：验证缺少交付文档影响字段时能够报告错误。 +- `wiki-docs.json`：登记交付指南、岗位模板和本任务归档的镜像映射。 +- `docs/README.md`：Home Wiki 的只读镜像，增加交付文档入口。 +- `docs/07-new-project-documentation-setup.md`：新项目初始化 Wiki 的只读镜像。 +- `docs/delivery/README.md`：交付文档指南的只读镜像。 +- `docs/delivery/audience-document-template.md`：岗位文档模板的只读镜像。 +- `docs/task/11-交付文档指南与岗位文档模板.md`：本页的自动导出镜像。 ## 验收结果 | 验收标准 | 结果 | |---|---| -| | 通过 / 未通过 | +| 指南覆盖选择规则、内外边界、流程和验收 | 通过 | +| 岗位模板字段完整且可复用 | 通过 | +| 工单模板要求评估交付文档影响 | 通过 | +| 新项目初始化识别交付对象并按需建文档 | 通过 | +| Home 可进入新增页面 | 通过 | +| 两页镜像到 `docs/delivery/` 并可追踪 revision | 通过 | +| Harness 严格检查和单元测试 | 通过 | +| 实现提交已推送且归档单独提交 | 进行中：归档提交后回写工单 | +| 用户明确验收 | 待验收 | ## 测试 -- 执行命令：`<命令>` -- 结果： -- **未验证部分**： - -## 遗留问题 - - +- 执行命令：`python dev_scripts/check_harness.py --strict` +- 结果：通过。 +- 执行命令：`python -m unittest discover -s tests -v` +- 结果：22/22 通过。 +- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` +- 结果：归档前 22/22 映射一致；归档完成后重新检查。 +- 执行命令：`git diff --check` +- 结果：通过。 +- **未验证部分**：未创建具体产品的岗位文档，因此没有真实目标岗位或客户环境可执行验证；这属于已确认非目标，具体项目创建实际文档时必须补充目标岗位验证。 ## 相关提交 -- `<提交哈希>` <提交说明> +- `3474870` `docs: 建立最小交付文档体系 (#11)` +- 归档提交哈希在提交后回写 Gitea 工单，避免归档自引用。