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

新增面向维护者的部署文档模板与位置约定 #24

New Issue
Closed
opened 2026-08-19 09:48:00 +08:00 by ila · 2 comments
ila commented 2026-08-19 09:48:00 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 所属 Epic：#
  • 所属 MVP / 版本：#
  • 阶段：模板核心

依赖与并行

  • 前置工单：无
  • 是否允许与前置工单并行：是
  • 原因：无前置依赖，仅涉及 DevHarness 模板自身文档与结构检查。

子项目影响

  • 仅影响的子项目 / 交付单元：DevHarness 模板本体（单一交付单元）
  • 是否跨子项目：否
  • 是否修改共享接口或契约：是；唯一事实来源：dev_scripts/harness.py 的 REQUIRED_FILES（下游项目升级基线后需同步新增模板文件）
  • 各子项目需要执行的验证：python dev_scripts/harness.py check --strict、python -m unittest discover -s tests -v、python dev_scripts/harness.py sync --check

原始需求

  • 来源：用户对话
  • 提出时间：2026-08-19
  • 关键原话或脱敏摘要：用户先问「当前项目有必要增加怎样在服务部署的文档吗」，确认部署文档应存放在业务项目自身 Wiki 后选择「按照情况A来做」，并说明「大部分部署是先安装 nginx 和 supervisorctl，然后用 nginx 代理服务和用 supervisorctl 来管理服务」。后续确认两点：REQUIRED_FILES 要加；示例按 Python 风格写。

要解决什么

现状：AGENTS.md 与 docs/01-workflow.md 都要求「部署命令变化时必须更新对应 Wiki」，但核心文档集里没有任何一页承载部署职责，唯一相关落点是面向客户/运维岗位的 docs/delivery/，属于交付文档而非面向项目维护者的开发文档。规则存在指向空洞，各项目只能自行猜测部署文档写在哪里。

目标：为面向项目内部维护者的部署文档提供固定模板与位置约定，把 nginx 反向代理 + supervisor 进程托管这套标准做法固化下来，并让「本项目是否需要部署页」成为新项目初始化时的一次明确判定。

做什么 / 不做什么

  • 做：新增 Deployment-Template 模板页及镜像；在新项目初始化流程加入部署页判定；明确 AGENTS.md 与 docs/01-workflow.md 中部署文档的落点；REQUIRED_FILES 纳入模板文件；补充单元测试。
  • 不做：不为 dev_harness 自身编写部署文档（本仓库无常驻服务）；不改动 docs/delivery/ 的交付文档线；不把部署实例页加入 CORE_DOCUMENT_REQUIREMENTS 强制章节检查，避免纯库/CLI 项目被迫产出空文档。

已确认方案

模板页定位与 docs/templates/task-archive.md 同级，属于「复制后填写」的模板，不是 dev_harness 自身内容。

  1. 新增 Wiki 页面 Deployment-Template，镜像到 docs/templates/deployment.md，并在 wiki-docs.json 增加映射。章节：服务概览、环境要求、首次部署、supervisor 配置、nginx 配置、配置与凭据来源、日常运维、健康检查、升级与回滚、已知限制。示例按 Python 服务（gunicorn/uvicorn 风格）编写，每条命令写明预期结果，与 docs/04 风格一致；配置与凭据只写来源，禁止写真实值。
  2. docs/07-new-project-documentation-setup.md 的「9. 人工确认」增加判定：项目负责人确认本项目是否有需要部署的常驻服务；有则复制模板建立 Deployment-and-Operations 页并加入该项目 wiki-docs.json，无则在初始化工单记录原因。
  3. docs/01-workflow.md 与 AGENTS.md 中「部署命令变化必须更新对应 Wiki」补明落点：有部署页的项目更新 Deployment-and-Operations，无部署页的项目记录为无文档影响。
  4. dev_scripts/harness.py 的 REQUIRED_FILES 增加 docs/templates/deployment.md；不加入 CORE_DOCUMENT_REQUIREMENTS。
  5. tests/ 增加断言：模板文件缺失时 check --strict 失败。

不影响数据库与运行时安全边界。影响下游契约：已采用 DevHarness 的项目升级基线后，未同步该模板文件会导致 check --strict 失败，属预期升级动作，需写入升级说明。

预计修改文件：

  • docs/templates/deployment.md（新增，Wiki 镜像）
  • wiki-docs.json
  • docs/07-new-project-documentation-setup.md
  • docs/01-workflow.md
  • AGENTS.md
  • dev_scripts/harness.py
  • tests/（对应测试文件）

