prd-md-tool

PRD需求文档生成工具 - 自动截图并生成 Markdown 格式需求文档，支持页面元素自动发现。

特性

• 自动截图：使用 Playwright 自动登录系统并捕获页面截图。
• 自动发现：自动识别菜单结构、查询条件、数据表格字段、操作按钮等页面元素。
• Markdown 生成：根据配置自动生成符合规范的 PRD Markdown 文档。
• 增量需求支持：支持只截图新增功能页面，不重复截图登录页等通用页面。
• 智能标点：自动生成文档时确保每句话末尾都有标点符号。

安装

npm install -g prd-md-tool

快速开始（3步生成需求文档）

第1步：初始化配置

prd-md init -n v1.0.0-myproject

编辑生成的 prd-configs/v1.0.0-myproject.json，填写系统地址、账号密码、登录页选择器等基础信息。

第2步：自动发现页面元素（推荐）

prd-md discover -c v1.0.0-myproject

工具会自动登录系统，遍历所有菜单，识别查询条件、数据字段、操作按钮等，生成配置草稿 prd-configs/v1.0.0-myproject-draft.json。

检查草稿后重命名为正式配置：

mv prd-configs/v1.0.0-myproject-draft.json prd-configs/v1.0.0-myproject.json

第3步：生成文档

prd-md gen -c v1.0.0-myproject

工具会自动截图并生成 Markdown 需求文档到 prd/V1.0.0/ 目录。

完整使用流程

1. 初始化配置

prd-md init -n v1.0.0-myproject

生成的配置文件包含基础模板，需要修改以下关键字段：

{
  "productName": "你的产品名称",
  "requirementName": "需求名称",
  "version": "V1.0.0",
  "date": "20260430",
  "background": "需求背景描述。",
  "goals": ["目标1。", "目标2。"],
  "baseConfig": {
    "baseUrl": "http://localhost:3000",
    "viewport": { "width": 1440, "height": 900 },
    "username": "admin",
    "password": "admin123"
  },
  "loginConfig": {
    "url": "/login.html",
    "usernameSelector": "#username",
    "passwordSelector": "#password",
    "loginBtnSelector": "#loginBtn",
    "successUrlPattern": "index"
  }
}

2. 自动发现（推荐用于新项目）

prd-md discover -c v1.0.0-myproject

自动发现会：

1. 登录系统。
2. 识别所有侧边栏菜单。
3. 逐个点击菜单，分析页面结构。
4. 识别查询条件、数据表格字段、操作按钮。
5. 生成配置草稿。

发现完成后，手动完善以下信息：

• background：补充详细的需求背景。
• goals：补充具体的需求目标。
• menus[].description：补充每个菜单的业务描述。
• menus[].operations[].description：补充操作功能的详细说明。
• screenshots：配置需要截图的页面和操作步骤。

3. 手动配置截图步骤

对于需要截图的操作（如新增、编辑弹窗），在 operations[].screenshots 中配置前置操作：

{
  "name": "001-user-add",
  "description": "新增用户页面",
  "beforeScreenshot": [
    { "type": "click", "selector": ".btn-primary" },
    { "type": "delay", "ms": 1000 }
  ]
}

常用前置操作类型：

| 类型 | 说明 | 示例 | |-----|------|------| | click | 点击元素 | { "type": "click", "selector": ".btn-primary" } | | clickFirst | 点击第一个匹配元素 | { "type": "clickFirst", "selector": ".operation-btn" } | | fill | 填写表单 | { "type": "fill", "selector": "#name", "value": "测试" } | | delay | 等待指定时间 | { "type": "delay", "ms": 1000 } | | evaluate | 执行自定义 JS | { "type": "evaluate", "script": "document.querySelector('.tab').click()" } | | waitFor | 等待元素显示 | { "type": "waitFor", "selector": "#drawer" } |

4. 生成文档

# 完整流程：截图 + 生成文档
prd-md gen -c v1.0.0-myproject

# 仅截图
prd-md shot -c v1.0.0-myproject

# 跳过截图，使用已有图片
prd-md gen -c v1.0.0-myproject --no-screenshot

增量需求（V1.1.0及以后）

对于增量需求，配置中不需要包含 login 和 index 菜单：

{
  "productName": "你的产品名称",
  "requirementName": "新增XX功能",
  "version": "V1.1.0",
  "date": "20260501",
  "background": "在V1.0.0基础上新增XX功能。",
  "goals": ["新增XX功能。"],
  "baseConfig": {
    "baseUrl": "http://localhost:3000",
    "username": "admin",
    "password": "admin123"
  },
  "loginConfig": { ... },
  "menus": [
    {
      "id": "target-menu",
      "name": "目标菜单",
      "moduleName": "所属模块",
      "description": "新增功能描述。",
      "queryConditions": [],
      "dataFields": [...],
      "operations": [...]
    }
  ]
}

工具会自动登录（不截图），直接导航到目标菜单页面截图。

