# Req Doc

> 生成或细化需求说明书文档。支持完整文档生成和局部细化两种模式。适用场景：(1) 将需求概述转换为完整的需求说明书，(2) 对已有文档的特定章节进行详细补充和细化，(3) 只生成某个功能模块的详细说明，(4) 需要标准化的需求文档格式，支持多端系统（Web管理后台、Web学员端、移动App等）

- Skill: `wang-q-l/req-doc` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add wang-q-l/req-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wang-q-l/req-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wang-q-l (https://skillmd.com/u/wang-q-l)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wang-q-l/req-doc

---


# 需求文档生成器

根据用户提供的需求概述，生成符合标准格式的详细需求说明书。

## 文档封面规范

**每份需求说明书必须在文件最顶部加 YAML frontmatter**，用于生成封面页：

```yaml
---
title: '需求说明书'
subtitle: "[项目名称]\n\n[客户名称]"
author: '编制单位：[编制单位名称]'
date: '[年月]'
lang: zh-CN
toc: true
toc-depth: 3
numbersections: false
geometry: 'left=3.17cm,right=3.17cm,top=2.54cm,bottom=2.54cm'
---
```

**字段说明：**

- `title`: 文档标题（固定为"需求说明书"）
- `subtitle`: 项目名称和客户名称（使用 `\n\n` 分隔两行）
- `author`: 编制单位信息
- `date`: 编制日期（如"二零二五年三月"）

## 文档信息表格

**在 YAML frontmatter 之后，必须添加文档信息表格**，用于展示项目的基本信息：

```markdown
## 文档信息

| 项目编号 | [项目编号]                  |
| -------- | --------------------------- |
| 项目名称 | [项目名称]                  |
| 文档名称 | 需求说明书                  |
| 文档版本 | V1.0                        |
| 编制日期 | [YYYY-MM-DD]                |
| 编制人   | [编制人]                    |
| 审核人   | [审核人]                    |
| 批准人   | [批准人]                    |
| 客户单位 | [客户单位名称]              |
| 编制单位 | [编制单位名称]              |
| 适用范围 | [适用范围描述]              |
| 核心目标 | [核心目标描述]              |
| 文档状态 | [草稿/评审中/已批准/修订稿] |
```

**字段说明：**

- `项目编号`: 项目的唯一标识编号
- `项目名称`: 项目的完整名称
- `文档名称`: 固定为"需求说明书"
- `文档版本`: 版本号（如 V1.0, V1.1, V2.0）
- `编制日期`: 文档编制日期（YYYY-MM-DD 格式）
- `编制人`: 文档编制人员姓名或团队
- `审核人`: 文档审核人员姓名（未审核填"-"）
- `批准人`: 文档批准人员姓名（未批准填"-"）
- `客户单位`: 项目客户单位名称
- `编制单位`: 编制需求说明书的单位名称
- `适用范围`: 文档适用的范围描述
- `核心目标`: 项目的核心目标简述
- `文档状态`: 文档当前状态（草稿/评审中/已批准/修订稿）

## 目录管理策略

**双目录策略：Markdown 保留手动目录，Word 使用自动生成目录**

### Markdown 文件中的手动目录

**在文档信息表格之前，必须添加手动目录**，用于 Markdown 文件的阅读导航：

```markdown
---
title: '需求说明书'
toc: true
---

## 目录

- [一、文档信息](#一文档信息)
- [二、项目概述](#二项目概述)
  - [2.1 项目背景](#21-项目背景)
  - [2.2 项目建设目标](#22-项目建设目标)
- [三、项目建设内容](#三项目建设内容) ...

---

## 一、文档信息
```

**手动目录规范：**

- 位置：YAML frontmatter 之后，文档信息表格之前
- 格式：使用 Markdown 链接语法 `[章节名称](#anchor-link)`
- 层级：主要章节 + 重要子章节（不超过3级）
- 分隔：目录后使用 `---` 分隔线

### Word 导出时的目录处理

导出 Word 文档时，导出脚本会自动：

1. **删除手动目录**：`remove_manual_toc()` 函数删除 Markdown 中的手动目录章节
2. **生成自动目录**：Pandoc 根据 `toc: true` 自动生成 Word 目录
3. **中文标题**：`replace_toc_title()` 函数将 "Table of Contents" 替换为 "目录"

**为什么使用双目录策略？**

- Markdown 文件需要手动目录方便在编辑器中快速导航
- Word 文档使用 Pandoc 自动生成的目录，支持点击跳转和自动更新
- 避免 Word 中出现两个目录（手动 + 自动）

## Word 导出功能

**重要说明：**

- ⚠️ **不要自动导出 Word**：只在用户明确要求"导出 Word"、"生成 Word"时才执行导出
- ⚠️ **生成或调整需求说明书时不导出**：完成 Markdown 文档编辑后，等待用户主动要求导出

### 使用公共导出工具

需求说明书使用公共文档导出工具，与测试用例、操作手册等文档共享相同的样式配置。

**一键导出命令：**

```bash
# 使用公共导出工具
bash .claude/skills/common/doc-export/scripts/export-word.sh 需求说明书.md [输出.docx]

# 示例
bash .claude/skills/common/doc-export/scripts/export-word.sh 安全监督风险智能分析项目需求说明书.md
```

**文档标题自动识别：**

- 导出脚本会自动从 Markdown 文件的 YAML frontmatter 中读取 `title` 字段
- 需求说明书的 `title` 应设置为 "需求说明书"
- 无需手动指定文档类型

### 系统依赖

导出 Word 需要以下依赖（公共导出工具会自动检测并提示安装）：

**必需软件：**

1. **Python 3.7+**：用于文档后处理
2. **Pandoc**：用于 Markdown 转 Word
3. **python-docx**：Python 库，用于 Word 文档操作

**安装方法：**

**macOS：**

```bash
brew install python3 pandoc
pip3 install python-docx
```

**Windows：**

```bash
choco install python3 pandoc
pip3 install python-docx
```

**Linux：**

```bash
sudo apt install python3 python3-pip pandoc
pip3 install python-docx
```

### 样式说明

样式配置由公共导出工具统一管理（`.claude/skills/common/doc-export/config/style_config.py`），包括：

- **封面页**：Title（标题）、Subtitle（副标题）、Author（编制单位）、Date（日期）
- **标题层级**：Heading 1/2/3（仿宋\_GB2312，加粗）
- **正文**：Normal（仿宋\_GB2312，16pt）
- **代码块**：转换为单元格表格，浅灰色背景（#F5F5F5）、浅灰色边框（#D4D4D4）、仿宋\_GB2312字体、左对齐、无首行缩进
- **页码**：页脚居中"第 X 页，共 X 页"
- **页面**：A4，左右边距3.17cm，上下2.54cm

详细配置和自定义方法请参考：`.claude/skills/common/doc-export/README.md`

---

生成的需求说明书包含以下标准结构：

### 一、文档信息

- 项目基本信息表格（13个字段）

### 二、项目概述

- 2.1 项目背景：描述项目产生的原因和必要性
- 2.2 项目建设目标：列出3-5个具体、可衡量的目标
- 2.3 项目建设范围：明确包含和不包含的功能，说明涉及的端（Web管理后台、Web用户端、移动App等）
- 2.4 业务流程图：**使用 diagram-generator 技能生成**，包括系统风险计算逻辑、业务流程图（泳道）、用户操作流程、数据交互流程等
- 2.5 用户角色定义：定义各类用户及其权限，使用表格展示角色清单
- 2.6 需求分析：**使用表格描述，支持表格合并**，包含功能模块、子功能、需求描述三列
  - **表格合并语法**：使用 `^` 符号表示与上一行单元格合并
  - **示例**：
    ```markdown
    | 功能模块 | 子功能       | 需求描述         |
    | -------- | ------------ | ---------------- |
    | 库站管理 | 库站信息维护 | 维护库站基础信息 |
    | ^        | 业态设置     | 设置库站业态类型 |
    | ^        | 销量统计     | 维护月度销量数据 |
    | ^        | 员工查看     | 查看库站用户列表 |
    ```
  - 导出为 Word 时，相同功能模块的单元格会自动合并

### 三、项目建设内容

- 3.1 总体功能架构：**使用 diagram-generator 技能生成功能架构图**，展示完整的菜单结构和层级关系
- 3.2 页面访问权限：使用表格展示各角色对各功能模块的访问权限
- 3.3 功能详细设计：**每个功能模块作为独立的四级标题（#### 3.3.1、#### 3.3.2...）**，包含以下内容
  - **（一）功能需求概述**：简要说明功能目的和价值
  - **（二）用户操作流程**：
    - **使用活动图（D2语言）**展示业务流程
    - 只展示用户操作步骤和决策点，不涉及技术细节（如前端、后端、数据库）
    - 图片命名：`images/[功能名]-activity.png`
    - 删除文字描述的操作步骤，只保留图表
  - **（三）功能设计**：
    - **核心功能**：列出所有功能点
    - **系统交互时序**：使用时序图（PlantUML）展示技术交互
      - 展示用户、前端、后端、数据库之间的消息传递
      - 图片命名：`images/[功能名]-sequence.png`
    - **数据字段**：使用表格展示字段定义
    - **业务规则**：列出验证规则和业务约束
  - **（四）业务逻辑关联**：说明与其他功能模块的数据依赖关系
  - **注意：不要写页面布局设计**

**章节编号规则：**

- 3.3.1 登录页
- 3.3.2 组织架构管理
- 3.3.3 库站管理
- 3.3.4 检查问题台账
- 3.3.5 风险规则设置
- 3.3.6 风险画像大屏
- 3.3.7 风险值计算引擎
- ...（根据实际功能模块数量）

**重要提示：**

- ⚠️ 不要在文档中出现重复的章节标题（如两个"项目建设内容"）
- ⚠️ 确保章节编号连续且唯一
- ⚠️ "四、技术方案"之后不应该再出现"四、项目建设内容"

**功能架构图生成规范：**

- **自动识别场景**：根据用户需求描述，自动判断应该使用哪种菜单结构（纯左侧菜单、顶部+左侧菜单、纯顶部菜单等）
- **只列出菜单中显示的功能**，不列出隐藏页面（如详情页、编辑页）
- **清晰标注菜单类型**（顶部菜单、左侧菜单、底部导航等）
- **展示完整的层级关系**（一级、二级、三级...）
- **标注是否需要登录**

### 四、技术方案

- 4.1 技术架构：前后端技术栈、系统架构设计
- 4.2 数据交互：前后端数据交互方式、API 设计原则
- 4.3 外部系统集成：如果涉及外系统，说明数据交互方式、接口规范
- 4.4 安全方案：身份认证、权限控制、数据加密等
- **注意：只写技术方案和思路，不写具体技术代码**

### 五、非功能需求

- 5.1 性能需求：响应时间、并发用户数、数据处理能力
- 5.2 安全需求：身份认证、数据安全、权限控制
- 5.3 可用性需求：系统可用性、故障恢复、数据备份
- 5.4 兼容性需求：浏览器兼容性、设备兼容性、屏幕分辨率

### 六、数据需求

- 6.1 数据字典：枚举值定义（如风险等级、状态枚举等）
- 6.2 数据存储要求：数据保留期限、存储容量规划
- **注意：按项目实际情况而定，如无特殊数据需求可简化**

### 七、接口需求

- 7.1 第三方系统接入接口规范：接口地址、请求格式、响应格式、字段说明
- **注意：按项目实际情况而定，如无外部接口可简化**

### 八、项目实施与验收

- 8.1 实施阶段：需求确认、设计开发、测试部署、上线运行
- 8.2 系统培训服务：培训对象、培训内容、培训方式
- 8.3 验收标准：功能验收、性能验收、文档验收

### 九、附录

- 附录A：术语表
- 附录B：参考资料
- **注意：按项目实际情况而定**

---

## 业务流程图生成规范

**使用 diagram-generator 技能生成业务流程图**，包括：

- 系统整体流程图（如风险计算逻辑）
- 业务流程图（泳道图，展示多角色协作）
- 用户操作流程图（展示用户操作步骤）
- 数据交互流程图（展示数据流向）

**生成步骤：**

1. 分析业务流程，确定流程类型（普通流程、泳道流程等）
2. 调用 diagram-generator 技能生成流程图
3. 将生成的图片保存到 `images/` 目录
4. 在文档中插入图片引用：`![](images/文件名.png)`（不使用 alt 文本，避免在 Word 导出时显示图片标题）

### 四、功能需求详述（已废弃，使用"三、项目建设内容"代替）

- 4.1 xx端（如：WEB管理后台）
  - 4.1.1 功能模块
    - 4.1.1.1 功能需求概述
    - 4.1.1.2 用户操作流程
    - 4.1.1.3 功能设计

## 使用流程

### 步骤 1: 识别项目类型

**首先必须自动识别项目类型，不要询问用户。**

**识别规范：**

- 根据用户需求描述中的关键词和特征自动判断项目类型
- 不要列出所有项目类型让用户选择
- 直接在生成的需求文档中使用识别出的项目类型

**识别方法：**

通过用户描述中的关键词判断：

- "管理后台"、"后台系统"、"管理系统"、"CMS"、"数据管理" → 管理后台项目
- "官网"、"前台"、"用户端"、"门户"、"企业网站" → Web 用户前台项目
- "移动端"、"H5"、"App"、"小程序"、"手机端" → 移动端项目
- 同时包含多个端的描述 → 混合项目

通过菜单结构特征判断：

- 侧边栏多级菜单、数据表格、表单操作 → 管理后台项目
- 顶部导航、页面路由、内容展示 → Web 用户前台项目
- 底部 Tabbar、页面栈、下拉刷新 → 移动端项目

---

**以下是项目类型参考（仅供识别参考，不要列出给用户）：**

1. **管理后台项目**（Web Admin）
   - 特征：侧边栏菜单、顶部导航、数据表格、表单操作
   - 典型场景：后台管理系统、CMS、数据管理平台

2. **Web 用户前台项目**（Website）
   - 特征：顶部导航、页面路由、内容展示、用户交互
   - 典型场景：企业官网、产品官网、门户网站

3. **移动端项目**（Mobile App）
   - 特征：底部 Tabbar、页面栈、下拉刷新、上拉加载
   - 典型场景：H5 应用、移动端网站、小程序

4. **混合项目**（Multi-Platform）
   - 包含多个端：管理后台 + 用户前台 + 移动端
   - 每个端独立设计

### 步骤 2: 收集需求信息

询问用户以下关键信息：

- 项目类型和目标
- 目标用户群体
- 核心功能模块
- 涉及的端（Web管理后台、Web学员端、移动App等）
- 特殊需求或约束

### 步骤 3: 分析需求

基于用户提供的信息：

- 识别核心业务流程
- 确定用户角色和权限
- 梳理功能模块层级关系
- 明确各端的功能范围

### 步骤 4: 生成文档

按照标准结构生成需求说明书：

1. **项目概述部分**：
   - 项目背景：阐述项目产生的原因和必要性
   - 建设目标：列出3-5个具体、可衡量的目标
   - 建设范围：明确包含和不包含的功能，说明涉及的端
   - 业务流程图：**使用 diagram-generator 技能生成流程图**
   - 用户角色：使用表格定义各类用户及其权限
   - **需求分析表格**（新增）：使用表格描述需求，支持表格合并
     ```markdown
     | 功能模块     | 子功能           | 需求描述                                     |
     | ------------ | ---------------- | -------------------------------------------- |
     | 风险规则设置 | 固有风险规则     | 设置加能站的业态风险值和销量风险值的配置     |
     | 风险规则设置 | 检查问题风险规则 | 设置检查问题的严重程度、频次、修正系数等参数 |
     | 库站管理     | 库站信息维护     | 维护库站基础信息、业态设置、销量统计         |
     ```

2. **项目建设内容部分**：
   - **总体功能架构**：**使用 diagram-generator 技能生成功能架构图**
   - **页面访问权限**：使用表格展示各角色对各功能的访问权限
   - **各功能详细设计**：对每个功能模块详细描述
     - 功能需求概述：简要说明功能目的和价值
     - 所属菜单：说明是一级菜单、二级菜单还是其他
     - 用户操作流程：**使用 diagram-generator 技能生成流程图**，并用编号列表描述步骤
     - 功能设计：列出所有功能点、数据字段、验证规则、业务规则
     - 业务逻辑关联：说明与其他功能模块的数据依赖关系
     - **注意：不要写页面布局设计**

3. **技术方案部分**（新增）：
   - 技术架构：前后端技术栈、系统架构设计
   - 数据交互：前后端数据交互方式、API 设计原则
   - 外部系统集成：如果涉及外系统，说明数据交互方式
   - 安全方案：身份认证、权限控制、数据加密等
   - **注意：只写技术方案和思路，不写具体技术代码**

4. **非功能需求部分**（新增）：
   - 性能需求：响应时间、并发用户数、数据处理能力
   - 安全需求：身份认证、数据安全、权限控制
   - 可用性需求：系统可用性、故障恢复、数据备份
   - 兼容性需求：浏览器兼容性、设备兼容性

5. **数据需求部分**（新增，按实际情况）：
   - 数据字典：枚举值定义
   - 数据存储要求：数据保留期限、存储容量规划

6. **接口需求部分**（新增，按实际情况）：
   - 第三方系统接入接口规范

7. **项目实施与验收部分**（新增）：
   - 实施阶段：需求确认、设计开发、测试部署、上线运行
   - 系统培训服务：培训对象、培训内容、培训方式
   - 验收标准：功能验收、性能验收、文档验收

8. **附录部分**（新增，按实际情况）：
   - 术语表
   - 参考资料

### 步骤 4: 优化和完善

- 确保术语统一
- 检查逻辑完整性
- 补充必要的说明和示例
- 添加表格展示复杂数据结构

## 任务清单管理规范

### 何时使用任务清单

当需求文档内容较多时，**必须使用 TaskCreate 工具创建任务清单**，以便跟踪进度和组织工作。

**触发条件（满足任一即需要创建任务清单）：**

- 需要生成完整的需求说明书（包含多个功能模块）
- 需要细化 3 个或以上的功能模块
- 单个端（如 Web 管理后台）包含 5 个或以上的功能模块
- 涉及多个端（如 Web 管理后台 + Web 学员端 + 移动 App）

### 任务粒度规范

**重要：任务必须细化到功能模块级别，不能使用粗粒度的端作为任务。**

#### ✅ 正确的任务粒度

每个功能模块作为一个独立任务：

```typescript
// 示例：在线考试系统
TaskCreate({
  subject: '用户管理功能模块',
  description: '编写 Web 管理后台的用户管理功能模块需求，包括功能概述、操作流程、功能设计',
  activeForm: '编写用户管理功能模块'
})

TaskCreate({
  subject: '题库管理功能模块',
  description: '编写 Web 管理后台的题库管理功能模块需求，包括功能概述、操作流程、功能设计',
  activeForm: '编写题库管理功能模块'
})

TaskCreate({
  subject: '考试管理功能模块',
  description: '编写 Web 管理后台的考试管理功能模块需求，包括功能概述、操作流程、功能设计',
  activeForm: '编写考试管理功能模块'
})
```

#### ❌ 错误的任务粒度

不要使用端作为任务（太粗粒度）：

```typescript
// ❌ 错误示例：任务太粗，难以跟踪进度
TaskCreate({
  subject: 'Web 管理后台',
  description: '编写 Web 管理后台的所有功能需求',
  activeForm: '编写 Web 管理后台需求'
})
```

### 任务创建流程

#### 步骤 1: 分析需求范围

- 识别所有需要编写的功能模块
- 确定每个模块的所属端
- 评估每个模块的复杂度

#### 步骤 2: 创建任务清单

按照功能模块创建任务：

```typescript
// 1. 创建项目概述任务（如果需要）
TaskCreate({
  subject: '项目概述章节',
  description: '编写项目背景、建设目标、建设范围、业务流程图、用户角色定义',
  activeForm: '编写项目概述'
})

// 2. 为每个功能模块创建任务
TaskCreate({
  subject: '用户管理功能模块',
  description:
    '编写用户管理功能的完整需求，包括：\n- 功能需求概述\n- 用户操作流程\n- 功能设计（核心功能、数据字段、业务规则）',
  activeForm: '编写用户管理功能模块'
})

TaskCreate({
  subject: '角色权限管理功能模块',
  description:
    '编写角色权限管理功能的完整需求，包括：\n- 功能需求概述\n- 用户操作流程\n- 功能设计（核心功能、数据字段、业务规则）',
  activeForm: '编写角色权限管理功能模块'
})

// ... 其他功能模块
```

#### 步骤 3: 按任务执行

- 使用 TaskUpdate 将任务状态设置为 `in_progress`
- 完成任务后使用 TaskUpdate 将状态设置为 `completed`
- 按照任务 ID 顺序执行（从小到大）

#### 步骤 4: 跟踪进度

- 定期使用 TaskList 查看整体进度
- 确保每个任务完成后标记为 completed
- 如果发现新的功能模块，及时创建新任务

### 任务命名规范

**任务 subject 格式：**

- 格式：`[功能模块名称] + "功能模块"`
- 示例：
  - "用户管理功能模块"
  - "题库管理功能模块"
  - "考试管理功能模块"
  - "成绩统计功能模块"

**任务 description 格式：**

```
编写 [端名称] 的 [功能模块名称] 功能需求，包括：
- 功能需求概述
- 用户操作流程
- 功能设计（核心功能、数据字段、业务规则）
```

**任务 activeForm 格式：**

- 格式：`"编写" + [功能模块名称] + "功能模块"`
- 示例：
  - "编写用户管理功能模块"
  - "编写题库管理功能模块"

### 多端项目的任务组织

对于涉及多个端的项目，按端和功能模块组织任务：

```typescript
// Web 管理后台的功能模块
TaskCreate({
  subject: 'Web管理后台-用户管理功能模块',
  description: '编写 Web 管理后台的用户管理功能需求...',
  activeForm: '编写 Web 管理后台用户管理功能'
})

TaskCreate({
  subject: 'Web管理后台-题库管理功能模块',
  description: '编写 Web 管理后台的题库管理功能需求...',
  activeForm: '编写 Web 管理后台题库管理功能'
})

// Web 学员端的功能模块
TaskCreate({
  subject: 'Web学员端-在线考试功能模块',
  description: '编写 Web 学员端的在线考试功能需求...',
  activeForm: '编写 Web 学员端在线考试功能'
})

TaskCreate({
  subject: 'Web学员端-成绩查询功能模块',
  description: '编写 Web 学员端的成绩查询功能需求...',
  activeForm: '编写 Web 学员端成绩查询功能'
})
```

### 注意事项

1. **任务粒度一致**：所有任务应保持相同的粒度级别（功能模块级别）
2. **任务独立性**：每个任务应该是独立的，可以单独完成
3. **任务完整性**：每个任务应包含该功能模块的所有必要内容
4. **及时更新状态**：开始任务时设置为 in_progress，完成后设置为 completed
5. **按顺序执行**：优先完成 ID 较小的任务，保持工作的连贯性

## 局部细化模式

### 适用场景

当用户需要对已有需求文档进行局部细化时使用，包括：

- 对某个功能模块进行详细补充
- 扩展某个章节的内容
- 细化用户操作流程
- 补充功能设计细节

### 使用方式

#### 方式 1: 提供文档片段

用户直接提供需要细化的文档片段，说明需要细化的部分：

**示例：**

```
用户：请帮我细化这个功能模块：

2.1.3 题库管理
- 功能需求概述：管理员可以管理题库

请补充详细的用户操作流程和功能设计。
```

#### 方式 2: 指定章节路径

用户说明文档的章节路径和需要细化的内容：

**示例：**

```
用户：我有一个在线考试系统的需求文档，需要细化"2.1.3 题库管理"这个模块，
包括添加题目、编辑题目、删除题目、导入导出等功能的详细说明。
```

#### 方式 3: 提供上下文

用户提供完整文档或相关章节，指出需要细化的部分：

**示例：**

```
用户：这是我的需求文档的功能模块列表：
- 用户管理
- 题库管理（需要细化）
- 考试管理
- 成绩管理

请详细补充"题库管理"模块的所有内容。
```

### 细化流程

#### 步骤 1: 理解上下文

- 分析用户提供的文档片段或描述
- 识别需要细化的具体部分
- 了解文档的整体结构和风格
- 确认细化的深度和范围

#### 步骤 2: 确认细化范围

询问用户需要细化的具体内容：

- 是否需要补充用户操作流程？
- 是否需要详细的功能设计？
- 是否需要数据字段说明？

#### 步骤 3: 直接修改原文件

**重要：使用 Edit 工具直接在原需求说明书文件上进行修改，不要创建新的临时文件。**

操作步骤：

1. 使用 Read 工具读取原需求说明书文件
2. 定位需要细化的章节位置
3. 使用 Edit 工具的 old_string 和 new_string 参数直接替换内容
4. 确保替换后的内容格式与原文档保持一致

示例：

```typescript
// 读取原文件
Read({ file_path: '/path/to/需求说明书.md' })

// 直接修改原文件中的章节
Edit({
  file_path: '/path/to/需求说明书.md',
  old_string: '#### 2.1.3 题库管理\n\n- 功能需求概述：管理员可以管理题库',
  new_string:
    '#### 2.1.3 题库管理\n\n##### 2.1.3.1 功能需求概述\n\n题库管理模块为管理员提供题目的全生命周期管理功能...'
})
```

按照标准格式生成细化内容：

- **功能需求概述**：简要说明功能目的和价值
- **用户操作流程**：详细的步骤说明，包括正常流程和异常处理
- **功能设计**：列出所有功能点、数据字段、验证规则、业务规则

#### 步骤 4: 保持一致性

- 使用与原文档相同的术语
- 遵循相同的编号和格式规范
- 保持相同的详细程度
- 确保逻辑连贯性

### 细化示例

**用户输入：**

```
请细化这个功能：

2.1.3 题库管理
- 功能需求概述：管理员可以管理题库
```

**生成的细化内容：**

```markdown
#### 2.1.3 题库管理

##### 2.1.3.1 功能需求概述

题库管理模块为管理员提供题目的全生命周期管理功能，包括题目的创建、编辑、删除、分类、导入导出等操作。支持多种题型（单选题、多选题、判断题、填空题、简答题），确保考试题目的规范化管理和高效复用。

##### 2.1.3.2 用户操作流程

**添加题目流程：**

1. 管理员进入题库管理页面
2. 点击【+ 添加题目】按钮
3. 系统打开添加题目弹窗
4. 管理员选择题目类型（单选/多选/判断/填空/简答）
5. 管理员填写题目信息：
   - 题目内容（必填）
   - 题目分类（必填）
   - 难度等级（必填）
   - 分值（必填）
   - 选项内容（选择题必填）
   - 正确答案（必填）
   - 答案解析（选填）
6. 管理员点击【保存】按钮
7. 系统验证数据：
   - 验证通过：保存题目，显示成功提示，关闭弹窗，刷新列表
   - 验证失败：显示错误提示，停留在弹窗

**编辑题目流程：**

1. 管理员在题库列表中找到目标题目
2. 点击操作列的【编辑】按钮
3. 系统打开编辑弹窗，回显题目信息
4. 管理员修改题目信息
5. 点击【保存】按钮
6. 系统验证并保存，刷新列表

**删除题目流程：**

1. 管理员在题库列表中找到目标题目
2. 点击操作列的【删除】按钮
3. 系统弹出二次确认对话框："确定要删除该题目吗？"
4. 管理员点击【确定】
5. 系统执行软删除，显示成功提示，刷新列表

##### 2.1.3.3 功能设计

**核心功能：**

- 题目列表展示：分页展示题目，支持按题型、分类、难度筛选
- 多条件筛选：支持按关键词、题型、分类、难度、创建时间筛选
- 添加题目：打开添加弹窗，支持多种题型
- 编辑题目：打开编辑弹窗，回显题目信息
- 删除题目：软删除，需二次确认
- 批量删除：选中多个题目批量删除
- 导入题目：支持 Excel 批量导入
- 导出题目：支持导出为 Excel 文件
- 题目预览：查看题目详细信息

**数据字段：**

| 字段名称 | 字段类型 | 长度限制 | 是否必填 | 默认值 | 验证规则 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| 题目ID | number | - | 自动生成 | - | - | 唯一标识 |
| 题目类型 | number | - | 是 | 1 | 1-5 | 1-单选，2-多选，3-判断，4-填空，5-简答 |
| 题目内容 | string | 500 | 是 | - | 非空 | 题目描述 |
| 题目分类 | number | - | 是 | - | 非空 | 关联分类表 |
| 难度等级 | number | - | 是 | 1 | 1-3 | 1-简单，2-中等，3-困难 |
| 分值 | number | - | 是 | 1 | >0 | 题目分值 |
| 选项内容 | array | - | 条件必填 | - | - | 选择题必填，JSON格式 |
| 正确答案 | string | 200 | 是 | - | 非空 | 正确答案 |
| 答案解析 | string | 500 | 否 | - | - | 答案解析说明 |
| 创建时间 | datetime | - | 自动生成 | - | - | 创建时间 |
| 更新时间 | datetime | - | 自动更新 | - | - | 最后更新时间 |
| 状态 | number | - | 是 | 1 | 0或1 | 1-启用，0-停用 |

**业务规则：**

- 题目内容不能为空，最多500字
- 选择题必须至少有2个选项，最多6个选项
- 单选题只能有1个正确答案，多选题可以有多个正确答案
- 题目分值必须大于0
- 删除题目为软删除，不物理删除数据
- 已被使用的题目（在试卷中）不允许删除，只能停用

**业务逻辑关联：**

- **题目分类数据来源**：题目分类来源于【分类管理】模块，只能选择状态为"启用"的分类
- **试卷引用关系**：题目被【试卷管理】模块引用，用于组卷
- **考试使用关系**：题目通过试卷被【考试管理】模块使用，用于生成考试
- **数据流向**：题库管理 → 试卷管理 → 考试管理 → 成绩管理
- **删除限制**：如果题目已被试卷引用，则不允许删除，只能停用；系统会检查题目的引用关系
```

### 表格组件使用规范

**适用于：管理后台项目**

**ElTable 使用规范：**

- 使用 Element Plus 的 ElTable 组件（不使用项目内 artTable 组件）
- 表头固定：给 ElTable 添加 `height="100%"` 属性
- 表格容器：设置 `flex: 1; overflow: auto;`
- 树形表格：使用 `row-key="id"` 和 `:tree-props="{ children: 'children' }"`
- 表头不能滚动，数据滚动

**列宽建议：**

- 选择列：50px
- ID列：80px
- 操作列：200px
- 状态列：100px
- 时间列：180px
- 其他列：根据内容自适应

### 图标使用规范

**图标类名：**

- 使用 `iconfont-sys` 类显示图标（不使用 `iconfont` 类）
- 图标代码使用 HTML 实体格式（如 ``）
- 在 template 中使用 `v-html` 渲染：`<i class="iconfont-sys" v-html="icon"></i>`

**图标样式：**

- 字体大小一般设置为 18px
- 颜色继承父元素或使用主题色

### 操作流程描述规范

使用编号清晰标注步骤：

```
用户添加功能流程：
1. 用户点击【添加】按钮
2. 系统打开添加弹窗
3. 用户填写必填字段
4. 用户点击【保存】按钮
5. 系统验证数据
   - 验证通过：保存数据，显示成功提示，关闭弹窗，刷新列表
   - 验证失败：显示错误提示，停留在弹窗
```

### 功能设计描述规范

使用列表或表格清晰展示：

**列表形式**：

```
核心功能：
- 数据列表展示：分页展示数据，支持排序
- 多条件筛选：支持按状态、时间范围筛选
- 添加功能：打开添加弹窗
- 编辑功能：打开编辑弹窗
- 删除功能：软删除，需二次确认
```

**表格形式**（用于字段说明）：

```markdown
| 字段名称 | 字段类型 | 长度限制 | 是否必填 | 默认值 | 验证规则 | 说明           |
| -------- | -------- | -------- | -------- | ------ | -------- | -------------- |
| 名称     | string   | 50       | 是       | -      | 非空     | 功能名称       |
| 状态     | number   | -        | 是       | 1      | 0或1     | 1-启用，0-停用 |
```

## 参考资源

查看 `references/template.md` 获取完整的文档模板和示例。

## 技术实现规范

在编写需求文档时，需要考虑以下技术实现规范：

### API 和 Mock 数据规范

**API 请求方法**：

- 使用 `request.get()`、`request.post()`、`request.put()`、`request.del()` 方法
- 不要使用 `request()` 直接调用或使用 `method` 参数

**Mock 数据处理**：

- 项目使用手动 Mock 模式，不使用 vite-plugin-mock 自动拦截
- Mock 文件需要导出具体的 Mock 函数
- API 文件中需要判断 `USE_MOCK` 环境变量
- Mock 数据使用固定数据，不使用随机数据
- Mock API 延迟 300ms 返回结果

**类型定义**：

- 类型定义统一放在 `src/types/` 目录下，按模块分文件
- 查询参数中的状态、类型、难度等筛选字段需要支持 `number | string | null` 类型
- 原因：从 URL 查询参数传过来的值可能是字符串类型

示例：

```typescript
/**
 * 列表查询参数
 */
export interface ListParams {
  name?: string
  status?: number | string | null // 支持 number | string | null
  type?: number | string | null // 支持 number | string | null
  page: number
  pageSize: number
}
```

**API 函数命名**：

- 遵循 RESTful 风格：get/add/update/delete + 资源名称
- 批量操作：batch + 操作 + 资源名称（如 `batchDeleteItems`）

**清理脚本**：

- 清理脚本已固定，实现新功能时不需要更新清理脚本

### 表格组件规范

**表格边框**：

- 默认不使用 `border` 属性，表格只有横向分隔线，没有竖边框
- ✅ 正确：`<el-table :data="tableData" height="100%">`
- ❌ 错误：`<el-table :data="tableData" height="100%" border>`
- 除非特殊说明需要完整边框，否则都不添加 `border` 属性

**其他规范**：

- 使用 Element Plus 的 ElTable，不使用项目内 artTable 组件
- 表头固定：给 ElTable 添加 `height="100%"` 属性
- 表格容器：设置 `flex: 1; overflow: hidden;`
- 列宽建议：操作列 200px，状态列 100px，时间列 180px
- 表头不能滚动，数据滚动

## 注意事项

1. **保持一致性**：整个文档使用统一的术语和格式
2. **详细但不冗余**：提供足够的细节，但避免重复
3. **用户视角**：从用户角度描述功能和流程
4. **可执行性**：文档应足够详细，开发人员可直接参考实现
5. **结构清晰**：使用标题、列表、表格等提高可读性
6. **业务逻辑关联**：必须说明功能模块之间的数据依赖和调用关系
7. **不写页面布局设计**：需求说明书只描述业务需求和功能逻辑，不包含具体的 UI 组件实现细节（如"使用 Element Plus 嵌套列头"、"使用 InputNumber 组件"等技术实现内容）
8. **技术方案只写方案**：技术方案章节只写技术思路和方案，不写具体的技术代码
9. **使用流程图**：业务流程、用户操作流程、功能架构等必须使用 diagram-generator 技能生成流程图
10. **需求分析表格**：使用表格描述需求，支持表格合并，清晰展示功能模块、子功能、需求描述的层级关系
11. **Markdown 列表格式规范**：为确保 Pandoc 正确转换为 Word 文档，必须遵循以下列表格式规范：
    - 粗体标题后接列表时，标题行与列表项之间必须有一个空行
    - ✅ 正确格式：

      ```markdown
      **标题**：

      - 列表项1
      - 列表项2
      ```

    - ❌ 错误格式：
      ```markdown
      **标题**：

      - 列表项1
      - 列表项2
      ```
    - 原因：Pandoc 需要空行来正确解析列表，否则在 Word 中列表会挤在一起

## 文档转换功能

### 使用场景

当用户需要将生成的 Markdown 格式需求说明书转换为其他格式时使用。

### 支持的转换格式

- **Word 文档**（.docx）：适合打印和分发
- **PDF 文档**（.pdf）：适合正式交付和存档
- **HTML 文档**（.html）：适合在线查看

### 转换方法

#### 方法一：使用 Pandoc 工具

**前提条件**：

- 系统已安装 Pandoc（`brew install pandoc` 或从官网下载）
- 对于 Word 转换，建议安装 LibreOffice 以获得更好的效果

**转换命令**：

```bash
# 转换为 Word 文档
pandoc 需求说明书.md -o 需求说明书.docx

# 转换为 PDF 文档（需要安装 LaTeX）
pandoc 需求说明书.md -o 需求说明书.pdf --pdf-engine=xelatex -V CJKmainfont="PingFang SC"

# 转换为 HTML 文档
pandoc 需求说明书.md -o 需求说明书.html --standalone --toc
```

**转换步骤**：

1. 确认需求说明书文件路径
2. 根据用户需要的格式选择对应的转换命令
3. 使用 Bash 工具执行转换命令
4. 转换完成后告知用户输出文件路径

**示例**：

```bash
# 用户请求：请把需求说明书转换成 Word 文档
cd /path/to/document
pandoc 在线考试系统需求说明书.md -o 在线考试系统需求说明书.docx
```

#### 方法二：在线转换工具

如果系统未安装 Pandoc，可以建议用户使用在线转换工具：

- Markdown to Word：https://www.markdowntoword.com/
- Markdown to PDF：https://www.markdowntopdf.com/
- CloudConvert：https://cloudconvert.com/md-to-docx

### 转换注意事项

1. **中文字体**：转换为 PDF 时需要指定中文字体（如 PingFang SC、SimSun）
2. **表格格式**：复杂表格在转换后可能需要手动调整
3. **图片路径**：如果文档中包含图片，确保图片路径正确
4. **目录生成**：使用 `--toc` 参数可以自动生成目录
5. **样式定制**：可以使用 `--reference-doc` 参数指定 Word 模板

### 用户调用示例

**用户请求**：

```
请把我的需求说明书转换成 Word 文档
```

**处理流程**：

1. 确认需求说明书文件路径
2. 检查系统是否安装 Pandoc（使用 `which pandoc` 命令）
3. 如果已安装，执行转换命令
4. 如果未安装，提示用户安装 Pandoc 或使用在线工具
5. 转换完成后告知用户输出文件路径

**用户请求**：

```
请把需求说明书转换成 PDF，并生成目录
```

**处理流程**：

1. 确认需求说明书文件路径
2. 使用带目录的 PDF 转换命令
3. 指定中文字体以支持中文显示
4. 转换完成后告知用户输出文件路径