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

- 截图规范统一:JPEG 质量85% + 分终端目录 + 只截主界面/详情页 + 全屏视口(1440×900)
- 内容通用化:全文去除客户名称与项目名称,文档可供任意客户阅读
- 交付格式规范:.md 为源 + 竖版 A4 PDF 最终交付,明确分页三原则
- PRD 合并优化:系统功能清单 HTML 表格(rowspan)替代页面清单,清理 .html 文件名与来源说明区
- 业务架构图模板重构:应用与服务层改横排竖版板块 + 层间横向分隔线
- .gitignore 忽略 /交付文档/ 目录;记忆新增操作手册截图规范

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
fengpu
2026-09-10 17:07:54 +08:00
co-authored by Claude Opus 4.7
parent 256b741c8f
commit b5a8b83e6d
15 changed files with 324 additions and 136 deletions
+116 -34
View File
@@ -2,6 +2,18 @@
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<!--
业务架构图模板(doc-detailed-design skill 使用)
说明:
- 四层自上而下:用户交互层 / 应用与服务层 / 数据整合层 / 数据服务层,层间用横向分隔线(.divider)分隔
- 应用与服务层:按「一级菜单」分组为横排竖版板块(.domain),板块内功能项竖版排列
· .d-item = Web 管理端功能(蓝底标签)
· .d-item--app = 员工端 APP 功能(绿底标签,建议 📱 前缀)
· .domain-model = 智能模型类板块(虚线特殊样式)
· .legend = 底部双端图例
- 板块数量按子系统一级菜单数调整;菜单过多时可精简功能项或分两行
- 标题/副标题/各层内容由 skill 按子系统替换
-->
<style>
*{margin:0;padding:0;box-sizing:border-box;}
body{font-family:"Microsoft YaHei","PingFang SC",sans-serif;background:#fff;padding:28px 24px;width:960px;}
@@ -11,7 +23,6 @@
.subtitle{font-size:12px;color:#7b8ba0;margin-top:6px;letter-spacing:2px;}
.layer{display:flex;border-radius:14px;overflow:hidden;box-shadow:0 4px 16px rgba(24,80,140,.08);margin-bottom:0;}
.layer + .arrow{margin:0 auto;}
.side{width:34px;display:flex;align-items:center;justify-content:center;font-size:18px;color:#fff;writing-mode:vertical-rl;letter-spacing:4px;}
.body{flex:1;padding:16px 20px;}
.lname{font-size:14px;font-weight:800;display:flex;align-items:center;gap:8px;margin-bottom:12px;}
@@ -19,18 +30,35 @@
.items{display:flex;flex-wrap:wrap;gap:8px;}
.item{font-size:12px;padding:7px 13px;border-radius:8px;background:#fff;border:1px solid rgba(0,0,0,.06);box-shadow:0 2px 6px rgba(0,0,0,.04);color:#3a4c66;}
/* 层间横向分隔线 */
.divider{display:flex;align-items:center;height:22px;padding:0 4px;}
.divider-line{flex:1;height:1px;background:linear-gradient(90deg,transparent,#bcd2ec 18%,#bcd2ec 82%,transparent);}
/* 用户交互层 */
.l1{background:linear-gradient(135deg,#e8f4ff,#d8ecff);}
.l1 .side{background:linear-gradient(180deg,#4da3ff,#1d7be0);}
.l1 .lname{color:#0a5cb8;}
.l1 .item{border-color:#c3e2ff;}
/* 应用与服务层 */
/* 应用与服务层(竖版板块横排一行) */
.l2{background:linear-gradient(135deg,#eef3ff,#e4ecff);}
.l2 .side{background:linear-gradient(180deg,#7a9bff,#4a6fe0);}
.l2 .lname{color:#3d57c9;}
.l2 .item{border-color:#d4dfff;}
.model{background:linear-gradient(135deg,#e6f7ff,#d9f0ff);border:1px dashed #69c0ff;color:#0a5cb8;font-weight:700;}
.domains{display:flex;gap:8px;align-items:stretch;}
.domain{flex:1;min-width:0;background:#fff;border:1px solid #d4dfff;border-radius:10px;padding:10px 6px;box-shadow:0 2px 6px rgba(0,0,0,.04);display:flex;flex-direction:column;}
.domain-head{font-size:12px;font-weight:800;color:#3d57c9;margin-bottom:8px;text-align:center;display:flex;align-items:center;justify-content:center;gap:4px;line-height:1.2;}
.domain-head::before{content:'';width:4px;height:13px;background:linear-gradient(180deg,#7a9bff,#4a6fe0);border-radius:2px;flex-shrink:0;}
.domain-items{display:flex;flex-direction:column;gap:5px;}
.d-item{font-size:10.5px;padding:5px 4px;border-radius:6px;background:#f3f6ff;border:1px solid #d4dfff;color:#3a4c66;text-align:center;white-space:nowrap;line-height:1.3;}
.d-item--app{background:#e9f9f0;border:1px solid #b7ebc8;color:#1d7a45;}
.domain-model{background:linear-gradient(135deg,#e6f7ff,#d9f0ff);border:1px dashed #69c0ff;}
.domain-model .domain-head{color:#0a5cb8;}
.domain-model .domain-head::before{background:linear-gradient(180deg,#69c0ff,#1890ff);}
.domain-model .d-item{background:#fff;border-color:#91d5ff;color:#0a5cb8;font-weight:600;}
.legend{display:flex;gap:14px;margin-top:10px;font-size:10.5px;color:#7b8ba0;align-items:center;}
.legend .dot{display:inline-block;width:10px;height:10px;border-radius:3px;margin-right:4px;vertical-align:-1px;}
.legend .dot--mgmt{background:#f3f6ff;border:1px solid #d4dfff;}
.legend .dot--app{background:#e9f9f0;border:1px solid #b7ebc8;}
/* 数据整合层 */
.l3{background:linear-gradient(135deg,#e9fbf8,#ddf6f1);}
@@ -43,54 +71,107 @@
.l4 .side{background:linear-gradient(180deg,#6b8cff,#3f5bd8);}
.l4 .lname{color:#2f4abf;}
.l4 .item{background:#f3f6ff;border-color:#d3dcf7;}
.arrow{display:flex;justify-content:center;align-items:center;height:30px;}
.arrow-line{width:2px;height:100%;background:linear-gradient(180deg,#4da3ff,#2ba8a0);}
.arrow-dot{width:10px;height:10px;border-left:2px solid #4da3ff;border-bottom:2px solid #4da3ff;transform:rotate(-45deg);margin-top:-2px;}
</style>
</head>
<body>
<div class="wrap">
<div class="head">
<div class="title">体重管理系统业务架构图</div>
<div class="subtitle">数据驱动 · 智能指导 · 闭环管理</div>
<div class="title">{子系统名}业务架构图</div>
<div class="subtitle">{核心理念副标题,如:数据驱动 · 智能监测 · 闭环管理}</div>
</div>
<!-- 用户交互层 -->
<!-- 用户交互层:按端替换(员工端 + 管理端) -->
<div class="layer l1">
<div class="side">用户交互层</div>
<div class="body">
<div class="lname">用户交互层(应用层)<span class="ltag">价值呈现端</span></div>
<div class="items">
<div class="item">👤 油田员工 · 健康长庆 APP / 小程序</div>
<div class="item">🖥️ 管理专员 · 管理后台</div>
<div class="item">👤 企业员工 · 员工端 APP</div>
<div class="item">🖥️ 管理专员 · 管理后台Web 管理端)</div>
</div>
</div>
</div>
<div class="arrow"><div class="arrow-line"></div></div>
<div class="divider"><div class="divider-line"></div></div>
<!-- 应用与服务层 -->
<!-- 应用与服务层:按一级菜单分组为横排竖版板块;d-item=管理端,d-item--app=员工端 -->
<div class="layer l2">
<div class="side">应用与服务层</div>
<div class="body">
<div class="lname">应用与服务层<span class="ltag">业务中枢</span></div>
<div class="items">
<div class="item">活动管理</div>
<div class="item">报名管理</div>
<div class="item">每日打卡</div>
<div class="item">吃动平衡</div>
<div class="item">数据分析</div>
<div class="item">自我管理</div>
<div class="item">员工档案</div>
<div class="item">数据接入</div>
<div class="item model">🧠 营养膳食模型</div>
<div class="item model">🏃 运动处方模型</div>
<div class="domains">
<div class="domain">
<div class="domain-head">健康档案</div>
<div class="domain-items">
<span class="d-item">个人监测数据</span>
<span class="d-item">单位报表数据</span>
<span class="d-item">算法模型</span>
</div>
</div>
<div class="domain">
<div class="domain-head">健康现状</div>
<div class="domain-items">
<span class="d-item">员工评估信息</span>
<span class="d-item">单位评估统计</span>
<span class="d-item d-item--app">📱 现状仪表盘</span>
</div>
</div>
<div class="domain">
<div class="domain-head">健康排查</div>
<div class="domain-items">
<span class="d-item">问卷管理</span>
<span class="d-item">活动管理</span>
<span class="d-item d-item--app">📱 活动参与</span>
<span class="d-item d-item--app">📱 问卷填写</span>
</div>
</div>
<div class="domain">
<div class="domain-head">穿戴监测</div>
<div class="domain-items">
<span class="d-item">设备管理</span>
<span class="d-item">用户数据</span>
<span class="d-item">告警记录</span>
<span class="d-item">数据统计</span>
<span class="d-item">运维中心</span>
<span class="d-item d-item--app">📱 指标详情</span>
<span class="d-item d-item--app">📱 预警历史</span>
</div>
</div>
<div class="domain">
<div class="domain-head">健康环境</div>
<div class="domain-items">
<span class="d-item">设备管理</span>
<span class="d-item">数据监测</span>
<span class="d-item">异常报警</span>
<span class="d-item">数据分析</span>
<span class="d-item d-item--app">📱 地图查看</span>
<span class="d-item d-item--app">📱 设备详情</span>
<span class="d-item d-item--app">📱 报警数据</span>
</div>
</div>
<div class="domain">
<div class="domain-head">异常事件</div>
<div class="domain-items">
<span class="d-item">系统脏数据</span>
<span class="d-item">结果异常</span>
</div>
</div>
<div class="domain domain-model">
<div class="domain-head">智能模型</div>
<div class="domain-items">
<span class="d-item">🧠 健康评估模型</span>
<span class="d-item">🚨 告警预警模型</span>
</div>
</div>
</div>
<div class="legend">
<span><span class="dot dot--mgmt"></span>Web 管理端功能</span>
<span><span class="dot dot--app"></span>员工端 APP 功能</span>
</div>
</div>
</div>
<div class="arrow"><div class="arrow-line"></div></div>
<div class="divider"><div class="divider-line"></div></div>
<!-- 数据整合层 -->
<!-- 数据整合层:通用,一般无需替换 -->
<div class="layer l3">
<div class="side">数据整合层</div>
<div class="body">
@@ -103,18 +184,19 @@
</div>
</div>
</div>
<div class="arrow"><div class="arrow-line"></div></div>
<div class="divider"><div class="divider-line"></div></div>
<!-- 数据服务层 -->
<!-- 数据服务层:按子系统对接的硬件/设备替换 -->
<div class="layer l4">
<div class="side">数据服务层</div>
<div class="body">
<div class="lname">数据服务层<span class="ltag">数据感知网络</span></div>
<div class="items">
<div class="item">🍚 食堂智能餐线</div>
<div class="item"> 智能体脂秤</div>
<div class="item">⌚ 智能穿戴设备</div>
<div class="item">🏋️ 运动器械</div>
<div class="item">⌚ 智能穿戴设备(手表)</div>
<div class="item">🌡 室内空气监测设备</div>
<div class="item">🌤️ 室外空气监测设备</div>
<div class="item">💧 水质监测设备</div>
<div class="item">🌸 花粉监测设备</div>
</div>
</div>
</div>
+3 -1
View File
@@ -9,7 +9,9 @@
用途:doc-brochure skill 的生成骨架
说明:{占位符} 由 skill 填充;横版 A4(297×210mm)分页,便于打印/转 PDF
转 PDF@page 已设 A4 landscape,浏览器打印(Ctrl+P)或 headless 截图即可
约束:宣传册必须通用,不得现客户信息(如"油田"、客户公司名等
约束:宣传册必须通用,不得现客户名称与项目名称(客户公司名、甲方名称、委托方、油田等一律不写
分页:每 .page 一页(297×210mm 横版 A4),内容需在该页内铺满且不溢出(overflow:hidden 兜底),
避免同一版块的文字与截图被切到下一页
-->
<style>
:root{
@@ -2,6 +2,19 @@
数据库设计说明书模板
用途:doc-database-design skill 的生成骨架,表结构格式沿用「doc/体重管理项目系统设计说明.docx」5.3 节
填写约定:{占位符} 由 skill 依据研发提供的 SQL 文件解析填充
通用约束:全文不得出现客户名称与项目名称,只介绍数据库自身设计,产出文档可供任意客户与人群阅读。
PDF 导出规范(竖版 A4):
- 版式:竖版 A4(210×297mm),最终交付为 PDF;本 .md 为源,导出时按下方分页原则处理
- 分页三原则:① 标题不孤行(标题与其后内容同页)② 图文不割裂 ③ 表行不切割
(字段表单行、数据字典表单行不被水平切成两页)
- 可选 CSS(浏览器 / Puppeteer 系导出工具):
@page { size: A4 portrait; margin: 18mm 16mm; }
h1,h2,h3,h4 { page-break-after: avoid; }
img, pre, blockquote { page-break-inside: avoid; }
tr { page-break-inside: avoid; }
- 无法避免的跨页(超大字段表等)由使用方在导出时自行处理
-->
# {子系统名}数据库设计说明书
+16 -3
View File
@@ -4,6 +4,20 @@
填写约定:{占位符} 由 skill 依据「子系统页面清单 + 项目背景.md + 各终端 PRD.md」自动填充
架构图:业务架构图/技术架构图用 H5 布局生成后截图,以 PNG 引用(见 doc-detailed-design skill
HTML 注释(<!-- -->)仅作填写指引,转 PDF 时不会显示
通用约束:全文不得出现客户名称与项目名称(客户公司名、甲方名称、委托方等一律不写),
只介绍系统自身概况,产出文档可供任意客户与人群阅读。
PDF 导出规范(竖版 A4):
- 版式:竖版 A4(210×297mm),最终交付为 PDF;本 .md 为源,导出时按下方分页原则处理
- 分页三原则:① 标题不孤行(标题与其后内容同页)② 图文不割裂(图片与其说明/标题同页)
③ 表行不切割(表格单行不被水平切成两页)
- 可选 CSS(浏览器 / Puppeteer 系导出工具):
@page { size: A4 portrait; margin: 18mm 16mm; }
h1,h2,h3,h4 { page-break-after: avoid; }
img, pre, blockquote { page-break-inside: avoid; }
tr { page-break-inside: avoid; }
- 无法避免的跨页(超大表格 / 超长截图)由使用方在导出时自行处理
-->
# {子系统名}详细设计说明书
@@ -12,8 +26,7 @@
| 项 | 内容 |
|----|------|
| 项目名称 | 健康CQ升级 —— {子系统名} |
| 委托方 | CQ能源公司 |
| 系统名称 | {子系统名} |
| 文档类型 | 系统详细设计说明书 |
| 版本号 | V1.0 |
| 编制日期 | {YYYY-MM-DD} |
@@ -26,7 +39,7 @@
## 一、项目背景
{一段话:先交代健康CQ升级平台整体背景,再落到本子系统定位}
{一段话:先交代企业健康管理平台整体背景,再落到本子系统定位}
- 素材来源:`项目背景.md` 6.1 节 + 本子系统各终端 PRD 的「模块概述」段
## 二、建设目标
+21 -2
View File
@@ -2,6 +2,25 @@
操作手册模板
用途:doc-operation-manual skill 的生成骨架
粒度:按「子系统 + 终端」分册,每个终端单独一份操作手册
截图规范(必须遵守):
- 范围:只截「主界面」+「重要表单/详情页」;弹窗、筛选下拉等轻量交互不单独截图,在功能描述/注意事项中用文字或表格说明
- 规格:JPEG 质量 85%(清晰度优先,不设文件大小上限),APP 端宽度 390px、Web 端视口 1440×900(截图前确保浏览器全屏,避免截图不完整/比例失调,参考 项目背景.md 7.4 节 PRD 截图规范)
- 目录:按终端分目录 screenshots/{终端目录}/employee-app / web-admin / medical-pad 等),截图命名用中文页面名
- 引用:相对路径 screenshots/{终端目录}/{页面名}.jpg
通用约束:全文不得出现客户名称与项目名称,只介绍系统自身操作,产出文档可供任意客户与人群阅读。
PDF 导出规范(竖版 A4):
- 版式:竖版 A4(210×297mm),最终交付为 PDF;本 .md 为源,导出时按下方分页原则处理
- 分页三原则:① 标题不孤行(标题与其后内容同页)② 图文不割裂(操作步骤/截图/注意事项作为一个版块,
图片与其标题不跨页)③ 表行不切割(常见问题表格单行不被水平切成两页)
- 可选 CSS(浏览器 / Puppeteer 系导出工具):
@page { size: A4 portrait; margin: 18mm 16mm; }
h1,h2,h3,h4 { page-break-after: avoid; }
img, pre, blockquote { page-break-inside: avoid; }
tr { page-break-inside: avoid; }
- 无法避免的跨页(超长截图等)由使用方在导出时自行处理
-->
# {子系统名} · {终端名}操作手册
@@ -28,7 +47,7 @@
### 1.2 适用对象
{本终端面向的用户角色,如:平台管理员 / 能源员工 / 体检医生 / 医疗点医护人员}
{本终端面向的用户角色,如:平台管理员 / 企业员工 / 体检医生 / 医疗点医护人员}
### 1.3 运行环境
@@ -68,7 +87,7 @@
**界面截图**
![{功能点}]({截图相对路径})
![{功能点}](screenshots/{终端目录}/{页面名}.jpg)
**注意事项**
- {注意点1}
+51 -61
View File
@@ -2,70 +2,76 @@
产品需求文档(合并版)模板
用途:doc-prd-merge skill 的生成骨架
核心逻辑:同一子系统的多个终端已各自维护 doc/PRD.md,本模板用于「合成一份新文件」,不改动原有 PRD、沿用现有截图
交付定位:单独交付(不与原型代码一起交付),文档内不得出现页面文件路径与页面文件名
通用约束:全文不得出现客户名称与项目名称,只介绍产品需求本身,产出文档可供任意客户与人群阅读。
PDF 导出规范(竖版 A4):
- 版式:竖版 A4(210×297mm),最终交付为 PDF;本 .md 为源,导出时按下方分页原则处理
- 分页三原则:① 标题不孤行(标题与其后内容同页)② 图文不割裂(页面标题/截图/功能说明作为一个版块,
图片与其标题不跨页)③ 表行不切割(「系统功能清单」HTML 表格含 rowspan 合并单元格,
导出时尤需保证合并单元整体不被水平切成两页)
- 可选 CSS(浏览器 / Puppeteer 系导出工具):
@page { size: A4 portrait; margin: 18mm 16mm; }
h1,h2,h3,h4 { page-break-after: avoid; }
img, pre, blockquote { page-break-inside: avoid; }
tr { page-break-inside: avoid; }
- 无法避免的跨页(超大功能清单表 / 超长截图)由使用方在导出时自行处理
-->
# {子系统名}产品需求文档
<!-- 合并说明:标注来源,便于追溯 -->
> 本文档由以下终端 PRD 合并生成(原始文件未改动):
> - {终端1}{原 PRD 相对路径}
> - {终端2}{原 PRD 相对路径}
---
## 1. 子系统概述
{整合各终端「模块概述」,改写成统一的一段,覆盖本子系统所有终端的整体功能}
- 素材:各终端 PRD 的「模块概述」段
### 页面导航结构
### 系统功能清单
{按端分组,呈现统一的导航结构树。每端沿用原 PRD 的导航结构树,加一级「{端名}」前缀}
{按端分组,用 HTML 表格 + rowspan 合并单元格呈现功能层级,三列:功能模块 / 功能子模块 / 功能点}
{合并规则:列1「功能模块」= 一级菜单,rowspan 合并;列2「功能子模块」= 二级菜单,rowspan 合并;列3「功能点」= 叶子功能,每行一个}
{无二级子模块的模块(如健康现状),列2 留空即可}
```
{子系统名}
├── {端1(如 Web管理端)}
│ ├── {一级菜单1}
│ │ ├── {二级菜单/页面}
│ │ └── ...
│ └── ...
├── {端2(如 员工端APP}
│ └── ...
└── ...
```
#### {端1(如 Web管理端)}
### 状态流转图
<table border="1" cellspacing="0" cellpadding="8" style="border-collapse:collapse; font-size:14px;">
<thead>
<tr>
<th style="width:120px;">功能模块</th>
<th style="width:220px;">功能子模块</th>
<th>功能点</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="2">档案</td>
<td rowspan="2">个人监测数据</td>
<td>个人监测数据列表</td>
</tr>
<tr>
<td>个人监测详情</td>
</tr>
<tr>
<td>健康现状</td>
<td></td>
<td>员工评估信息</td>
</tr>
</tbody>
</table>
```mermaid
{合并各端状态流转图;若无则本小节省略}
```
#### {端2}
## 2. 页面清单
{同上}
{按端分组,每端沿用原 PRD 的页面清单表格;公共页面(登录/消息等)归入「公共部分」小节,不重复罗列}
## 2. 逐页说明
### 公共部分
| 页面/弹窗 | 文件 | 所属 | 类型 |
|-----------|------|------|------|
{按端分组,每页标题仅保留功能名(不含文件名),截图路径改为从本文档位置指回原模块 doc/screenshots/ 的相对路径}
### {端1}
{沿用原 PRD 页面清单表格}
#### {页面功能名}
### {端2}
{沿用原 PRD 页面清单表格}
## 3. 逐页说明
{按端分组,每端沿用原 PRD 逐页说明;截图路径改为从本文档位置指回原模块 doc/screenshots/ 的相对路径}
### {端1}
#### {页面1}
![{页面1}]({指回原截图的相对路径})
![{页面功能名}]({指回原截图的相对路径})
**功能说明**{沿用原文}
@@ -73,24 +79,8 @@
**交互说明**{沿用原文}
#### {页面2}
{同上}
### {端2}
{同上}
## 4. 表单字段表
{按端分组,合并各端原 PRD 的表单字段表}
### {端1}
| 字段名 | 类型 | 是否必填 | 校验规则 |
|--------|------|---------|---------|
### {端2}
| 字段名 | 类型 | 是否必填 | 校验规则 |
|--------|------|---------|---------|
{表单字段表:仅当各终端原 PRD 存在独立「表单字段表」段时才合并生成,否则本部分省略}