命令说明

| 命令 | 别名 | 说明 | |-----|------|------| | prd-md init | - | 初始化示例配置文件。 | | prd-md generate | gen | 生成 PRD Markdown 文档（截图 + 文档）。 | | prd-md screenshot | shot | 仅执行截图。 | | prd-md discover | - | 自动发现页面元素并生成配置草稿。 | | prd-md list | - | 列出可用配置。 |

generate 命令选项

| 选项 | 说明 | |-----|------| | -c, --config <name> | 配置文件名（不含 .json 扩展名）。 | | -o, --output <dir> | 输出目录，默认 ./prd。 | | --config-dir <dir> | 配置文件目录，默认 ./prd-configs。 | | --no-screenshot | 跳过截图步骤，使用已有图片。 | | --use-existing | 截图失败时使用已有截图。 |

配置说明

基础配置

| 字段 | 说明 | |-----|------| | productName | 产品名称。 | | requirementName | 需求名称。 | | version | 版本号，如 V1.0.0。 | | date | 日期（用于文件名），如 20260428。 | | docNumber | 文档编号。 | | department | 归属部门。 | | author | 编写人。 | | writeDate | 编写日期。 | | background | 需求背景描述。 | | goals | 需求目标数组。 | | autoDiscovery | 是否启用自动发现，默认 true。 | | discoverFields | 是否自动发现字段（截图时），默认 false。 |

登录配置（loginConfig）

| 字段 | 说明 | |-----|------| | url | 登录页路径，如 /login.html。 | | usernameSelector | 用户名输入框选择器，如 #phone。 | | passwordSelector | 密码输入框选择器，如 #password。 | | captchaSelector | 验证码输入框选择器（可选）。 | | captchaValue | 验证码值（可选）。 | | loginBtnSelector | 登录按钮选择器，如 #loginBtn。 | | successUrlPattern | 登录成功后的 URL 匹配模式，如 index。 | | delayAfterLogin | 登录成功后等待时间（毫秒）。 |

菜单配置

| 字段 | 说明 | |-----|------| | id | 页面 ID（用于路由和截图文件名）。 | | name | 菜单名称。 | | moduleName | 所属模块名称。 | | moduleIndex | 模块序号。 | | menuIndex | 菜单在模块中的序号。 | | description | 需求描述。 | | queryConditions | 查询条件列表（留空数组表示无查询条件）。 | | dataFields | 数据字段列表。 | | operations | 操作功能列表。 | | screenshots | 截图配置列表。 |

查询条件配置

{
  "name": "策略名称",
  "type": "文本输入",
  "required": false,
  "defaultValue": "",
  "description": "支持模糊查询。"
}

数据字段配置

{
  "name": "策略名称",
  "description": "策略的名称。",
  "format": "-"
}

操作功能配置

{
  "name": "新增策略",
  "description": "点击新增按钮，弹出新增策略抽屉。",
  "fields": [
    { "name": "策略名称", "required": true, "editable": true, "description": "必填。" }
  ],
  "screenshots": [
    {
      "name": "001-rules-add",
      "description": "新增策略页面",
      "beforeScreenshot": [
        { "type": "click", "selector": ".btn-primary" },
        { "type": "delay", "ms": 1000 }
      ]
    }
  ]
}

输出文件结构

prd/
└── V1.0.0/
    ├── 【产品名称】需求名称_需求文档_V1.0.0_20260428.md
    └── image/
        ├── 001-login-page.png
        ├── 002-index-page.png
        └── ...

自动发现支持的页面元素

工具会自动识别以下元素（适配不同前端框架）：

| 元素类型 | 支持的选择器 | |---------|------------| | 菜单 | .submenu-item[data-key], .menu-item, .sidebar-menu li | | 查询条件 | .search-area input, .search-area select, .query-area input | | 数据表格 | table.data-table thead th, .el-table th | | 操作按钮 | .operation-btn, td:last-child button, .footer-btns button | | 弹窗/抽屉 | .drawer, .modal, .el-drawer, .el-dialog |

常见问题

Q: 自动发现没有识别到我的菜单？

A: 检查菜单元素是否有 data-key 属性或是否在 .sidebar-menu 容器内。可以手动在配置中添加菜单，或使用 evaluate 操作执行自定义点击。

Q: 截图时弹窗/抽屉无法正确关闭？

A: 在 beforeScreenshot 中添加自定义关闭操作，或扩展 screenshot.js 中 closeAllDrawers() 的选择器列表。

Q: 如何只截图部分页面？

A: 在配置文件中只保留需要截图的菜单。增量需求不需要配置 login 和 index。

Q: 如何适配不同的前端框架？

A: 工具使用多种策略自动识别元素。如果默认选择器不匹配，可以：

1. 使用 prd-md discover 测试自动发现效果。
2. 在配置中手动指定元素信息。
3. 修改 auto-discovery.js 中的选择器策略。

License

MIT