OPC/dev_harness
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

建立最小交付文档指南与岗位文档模板 #11

New Issue
Closed
opened 2026-08-16 23:06:41 +08:00 by ila · 1 comment
ila commented 2026-08-16 23:06:41 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：单元任务
  • 状态：已完成
  • 所属 Epic：无
  • 所属 MVP：无

前置关系

  • 前置工单：无
  • 是否可与其他任务并行：是
  • 原因：本任务只扩展交付文档规范、模板和流程检查，不依赖未完成任务。

原始需求

  • 来源：用户与 Agent 对话
  • 记录时间：2026-08-10
  • 关键原话：“按照你的建议建工单，做”
  • 已确认上下文：在当前项目基础上做最小实现，增加“交付文档指南”和“岗位文档模板”。

问题与目标

当前 Harness 只覆盖开发维护文档，缺少面向客户及其他岗位的交付文档选择、边界、编写与验收规则，也没有可复用的岗位文档模板。

目标：以最小范围建立交付文档闭环，新项目可按实际受众选择并生成需要的文档。

范围

要做

  • 在 Gitea Wiki 新增“交付文档指南”。
  • 在 Gitea Wiki 新增通用“岗位文档模板”。
  • 将两页显式映射导出到 docs/delivery/。
  • 工单模板增加“交付文档影响”字段。
  • 新项目文档初始化流程增加“确定交付对象和所需文档”步骤。
  • 更新 Home 入口以及 Harness 严格检查和自动化测试。
  • 完成 Wiki 同步、测试、Git 提交、工单证据和任务归档。

不做

  • 不预建用户手册、管理员手册、运维手册等空文档。
  • 不生成 PDF、HTML 或发布包。
  • 不引入新的生成脚本、框架或第三方依赖。
  • 不改变现有 Wiki 与 docs/ 的事实源边界。

已确认方案

  1. 新增交付文档指南，说明适用时机、受众与文档选择、内外部边界、生命周期、验收与维护规则。
  2. 新增一套岗位文档模板，覆盖受众、适用版本、验证日期、负责人、可见范围、目的、前置条件、步骤、预期结果、常见错误与恢复、安全、限制和支持渠道。
  3. 在任务工单中强制评估交付文档影响。
  4. 在新项目文档初始化中要求先识别交付对象，再按需创建实际文档。
  5. Wiki 为事实来源，本地只保存 docs/delivery/ 镜像。

需求变更记录

  • 2026-08-10：首次确认，无变更。

长期开发文档影响

  • 新增 Wiki：Delivery-Documentation-Guide
  • 新增 Wiki：Audience-Document-Template
  • 更新 Wiki：Home
  • 更新 Wiki：New-Project-Documentation-Setup

交付文档影响

  • 本任务建立交付文档规范和模板本身。
  • 不生成具体产品岗位文档，因为当前没有具体产品、受众和版本。

验收标准

  • Wiki 中存在交付文档指南，覆盖选择规则、内外边界、流程和验收。
  • Wiki 中存在岗位文档模板，字段完整且能被不同岗位复用。
  • 工单模板要求选择交付文档影响或说明无影响。
  • 新项目文档初始化包含识别交付对象和按需建文档步骤。
  • Home 可进入新增页面。
  • 两页正确镜像到 docs/delivery/，且标明 Wiki 来源和 revision。
  • Harness 严格检查与单元测试通过。
  • 实现和归档均已提交并推送。
  • 工单保持待验收，等待用户明确验收。

验证方法

  • python dev_scripts/check_harness.py --strict
  • python -m unittest discover -s tests -v
  • python dev_scripts/sync_wiki_docs.py --check
  • git status --short --branch

风险与回退

  • 风险：交付文档与内部开发文档边界不清，可能暴露内部信息；通过指南中的可见范围和外部内容禁区控制。
  • 风险：提前生成无用空文档；通过“按受众按需创建”控制。
  • 回退：恢复 Wiki 页面、映射、工单模板和检查规则到本任务前版本；页面删除属于破坏性操作，回退时需另行确认。

