From 982cb1c068a9a23a74248de27ba8d49e2b058061 Mon Sep 17 00:00:00 2001 From: fengpu <18691763612@163.com> Date: Wed, 9 Sep 2026 18:17:21 +0800 Subject: [PATCH] =?UTF-8?q?feat=EF=BC=9A=E6=95=B4=E7=90=86=E4=BA=A7?= =?UTF-8?q?=E5=93=81=E6=96=87=E6=A1=A3=E7=94=9F=E6=88=90=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E5=8C=85=E4=BB=A5=E5=8F=8A=E6=96=87=E6=A1=A3=E6=A8=A1=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../SKILL.md} | 5 + .claude/skills/doc-brochure/SKILL.md | 68 +++++ .claude/skills/doc-database-design/SKILL.md | 74 ++++++ .claude/skills/doc-detailed-design/SKILL.md | 92 +++++++ .claude/skills/doc-operation-manual/SKILL.md | 77 ++++++ .claude/skills/doc-prd-merge/SKILL.md | 73 ++++++ _templates/docs/architecture-business.html | 123 ++++++++++ _templates/docs/architecture-technical.html | 164 +++++++++++++ _templates/docs/brochure-template.html | 197 +++++++++++++++ _templates/docs/common-sections-template.md | 57 +++++ _templates/docs/database-design-template.md | 96 ++++++++ _templates/docs/detailed-design-template.md | 232 ++++++++++++++++++ _templates/docs/merge-prd.js | 92 +++++++ _templates/docs/operation-manual-template.md | 96 ++++++++ _templates/docs/parse-sql.js | 207 ++++++++++++++++ _templates/docs/prd-merge-template.md | 96 ++++++++ 16 files changed, 1749 insertions(+) rename .claude/skills/{design-overview.md => design-overview/SKILL.md} (96%) create mode 100644 .claude/skills/doc-brochure/SKILL.md create mode 100644 .claude/skills/doc-database-design/SKILL.md create mode 100644 .claude/skills/doc-detailed-design/SKILL.md create mode 100644 .claude/skills/doc-operation-manual/SKILL.md create mode 100644 .claude/skills/doc-prd-merge/SKILL.md create mode 100644 _templates/docs/architecture-business.html create mode 100644 _templates/docs/architecture-technical.html create mode 100644 _templates/docs/brochure-template.html create mode 100644 _templates/docs/common-sections-template.md create mode 100644 _templates/docs/database-design-template.md create mode 100644 _templates/docs/detailed-design-template.md create mode 100644 _templates/docs/merge-prd.js create mode 100644 _templates/docs/operation-manual-template.md create mode 100644 _templates/docs/parse-sql.js create mode 100644 _templates/docs/prd-merge-template.md diff --git a/.claude/skills/design-overview.md b/.claude/skills/design-overview/SKILL.md similarity index 96% rename from .claude/skills/design-overview.md rename to .claude/skills/design-overview/SKILL.md index 5f78932..39aa573 100644 --- a/.claude/skills/design-overview.md +++ b/.claude/skills/design-overview/SKILL.md @@ -1,3 +1,8 @@ +--- +name: design-overview +description: 生成模块设计总览页（页面形态清单 + 截图复用 + 设计总览 HTML）。当用户要求「生成设计总览」「design overview」时使用。 +--- + # Skill: 生成模块设计总览页 ## 触发方式 diff --git a/.claude/skills/doc-brochure/SKILL.md b/.claude/skills/doc-brochure/SKILL.md new file mode 100644 index 0000000..0b88249 --- /dev/null +++ b/.claude/skills/doc-brochure/SKILL.md @@ -0,0 +1,68 @@ +--- +name: doc-brochure +description: 生成指定子系统的《产品宣传册》（HTML 静态页，A4 分页排版，可直接转 PDF）。当用户要求「生成 XX 系统的宣传册/产品手册」时使用。 +--- + +# Skill：生成产品宣传册 + +## 触发方式 + +用户说「生成 XX 系统的宣传册」「做一份 XX 系统产品手册」时触发。 +参数「XX 系统」为业务域子系统名。 + +## 输入参数 + +- **子系统名**（必须，中文）：如 `体重管理系统` +- **Slogan / 价值主张**（可选）：缺省由 skill 依据子系统概述提炼 +- **平台品牌名**（可选）：缺省用通用名「企业健康管理平台」，不得含客户信息 + +## 模板与素材 + +- 模板：`_templates/docs/brochure-template.html` +- 素材：该子系统各终端 `doc/PRD.md` 的模块概述、页面清单；`项目背景.md` 的终端/角色说明 + +## 执行流程 + +### Step 1：采集子系统信息 + +1. 定位子系统各端目录（方法见 doc-detailed-design Step 1） +2. 读各端 PRD「模块概述」提炼：产品定位、核心价值、功能模块清单 +3. 从页面清单统计：终端数、功能模块数、页面数（用于概述页的指标卡片） +4. 从 `项目背景.md` 6.2 用户群体表提炼「终端覆盖 + 服务人群」 + +### Step 2：提炼宣传内容（精炼，忌堆砌） + +- **封面**：产品名 = 子系统名，Slogan 一句话价值主张，3 个关键词 tag +- **概述**：定位一句话 + 价值 2~3 句 + 4 个量化指标（终端/模块/页面/人群） +- **核心功能**：选 4~6 个最有代表性的功能模块，每个配 1 个 emoji 图标 + 简介 + 2 个亮点 +- **特色优势**：6 条优势（01~06 编号卡片） +- **终端覆盖**：列出该子系统覆盖的终端（每个配 emoji + 一句说明） + +### Step 3：填充 HTML 模板 + +1. 复制 `brochure-template.html`，将 `{占位符}` 替换为采集到的内容 +2. 功能模块页如超过 6 个功能，复制 `.feat` 卡片或新增一页「核心功能」 +3. 保持内联 CSS 与设计令牌不变，仅替换文字与 emoji +4. 确保所有 `{...}` 占位符都被替换，不留占位符残留 + +### Step 4：写入输出文件 + +输出到 `交付文档/{子系统名}/{子系统名}产品宣传册.html`。 + +### Step 5：转 PDF 检查（可选） + +- 宣传册模板已内置 `@page A4 landscape`（横版）与 `.page` 分页 +- 可用 headless 浏览器打印转 PDF，或直接交付 HTML（甲方以 HTML 浏览 / 转 PDF 均可） + +## 输出物 + +- `交付文档/{子系统名}/{子系统名}产品宣传册.html` + +## 注意事项 + +- **美观精炼**：宣传册面向客户，语言要有感染力，忌长篇技术描述；每页信息密度适中，元素丰富（图标/装饰/渐变卡片），避免单一 +- **横版分页**：每 `.page` 一屏一页（297×210mm 横版 A4），内容横向铺满，避免纵向留白 +- **配色统一**：沿用模板品牌蓝 `#1890FF` 设计令牌，不另造配色 +- **内容通用**：宣传册必须通用，不得体现客户信息（如「油田」、客户公司名、委托方名称等） +- emoji 图标用于视觉占位，正式交付如需替换为专业图标，告知用户 +- 文档名称「{子系统名}产品宣传册.html」为中文，符合甲方要求 diff --git a/.claude/skills/doc-database-design/SKILL.md b/.claude/skills/doc-database-design/SKILL.md new file mode 100644 index 0000000..007b8fe --- /dev/null +++ b/.claude/skills/doc-database-design/SKILL.md @@ -0,0 +1,74 @@ +--- +name: doc-database-design +description: 生成指定子系统的《数据库设计说明书》，根据研发提供的 SQL 文件解析表结构。当用户要求「生成 XX 系统的数据库设计说明书」并提供 SQL 文件/目录时使用。 +--- + +# Skill：生成数据库设计说明书 + +## 触发方式 + +用户说「生成 XX 系统的数据库设计说明书」并给出 SQL 文件或目录时触发。 +参数「XX 系统」为业务域子系统名。 + +## 输入参数 + +- **子系统名**（必须，中文）：如 `体重管理系统` +- **SQL 文件或目录**（必须）：研发提供的建表 SQL（单个 `.sql` 文件或含多个 SQL 的目录） + +## 模板与素材 + +- 模板：`_templates/docs/database-design-template.md` +- 解析脚本：`_templates/docs/parse-sql.js`（自动解析 PostgreSQL SQL，直接生成 Markdown） +- 表结构格式沿用 `doc/体重管理项目系统设计说明.docx` 5.3 节（注意：docx 为 MySQL 示例，本项目实际为 PostgreSQL） + +## 执行流程 + +### Step 1：定位 SQL 源 + +1. 用户指定的 SQL 文件/目录路径；目录则 Glob `**/*.sql` 收集全部 SQL 文件 +2. 逐个读取，定位 `CREATE TABLE` 语句 + +### Step 2：解析表结构（PostgreSQL） + +**本项目数据库为 PostgreSQL**，优先用脚本自动解析： + +```bash +node _templates/docs/parse-sql.js <输出md路径> <子系统名> PostgreSQL +``` + +脚本自动解析：`CREATE TABLE` 块、表注释、字段注释、主键、索引，并直接生成 Markdown。 + +**手动解析时**，PostgreSQL 格式规则： +- 表名：`CREATE TABLE "schema"."table" (` 中的 `table` +- 表注释：`COMMENT ON TABLE "schema"."table" IS '...'` +- 字段注释：`COMMENT ON COLUMN "schema"."table"."col" IS '...'` +- 主键：`ALTER TABLE ... ADD CONSTRAINT ... PRIMARY KEY ("col")`（本项目主键统一为雪花 `id`） +- 允许空值：`NOT NULL` → `NO`，否则 `YES` +- 数据类型+长度：`varchar(255)` → varchar/255；`numeric(6,2)` → numeric/6,2；`int8`/`int4`/`int2`/`timestamp(0)`/`date`/`text` → 长度空 + +### Step 3：按模板生成 + +按 `database-design-template.md` 生成： + +- **1. 概述**：数据库环境（PostgreSQL / UTF-8）+ 命名规范 + 设计原则（直接复用模板通用条文） +- **2. 数据表清单**：汇总所有表「表中文名（取表注释，无注释则暂留空）+ 英文表名 + 说明」，按业务模块分组 +- **3. 数据表结构说明**：每表一个小节，标题 `### 3.x {表中文名}({英文表名})`，字段表 7 列： + `| 序号 | 列名 | 数据类型 | 长度 | 主键 | 允许空值 | 列说明 |` +- **4. 表关系与 ER 图**：根据外键/关联字段推断表关系，生成 Mermaid `erDiagram`；无法推断则列出主外键关联说明 +- **5. 索引与约束设计**：整理主键、唯一索引、普通索引 +- **6. 数据字典**：整理枚举类字段（如状态、类型）的取值字典，从字段注释中的「0-xx,1-xx」描述提取 + +### Step 4：写入输出文件 + +输出到 `交付文档/{子系统名}/{子系统名}数据库设计说明书.md`。 + +## 输出物 + +- `交付文档/{子系统名}/{子系统名}数据库设计说明书.md` + +## 注意事项 + +- SQL 注释是字段中文说明的唯一来源，`COMMENT ON COLUMN` 缺失时列说明留空并汇总提示用户补充 +- 表结构字段表严格沿用 7 列格式（序号/列名/数据类型/长度/主键/允许空值/列说明） +- 若 SQL 无表注释，表中文名先留空，提醒用户补齐 +- 文档全部使用简体中文 diff --git a/.claude/skills/doc-detailed-design/SKILL.md b/.claude/skills/doc-detailed-design/SKILL.md new file mode 100644 index 0000000..b110fdc --- /dev/null +++ b/.claude/skills/doc-detailed-design/SKILL.md @@ -0,0 +1,92 @@ +--- +name: doc-detailed-design +description: 生成指定子系统的《详细设计说明书》（8 章正式框架）。当用户要求「生成/编写 XX 系统的详细设计说明书」「系统设计说明」「详细设计」时使用。参考 doc/体重管理项目系统设计说明.docx 的章节结构。 +--- + +# Skill：生成详细设计说明书 + +## 触发方式 + +用户说「生成 XX 系统的详细设计说明书」「编写 XX 系统设计说明书」「XX 系统详细设计」时触发。 +参数「XX 系统」为业务域子系统名，如「体重管理系统」「健康体检系统」。 + +## 输入参数 + +- **子系统名**（必须，中文）：如 `体重管理系统` +- **补充信息**（可选）：甲方名称、技术架构说明等，缺省用模板默认值 + +## 模板与素材 + +- 模板：`_templates/docs/detailed-design-template.md` +- 架构图模板：`_templates/docs/architecture-business.html`（业务架构图）、`_templates/docs/architecture-technical.html`（技术架构图） +- 公共章节素材：`_templates/docs/common-sections-template.md` +- 项目背景：根目录 `项目背景.md` +- 各终端 PRD：`{模块目录}/doc/PRD.md`（提供模块概述、导航结构、逐页说明） + +## 执行流程 + +### Step 1：定位子系统目录（多端） + +1. 读根目录 `index.html`，grep `SITE_MAP` 中 `name:'{子系统名}'` 的模块条目（同一子系统可能出现在多个端，如 Web 管理端与员工端 APP 各一条） +2. 每个条目提取两个字段： + - `dir`：模块英文目录（如 `web-admin/weight-management`） + - `prd`：PRD 文档路径（如 `web-admin/weight-management/doc/PRD.md`，部分模块可能缺失） +3. 汇总得到「端目录列表 + 各端 PRD 路径」 +4. 兜底：某端 `prd` 字段缺失时，用 Glob 检查 `{dir}/doc/PRD.md` 是否存在；SITE_MAP 未收录的独立产物（如 other-module 子设备）用 Glob 扫描补全 + +### Step 2：扫描页面清单 + +1. 对每个端目录，从 SITE_MAP 的 `pages` 数组读取页面（`file` + `label` 中文名） +2. 若 SITE_MAP 未覆盖（如 other-module 子设备），用 Glob 列目录下 `.html` 文件 +3. 读各端 `doc/PRD.md` 的「模块概述」「页面导航结构」段，获取业务主线分组（一级菜单/侧边栏组） + +### Step 3：填充模板 + +按 `detailed-design-template.md` 逐章填充： + +- **封面**：项目名 = `健康CQ升级 —— {子系统名}`，委托方 = CQ能源公司，日期 = 当天 +- **一、项目背景**：综合 `项目背景.md` 6.1 节 + 各端 PRD 模块概述 +- **二、建设目标**：分条，参考 docx「建设目标」句式（构建生态/打造引擎/实现追踪/建立评估） +- **三、需求说明与功能设计**： + - 3.1 需求概述：按端分列需求点 + - 3.2 功能清单：列表罗列各端菜单名称（后台 + 移动端分开） + - 3.3 业务架构设计：四层描述（交互层/应用服务层/整合层/数据服务层）+ 业务架构图（H5 生成后截图，见 Step 4） + - 3.4 核心业务详细设计：**按「端 → 功能模块（一级菜单）→ 功能点」三级展开**，每个功能点写「功能描述 + 功能点列表」 +- **四、技术架构**：基于实际技术栈（后端 Spring Cloud Alibaba + Nacos + PostgreSQL + Redis + RocketMQ + XXL-Job + MinIO + Feign + Sentinel + Sa-Token；前端 Qiankun 微前端 + Vue3 + Ant Design Vue）+ 技术架构图（H5 生成后截图） +- **五、数据库**：写概述 + 引用《{子系统名}数据库设计说明书》 +- **六、安全与可用性**：补全安全措施（身份认证/权限/加密/传输/审计/脱敏）+ 可用性设计（性能指标表，参考共性需求说明.md 性能要求） +- **七、部署与运维**：补全部署架构、环境划分、部署步骤、运维方案、告警机制 +- **八、售后服务**：可选，甲方无要求则标注「本章略」 + +### Step 4：并入公共章节 + +从 `common-sections-template.md` 复制「登录与认证 / 消息 / AI 助手 / 个人中心 / 组织架构」章节，作为「三、需求说明」下的「公共部分」小节，或按需融入各端功能设计。 + +### Step 5：架构图与截图引用 + +**架构图生成（业务架构图 + 技术架构图）**： +1. 复制 `_templates/docs/architecture-business.html` / `architecture-technical.html`，按子系统内容修改各层盒子的标题与子项 +2. 用浏览器打开 HTML，设置视口宽度 1008px、高度设为内容实际高度（用 JS 获取最后一个盒子底部位置 + body padding） +3. 截图保存为 `交付文档/{子系统名}/业务架构图.png`、`技术架构图.png` +4. 文档中引用 `![业务架构图](业务架构图.png)`、`![技术架构图](技术架构图.png)` + +**界面原型截图**： +- 沿用各端 `doc/screenshots/` 现有截图 +- 路径从输出文档位置指回：`../../{端目录}/doc/screenshots/{页面名}.jpg` +- 无截图则省略「界面原型」图，保留文字说明 + +### Step 6：写入输出文件 + +输出到 `交付文档/{子系统名}/{子系统名}详细设计说明书.md`，目录不存在则创建。 + +## 输出物 + +- `交付文档/{子系统名}/{子系统名}详细设计说明书.md` + +## 注意事项 + +- **截图沿用现有**，不重新截取；无现成截图就不放图 +- 技术架构/安全/部署/售后等通用章节可跨子系统复用，不必每次从零写 +- 3.3 核心业务详细设计是本说明书的主体，功能点要与页面清单一一对应，不得遗漏页面 +- 文档全部使用简体中文，表格、标题层级严格按模板 +- 不改动任何现有文件，只新建交付文档 diff --git a/.claude/skills/doc-operation-manual/SKILL.md b/.claude/skills/doc-operation-manual/SKILL.md new file mode 100644 index 0000000..d75d9a6 --- /dev/null +++ b/.claude/skills/doc-operation-manual/SKILL.md @@ -0,0 +1,77 @@ +--- +name: doc-operation-manual +description: 生成指定子系统、指定终端的《操作手册》。当用户要求「生成 XX 系统 XX 端操作手册」「编写 XX 端使用手册/操作说明」时使用。操作手册按「子系统 + 终端」分册。 +--- + +# Skill：生成操作手册 + +## 触发方式 + +用户说「生成 XX 系统的 XX 端操作手册」「编写 XX 端操作说明/使用手册」时触发。 +需同时指定「子系统名」和「终端名」。 + +## 输入参数 + +- **子系统名**（必须，中文）：如 `体重管理系统` +- **终端名**（必须，中文）：如 `Web管理端` / `员工端APP` / `体检医生工作台` / `医疗点PAD` +- **适用对象**（可选）：用户角色，缺省按终端推断 + +## 模板与素材 + +- 模板：`_templates/docs/operation-manual-template.md` +- 公共章节素材：`_templates/docs/common-sections-template.md` +- 素材：该终端 `doc/PRD.md` 的「逐页说明」（功能说明 + 交互说明）与截图 + +## 执行流程 + +### Step 1：定位目标终端目录 + +1. 读根目录 `index.html`，grep `SITE_MAP` 中 `name:'{子系统名}'` 的条目 +2. 根据「终端名」匹配所属端（SITE_MAP 顶层 `id`/`label`，如「Web管理端」→ `id:'web-admin'`），定位到唯一模块目录，如 `web-admin/weight-management` +3. 读该终端 `prd` 字段指向的 `doc/PRD.md`（缺失则 Glob 补查），获取页面清单与逐页说明 + +### Step 2：整理运行环境与适用对象 + +- 运行环境引用 `项目背景.md` 2.x 视觉规范对应终端尺寸： + - Web 管理端：浏览器，最小宽度 1280px，侧边栏 240px + - 员工端 APP：390×844（iPhone 14） + - 医疗点 PAD：1280×800 横屏 + - 微信小程序：375×812 +- 适用对象按终端推断（平台管理员/能源员工/体检医生/医疗点医护人员等） + +### Step 3：将 PRD 改写为操作手册 + +按 `operation-manual-template.md` 生成，核心是把 PRD 的「交互说明」从**设计视角改写为「用户操作视角」的分步操作**： + +- **1. 概述**：系统简介 + 适用对象 + 运行环境 + 登录说明（步骤化） +- **2. 界面总览**：布局说明 + 首页/工作台截图 + 导航结构 +- **3. 功能操作指南**：按「一级菜单/业务线」分组，每个功能点写： + - **操作步骤**（编号列表，从「进入某页面」到「完成某操作」） + - **界面截图**（沿用 PRD 截图） + - **注意事项**（从 PRD 业务规则提炼用户须知的要点） +- **4. 常见问题与故障处理**：提炼常见操作疑问与处理方法（表格） +- **5. 附录**：术语表 + 快捷操作 + +### Step 4：并入公共操作章节 + +从 `common-sections-template.md` 复制「登录与认证 / 消息 / AI 助手 / 个人中心」相关操作说明，并入第 3 章相应位置。 + +### Step 5：截图引用 + +- 沿用该终端 `doc/screenshots/` 现有截图 +- 路径从 `交付文档/{子系统名}/操作手册/` 指回：`../../../{端目录}/doc/screenshots/{页面名}.jpg` + +### Step 6：写入输出文件 + +输出到 `交付文档/{子系统名}/操作手册/{子系统名}{终端名}操作手册.md`。 + +## 输出物 + +- `交付文档/{子系统名}/操作手册/{子系统名}{终端名}操作手册.md` + +## 注意事项 + +- 操作手册面向**终端用户**，语言要通俗、步骤化，避免出现实现细节（如字段名、接口名） +- 截图沿用现有，不重新截图 +- 每个子系统的每个终端单独一份手册，公共操作（登录/消息等）在各手册中重复体现（甲方要求） +- 文档全部使用简体中文 diff --git a/.claude/skills/doc-prd-merge/SKILL.md b/.claude/skills/doc-prd-merge/SKILL.md new file mode 100644 index 0000000..c4e99cc --- /dev/null +++ b/.claude/skills/doc-prd-merge/SKILL.md @@ -0,0 +1,73 @@ +--- +name: doc-prd-merge +description: 将同一子系统的多个终端 PRD 合并成一份《产品需求文档》。当用户要求「合并 XX 系统的 PRD」「生成 XX 系统产品需求文档」时使用。只合成新文件，不改动现有各终端 PRD，沿用现有截图。 +--- + +# Skill：合并产品需求文档（PRD） + +## 触发方式 + +用户说「合并 XX 系统的 PRD」「生成 XX 系统产品需求文档」「整理 XX 系统 PRD」时触发。 +参数「XX 系统」为业务域子系统名。 + +## 输入参数 + +- **子系统名**（必须，中文）：如 `体重管理系统` + +## 模板与素材 + +- 模板：`_templates/docs/prd-merge-template.md` +- 素材：各终端已有的 `{模块目录}/doc/PRD.md`（**只读取，不改动**） + +## 执行流程 + +### Step 1：定位子系统各终端的 PRD + +1. 读根目录 `index.html`，grep `SITE_MAP` 中 `name:'{子系统名}'` 的条目，提取每条目的 `prd` 字段，得到「终端名 → PRD 路径」映射，如： + - Web管理端 → `web-admin/weight-management/doc/PRD.md` + - 员工端APP → `employee-app/weight-management/doc/PRD.md` +2. `prd` 字段缺失的端，用 Glob 检查 `{dir}/doc/PRD.md` 是否存在 +3. 确认每条 PRD 路径文件真实存在后再读取 + +### Step 2：读取各终端 PRD 内容 + +对每个 PRD，提取四类内容： +1. **模块概述**（`## 模块概述` 段 + 页面导航结构树） +2. **页面清单**（`## 页面清单` 段，表格） +3. **逐页说明**（`## 逐页说明` 段，含截图引用、功能说明、业务规则、交互说明） +4. **表单字段表**（`## 表单字段表` 段） + +### Step 3：按模板合成新文档 + +按 `prd-merge-template.md` 合成： + +- **标题**：`{子系统名}产品需求文档` +- **合并说明**：顶部标注各终端 PRD 来源路径（原始文件未改动） +- **1. 子系统概述**：整合各终端「模块概述」为统一一段 + 按端分组的统一导航结构树 + 状态流转图（如有） +- **2. 页面清单**：按端分组沿用原表格；**公共页面（登录/消息等）归入「公共部分」小节，不重复罗列** +- **3. 逐页说明**：按端分组沿用原文，截图路径改为「从本文档位置指回原模块 doc/screenshots/ 的相对路径」 +- **4. 表单字段表**：按端分组合并 + +### Step 4：重算截图相对路径 + +- 原 PRD 内截图引用为 `screenshots/xxx.jpg`（相对其所在 `doc/` 目录） +- 合并后文档位于 `交付文档/{子系统名}/{子系统名}产品需求文档.md` +- 指向 `web-admin/weight-management/doc/screenshots/xxx.jpg` 的相对路径为： + `../../web-admin/weight-management/doc/screenshots/xxx.jpg` +- 逐一改写合并文档中的截图路径，**沿用现有图片文件，不复制、不重新截图** + +### Step 5：写入输出文件 + +输出到 `交付文档/{子系统名}/{子系统名}产品需求文档.md`。 + +## 输出物 + +- `交付文档/{子系统名}/{子系统名}产品需求文档.md`（合并版，新文件） + +## 注意事项 + +- **绝对不改动现有各终端 PRD 文件**，只新建合并文档 +- **截图沿用现有**：用相对路径指回原位置，不复制图片、不重新截图 +- 同一子系统各终端 PRD 若存在同名的公共页面，只保留一处（归「公共部分」），避免重复 +- 页面清单、逐页说明、表单字段表均按「端」分组，保持各端内容完整可追溯 +- 文档全部使用简体中文 diff --git a/_templates/docs/architecture-business.html b/_templates/docs/architecture-business.html new file mode 100644 index 0000000..50331f1 --- /dev/null +++ b/_templates/docs/architecture-business.html @@ -0,0 +1,123 @@ + + + + + + + +
+
+
体重管理系统业务架构图
+
数据驱动 · 智能指导 · 闭环管理
+
+ + +
+
用户交互层
+
+
用户交互层（应用层）价值呈现端
+
+
👤 油田员工 · 健康长庆 APP / 小程序
+
🖥️ 管理专员 · 管理后台
+
+
+
+
+ + +
+
应用与服务层
+
+
应用与服务层业务中枢
+
+
活动管理
+
报名管理
+
每日打卡
+
吃动平衡
+
数据分析
+
自我管理
+
员工档案
+
数据接入
+
🧠 营养膳食模型
+
🏃 运动处方模型
+
+
+
+
+ + +
+
数据整合层
+
+
数据整合层（接入层）数据中枢
+
+
数据清洗
+
数据转换
+
数据加密
+
数据融合
+
+
+
+
+ + +
+
数据服务层
+
+
数据服务层数据感知网络
+
+
🍚 食堂智能餐线
+
⚖️ 智能体脂秤
+
⌚ 智能穿戴设备
+
🏋️ 运动器械
+
+
+
+
+ + diff --git a/_templates/docs/architecture-technical.html b/_templates/docs/architecture-technical.html new file mode 100644 index 0000000..62649b1 --- /dev/null +++ b/_templates/docs/architecture-technical.html @@ -0,0 +1,164 @@ + + + + + + + +
+
体重管理系统技术架构图
+ + +
+
前端层
+
+
前端层 · Qiankun 微前端（Monorepo：Turbo + npm workspaces）
+
+
主应用 main（基座）
+
体重管理子应用
+
营养管理子应用
+
健康监测子应用
+
专家咨询子应用
+
+
Vue 3.5
+
Ant Design Vue 4
+
Vite 8
+
Pinia
+
+
+
+
+ + +
+
接入层
+
+
接入层 · 统一入口
+
+
Nginx 反向代理 · 负载均衡
+
Spring Cloud Gateway · 统一鉴权 / 限流 / 路由
+
Sa-Token 认证授权
+
+
+
+
+ + +
+
服务层
+
+
服务层 · Spring Cloud Alibaba 微服务（Java 21 + Spring Boot 3.3）
+
+
体重管理服务
+
营养管理服务
+
健康监测服务
+
健康评估服务
+
专家咨询服务
+
应急就医服务
+
系统管理服务
+
+
Nacos 注册 / 配置
+
Feign 服务调用 + 降级
+
Sentinel 熔断限流
+
MyBatis-Plus ORM
+
+
+
+
+ + +
+
中间件层
+
+
中间件层 · 公共服务
+
+
Redis 缓存 / 分布式锁 / 幂等
+
RocketMQ 消息队列
+
XXL-Job 定时任务
+
MinIO 文件存储
+
+
+
+
+ + +
+
数据层
+
+
数据层 · 持久化存储
+
+
PostgreSQL 15 数据库
+
+
+
+
+ + +
+
运维监控
+
+
运维监控层 · 可观测性
+
+
Prometheus + Grafana 指标监控
+
SkyWalking 链路追踪
+
ELK 日志搜集分析
+
+
+
+
+ + diff --git a/_templates/docs/brochure-template.html b/_templates/docs/brochure-template.html new file mode 100644 index 0000000..efe4160 --- /dev/null +++ b/_templates/docs/brochure-template.html @@ -0,0 +1,197 @@ + + + + + +{子系统名} · 产品宣传册 + + + + + + +
+
+
+ + 产品宣传册 +
+
+
+
{子系统名}
+