需求变化记录

日期 变化内容 原因 用户确认
2026-08-19 REQUIRED_FILES 纳入模板文件；示例按 Python 风格编写 方案确认时用户对两个待定点拍板 是

设计与原型门禁

  • 修改类型：非 UI
  • 所需设计证据：架构、API、数据、状态或流程设计
  • 可编辑设计源链接、版本或事实来源：本工单「已确认方案」；Gitea Wiki 为文档事实来源
  • 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，非 UI 变更，无页面结构或交互
  • 本地浏览方式和资源完整性检查：不适用
  • 版本、revision 或确认日期：2026-08-19
  • 状态：已确认
  • 确认人、确认时间和覆盖范围：ila，2026-08-19，覆盖模板章节结构、初始化判定、规则落点、REQUIRED_FILES 变更与测试范围
  • 无需 UI 原型或无需任何原型的原因：纯文档模板与结构检查变更，不涉及任何用户界面

文档影响

  • 更新其他 Wiki 页面：新增 Deployment-Template；更新 Development-Workflow、New-Project-Documentation-Setup

交付文档影响

  • 无交付文档影响，原因：本次仅新增面向项目内部维护者的部署文档模板，未改变面向客户或运维岗位的交付文档内容与支持方式；docs/delivery/ 线保持不变。

验收标准

  • Deployment-Template Wiki 页面创建成功并在线回读取得 revision，镜像导出为 docs/templates/deployment.md
  • 模板包含全部十个约定章节，示例为 Python 服务风格，每条命令有预期结果，且不含任何真实凭据或生产数据
  • wiki-docs.json 增加对应映射，sync --check 通过
  • docs/07、docs/01、AGENTS.md 的部署文档落点与初始化判定描述一致，无残留指向空洞
  • REQUIRED_FILES 包含 docs/templates/deployment.md，且该文件缺失时 check --strict 返回失败（有测试覆盖）
  • check --strict 与全部单元测试通过

验证方式

python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v
python dev_scripts/harness.py sync --check

风险和回退

风险低。唯一契约风险是 REQUIRED_FILES 新增项会让已采用 DevHarness 的下游项目在升级基线后 check --strict 失败，直到同步该模板文件；需在升级说明中写明。回退方式：还原上述文件并删除 Wiki 页面与映射，无数据、状态或不可逆变更。

