feat: 文档技能包与模板规范完善

- 截图规范统一：JPEG 质量85% + 分终端目录 + 只截主界面/详情页 + 全屏视口(1440×900) - 内容通用化：全文去除客户名称与项目名称，文档可供任意客户阅读 - 交付格式规范：.md 为源 + 竖版 A4 PDF 最终交付，明确分页三原则 - PRD 合并优化：系统功能清单 HTML 表格(rowspan)替代页面清单，清理 .html 文件名与来源说明区 - 业务架构图模板重构：应用与服务层改横排竖版板块 + 层间横向分隔线 - .gitignore 忽略 /交付文档/ 目录；记忆新增操作手册截图规范 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-09-10 17:07:54 +08:00
parent 256b741c8f
commit b5a8b83e6d
15 changed files with 324 additions and 136 deletions
@@ -112,13 +112,35 @@ adb shell cat /sdcard/ui.xml | grep -oE 'text="[^"]+"[^>]*bounds="\[[0-9]+,[0-9]
 # 从 bounds="[x1,y1][x2,y2]" 取中心点：tap_x=(x1+x2)/2, tap_y=(y1+y2)/2
 ```

-### Step 5：交给操作手册 skill
+### Step 5：截图后处理（压缩 + 分目录）

-截图完成后，交给 `doc-operation-manual` skill 组织成操作手册。
+真机截图原始为 1264×2800 的 PNG（体积可达 1.5MB），需压缩后才能用于操作手册：
+
+1. **转 JPEG + 缩宽**：用 PowerShell System.Drawing 将 PNG 缩放为 390px 宽、质量 85% 的 JPEG（参考 `项目背景.md` 7.4 节 PRD 截图规范，目标单张约 80KB 以内）
+2. **分目录存放**：按终端分目录 `交付文档/{子系统名}/操作手册/screenshots/{终端目录}/`（如 `employee-app`），命名用中文页面名
+
+```powershell
+# 示例：将 PNG 缩放为 390px 宽、JPEG 质量 85%
+Add-Type -AssemblyName System.Drawing
+$img = [System.Drawing.Image]::FromFile("源.png")
+$w = 390; $h = [int]($img.Height * $w / $img.Width)
+$bmp = New-Object System.Drawing.Bitmap($w, $h)
+$g = [System.Drawing.Graphics]::FromImage($bmp)
+$g.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
+$g.DrawImage($img, 0, 0, $w, $h)
+$enc = [System.Drawing.Imaging.ImageCodecInfo]::GetImageEncoders() | Where-Object { $_.MimeType -eq 'image/jpeg' }
+$ep = New-Object System.Drawing.Imaging.EncoderParameters(1)
+$ep.Param[0] = New-Object System.Drawing.Imaging.EncoderParameter([System.Drawing.Imaging.Encoder]::Quality, [long]85)
+$bmp.Save("目标.jpg", $enc, $ep)
+```
+
+### Step 6：交给操作手册 skill
+
+截图压缩完成后，交给 `doc-operation-manual` skill 组织成操作手册。

 ## 输出物

- `交付文档/{子系统名}/操作手册/screenshots/*.png`（APP 实际页面截图）
+- `交付文档/{子系统名}/操作手册/screenshots/{终端目录}/*.jpg`（APP 实际页面截图，JPEG 390px）

 ## 注意事项

@@ -126,6 +148,8 @@ adb shell cat /sdcard/ui.xml | grep -oE 'text="[^"]+"[^>]*bounds="\[[0-9]+,[0-9]
 - **读文字验证画面**：截图前务必用 uiautomator 读 text 确认页面，避免截错
 - **配对码时效短**：无线调试配对码几十秒就失效，拿到立刻配对
 - **截图命名用中文页面名**，与操作手册章节一一对应
+- **截图必须压缩**：真机截图原始 PNG 体积大，需缩放为 390px 宽 JPEG（质量 85%）再交付，不直接用原图
+- **截图按终端分目录**：`screenshots/{终端目录}/`，避免多终端截图混在同一目录
 - **点击坐标依分辨率换算**：先 `adb shell wm size` 确认（本机 1264×2800）
 - **中文输入受限**：`adb shell input text` 只支持 ASCII，中文需 adbkeyboard 或 `am broadcast`
 - 登录页等需要验证码/密码的场景，输入密码可自动化，验证码需人工识别
@@ -65,8 +65,8 @@ description: 生成指定子系统的《产品宣传册》（横版 A4，HTML
 ## 注意事项

 - **美观精炼**：宣传册面向客户，语言要有感染力，忌长篇技术描述；每页信息密度适中，元素丰富（图标/装饰/渐变卡片），避免单一
- **横版分页**：每 `.page` 一屏一页（297×210mm 横版 A4），内容横向铺满，避免纵向留白
+- **横版分页**：每 `.page` 一屏一页（297×210mm 横版 A4），内容横向铺满，避免纵向留白；同一版块的文字与截图不跨页（内容超出一页时精简或拆页，不硬塞导致切割）
 - **配色统一**：沿用模板品牌蓝 `#1890FF` 设计令牌，不另造配色
- **内容通用**：宣传册必须通用，不得体现客户信息（如「油田」、客户公司名、委托方名称等）
+- **内容通用**：宣传册必须通用，不得出现客户名称与项目名称（客户公司名、甲方名称、委托方、油田等一律不写）
 - emoji 图标用于视觉占位，正式交付如需替换为专业图标，告知用户
 - 文档名称「{子系统名}产品宣传册.html / .pdf」为中文，符合甲方要求
@@ -64,11 +64,14 @@ node _templates/docs/parse-sql.js <SQL文件> <输出md路径> <子系统名> Po

 ## 输出物

- `交付文档/{子系统名}/{子系统名}数据库设计说明书.md`
+- `交付文档/{子系统名}/{子系统名}数据库设计说明书.md`（源文件）
+- `交付文档/{子系统名}/{子系统名}数据库设计说明书.pdf`（最终交付物，竖版 A4，由使用方从 .md 转出）

 ## 注意事项

 - SQL 注释是字段中文说明的唯一来源，`COMMENT ON COLUMN` 缺失时列说明留空并汇总提示用户补充
 - 表结构字段表严格沿用 7 列格式（序号/列名/数据类型/长度/主键/允许空值/列说明）
 - 若 SQL 无表注释，表中文名先留空，提醒用户补齐
+- **内容通用**：全文不得出现客户名称与项目名称，只介绍数据库自身设计，产出文档可供任意客户与人群阅读
+- **交付格式**：最终交付为竖版 A4 PDF（.md 为源，由使用方导出），分页遵循模板「PDF 导出规范」三原则，避免表行切割
 - 文档全部使用简体中文
@@ -13,7 +13,7 @@ description: 生成指定子系统的《详细设计说明书》（8 章正式
 ## 输入参数

 - **子系统名**（必须，中文）：如 `体重管理系统`
- **补充信息**（可选）：甲方名称、技术架构说明等，缺省用模板默认值
+- **补充信息**（可选）：技术架构说明等，缺省用模板默认值（不得含甲方名称等客户信息）

 ## 模板与素材

@@ -44,7 +44,7 @@ description: 生成指定子系统的《详细设计说明书》（8 章正式

 按 `detailed-design-template.md` 逐章填充：

- **封面**：项目名 = `健康CQ升级 —— {子系统名}`，委托方 = CQ能源公司，日期 = 当天
+- **封面**：系统名称 = `{子系统名}`，日期 = 当天（信息表不写委托方，见模板）
 - **一、项目背景**：综合 `项目背景.md` 6.1 节 + 各端 PRD 模块概述
 - **二、建设目标**：分条，参考 docx「建设目标」句式（构建生态/打造引擎/实现追踪/建立评估）
 - **三、需求说明与功能设计**：
@@ -66,6 +66,8 @@ description: 生成指定子系统的《详细设计说明书》（8 章正式

 **架构图生成（业务架构图 + 技术架构图）**：
 1. 复制 `_templates/docs/architecture-business.html` / `architecture-technical.html`，按子系统内容修改各层盒子的标题与子项
+   - **业务架构图·应用与服务层**：按一级菜单分组为横排竖版板块（`.domain`），板块内挂二级菜单或提炼的核心功能项；管理端功能用 `.d-item`、员工端 APP 功能用 `.d-item--app`（建议 📱 前缀）；智能模型类用 `.domain-model` 虚线板块；底部保留双端图例（`.legend`）
+   - 业务架构图层与层之间用横向分隔线（`.divider`）分隔，不使用竖线箭头
 2. 用浏览器打开 HTML，设置视口宽度 1008px、高度设为内容实际高度（用 JS 获取最后一个盒子底部位置 + body padding）
 3. 截图保存为 `交付文档/{子系统名}/业务架构图.png`、`技术架构图.png`
 4. 文档中引用 `![业务架构图](业务架构图.png)`、`![技术架构图](技术架构图.png)`
@@ -81,12 +83,15 @@ description: 生成指定子系统的《详细设计说明书》（8 章正式

 ## 输出物

- `交付文档/{子系统名}/{子系统名}详细设计说明书.md`
+- `交付文档/{子系统名}/{子系统名}详细设计说明书.md`（源文件）
+- `交付文档/{子系统名}/{子系统名}详细设计说明书.pdf`（最终交付物，竖版 A4，由使用方从 .md 转出）

 ## 注意事项

 - **截图沿用现有**，不重新截取；无现成截图就不放图
 - 技术架构/安全/部署/售后等通用章节可跨子系统复用，不必每次从零写
 - 3.3 核心业务详细设计是本说明书的主体，功能点要与页面清单一一对应，不得遗漏页面
+- **内容通用**：全文不得出现客户名称与项目名称（客户公司名、甲方名称、委托方等一律不写），只介绍系统自身概况，产出文档可供任意客户与人群阅读
+- **交付格式**：最终交付为竖版 A4 PDF（.md 为源，由使用方导出），分页遵循模板「PDF 导出规范」三原则，避免图文割裂、表行切割
 - 文档全部使用简体中文，表格、标题层级严格按模板
 - 不改动任何现有文件，只新建交付文档
@@ -13,7 +13,7 @@ description: 生成指定子系统、指定终端的《操作手册》。当用
 ## 输入参数

 - **子系统名**（必须，中文）：如 `健康监测系统`
- **终端名**（必须，中文）：如 `Web管理端` / `员工端APP` / `医疗点PAD`
+- **终端名**（必须，中文）：如 `Web管理端` / `员工端APP` / `医疗点PAD`/ `健康应急APP`
 - **适用对象**（可选）：用户角色，缺省按终端推断

 ## 核心原则：截图必须用实际系统截图
@@ -32,7 +32,7 @@ description: 生成指定子系统、指定终端的《操作手册》。当用
 - 模板：`_templates/docs/operation-manual-template.md`
 - 公共章节素材：`_templates/docs/common-sections-template.md`
 - **文字素材**：该终端 `doc/PRD.md` 的「逐页说明」（功能说明 + 交互说明 + 业务规则），用于提炼操作步骤与注意事项
- **截图素材**：由截图 skill（`web-capture` / `android-capture`）生成的实际系统截图，存放在 `交付文档/{子系统名}/操作手册/screenshots/`
+- **截图素材**：由截图 skill（`web-capture` / `android-capture`）生成的实际系统截图，按终端分目录存放 `交付文档/{子系统名}/操作手册/screenshots/{终端目录}/`

 ## 执行流程

@@ -40,8 +40,10 @@ description: 生成指定子系统、指定终端的《操作手册》。当用

 1. **Web 管理端**：调用 `web-capture` skill，登录测试环境 → 导航到目标模块 → 逐页面截图
 2. **员工端 APP**：调用 `android-capture` skill，真机 adb 逐页面截图
-3. 截图存放 `交付文档/{子系统名}/操作手册/screenshots/`，命名用中文页面名
-4. 若截图 skill 尚未就绪或模块未上线，**暂停并告知用户**，不退回用原型图
+3. **截图范围**：只截「主界面」和「重要表单/详情页」，弹窗、筛选下拉等轻量交互不单独截图（在功能描述中用文字/表格说明）
+4. **分目录存放**：截图按终端分目录，`交付文档/{子系统名}/操作手册/screenshots/{终端目录}/`，终端目录用英文（`employee-app` / `web-admin` / `medical-pad` 等），命名用中文页面名
+5. **截图规格**：输出 JPEG（质量 85%，清晰度优先，不设文件大小上限），APP 端宽度 390px、Web 端视口 1440×900；截图前确保浏览器全屏或设置正确视口，避免截图不完整、比例失调（参考 `项目背景.md` 7.4 节 PRD 截图规范）
+6. 若截图 skill 尚未就绪或模块未上线，**暂停并告知用户**，不退回用原型图

 ### Step 1：定位模块文字素材

@@ -56,7 +58,7 @@ description: 生成指定子系统、指定终端的《操作手册》。当用
  - 员工端 APP：390×844（iPhone 14）
  - 医疗点 PAD：1280×800 横屏
  - 微信小程序：375×812
- 适用对象按终端推断（平台管理员/能源员工/医疗点医护人员等）
+- 适用对象按终端推断（平台管理员/企业员工/医疗点医护人员等）

 ### Step 3：按业务线路组织操作手册（核心）

@@ -69,7 +71,7 @@ description: 生成指定子系统、指定终端的《操作手册》。当用
 **选择性覆盖原则**（与 PRD 前后呼应，但绝不完全一样）：

 - 只覆盖**核心操作**（高频、关键业务操作），不罗列所有小交互
- 只收录**主要弹窗**和**核心二级页面**（详情页等），不列所有弹窗
+- **截图只截主界面 + 重要表单/详情页**：操作手册的截图仅覆盖「主界面」和「重要表单/详情页」；弹窗、筛选条件下拉、选项列表等轻量交互**不单独截图**，在「功能说明」或「注意事项」中用文字/表格说明即可
 - **页面状态选择性说明**：只说明用户常见的关键状态，不穷举所有状态（如只讲"进行中"和"已结束"，不讲所有中间态）

 按 `operation-manual-template.md` 生成：
@@ -89,8 +91,8 @@ description: 生成指定子系统、指定终端的《操作手册》。当用

 ### Step 5：截图引用

- 引用 `交付文档/{子系统名}/操作手册/screenshots/` 下的实际系统截图
- 路径相对操作手册文件：`screenshots/{页面名}.png`
+- 引用 `交付文档/{子系统名}/操作手册/screenshots/{终端目录}/` 下的实际系统截图
+- 路径相对操作手册文件：`screenshots/{终端目录}/{页面名}.jpg`
 - 若某页面截图缺失，标注「待补」，不退回用原型图

 ### Step 6：写入输出文件
@@ -99,13 +101,19 @@ description: 生成指定子系统、指定终端的《操作手册》。当用

 ## 输出物

- `交付文档/{子系统名}/操作手册/{子系统名}{终端名}操作手册.md`
- `交付文档/{子系统名}/操作手册/screenshots/*.png`（实际系统截图）
+- `交付文档/{子系统名}/操作手册/{子系统名}{终端名}操作手册.md`（源文件）
+- `交付文档/{子系统名}/操作手册/{子系统名}{终端名}操作手册.pdf`（最终交付物，竖版 A4，由使用方从 .md 转出）
+- `交付文档/{子系统名}/操作手册/screenshots/{终端目录}/*.jpg`（实际系统截图，JPEG 390px）

 ## 注意事项

 - **截图必须实际系统截图**，严禁原型图；模块未上线或截图 skill 未就绪时，暂停并告知用户
+- **截图只截主界面 + 重要表单/详情页**：弹窗、筛选下拉等轻量交互不单独截图，在功能描述中用文字/表格说明
+- **截图规格**：JPEG 质量 85%（清晰度优先，不设文件大小上限），APP 端宽度 390px、Web 端视口 1440×900（截图前确保浏览器全屏，参考 `项目背景.md` 7.4 节）
+- **截图按终端分目录**：`screenshots/{终端目录}/`，终端目录用英文，避免多终端截图混在同一目录
 - **与 PRD 前后呼应**：手册章节对应 PRD 功能模块，但只覆盖核心操作、主要弹窗、核心二级页面，不逐页罗列所有弹窗/小交互/页面状态
 - 操作手册面向**终端用户**，语言通俗、步骤化，避免实现细节（字段名、接口名）
 - 每个子系统的每个终端单独一份手册，公共操作（登录/消息等）在各手册中重复体现（甲方要求）
+- **内容通用**：全文不得出现客户名称与项目名称，只介绍系统自身操作，产出文档可供任意客户与人群阅读
+- **交付格式**：最终交付为竖版 A4 PDF（.md 为源，由使用方导出），分页遵循模板「PDF 导出规范」三原则，避免图文割裂、表行切割
 - 文档全部使用简体中文
@@ -39,14 +39,17 @@ description: 将同一子系统的多个终端 PRD 合并成一份《产品需

 ### Step 3：按模板合成新文档

-按 `prd-merge-template.md` 合成：
+按 `prd-merge-template.md` 合成。**交付定位：单独交付、不与原型代码一起交付，正文与标题中不得出现页面文件路径与页面文件名（`.html` 文件名、目录路径一律清理）**：

- **标题**：`{子系统名}产品需求文档`
- **合并说明**：顶部标注各终端 PRD 来源路径（原始文件未改动）
- **1. 子系统概述**：整合各终端「模块概述」为统一一段 + 按端分组的统一导航结构树 + 状态流转图（如有）
- **2. 页面清单**：按端分组沿用原表格；**公共页面（登录/消息等）归入「公共部分」小节，不重复罗列**
- **3. 逐页说明**：按端分组沿用原文，截图路径改为「从本文档位置指回原模块 doc/screenshots/ 的相对路径」
- **4. 表单字段表**：按端分组合并
+- **标题**：`{子系统名}产品需求文档`；**不写**「本文档由…合并生成」来源说明区
+- **1. 子系统概述**：整合各终端「模块概述」为统一一段 + 按端分组的「系统功能清单」
+  - 「系统功能清单」用 **HTML 表格 + rowspan 合并单元格**，三列：功能模块 / 功能子模块 / 功能点（一级=功能模块，二级=功能子模块，叶子=功能点；无二级的模块列2留空）
+  - 取代原「页面导航结构」树与「页面清单」章节，不再单列页面清单
+- **2. 逐页说明**：按端分组沿用原文，但：
+  - 每页标题仅保留功能名，**去掉「（文件名.html）」**
+  - 正文中「跳转到 XX（filename.html）」等引用，**去掉括号内文件名**
+  - 截图路径改为「从本文档位置指回原模块 doc/screenshots/ 的相对路径」，截图本身保留
+- **3. 表单字段表**：仅当各终端原 PRD 存在独立「表单字段表」段时才合并，否则省略

 ### Step 4：重算截图相对路径

@@ -62,12 +65,17 @@ description: 将同一子系统的多个终端 PRD 合并成一份《产品需

 ## 输出物

- `交付文档/{子系统名}/{子系统名}产品需求文档.md`（合并版，新文件）
+- `交付文档/{子系统名}/{子系统名}产品需求文档.md`（合并版源文件，新文件）
+- `交付文档/{子系统名}/{子系统名}产品需求文档.pdf`（最终交付物，竖版 A4，由使用方从 .md 转出）

 ## 注意事项

 - **绝对不改动现有各终端 PRD 文件**，只新建合并文档
 - **截图沿用现有**：用相对路径指回原位置，不复制图片、不重新截图
- 同一子系统各终端 PRD 若存在同名的公共页面，只保留一处（归「公共部分」），避免重复
- 页面清单、逐页说明、表单字段表均按「端」分组，保持各端内容完整可追溯
+- **交付文档单独交付，不与原型一起交付**：正文与标题中**不得出现页面文件路径与页面文件名**（`.html` 文件名、目录路径一律清理）；截图是必需交付内容，其引用路径保留相对路径指回原 `doc/screenshots/`
+- **不写**「本文档由以下终端 PRD 合并生成」来源说明区
+- **系统功能清单**替代「页面导航结构」树与「页面清单」章节，用 HTML 表格 + rowspan 合并单元格（三列：功能模块 / 功能子模块 / 功能点）
+- 逐页说明、表单字段表均按「端」分组，保持各端内容完整可追溯
+- **内容通用**：全文不得出现客户名称与项目名称，只介绍产品需求本身，产出文档可供任意客户与人群阅读
+- **交付格式**：最终交付为竖版 A4 PDF（.md 为源，由使用方导出），分页遵循模板「PDF 导出规范」三原则；「系统功能清单」rowspan 合并表尤需保证合并单元整体不跨页切割
 - 文档全部使用简体中文
@@ -68,13 +68,15 @@ description: 截取 Web 管理端测试环境的实际系统页面截图（用
 ### Step 4：摸清模块菜单结构

 1. `take_snapshot` 获取侧边栏菜单：一级菜单（`menuitem`）+ 二级菜单
-2. 记录菜单层级，规划截图清单（每个叶子页面截一张）
+2. 记录菜单层级，规划截图清单——**只截「主界面」+「重要表单/详情页」**，弹窗、筛选下拉、选项列表等轻量交互不单独截图

 ### Step 5：逐页面截图

-1. 对每个叶子页面：`router.push` 到对应 URL（或点击侧边栏菜单项）
-2. `take_screenshot` 保存到 `交付文档/{子系统名}/操作手册/screenshots/{页面名}.png`
-3. 截图命名用中文页面名（如 `个人监测数据.png`），与操作手册章节对应
+1. **确保视口正确（避免截图不完整/比例失调）**：截图前先 `resize_page` 将浏览器窗口设置为 1440×900（或更大以匹配完整页面），确保窗口已全屏、无横向滚动条遗漏；页面加载后再截图
+2. 对每个目标页面：`router.push` 到对应 URL（或点击侧边栏菜单项），等待页面加载完成（`readyState === 'complete'`）
+3. `take_screenshot` 用 `format: "jpeg"` + `quality: 85`，保存为 `.jpg`（不是 `.png`）
+4. **分终端目录存放**：`交付文档/{子系统名}/操作手册/screenshots/web-admin/{页面名}.jpg`，截图命名用中文页面名（如 `个人监测数据.jpg`）
+5. **压缩比例**：JPEG 质量 85%（参考 `项目背景.md` 7.4 节 PRD 截图规范），清晰度优先，不设文件大小上限

 ### Step 6：交给操作手册 skill

@@ -82,11 +84,14 @@ description: 截取 Web 管理端测试环境的实际系统页面截图（用

 ## 输出物

- `交付文档/{子系统名}/操作手册/screenshots/*.png`（实际系统截图）
+- `交付文档/{子系统名}/操作手册/screenshots/web-admin/*.jpg`（实际系统截图，JPEG 质量 85%）

 ## 注意事项

 - **验证码是每次登录的障碍**：优先建议让开发在测试环境关闭验证码；未关闭则每次登录请用户人工报验证码
 - **模块可能未上线**：首页模块卡片标「开发中,敬请期待」的模块不可截图，先和用户确认目标模块是否可用
 - **截图以实际系统为准**：操作手册严禁用原型图，必须是测试环境真实页面
+- **截图前确保浏览器全屏/正确视口**：窗口未全屏会导致截图不完整、比例失调，截图前先 `resize_page` 设置 1440×900 视口
+- **截图只截主界面 + 重要表单/详情页**：弹窗、筛选下拉等轻量交互不单独截图，在功能描述中用文字/表格说明
+- **截图规格**：JPEG 质量 85%（清晰度优先，不设文件大小上限），分终端目录 `web-admin/` 存放
 - 截图文件名用中文页面名，与操作手册章节一一对应