Req Doc

需求文档生成器

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

文档封面规范

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

---
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 之后，必须添加文档信息表格，用于展示项目的基本信息：

## 文档信息

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

字段说明：

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

目录管理策略

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

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 .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：

brew install python3 pandoc
pip3 install python-docx

Windows：

choco install python3 pandoc
pip3 install python-docx

Linux：

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 需求分析：使用表格描述，支持表格合并，包含功能模块、子功能、需求描述三列
  • 表格合并语法：使用 ^ 符号表示与上一行单元格合并
  • 示例：

    | 功能模块 | 子功能       | 需求描述         |
    | -------- | ------------ | ---------------- |
    | 库站管理 | 库站信息维护 | 维护库站基础信息 |
    | ^        | 业态设置     | 设置库站业态类型 |
    | ^        | 销量统计     | 维护月度销量数据 |
    | ^        | 员工查看     | 查看库站用户列表 |
    

  • 导出为 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 技能生成流程图
   • 用户角色：使用表格定义各类用户及其权限
   • 需求分析表格（新增）：使用表格描述需求，支持表格合并

     | 功能模块     | 子功能           | 需求描述                                     |
     | ------------ | ---------------- | -------------------------------------------- |
     | 风险规则设置 | 固有风险规则     | 设置加能站的业态风险值和销量风险值的配置     |
     | 风险规则设置 | 检查问题风险规则 | 设置检查问题的严重程度、频次、修正系数等参数 |
     | 库站管理     | 库站信息维护     | 维护库站基础信息、业态设置、销量统计         |
     

2. 项目建设内容部分：

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

3. 技术方案部分（新增）：

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

4. 非功能需求部分（新增）：

   • 性能需求：响应时间、并发用户数、数据处理能力
   • 安全需求：身份认证、数据安全、权限控制
   • 可用性需求：系统可用性、故障恢复、数据备份
   • 兼容性需求：浏览器兼容性、设备兼容性

5. 数据需求部分（新增，按实际情况）：

   • 数据字典：枚举值定义
   • 数据存储要求：数据保留期限、存储容量规划

6. 接口需求部分（新增，按实际情况）：

   • 第三方系统接入接口规范

7. 项目实施与验收部分（新增）：

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

8. 附录部分（新增，按实际情况）：

   • 术语表
   • 参考资料

步骤 4: 优化和完善

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

任务清单管理规范

何时使用任务清单

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

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

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

任务粒度规范

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

✅ 正确的任务粒度

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

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

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

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

❌ 错误的任务粒度

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

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

任务创建流程

步骤 1: 分析需求范围

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

步骤 2: 创建任务清单

按照功能模块创建任务：

// 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 格式：

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

多端项目的任务组织

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

// 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. 确保替换后的内容格式与原文档保持一致

示例：

// 读取原文件
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 题库管理
- 功能需求概述：管理员可以管理题库

生成的细化内容：

#### 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. 系统验证数据
   - 验证通过：保存数据，显示成功提示，关闭弹窗，刷新列表
   - 验证失败：显示错误提示，停留在弹窗

功能设计描述规范

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

列表形式：

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

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

| 字段名称 | 字段类型 | 长度限制 | 是否必填 | 默认值 | 验证规则 | 说明           |
| -------- | -------- | -------- | -------- | ------ | -------- | -------------- |
| 名称     | 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 查询参数传过来的值可能是字符串类型

示例：

/**
 * 列表查询参数
 */
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 文档，必须遵循以下列表格式规范：

    • 粗体标题后接列表时，标题行与列表项之间必须有一个空行

    • ✅ 正确格式：

      **标题**：
      
      - 列表项1
      - 列表项2
      

    • ❌ 错误格式：

      **标题**：
      
      - 列表项1
      - 列表项2
      

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

文档转换功能

使用场景

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

支持的转换格式

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

转换方法

方法一：使用 Pandoc 工具

前提条件：

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

转换命令：

# 转换为 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. 转换完成后告知用户输出文件路径

示例：

# 用户请求：请把需求说明书转换成 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. 转换完成后告知用户输出文件路径