## 基本信息 - 类型：需求 - 所属 Epic：# - 所属 MVP / 版本：# - 阶段：模板核心 ## 依赖与并行 - 前置工单：无 - 是否允许与前置工单并行：是 - 原因：无前置依赖，仅涉及 DevHarness 模板自身文档与结构检查。 ## 子项目影响 - 仅影响的子项目 / 交付单元：DevHarness 模板本体（单一交付单元） - 是否跨子项目：否 - 是否修改共享接口或契约：是；唯一事实来源：`dev_scripts/harness.py` 的 `REQUIRED_FILES`（下游项目升级基线后需同步新增模板文件） - 各子项目需要执行的验证：`python dev_scripts/harness.py check --strict`、`python -m unittest discover -s tests -v`、`python dev_scripts/harness.py sync --check` ## 原始需求 - 来源：用户对话 - 提出时间：2026-08-19 - 关键原话或脱敏摘要：用户先问「当前项目有必要增加怎样在服务部署的文档吗」，确认部署文档应存放在业务项目自身 Wiki 后选择「按照情况A来做」，并说明「大部分部署是先安装 nginx 和 supervisorctl，然后用 nginx 代理服务和用 supervisorctl 来管理服务」。后续确认两点：`REQUIRED_FILES` 要加；示例按 Python 风格写。 ## 要解决什么 现状：`AGENTS.md` 与 `docs/01-workflow.md` 都要求「部署命令变化时必须更新对应 Wiki」，但核心文档集里没有任何一页承载部署职责，唯一相关落点是面向客户/运维岗位的 `docs/delivery/`，属于交付文档而非面向项目维护者的开发文档。规则存在指向空洞，各项目只能自行猜测部署文档写在哪里。 目标：为面向项目内部维护者的部署文档提供固定模板与位置约定，把 nginx 反向代理 + supervisor 进程托管这套标准做法固化下来，并让「本项目是否需要部署页」成为新项目初始化时的一次明确判定。 ## 做什么 / 不做什么 - 做：新增 `Deployment-Template` 模板页及镜像；在新项目初始化流程加入部署页判定；明确 `AGENTS.md` 与 `docs/01-workflow.md` 中部署文档的落点；`REQUIRED_FILES` 纳入模板文件；补充单元测试。 - 不做：不为 dev_harness 自身编写部署文档（本仓库无常驻服务）；不改动 `docs/delivery/` 的交付文档线；不把部署实例页加入 `CORE_DOCUMENT_REQUIREMENTS` 强制章节检查，避免纯库/CLI 项目被迫产出空文档。 ## 已确认方案 模板页定位与 `docs/templates/task-archive.md` 同级，属于「复制后填写」的模板，不是 dev_harness 自身内容。 1. 新增 Wiki 页面 `Deployment-Template`，镜像到 `docs/templates/deployment.md`，并在 `wiki-docs.json` 增加映射。章节：服务概览、环境要求、首次部署、supervisor 配置、nginx 配置、配置与凭据来源、日常运维、健康检查、升级与回滚、已知限制。示例按 Python 服务（gunicorn/uvicorn 风格）编写，每条命令写明预期结果，与 `docs/04` 风格一致；配置与凭据只写来源，禁止写真实值。 2. `docs/07-new-project-documentation-setup.md` 的「9. 人工确认」增加判定：项目负责人确认本项目是否有需要部署的常驻服务；有则复制模板建立 `Deployment-and-Operations` 页并加入该项目 `wiki-docs.json`，无则在初始化工单记录原因。 3. `docs/01-workflow.md` 与 `AGENTS.md` 中「部署命令变化必须更新对应 Wiki」补明落点：有部署页的项目更新 `Deployment-and-Operations`，无部署页的项目记录为无文档影响。 4. `dev_scripts/harness.py` 的 `REQUIRED_FILES` 增加 `docs/templates/deployment.md`；不加入 `CORE_DOCUMENT_REQUIREMENTS`。 5. `tests/` 增加断言：模板文件缺失时 `check --strict` 失败。 不影响数据库与运行时安全边界。影响下游契约：已采用 DevHarness 的项目升级基线后，未同步该模板文件会导致 `check --strict` 失败，属预期升级动作，需写入升级说明。 预计修改文件： - `docs/templates/deployment.md`（新增，Wiki 镜像） - `wiki-docs.json` - `docs/07-new-project-documentation-setup.md` - `docs/01-workflow.md` - `AGENTS.md` - `dev_scripts/harness.py` - `tests/`（对应测试文件） ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-19 | `REQUIRED_FILES` 纳入模板文件；示例按 Python 风格编写 | 方案确认时用户对两个待定点拍板 | 是 | ## 设计与原型门禁 - 修改类型：非 UI - 所需设计证据：架构、API、数据、状态或流程设计 - 可编辑设计源链接、版本或事实来源：本工单「已确认方案」；Gitea Wiki 为文档事实来源 - 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，非 UI 变更，无页面结构或交互 - 本地浏览方式和资源完整性检查：不适用 - 版本、revision 或确认日期：2026-08-19 - 状态：已确认 - 确认人、确认时间和覆盖范围：ila，2026-08-19，覆盖模板章节结构、初始化判定、规则落点、`REQUIRED_FILES` 变更与测试范围 - 无需 UI 原型或无需任何原型的原因：纯文档模板与结构检查变更，不涉及任何用户界面 ## 文档影响 - [x] 更新其他 Wiki 页面：新增 `Deployment-Template`；更新 `Development-Workflow`、`New-Project-Documentation-Setup` ## 交付文档影响 - [x] 无交付文档影响，原因：本次仅新增面向项目内部维护者的部署文档模板，未改变面向客户或运维岗位的交付文档内容与支持方式；`docs/delivery/` 线保持不变。 ## 验收标准 - [ ] `Deployment-Template` Wiki 页面创建成功并在线回读取得 revision，镜像导出为 `docs/templates/deployment.md` - [ ] 模板包含全部十个约定章节，示例为 Python 服务风格，每条命令有预期结果，且不含任何真实凭据或生产数据 - [ ] `wiki-docs.json` 增加对应映射，`sync --check` 通过 - [ ] `docs/07`、`docs/01`、`AGENTS.md` 的部署文档落点与初始化判定描述一致，无残留指向空洞 - [ ] `REQUIRED_FILES` 包含 `docs/templates/deployment.md`，且该文件缺失时 `check --strict` 返回失败（有测试覆盖） - [ ] `check --strict` 与全部单元测试通过 ## 验证方式 ``` python dev_scripts/harness.py check --strict python -m unittest discover -s tests -v python dev_scripts/harness.py sync --check ``` ## 风险和回退 风险低。唯一契约风险是 `REQUIRED_FILES` 新增项会让已采用 DevHarness 的下游项目在升级基线后 `check --strict` 失败，直到同步该模板文件；需在升级说明中写明。回退方式：还原上述文件并删除 Wiki 页面与映射，无数据、状态或不可逆变更。
ila commented 2026-08-19 09:55:53 +08:00
Author
Owner
Copy Link
Copy Source

