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

New Issue

2026-08-10T14:20:55+08:00

ila commented

2026-08-10 14:20:55 +08:00

基本信息

类型：单元任务
状态：待验收
所属 Epic：无
所属 MVP：无

前置关系

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

原始需求

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

问题与目标

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

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

范围

要做

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

不做

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

已确认方案

新增交付文档指南，说明适用时机、受众与文档选择、内外部边界、生命周期、验收与维护规则。
新增一套岗位文档模板，覆盖受众、适用版本、验证日期、负责人、可见范围、目的、前置条件、步骤、预期结果、常见错误与恢复、安全、限制和支持渠道。
在任务工单中强制评估交付文档影响。
在新项目文档初始化中要求先识别交付对象，再按需创建实际文档。
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 referenced this issue from a commit

2026-08-10 14:25:45 +08:00

docs: 建立最小交付文档体系 (#11)

ila referenced this issue from a commit

2026-08-10 14:30:18 +08:00

docs: 归档任务 #11

ila referenced this issue

2026-08-10 14:54:51 +08:00

新增已有项目接入 DevHarness 指南 #12

Sign in to join this conversation.