{一句话 Slogan / 价值主张}

+
+ {关键词1} + {关键词2} + {关键词3} +
+
+
+
+
{解决方案定位}{编制日期}
+
+
+ + +
+
+
产品概述

{子系统定位一句话}

+

{产品价值说明，2~3 句}

+
+
📱
{N}{指标1}
+
🧩
{N}{指标2}
+
📄
{N}{指标3}
+
👥
{N}{指标4}
+
+

{补充说明}

+
+
+ + +
+
+
核心功能

{功能板块标题}

+
+
+
{emoji}

{功能名}

+

{功能简介}

+
  • {亮点1}
  • {亮点2}
+
+ +
+
+
+ + +
+
+
特色优势

为什么选择我们

+
+
01

{优势标题}

{优势说明}

+ +
+
+
+ + +
+
+
终端覆盖

多端协同，全场景覆盖

+
+
{emoji}
{终端名}{终端说明}
+ +
+
+
+ + +
+
+
{子系统名}
+
{感谢语 / 联系方式 / 口号}
+
{编制日期} · 版权所有
+
+
+ + + diff --git a/_templates/docs/common-sections-template.md b/_templates/docs/common-sections-template.md new file mode 100644 index 0000000..212c950 --- /dev/null +++ b/_templates/docs/common-sections-template.md @@ -0,0 +1,57 @@ + + +# 公共部分 + + + +## 一、登录与认证 + +### 功能说明 + +平台提供统一的账号密码登录入口，各终端（Web 管理端 / 员工端 APP / 健康应急 APP / 医疗点 PAD / 小程序）共用统一身份认证体系。 + +### 业务规则 + +- 用户账号由平台管理员统一创建并分配角色权限 +- 登录成功后按角色加载对应菜单与功能权限 +- 连续多次密码错误触发账号临时锁定 + +### 交互说明 + +1. 打开终端进入登录页 +2. 输入账号、密码 +3. 点击「登录」进入工作台/首页 + +## 二、消息与即时通讯 + +### 功能说明 + +提供站内消息通知与即时通讯能力，支持系统通知、业务提醒、点对点会话。 + +### 业务规则 + +- 系统通知按业务事件自动推送 +- 未读消息以角标形式在入口处提示 + +## 三、AI 助手 + +### 功能说明 + +提供智能问答与健康建议能力，支持文本输入、常见问题推送、数据统计。 + +## 四、个人中心 + +### 功能说明 + +提供当前登录用户的基本信息查看与维护、账号设置等能力。 + +## 五、组织架构与权限 + +### 功能说明 + +平台统一维护单位/部门/人员组织架构，各子系统共享组织架构数据，按角色控制功能访问权限。 diff --git a/_templates/docs/database-design-template.md b/_templates/docs/database-design-template.md new file mode 100644 index 0000000..dee5fa7 --- /dev/null +++ b/_templates/docs/database-design-template.md @@ -0,0 +1,96 @@ + + +# {子系统名}数据库设计说明书 + +| 项 | 内容 | +|----|------| +| 文档类型 | 数据库设计说明书 | +| 数据库 | PostgreSQL | +| Schema | {schema 名，如 platform-weight} | +| 字符集 | UTF-8 | +| 版本号 | V1.0 | +| 编制日期 | {YYYY-MM-DD} | + +--- + +## 目录 + + + +## 1. 概述 + +### 1.1 数据库环境 + +{数据库类型 / 版本 / Schema / 字符集} + +### 1.2 命名规范 + +{按 PostgreSQL 整理，如：} +- 采用 UTF-8 字符集 +- 表名统一按业务域前缀命名（如 `wm_` 表示体重管理域），采用小写下划线命名 +- 字段名采用小写下划线命名（如 `org_code`） +- 每张表均设置主键 `id`（雪花 ID，不表示业务含义），严禁大表使用 UUID/MD5 作主键 +- 必须为表、字段添加注释 +- 不使用数据库外键，表间关联由程序保证 +- 数据量可能很大的表（超 2000 万）采用分库/分表/分区表 + +### 1.3 设计原则 + +{沿用 docx 5.1 节：} +- **一致性原则**：统一、系统地分析与设计数据来源，保证数据一致性与有效性 +- **数据独立性原则**：数据空间独立、数据结构独立 +- **完整性原则**：对输入数据有审核和约束机制 +- **安全性原则**：认证与授权机制、数据隔离、实时备份、数据加密 +- **可伸缩性与可扩展性原则**：充分考虑发展与移植需要 +- **规范化**：遵循规范化理论，减少插入/删除/修改异常 + +## 2. 数据表清单 + +| 序号 | 表中文名 | 英文表名 | 说明 | +|------|---------|---------|------| +| 1 | {表中文名} | {table_name} | {一句话说明} | + + + +## 3. 数据表结构说明 + + + +### 3.1 {表中文名}({英文表名}) + +{表用途一句话} + +| 序号 | 列名 | 数据类型 | 长度 | 主键 | 允许空值 | 列说明 | +|------|------|---------|------|------|---------|--------| +| 1 | id | bigint(32) | | 是 | NO | ID | +| 2 | {col_name} | {varchar(255)} | {255} | 否 | {YES/NO} | {说明} | + +## 4. 表关系与 ER 图 + +```mermaid +erDiagram + {表A} ||--o{ {表B} : {关系说明} + {表A} { + bigint id PK + varchar col_name "说明" + } +``` + +## 5. 索引与约束设计 + +{主键索引 / 唯一索引 / 普通索引 / 外键约束（由程序保证）的说明} + +| 表 | 索引名 | 字段 | 类型 | 说明 | +|----|--------|------|------|------| + +## 6. 数据字典 + +{枚举类字段的取值字典，按字段分组} + +| 字段 | 取值 | 含义 | +|------|------|------| +| {state} | 0/1/2/3/4 | {各取值含义} | diff --git a/_templates/docs/detailed-design-template.md b/_templates/docs/detailed-design-template.md new file mode 100644 index 0000000..ee6ae01 --- /dev/null +++ b/_templates/docs/detailed-design-template.md @@ -0,0 +1,232 @@ +）仅作填写指引，转 PDF 时不会显示 +--> + +# {子系统名}详细设计说明书 + + + +| 项 | 内容 | +|----|------| +| 项目名称 | 健康CQ升级 —— {子系统名} | +| 委托方 | CQ能源公司 | +| 文档类型 | 系统详细设计说明书 | +| 版本号 | V1.0 | +| 编制日期 | {YYYY-MM-DD} | + +--- + +## 目录 + + + +## 一、项目背景 + +{一段话：先交代健康CQ升级平台整体背景，再落到本子系统定位} +- 素材来源：`项目背景.md` 6.1 节 + 本子系统各终端 PRD 的「模块概述」段 + +## 二、建设目标 + +{分条列建设目标，每条「动词 + 宾语 + 效果」结构，参考 docx「建设目标」章节} +- 示例句式：构建……生态体系 / 打造……核心引擎 / 实现……追踪与激励 / 建立……评估与决策支撑 + +## 三、需求说明与功能设计 + +### 3.1 需求概述 + +{按端分列，说明本子系统涉及哪些终端、每端实现哪些需求点} + +### 3.2 功能清单 + +{以列表/表格形式罗列各端菜单名称，后台 + 移动端分开罗列} + +**Web 管理端**： +- {一级菜单1}：{二级菜单/功能点罗列} +- {一级菜单2}：{……} + +**员工端 APP**： +- {业务线1}：{功能点罗列} +- {业务线2}：{……} + +### 3.3 业务架构设计 + +{分层描述业务架构，自上而下四层：用户交互层 → 应用与服务层 → 数据整合层 → 数据服务层} + +**业务架构图**： + +![业务架构图]({业务架构图.png 相对路径}) + +### 3.4 核心业务详细设计 + +{按「端 → 功能模块（一级菜单）→ 功能点（页面/弹窗）」三级展开。功能模块与功能清单对齐，功能点与页面/弹窗对齐} + +#### 3.4.1 {端名，如 Web管理端} + +##### 3.4.1.1 {功能模块1} + +**功能描述**：{一句话说明该模块用途} + +**功能点**： +- **{功能点名}**：{描述} +- **{功能点名}**：{描述} + +##### 3.4.1.2 {功能模块2} + +{同上结构} + +#### 3.4.2 {端名2} + +{同上结构} + +## 四、项目技术架构设计方案 + +### 4.1 系统技术架构 + +系统采用前后端分离架构，后端基于 Spring Cloud Alibaba 微服务体系，前端基于 Qiankun 微前端架构。 + +- **后端**：Java 21 + Spring Boot 3.3 + Spring Cloud Alibaba（Nacos 注册配置中心）；MyBatis-Plus 作为 ORM 框架；Sa-Token 统一认证授权；服务间调用采用 Feign（FallbackFactory 降级兜底）；熔断限流采用 Sentinel；PostgreSQL 15 数据存储；Redis 缓存与分布式锁；RocketMQ 消息队列；XXL-Job 定时任务；MinIO 文件存储。 +- **前端**：Qiankun 微前端 + Monorepo（Turbo + npm workspaces）；Vue 3 + TypeScript + Vite；Ant Design Vue 组件库；Pinia 状态管理；secure-ls（AES）与 jsencrypt（RSA）安全存储与传输。 + +**技术架构图**： + +![技术架构图]({技术架构图.png 相对路径}) + +### 4.2 系统技术选型说明 + +| 技术 | 服务类型 | 选型原因 | +|------|---------|---------| +| Java 21 | 开发语言 | 主流开发语言，LTS 版本，具备分布式、健壮性、安全性等特点 | +| Spring Boot 3.3 | 容器+MVC框架 | 简化配置，提高开发效率 | +| Spring Cloud Alibaba | 微服务框架 | Nacos 注册配置、Sentinel 熔断限流，与国内生态无缝集成 | +| Nacos | 注册配置中心 | 服务注册发现 + 动态配置管理 | +| MyBatis-Plus | ORM框架 | 主流 ORM 映射框架，简化 CRUD | +| Sa-Token | 认证授权 | 轻量级认证授权框架，支持 Token 会话 | +| Feign | 服务调用 | 声明式 HTTP 客户端，支持 FallbackFactory 降级 | +| Sentinel | 熔断限流 | 分布式系统流量防护，熔断、限流、降级 | +| PostgreSQL 15 | 数据库 | 开源关系型数据库，功能丰富、扩展性强 | +| Redis | 缓存 | 高性能缓存、分布式锁、幂等控制 | +| RocketMQ | 消息队列 | 分布式消息流平台，削峰填谷、异步解耦 | +| XXL-Job | 定时任务 | 分布式定时任务调度 | +| MinIO | 文件存储 | 开源对象存储系统 | +| Vue 3 + TypeScript | 前端框架 | 渐进式前端框架，类型安全 | +| Qiankun | 微前端 | 微前端框架，主子应用解耦 | +| Ant Design Vue | UI 组件库 | 企业级 UI 组件库 | +| Vite | 构建工具 | 新一代前端构建工具，快速冷启动 | +| nginx | 反向代理 | 高性能反向代理 Web 服务器，负载均衡 | +| docker | 容器技术 | 高性能、开源、轻量级容器引擎 | + +### 4.3 系统接口设计规范 + +- 接口命名用名词（资源），操作类型由 HTTP 动词表达 +- HTTP Method 对应资源 CURD；请求/返回格式优先 JSON +- 保证接口幂等性；URL 加入版本号 +- 参数与 URL 采用蛇行命名（如 `updated_time`） +- 使用 SSL 安全套接层 + +### 4.4 系统对接方案 + +#### 4.4.1 对接目标与原则 + +{标准与规范性 / 安全与保密性 / 可靠与稳定性 / 松耦合与可扩展性 四原则} + +#### 4.4.2 对接系统范围与内容分析 + +| 对接类别 | 具体对接系统/设备 | 核心对接内容与数据流向 | 对接方式 | +|---------|------------------|----------------------|---------| +| {内部企业系统 / 智能硬件与物联网} | {系统名} | {单向/双向 + 数据内容} | {RESTful API / 消息队列 / 数据库视图 / SFTP} | + +#### 4.4.3 技术架构与对接模式 + +{API 网关中心模式 / 混合对接 RESTful+JSON / 消息队列 / 数据库视图 / SFTP 文件传输} + +#### 4.4.4 数据安全与隐私保护方案 + +{传输安全 / 系统级认证 / 用户级授权 / 数据脱敏 / 数据最小化 / 沙箱测试环境} + +## 五、数据库结构设计方案 + +{概述一句 + 引用独立文档} + +> 本系统数据库表结构设计详见《{子系统名}数据库设计说明书》，本章不再赘述。 + +## 六、系统安全与可用性设计方案 + +### 6.1 系统安全防护措施 + +{补全安全措施，分条：} +- **身份认证**：统一身份认证体系，按角色控制功能访问权限 +- **权限控制**：基于角色的访问控制（RBAC），最小权限原则 +- **数据加密**：敏感数据传输加密（HTTPS/TLS 1.2+），数据库存储加密 +- **传输安全**：所有数据传输使用 HTTPS 加密，禁止明文传输敏感信息 +- **操作审计**：关键操作日志记录，支持追溯 +- **数据脱敏**：对外提供数据时对个人身份信息脱敏 + +### 6.2 系统可用性设计方案 + +{补全可用性设计，参考共性需求说明.md 性能要求：} + +**性能指标**： + +| 指标 | 标准 | +|------|------| +| 请求响应时间（RT） | 平均响应 1s 以下，统计查询接口 3s 以下 | +| 系统处理能力 | HPS 10000次/秒、TPS 3000笔/秒、QPS 5000次/秒 | +| 并发用户数 | 正常负载下支持并发 3000+ | +| 错误率 | 低于千分之六（成功率高于 99.6%） | +| 稳定性 | 7×24 小时稳定运行 | + +**高可用保障**： +- **高可用架构**：微服务集群部署，Nacos 服务注册发现，Nginx 负载均衡 +- **集群切换**：故障节点自动剔除，业务无中断，节点恢复无感知切换 +- **熔断限流**：Sentinel 熔断、限流、降级；Feign 调用 FallbackFactory 降级兜底 +- **幂等与并发控制**：Redis 分布式锁、接口幂等控制 +- **容灾备份**：全量 + 增量备份，以小时为单位周期循环 +- **监控告警**：Prometheus + Grafana 指标监控 + SkyWalking 链路追踪 + ELK 日志分析 + 告警通知 + +## 七、部署与运维方案 + +### 7.1 项目部署概述 + +{补全部署方案：} +- **部署架构**：Docker 容器化部署，前端 Nginx + 后端微服务集群，支持水平扩展 +- **环境划分**：local（本地）/ dev（开发）/ test（测试）/ uat（预生产）/ prod（生产），通过 Maven Profile 激活，配置由 Nacos 统一管理 +- **资源规划**：前端静态资源 Nginx 分发，数据库与缓存独立部署 +- **部署步骤**：环境准备 → 数据库初始化 → Nacos 配置 → 服务部署 → 网关配置 → 前端发布 + +### 7.2 项目运维方案 + +{补全运维方案，含运维架构与监控指标：} + +**运维架构**：系统运维监控体系由指标监控、链路追踪、日志分析三大支柱构成： +- 指标监控：Prometheus + Grafana +- 链路追踪：SkyWalking +- 日志分析：ELK（Elasticsearch + Logstash/Filebeat + Kibana） + +**监控核心指标**： + +| 监控维度 | 监控指标 | +|---------|---------| +| 系统资源 | CPU 使用率、内存使用率、磁盘 IO、网络吞吐 | +| JVM | 堆内存使用、GC 频率与耗时、线程数 | +| 应用接口 | QPS、接口响应时间（RT）、错误率、慢查询 | +| 中间件 | Redis 命中率/连接数、PostgreSQL 连接数/慢查询、RocketMQ 消息积压 | + +**告警机制**：接口故障或性能劣化时通过短信、邮件、钉钉即时通知；阈值告警（CPU > 80%、内存 > 80%、接口 RT > 3s、错误率 > 0.6% 等）触发 + +**升级策略**：灰度发布、版本回滚 +**备份策略**：数据库全量 + 增量备份、异地容灾 + +## 八、售后服务方案（可选章节） + + + +### 8.1 售后服务概述 +### 8.2 售后服务体系 +### 8.3 售后服务流程 +### 8.4 售后服务承诺 +### 8.5 售后服务计划 +### 8.6 技术支持响应承诺 diff --git a/_templates/docs/merge-prd.js b/_templates/docs/merge-prd.js new file mode 100644 index 0000000..34f7b80 --- /dev/null +++ b/_templates/docs/merge-prd.js @@ -0,0 +1,92 @@ +#!/usr/bin/env node +/** + * PRD 合并器：将同一子系统的多个终端 PRD 合并为一份《产品需求文档》 + * 用法：node merge-prd.js <子系统名> <输出md路径> <终端配置JSON> + * 终端配置JSON 形如： + * [{"name":"Web管理端","prd":"web-admin/weight-management/doc/PRD.md","shot":"../../web-admin/weight-management/doc/screenshots/"}] + * 说明：只读取各终端 PRD，不改动原始文件；截图路径改写为从合并文档位置指回原模块 + */ +const fs = require('fs'); + +const sysName = process.argv[2] || '体重管理系统'; +const outPath = process.argv[3] || `交付文档/${sysName}/${sysName}产品需求文档.md`; +const terms = process.argv[4] + ? JSON.parse(process.argv[4]) + : [ + { name: 'Web管理端', prd: 'web-admin/weight-management/doc/PRD.md', shot: '../../web-admin/weight-management/doc/screenshots/' }, + { name: '员工端APP', prd: 'employee-app/weight-management/doc/PRD.md', shot: '../../employee-app/weight-management/doc/screenshots/' }, + ]; + +// 提取某标记之后、到下一个 ##/### 标题之前的内容 +function sectionAfter(content, startMarker) { + const i = content.indexOf(startMarker); + if (i < 0) return ''; + const rest = content.slice(i + startMarker.length); + const m = rest.match(/\n##?\s/); + const end = m ? m.index : rest.length; + return rest.slice(0, end).trim(); +} + +// 提取两个标记之间的内容；end 标记不存在时返回空字符串 +function between(content, start, end) { + const i = content.indexOf(start); + if (i < 0) return ''; + let j = end ? content.indexOf(end, i + start.length) : content.length; + if (j < 0) return ''; + return content.slice(i + start.length, j).trim(); +} + +// 整合后的子系统概述（各子系统需定制，此处为体重管理示例） +const overview = `体重管理系统覆盖 Web 管理端与员工端 APP 两大终端，构建「目标设定—活动组织—过程监测—效果评估」的员工体重管理闭环。 + +- **Web 管理端**：为管理人员提供干预活动创建与管理、员工报名跟踪与目标体重审核、过程数据监测、历史活动归档、人员数据查询、个人目标管理、多类型体重测量设备管理及异常事件汇总等能力。 +- **员工端 APP**：为员工提供目标设定与审核、每日吃/动/体重打卡、吃动平衡分析、膳食与运动建议、体重记录与报告、排行榜，以及蓝牙体脂秤设备管理等能力。`; + +let md = ''; +md += `# ${sysName}产品需求文档\n\n`; +md += `> 本文档由以下终端 PRD 合并生成（原始文件未改动）：\n`; +terms.forEach(t => (md += `> - ${t.name}：\`${t.prd}\`\n`)); +md += `\n---\n\n`; +md += `## 1. 子系统概述\n\n${overview}\n\n`; + +// 页面导航结构（按端分组） +md += `### 页面导航结构\n\n`; +terms.forEach(t => { + const prd = fs.readFileSync(t.prd, 'utf8'); + let nav = between(prd, '### 页面导航结构', '### 状态流转图'); + if (!nav) nav = between(prd, '### 页面导航结构', '## 页面清单'); + md += `#### ${t.name}\n\n${nav}\n\n`; +}); + +// 状态流转图（存在才输出） +const firstPrd = fs.readFileSync(terms[0].prd, 'utf8'); +let stateDiagram = between(firstPrd, '### 状态流转图', '## 页面清单'); +if (!stateDiagram) { + for (let k = 1; k < terms.length; k++) { + const prd = fs.readFileSync(terms[k].prd, 'utf8'); + stateDiagram = between(prd, '### 状态流转图', '## 页面清单'); + if (stateDiagram) break; + } +} +if (stateDiagram) md += `### 状态流转图\n\n${stateDiagram}\n\n`; + +// 页面清单（按端分组） +md += `## 2. 页面清单\n\n`; +terms.forEach(t => { + const prd = fs.readFileSync(t.prd, 'utf8'); + const list = between(prd, '## 页面清单', '## 逐页说明'); + md += `### ${t.name}\n\n${list}\n\n`; +}); + +// 逐页说明（按端分组，截图路径改写） +md += `## 3. 逐页说明\n\n`; +terms.forEach(t => { + const prd = fs.readFileSync(t.prd, 'utf8'); + let detail = between(prd, '## 逐页说明', null); + detail = detail.replace(/screenshots\//g, t.shot); + md += `### ${t.name}\n\n${detail}\n\n`; +}); + +fs.writeFileSync(outPath, md, 'utf8'); +console.log(`已生成：${outPath}`); +console.log(`合并终端：${terms.map(t => t.name).join('、')}`); diff --git a/_templates/docs/operation-manual-template.md b/_templates/docs/operation-manual-template.md new file mode 100644 index 0000000..cc337ef --- /dev/null +++ b/_templates/docs/operation-manual-template.md @@ -0,0 +1,96 @@ + + +# {子系统名} · {终端名}操作手册 + +| 项 | 内容 | +|----|------| +| 文档类型 | 操作手册 | +| 适用终端 | {终端名} | +| 适用对象 | {用户角色} | +| 版本号 | V1.0 | +| 编制日期 | {YYYY-MM-DD} | + +--- + +## 目录 + + + +## 1. 概述 + +### 1.1 系统简介 + +{一句话说明本终端在子系统中的用途与价值} + +### 1.2 适用对象 + +{本终端面向的用户角色，如：平台管理员 / 能源员工 / 体检医生 / 医疗点医护人员} + +### 1.3 运行环境 + +{设备 / 浏览器 / 分辨率要求，引用 `项目背景.md` 2.x 视觉规范对应终端的尺寸} +- 示例：Web 管理端需 Chrome 浏览器，最小宽度 1280px + +### 1.4 登录说明 + +{登录步骤 + 界面截图 + 账号说明} + +**操作步骤**： +1. {打开系统，进入登录页} +2. {输入账号密码} +3. {点击登录} + +![登录页]({截图相对路径}) + +## 2. 界面总览 + +{整体布局与功能区说明 + 首页/工作台截图 + 导航结构说明} +- 顶部导航 / 侧边栏 / 内容区 各功能区职责 + +![首页]({截图相对路径}) + +## 3. 功能操作指南 + +{按「一级菜单/业务线」分组，逐功能描述；每个功能含 操作步骤 + 截图 + 注意事项} + +### 3.1 {一级功能1} + +#### 3.1.1 {功能点} + +**操作步骤**： +1. {步骤1} +2. {步骤2} +3. {步骤3} + +**界面截图**： + +![{功能点}]({截图相对路径}) + +**注意事项**： +- {注意点1} +- {注意点2} + +### 3.2 {一级功能2} + +{同上结构} + +## 4. 常见问题与故障处理 + +| 序号 | 问题现象 | 可能原因 | 处理方法 | +|------|---------|---------|---------| +| 1 | {问题} | {原因} | {处理} | + +## 5. 附录 + +### 5.1 术语表 + +| 术语 | 说明 | +|------|------| + +### 5.2 快捷操作 + +{键盘快捷键 / 常用入口 汇总} diff --git a/_templates/docs/parse-sql.js b/_templates/docs/parse-sql.js new file mode 100644 index 0000000..1b35861 --- /dev/null +++ b/_templates/docs/parse-sql.js @@ -0,0 +1,207 @@ +#!/usr/bin/env node +/** + * SQL 解析器：将 Navicat 导出的 PostgreSQL/MySQL 建表 SQL 解析为数据库设计说明书 Markdown + * 用法：node parse-sql.js <输出md路径> <子系统名> [数据库类型] + * 示例：node parse-sql.js doc/platform-weight.sql 交付文档/体重管理系统/数据库设计说明书.md 体重管理系统 PostgreSQL + */ +const fs = require('fs'); + +const sqlPath = process.argv[2]; +const outPath = process.argv[3]; +const systemName = process.argv[4] || ''; +const dbType = (process.argv[5] || 'PostgreSQL'); + +if (!sqlPath || !outPath) { + console.error('用法：node parse-sql.js <输出md> <子系统名> [数据库类型]'); + process.exit(1); +} + +const sql = fs.readFileSync(sqlPath, 'utf8'); + +// 自动识别 schema：取第一个 CREATE TABLE 里的 "schema"."table" +const schemaMatch = sql.match(/CREATE TABLE "([^"]+)"\."(\w+)" \(/); +const schema = schemaMatch ? schemaMatch[1] : ''; + +// ===== 解析 CREATE TABLE 块 ===== +const tableBlocks = []; +const tableRe = /CREATE TABLE "[^"]+"\."(\w+)" \(([\s\S]*?)\)\s*;/g; +let m; +while ((m = tableRe.exec(sql))) { + tableBlocks.push({ name: m[1], body: m[2] }); +} + +// ===== 解析表注释 ===== +const tableComment = {}; +const tCommentRe = /COMMENT ON TABLE "[^"]+"\."(\w+)" IS '([^']*)';/g; +while ((m = tCommentRe.exec(sql))) tableComment[m[1]] = m[2]; + +// ===== 解析字段注释 ===== +const colComment = {}; +const cCommentRe = /COMMENT ON COLUMN "[^"]+"\."(\w+)"\."(\w+)" IS '([^']*)';/g; +while ((m = cCommentRe.exec(sql))) { + if (!colComment[m[1]]) colComment[m[1]] = {}; + colComment[m[1]][m[2]] = m[3]; +} + +// ===== 解析主键 ===== +const pkey = {}; +const pkRe = /ALTER TABLE "[^"]+"\."(\w+)" ADD CONSTRAINT "\w+" PRIMARY KEY \(([^)]*)\);/g; +while ((m = pkRe.exec(sql))) { + pkey[m[1]] = m[2].split(',').map(s => s.trim().replace(/"/g, '')); +} + +// ===== 解析索引 ===== +const indexes = {}; +const idxRe = /CREATE (UNIQUE )?INDEX "(\w+)" ON "[^"]+"\."(\w+)" USING \w+ \(([\s\S]*?)\)[^;]*;/g; +while ((m = idxRe.exec(sql))) { + const unique = !!m[1]; + const idxName = m[2]; + const table = m[3]; + const cols = m[4].split(',').map(s => s.trim().replace(/"/g, '').replace(/\s.*$/, '')); + if (!indexes[table]) indexes[table] = []; + indexes[table].push({ name: idxName, cols, unique }); +} + +// ===== 解析字段 ===== +function parseFields(body) { + const fields = []; + const lines = body.split('\n'); + for (const line of lines) { + const fm = line.match(/\s*"(\w+)"\s+(\w+)(?:\(([^)]*)\))?/); + if (!fm) continue; + const name = fm[1]; + const type = fm[2]; + const len = fm[3] || ''; + const notNull = /\bNOT NULL\b/.test(line); + fields.push({ name, type, len, notNull }); + } + return fields; +} + +// ===== 提取表中文名（取注释括号前部分）===== +function cnName(table) { + const c = tableComment[table] || ''; + const idx = c.indexOf('（'); + return idx > 0 ? c.slice(0, idx) : (c || table); +} + +// ===== 提取数据字典（枚举字段：注释含 数字- 模式）===== +function extractDict() { + const dict = []; + for (const table of tableBlocks.map(t => t.name)) { + for (const [col, comment] of Object.entries(colComment[table] || {})) { + // 注释含形如 "0-xx 1-xx" 的枚举 + if (/\d+\s*-\s*\S+/.test(comment) && !/主键|雪花|时间|日期|id|编号|编码|姓名|电话/.test(comment)) { + dict.push({ table, col, comment }); + } + } + } + return dict; +} + +// ===== 生成 Markdown ===== +const date = new Date().toISOString().slice(0, 10); +let md = ''; +md += `# ${systemName}数据库设计说明书\n\n`; +md += `| 项 | 内容 |\n|----|------|\n`; +md += `| 文档类型 | 数据库设计说明书 |\n`; +md += `| 数据库 | ${dbType} |\n`; +md += `| Schema | ${schema} |\n`; +md += `| 数据表数量 | ${tableBlocks.length} |\n`; +md += `| 版本号 | V1.0 |\n`; +md += `| 编制日期 | ${date} |\n\n`; +md += `---\n\n`; + +// 1. 概述 +md += `## 1. 概述\n\n`; +md += `### 1.1 数据库环境\n\n`; +md += `- 数据库类型：${dbType}\n`; +md += `- Schema：\`${schema}\`\n`; +md += `- 字符集：UTF-8\n\n`; +md += `### 1.2 命名规范\n\n`; +md += `- 表名统一以 \`wm_\` 前缀开头，采用小写下划线命名\n`; +md += `- 字段名采用小写下划线命名（如 \`org_code\`）\n`; +md += `- 每张表均设置主键 \`id\`（雪花 ID），主键不表示业务含义\n`; +md += `- 必须为表、字段添加注释\n`; +md += `- 不使用数据库外键，表间关联由程序保证\n\n`; +md += `### 1.3 设计原则\n\n`; +md += `- **一致性原则**：统一分析与设计数据来源，保证数据一致性与有效性\n`; +md += `- **数据独立性原则**：数据空间独立、数据结构独立\n`; +md += `- **完整性原则**：对输入数据有审核和约束机制\n`; +md += `- **安全性原则**：认证与授权机制、数据隔离、实时备份、数据加密\n`; +md += `- **可伸缩性与可扩展性原则**：充分考虑发展与移植需要\n`; +md += `- **规范化**：遵循规范化理论，减少插入/删除/修改异常\n\n`; + +// 2. 数据表清单 +md += `## 2. 数据表清单\n\n`; +md += `| 序号 | 表中文名 | 英文表名 | 说明 |\n|------|---------|---------|------|\n`; +tableBlocks.forEach((t, i) => { + md += `| ${i + 1} | ${cnName(t.name)} | \`${t.name}\` | ${tableComment[t.name] || ''} |\n`; +}); +md += `\n`; + +// 3. 数据表结构说明 +md += `## 3. 数据表结构说明\n\n`; +tableBlocks.forEach((t, i) => { + md += `### 3.${i + 1} ${cnName(t.name)}(\`${t.name}\`)\n\n`; + md += `${tableComment[t.name] || ''}\n\n`; + md += `| 序号 | 列名 | 数据类型 | 长度 | 主键 | 允许空值 | 列说明 |\n`; + md += `|------|------|---------|------|------|---------|--------|\n`; + const fields = parseFields(t.body); + const pkCols = pkey[t.name] || []; + fields.forEach((f, j) => { + const isPk = pkCols.includes(f.name); + md += `| ${j + 1} | ${f.name} | ${f.type} | ${f.len} | ${isPk ? '是' : '否'} | ${f.notNull ? 'NO' : 'YES'} | ${colComment[t.name]?.[f.name] || ''} |\n`; + }); + md += `\n`; +}); + +// 4. 表关系与 ER 图 +md += `## 4. 表关系与 ER 图\n\n`; +md += `数据库设计未使用外键约束，表间通过业务字段关联，由程序层保证引用完整性。\n\n`; +const fkMap = {}; +tableBlocks.forEach(t => { + parseFields(t.body).forEach(f => { + if (/_(id|code|no|sn)$/.test(f.name) && f.name !== 'id' && f.name !== 'original_id') { + if (!fkMap[f.name]) fkMap[f.name] = []; + fkMap[f.name].push(t.name); + } + }); +}); +if (Object.keys(fkMap).length) { + md += `**关联字段清单**（据此补全 ER 关系）：\n\n`; + Object.entries(fkMap).forEach(([fk, tables]) => { + md += `- \`${fk}\` → ${tables.map(t => '`' + t + '`').join('、')}\n`; + }); + md += `\n`; +} +md += `\`\`\`mermaid\nerDiagram\n`; +md += ` %% TODO: 由人工/技能根据上方关联字段清单补充核心表关系\n`; +md += `\`\`\`\n\n`; + +// 5. 索引与约束设计 +md += `## 5. 索引与约束设计\n\n`; +md += `| 表 | 索引/约束名 | 字段 | 类型 | 说明 |\n|----|------------|------|------|------|\n`; +tableBlocks.forEach(t => { + const pkCols = pkey[t.name] || []; + if (pkCols.length) { + md += `| ${t.name} | ${t.name}_pkey | ${pkCols.join(', ')} | 主键 | 主键约束 |\n`; + } + (indexes[t.name] || []).forEach(idx => { + md += `| ${t.name} | ${idx.name} | ${idx.cols.join(', ')} | ${idx.unique ? '唯一索引' : '普通索引'} | |\n`; + }); +}); +md += `\n`; + +// 6. 数据字典 +md += `## 6. 数据字典\n\n`; +const dict = extractDict(); +md += `| 表 | 字段 | 取值说明 |\n|----|------|---------|\n`; +dict.forEach(d => { + md += `| ${d.table} | ${d.col} | ${d.comment} |\n`; +}); +md += `\n`; + +fs.writeFileSync(outPath, md, 'utf8'); +console.log(`已生成：${outPath}`); +console.log(`表数量：${tableBlocks.length}，字段注释：${Object.values(colComment).reduce((s, t) => s + Object.keys(t).length, 0)}，索引：${Object.values(indexes).reduce((s, a) => s + a.length, 0)}，数据字典条目：${dict.length}`); diff --git a/_templates/docs/prd-merge-template.md b/_templates/docs/prd-merge-template.md new file mode 100644 index 0000000..6f3c50d --- /dev/null +++ b/_templates/docs/prd-merge-template.md @@ -0,0 +1,96 @@ + + +# {子系统名}产品需求文档 + + +> 本文档由以下终端 PRD 合并生成（原始文件未改动）： +> - {终端1}：{原 PRD 相对路径} +> - {终端2}：{原 PRD 相对路径} + +--- + +## 1. 子系统概述 + +{整合各终端「模块概述」，改写成统一的一段，覆盖本子系统所有终端的整体功能} +- 素材：各终端 PRD 的「模块概述」段 + +### 页面导航结构 + +{按端分组，呈现统一的导航结构树。每端沿用原 PRD 的导航结构树，加一级「{端名}」前缀} + +``` +{子系统名} +├── {端1（如 Web管理端）} +│ ├── {一级菜单1} +│ │ ├── {二级菜单/页面} +│ │ └── ... +│ └── ... +├── {端2（如 员工端APP）} +│ └── ... +└── ... +``` + +### 状态流转图 + +```mermaid +{合并各端状态流转图；若无则本小节省略} +``` + +## 2. 页面清单 + +{按端分组，每端沿用原 PRD 的页面清单表格；公共页面（登录/消息等）归入「公共部分」小节，不重复罗列} + +### 公共部分 + +| 页面/弹窗 | 文件 | 所属 | 类型 | +|-----------|------|------|------| + +### {端1} + +{沿用原 PRD 页面清单表格} + +### {端2} + +{沿用原 PRD 页面清单表格} + +## 3. 逐页说明 + +{按端分组，每端沿用原 PRD 逐页说明；截图路径改为从本文档位置指回原模块 doc/screenshots/ 的相对路径} + +### {端1} + +#### {页面1} + +![{页面1}]({指回原截图的相对路径}) + +**功能说明**：{沿用原文} + +**业务规则**：{沿用原文} + +**交互说明**：{沿用原文} + +#### {页面2} + +{同上} + +### {端2} + +{同上} + +## 4. 表单字段表 + +{按端分组，合并各端原 PRD 的表单字段表} + +### {端1} + +| 字段名 | 类型 | 是否必填 | 校验规则 | +|--------|------|---------|---------| + +### {端2} + +| 字段名 | 类型 | 是否必填 | 校验规则 | +|--------|------|---------|---------|