实施结果与证据

  • 实施结果：与已确认方案一致；未创建具体岗位空文档。
  • 线上 Wiki：
    • Delivery-Documentation-Guide，revision d9de4f8d8abc40630069c67948ca2a5086f90e70
    • Audience-Document-Template，revision 7a8f38df566fe639094497c9692e0559c9c080e6
    • Home，revision d7c0df9a900296850ca32296211504c5274c2b26
    • New-Project-Documentation-Setup，revision 710503a62b7a4ebd3c9d7a1a08dbd398161595d0
    • Task-11-交付文档指南与岗位文档模板，revision 4e5c30641d9bcbc69d4c235f33ff89dd47259f63
  • 本地镜像：
    • docs/delivery/README.md
    • docs/delivery/audience-document-template.md
    • docs/task/11-交付文档指南与岗位文档模板.md
  • 测试：
    • python dev_scripts/check_harness.py --strict：通过
    • python -m unittest discover -s tests -v：22/22 通过
    • python dev_scripts/sync_wiki_docs.py --check：23/23 一致
    • git diff --check：通过
  • 提交：
    • 3474870 docs: 建立最小交付文档体系 (#11)
    • eb92fb3 docs: 归档任务 #11
  • 未验证部分：没有具体产品、目标岗位或客户环境，因此未执行实际岗位操作验证；具体项目按模板创建真实文档时必须补充。
  • 当前状态：待验收。用户明确验收通过前不关闭工单。
## 基本信息 - 类型：单元任务 - 状态：已完成 - 所属 Epic：无 - 所属 MVP：无 ## 前置关系 - 前置工单：无 - 是否可与其他任务并行：是 - 原因：本任务只扩展交付文档规范、模板和流程检查，不依赖未完成任务。 ## 原始需求 - 来源：用户与 Agent 对话 - 记录时间：2026-08-10 - 关键原话：“按照你的建议建工单，做” - 已确认上下文：在当前项目基础上做最小实现，增加“交付文档指南”和“岗位文档模板”。 ## 问题与目标 当前 Harness 只覆盖开发维护文档，缺少面向客户及其他岗位的交付文档选择、边界、编写与验收规则，也没有可复用的岗位文档模板。 目标：以最小范围建立交付文档闭环，新项目可按实际受众选择并生成需要的文档。 ## 范围 ### 要做 - 在 Gitea Wiki 新增“交付文档指南”。 - 在 Gitea Wiki 新增通用“岗位文档模板”。 - 将两页显式映射导出到 `docs/delivery/`。 - 工单模板增加“交付文档影响”字段。 - 新项目文档初始化流程增加“确定交付对象和所需文档”步骤。 - 更新 Home 入口以及 Harness 严格检查和自动化测试。 - 完成 Wiki 同步、测试、Git 提交、工单证据和任务归档。 ### 不做 - 不预建用户手册、管理员手册、运维手册等空文档。 - 不生成 PDF、HTML 或发布包。 - 不引入新的生成脚本、框架或第三方依赖。 - 不改变现有 Wiki 与 `docs/` 的事实源边界。 ## 已确认方案 1. 新增交付文档指南，说明适用时机、受众与文档选择、内外部边界、生命周期、验收与维护规则。 2. 新增一套岗位文档模板，覆盖受众、适用版本、验证日期、负责人、可见范围、目的、前置条件、步骤、预期结果、常见错误与恢复、安全、限制和支持渠道。 3. 在任务工单中强制评估交付文档影响。 4. 在新项目文档初始化中要求先识别交付对象，再按需创建实际文档。 5. Wiki 为事实来源，本地只保存 `docs/delivery/` 镜像。 ## 需求变更记录 - 2026-08-10：首次确认，无变更。 ## 长期开发文档影响 - 新增 Wiki：Delivery-Documentation-Guide - 新增 Wiki：Audience-Document-Template - 更新 Wiki：Home - 更新 Wiki：New-Project-Documentation-Setup ## 交付文档影响 - 本任务建立交付文档规范和模板本身。 - 不生成具体产品岗位文档，因为当前没有具体产品、受众和版本。 ## 验收标准 - [x] Wiki 中存在交付文档指南，覆盖选择规则、内外边界、流程和验收。 - [x] Wiki 中存在岗位文档模板，字段完整且能被不同岗位复用。 - [x] 工单模板要求选择交付文档影响或说明无影响。 - [x] 新项目文档初始化包含识别交付对象和按需建文档步骤。 - [x] Home 可进入新增页面。 - [x] 两页正确镜像到 `docs/delivery/`，且标明 Wiki 来源和 revision。 - [x] Harness 严格检查与单元测试通过。 - [x] 实现和归档均已提交并推送。 - [ ] 工单保持待验收，等待用户明确验收。 ## 验证方法 - `python dev_scripts/check_harness.py --strict` - `python -m unittest discover -s tests -v` - `python dev_scripts/sync_wiki_docs.py --check` - `git status --short --branch` ## 风险与回退 - 风险：交付文档与内部开发文档边界不清，可能暴露内部信息；通过指南中的可见范围和外部内容禁区控制。 - 风险：提前生成无用空文档；通过“按受众按需创建”控制。 - 回退：恢复 Wiki 页面、映射、工单模板和检查规则到本任务前版本；页面删除属于破坏性操作，回退时需另行确认。 ## 实施结果与证据 - 实施结果：与已确认方案一致；未创建具体岗位空文档。 - 线上 Wiki： - Delivery-Documentation-Guide，revision `d9de4f8d8abc40630069c67948ca2a5086f90e70` - Audience-Document-Template，revision `7a8f38df566fe639094497c9692e0559c9c080e6` - Home，revision `d7c0df9a900296850ca32296211504c5274c2b26` - New-Project-Documentation-Setup，revision `710503a62b7a4ebd3c9d7a1a08dbd398161595d0` - Task-11-交付文档指南与岗位文档模板，revision `4e5c30641d9bcbc69d4c235f33ff89dd47259f63` - 本地镜像： - `docs/delivery/README.md` - `docs/delivery/audience-document-template.md` - `docs/task/11-交付文档指南与岗位文档模板.md` - 测试： - `python dev_scripts/check_harness.py --strict`：通过 - `python -m unittest discover -s tests -v`：22/22 通过 - `python dev_scripts/sync_wiki_docs.py --check`：23/23 一致 - `git diff --check`：通过 - 提交： - `3474870` `docs: 建立最小交付文档体系 (#11)` - `eb92fb3` `docs: 归档任务 #11` - 未验证部分：没有具体产品、目标岗位或客户环境，因此未执行实际岗位操作验证；具体项目按模板创建真实文档时必须补充。 - 当前状态：待验收。用户明确验收通过前不关闭工单。
ila commented 2026-08-25 10:24:34 +08:00
Author
Owner
Copy Link
Copy Source

验收结论

  • 验收时间：2026-08-25（Asia/Shanghai）
  • 结论：用户明确表示 #11 验收通过。
  • 长期需求状态：已在 Product-Requirements-Overview 更新为“已交付”，revision e9e0ebafd9189ae911094e615595a5e464e5e59b。
  • 镜像提交：19fb64b，已推送到 origin/main。
  • Wiki 镜像检查：15 个核心页面一致。
  • 父工单：无。
  • 任务快照：未新建、未导出；已有历史快照继续作为兼容证据，单次任务事实以本工单为准。

验收闭环完成，关闭工单。

## 验收结论 - 验收时间：2026-08-25（Asia/Shanghai） - 结论：用户明确表示 #11 验收通过。 - 长期需求状态：已在 Product-Requirements-Overview 更新为“已交付”，revision `e9e0ebafd9189ae911094e615595a5e464e5e59b`。 - 镜像提交：`19fb64b`，已推送到 `origin/main`。 - Wiki 镜像检查：15 个核心页面一致。 - 父工单：无。 - 任务快照：未新建、未导出；已有历史快照继续作为兼容证据，单次任务事实以本工单为准。 验收闭环完成，关闭工单。
ila closed this issue 2026-08-25 10:24:35 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/dev_harness#11