实施完成，待验收

提交：65c2061 docs: 新增部署文档模板与位置约定 (#24)，已推送到 origin/main。

Wiki

  • 新增 Deployment-Template，revision 948321c2f3e4
  • 更新 Development-Workflow，revision 98acbf90ebad
  • 更新 New-Project-Documentation-Setup，revision 581e2e04edbe
  • 任务归档 Task-24-部署文档模板与位置约定，revision 25ae4b570638

验证结果

  • python dev_scripts/harness.py check --strict：通过
  • python -m unittest discover -s tests -v：通过，42 项（新增 2 项）
  • python dev_scripts/harness.py sync --check：通过

未验证部分：模板描述的实际部署流程（nginx、supervisor、gunicorn 配置与命令）未在真实服务器上演练，本仓库无常驻服务；首个采用该模板的业务项目应在其部署工单中完成真实验证并回写差异。

遗留提示：下游项目升级基线时需同步 docs/templates/deployment.md，否则 check --strict 会因缺少必需文件失败。

全部验收标准已自检通过，工单保持「待验收」，等待人工验收。

## 实施完成，待验收 **提交**：`65c2061` docs: 新增部署文档模板与位置约定 (#24)，已推送到 `origin/main`。 **Wiki** - 新增 `Deployment-Template`，revision `948321c2f3e4` - 更新 `Development-Workflow`，revision `98acbf90ebad` - 更新 `New-Project-Documentation-Setup`，revision `581e2e04edbe` - 任务归档 `Task-24-部署文档模板与位置约定`，revision `25ae4b570638` **验证结果** - `python dev_scripts/harness.py check --strict`：通过 - `python -m unittest discover -s tests -v`：通过，42 项（新增 2 项） - `python dev_scripts/harness.py sync --check`：通过 **未验证部分**：模板描述的实际部署流程（nginx、supervisor、gunicorn 配置与命令）未在真实服务器上演练，本仓库无常驻服务；首个采用该模板的业务项目应在其部署工单中完成真实验证并回写差异。 **遗留提示**：下游项目升级基线时需同步 `docs/templates/deployment.md`，否则 `check --strict` 会因缺少必需文件失败。 全部验收标准已自检通过，工单保持「待验收」，等待人工验收。
ila commented 2026-08-19 10:07:09 +08:00
Author
Owner
Copy Link
Copy Source

验收通过，工单关闭

用户于 2026-08-19 明确验收通过。

收尾动作

  • 任务归档 Task-24-部署文档模板与位置约定 状态更新为「已完成」，revision 71b394ad752c
  • Product-Requirements-Overview 增加「服务部署文档」需求行，revision 8c1aeabb190c
  • 核心镜像同步提交 3696663，已推送 origin/main
  • 复核通过：check --strict、42 项单元测试、sync --check

父工单：本工单无所属 Epic 与 MVP，无需同步。

遗留提示（不阻塞验收）：下游项目升级 DevHarness 基线时需同步 docs/templates/deployment.md；模板中的 nginx/supervisor/gunicorn 流程尚未在真实服务器演练，首个采用项目应在其部署工单完成真实验证。

## 验收通过，工单关闭 用户于 2026-08-19 明确验收通过。 **收尾动作** - 任务归档 `Task-24-部署文档模板与位置约定` 状态更新为「已完成」，revision `71b394ad752c` - `Product-Requirements-Overview` 增加「服务部署文档」需求行，revision `8c1aeabb190c` - 核心镜像同步提交 `3696663`，已推送 `origin/main` - 复核通过：`check --strict`、42 项单元测试、`sync --check` **父工单**：本工单无所属 Epic 与 MVP，无需同步。 **遗留提示**（不阻塞验收）：下游项目升级 DevHarness 基线时需同步 `docs/templates/deployment.md`；模板中的 nginx/supervisor/gunicorn 流程尚未在真实服务器演练，首个采用项目应在其部署工单完成真实验证。
ila closed this issue 2026-08-19 10:07:10 +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#24