feat: 四端设计总览生成、截图补全与模板工具链完善

- 新增 operator/onsite/professional/employee-app 四端 design-overview.html - 补全约 30 张弹窗/状态截图，重拍长图（fullPage） - 新增 design-overview-template.html 模板与 design-overview skill - index.html 注册设计总览入口、修复 md-viewer 路径 - 删除已迁移的 md-viewer.html 和本地服务器方案文档 - 更新 package.json 依赖与项目背景文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-05-26 18:01:16 +08:00
parent 6e05f10396
commit 263b625015
53 changed files with 1454 additions and 668 deletions
@@ -0,0 +1,110 @@
+# Skill: 生成模块设计总览页
+
+## 触发方式
+用户说"生成设计总览"、"design overview"或指定某个模块需要生成设计总览时触发。
+
+## 输入参数
+- **模块路径**（必须）：如 `employee-app/emergency-medical`
+- **模块中文名**（必须）：如 `应急就医员工端APP`
+
+## 执行流程
+
+### Step 1: 扫描模块页面结构
+1. 列出模块目录下所有 `.html` 文件
+2. 逐个读取每个 HTML 文件，识别：
+   - 页面标题和主要内容
+   - 弹窗/对话框（`display:none` 的 modal、mask、overlay、panel 等）
+   - Tab 切换 / 状态切换（语音/文字模式、展开/收起等）
+   - 触发弹窗的 CSS 类名和切换方式
+3. 读取 `doc/PRD.md`（如存在），获取业务主线分组
+
+### Step 2: 整理页面形态清单 & 复用已有截图
+1. 检查 `doc/screenshots/` 目录下已有的截图文件
+2. 将已有截图与页面一一对应（按文件名匹配）
+3. 标记出缺失的弹窗/状态截图（仅这些需要新截取）
+4. **已有截图直接复用，不重新截取**
+
+### Step 3: 截取缺失的弹窗截图
+
+**截图工具优先级**（按可用性依次尝试）：
+1. **agent-browser**（首选）：原生 Rust CLI，截图质量最好
+2. **chrome-devtools MCP**（备选）：通过 MCP 协议控制 Chrome
+3. **Puppeteer 脚本**（兜底）：使用 `_templates/screenshot-modals.js`
+
+#### 使用 agent-browser 截图：
+```bash
+agent-browser open "file:///<绝对路径>/<页面>.html"
+agent-browser set viewport 390 844 2
+# 触发弹窗状态
+agent-browser snapshot -i  # 获取元素 ref
+agent-browser click @eN    # 或用 evaluate 执行 JS
+agent-browser screenshot "<输出路径>.jpg"
+agent-browser close
+```
+
+#### 使用 Puppeteer 脚本截图（兜底方案）：
+编写 config.json 配置文件，只包含缺失的截图任务：
+```json
+{
+  "baseDir": "<模块路径>",
+  "tasks": [
+    { "page": "xxx.html", "output": "xxx-modal.jpg",
+      "action": "() => { /* 触发弹窗的JS */ }" }
+  ]
+}
+```
+运行：`node _templates/screenshot-modals.js <config.json>`
+
+**关键参数**（Puppeteer）：
+```javascript
+// 视口必须大于 phone-shell 尺寸（390px宽），避免布局溢出
+page.setViewport({ width: 500, height: 900, deviceScaleFactor: 1 });
+
+// 只截取 .phone-shell 元素，避免外壳嵌套感
+const shell = await page.$('.phone-shell');
+if (shell) await shell.screenshot({ path, type: 'jpeg', quality: 85 });
+```
+
+**截图规范（参考项目背景.md 7.4 节）**：
+- 输出格式：JPEG，质量 85%（兼顾清晰度与文件体积）
+- deviceScaleFactor 设为 1（设计总览卡片仅 260px 宽，不需要 2x 分辨率）
+- 单张截图体积控制在 **60KB 以内**，避免项目膨胀
+- 视口宽度 500px（大于 phone-shell 的 390px 避免溢出），高度 900px
+- 只截取 `.phone-shell` 元素的可视区域（不展开滚动内容），保持手机屏幕视角
+- 截图命名规范：`{页面名}-{状态}.jpg`，如 `emergency-chat-confirm.jpg`
+- 常规页面截图命名与 HTML 文件名一致（去掉 `.html`），如 `index.jpg`
+
+### Step 4: 生成 design-overview.html
+使用 `_templates/design-overview-template.html` 模板，填充：
+- 导航标题：`{模块中文名} · 设计总览`
+- 各业务主线 section（id 为 `sec-{英文缩写}`）
+- 每张截图一个 card，包含图片、标签名、弹窗/状态标记
+- **截图路径必须与 `doc/screenshots/` 下的实际文件名一致**
+
+**样式规范（必须与模板一致）**：
+- 暗色背景 `#1a1a2e`
+- 卡片尺寸 `260×564px`（手机比例 375:812 的 ~70%）
+- 每条业务线横向滚动不换行（`overflow-x: auto`）
+- 弹窗标记用橙色 tag `tag--modal`
+- 状态切换标记用蓝色 tag `tag--state`
+- 点击图片灯箱放大查看
+
+### Step 5: 注册到导航页
+在根目录 `index.html` 的 `SITE_MAP` 中，找到对应模块的 `pages` 数组，在第一个位置插入：
+```javascript
+{ file:'../doc/design-overview.html', label:'页面总览' },
+```
+
+## 输出物
+1. `{模块目录}/doc/design-overview.html` — 设计总览页
+2. `{模块目录}/doc/screenshots/*-{状态}.jpg` — 新截取的弹窗截图（仅缺失部分）
+3. 根 `index.html` SITE_MAP 更新
+
+## 注意事项
+- **复用优先**：已有截图绝不重新截取，只补拍缺失的弹窗/状态截图
+- 截图脚本 `_templates/screenshot-modals.js` 放在 _templates 目录，每个模块复用
+- Puppeteer 视口必须设为 `500x900`（大于 phone-shell 的 390px），避免"空白页嵌套小页面"问题
+- 截图只截取 `.phone-shell` 元素，不截整个页面
+- 所有模块的 design-overview 共用同一套 CSS 样式（从模板复制）
+- 不要遗漏任何页面形态（弹窗、Tab 状态、展开/收起等）
+- 截图配置 json 文件用完后保留在项目根目录，方便后续重新截取