| name | req-doc |
| description | 生成或细化需求说明书文档。支持完整文档生成和局部细化两种模式。适用场景：(1) 将需求概述转换为完整的需求说明书，(2) 对已有文档的特定章节进行详细补充和细化，(3) 只生成某个功能模块的详细说明，(4) 需要标准化的需求文档格式，支持多端系统（Web管理后台、Web学员端、移动App等） |
需求文档生成器
根据用户提供的需求概述，生成符合标准格式的详细需求说明书。
文档封面规范
每份需求说明书必须在文件最顶部加 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 文档时，导出脚本会自动：
- 删除手动目录：
remove_manual_toc() 函数删除 Markdown 中的手动目录章节
- 生成自动目录：Pandoc 根据
toc: true 自动生成 Word 目录
- 中文标题：
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 需要以下依赖（公共导出工具会自动检测并提示安装）：
必需软件：
- Python 3.7+：用于文档后处理
- Pandoc：用于 Markdown 转 Word
- 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
生成的需求说明书包含以下标准结构：
一、文档信息
二、项目概述
- 2.1 项目背景：描述项目产生的原因和必要性
- 2.2 项目建设目标：列出3-5个具体、可衡量的目标
- 2.3 项目建设范围：明确包含和不包含的功能，说明涉及的端（Web管理后台、Web用户端、移动App等）
- 2.4 业务流程图：使用 diagram-generator 技能生成，包括系统风险计算逻辑、业务流程图（泳道）、用户操作流程、数据交互流程等
- 2.5 用户角色定义：定义各类用户及其权限，使用表格展示角色清单
- 2.6 需求分析：使用表格描述，支持表格合并，包含功能模块、子功能、需求描述三列
三、项目建设内容
- 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 技能生成业务流程图，包括：
- 系统整体流程图（如风险计算逻辑）
- 业务流程图（泳道图，展示多角色协作）
- 用户操作流程图（展示用户操作步骤）
- 数据交互流程图（展示数据流向）
生成步骤：
- 分析业务流程，确定流程类型（普通流程、泳道流程等）
- 调用 diagram-generator 技能生成流程图
- 将生成的图片保存到
images/ 目录
- 在文档中插入图片引用：
（不使用 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、页面栈、下拉刷新 → 移动端项目
以下是项目类型参考（仅供识别参考，不要列出给用户）：
-
管理后台项目（Web Admin）
- 特征：侧边栏菜单、顶部导航、数据表格、表单操作
- 典型场景：后台管理系统、CMS、数据管理平台
-
Web 用户前台项目（Website）
- 特征：顶部导航、页面路由、内容展示、用户交互
- 典型场景：企业官网、产品官网、门户网站
-
移动端项目（Mobile App）
- 特征：底部 Tabbar、页面栈、下拉刷新、上拉加载
- 典型场景：H5 应用、移动端网站、小程序
-
混合项目（Multi-Platform）
- 包含多个端：管理后台 + 用户前台 + 移动端
- 每个端独立设计
步骤 2: 收集需求信息
询问用户以下关键信息：
- 项目类型和目标
- 目标用户群体
- 核心功能模块
- 涉及的端（Web管理后台、Web学员端、移动App等）
- 特殊需求或约束
步骤 3: 分析需求
基于用户提供的信息：
- 识别核心业务流程
- 确定用户角色和权限
- 梳理功能模块层级关系
- 明确各端的功能范围
步骤 4: 生成文档
按照标准结构生成需求说明书：
-
项目概述部分：
-
项目建设内容部分：
- 总体功能架构：使用 diagram-generator 技能生成功能架构图
- 页面访问权限：使用表格展示各角色对各功能的访问权限
- 各功能详细设计：对每个功能模块详细描述
- 功能需求概述：简要说明功能目的和价值
- 所属菜单：说明是一级菜单、二级菜单还是其他
- 用户操作流程：使用 diagram-generator 技能生成流程图，并用编号列表描述步骤
- 功能设计：列出所有功能点、数据字段、验证规则、业务规则
- 业务逻辑关联：说明与其他功能模块的数据依赖关系
- 注意：不要写页面布局设计
-
技术方案部分（新增）：
- 技术架构：前后端技术栈、系统架构设计
- 数据交互：前后端数据交互方式、API 设计原则
- 外部系统集成：如果涉及外系统，说明数据交互方式
- 安全方案：身份认证、权限控制、数据加密等
- 注意：只写技术方案和思路，不写具体技术代码
-
非功能需求部分（新增）：
- 性能需求：响应时间、并发用户数、数据处理能力
- 安全需求：身份认证、数据安全、权限控制
- 可用性需求：系统可用性、故障恢复、数据备份
- 兼容性需求：浏览器兼容性、设备兼容性
-
数据需求部分（新增，按实际情况）：
- 数据字典：枚举值定义
- 数据存储要求：数据保留期限、存储容量规划
-
接口需求部分（新增，按实际情况）：
-
项目实施与验收部分（新增）：
- 实施阶段：需求确认、设计开发、测试部署、上线运行
- 系统培训服务：培训对象、培训内容、培训方式
- 验收标准：功能验收、性能验收、文档验收
-
附录部分（新增，按实际情况）：
步骤 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: 创建任务清单
按照功能模块创建任务：
TaskCreate({
subject: '项目概述章节',
description: '编写项目背景、建设目标、建设范围、业务流程图、用户角色定义',
activeForm: '编写项目概述'
})
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 格式：
- 格式：
"编写" + [功能模块名称] + "功能模块"
- 示例：
- "编写用户管理功能模块"
- "编写题库管理功能模块"
多端项目的任务组织
对于涉及多个端的项目，按端和功能模块组织任务：
TaskCreate({
subject: 'Web管理后台-用户管理功能模块',
description: '编写 Web 管理后台的用户管理功能需求...',
activeForm: '编写 Web 管理后台用户管理功能'
})
TaskCreate({
subject: 'Web管理后台-题库管理功能模块',
description: '编写 Web 管理后台的题库管理功能需求...',
activeForm: '编写 Web 管理后台题库管理功能'
})
TaskCreate({
subject: 'Web学员端-在线考试功能模块',
description: '编写 Web 学员端的在线考试功能需求...',
activeForm: '编写 Web 学员端在线考试功能'
})
TaskCreate({
subject: 'Web学员端-成绩查询功能模块',
description: '编写 Web 学员端的成绩查询功能需求...',
activeForm: '编写 Web 学员端成绩查询功能'
})
注意事项
- 任务粒度一致：所有任务应保持相同的粒度级别（功能模块级别）
- 任务独立性：每个任务应该是独立的，可以单独完成
- 任务完整性：每个任务应包含该功能模块的所有必要内容
- 及时更新状态：开始任务时设置为 in_progress，完成后设置为 completed
- 按顺序执行：优先完成 ID 较小的任务，保持工作的连贯性
局部细化模式
适用场景
当用户需要对已有需求文档进行局部细化时使用，包括：
- 对某个功能模块进行详细补充
- 扩展某个章节的内容
- 细化用户操作流程
- 补充功能设计细节
使用方式
方式 1: 提供文档片段
用户直接提供需要细化的文档片段，说明需要细化的部分：
示例：
用户：请帮我细化这个功能模块：
2.1.3 题库管理
- 功能需求概述：管理员可以管理题库
请补充详细的用户操作流程和功能设计。
方式 2: 指定章节路径
用户说明文档的章节路径和需要细化的内容：
示例：
用户：我有一个在线考试系统的需求文档，需要细化"2.1.3 题库管理"这个模块，
包括添加题目、编辑题目、删除题目、导入导出等功能的详细说明。
方式 3: 提供上下文
用户提供完整文档或相关章节，指出需要细化的部分：
示例：
用户：这是我的需求文档的功能模块列表：
- 用户管理
- 题库管理（需要细化）
- 考试管理
- 成绩管理
请详细补充"题库管理"模块的所有内容。
细化流程
步骤 1: 理解上下文
- 分析用户提供的文档片段或描述
- 识别需要细化的具体部分
- 了解文档的整体结构和风格
- 确认细化的深度和范围
步骤 2: 确认细化范围
询问用户需要细化的具体内容：
- 是否需要补充用户操作流程？
- 是否需要详细的功能设计？
- 是否需要数据字段说明？
步骤 3: 直接修改原文件
重要：使用 Edit 工具直接在原需求说明书文件上进行修改，不要创建新的临时文件。
操作步骤：
- 使用 Read 工具读取原需求说明书文件
- 定位需要细化的章节位置
- 使用 Edit 工具的 old_string 和 new_string 参数直接替换内容
- 确保替换后的内容格式与原文档保持一致
示例：
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
type?: 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
- 表头不能滚动，数据滚动
注意事项
- 保持一致性：整个文档使用统一的术语和格式
- 详细但不冗余：提供足够的细节，但避免重复
- 用户视角：从用户角度描述功能和流程
- 可执行性：文档应足够详细，开发人员可直接参考实现
- 结构清晰：使用标题、列表、表格等提高可读性
- 业务逻辑关联：必须说明功能模块之间的数据依赖和调用关系
- 不写页面布局设计：需求说明书只描述业务需求和功能逻辑，不包含具体的 UI 组件实现细节（如"使用 Element Plus 嵌套列头"、"使用 InputNumber 组件"等技术实现内容）
- 技术方案只写方案：技术方案章节只写技术思路和方案，不写具体的技术代码
- 使用流程图：业务流程、用户操作流程、功能架构等必须使用 diagram-generator 技能生成流程图
- 需求分析表格：使用表格描述需求，支持表格合并，清晰展示功能模块、子功能、需求描述的层级关系
- Markdown 列表格式规范：为确保 Pandoc 正确转换为 Word 文档，必须遵循以下列表格式规范：
文档转换功能
使用场景
当用户需要将生成的 Markdown 格式需求说明书转换为其他格式时使用。
支持的转换格式
- Word 文档（.docx）：适合打印和分发
- PDF 文档（.pdf）：适合正式交付和存档
- HTML 文档（.html）：适合在线查看
转换方法
方法一：使用 Pandoc 工具
前提条件：
- 系统已安装 Pandoc（
brew install pandoc 或从官网下载）
- 对于 Word 转换，建议安装 LibreOffice 以获得更好的效果
转换命令：
pandoc 需求说明书.md -o 需求说明书.docx
pandoc 需求说明书.md -o 需求说明书.pdf --pdf-engine=xelatex -V CJKmainfont="PingFang SC"
pandoc 需求说明书.md -o 需求说明书.html --standalone --toc
转换步骤：
- 确认需求说明书文件路径
- 根据用户需要的格式选择对应的转换命令
- 使用 Bash 工具执行转换命令
- 转换完成后告知用户输出文件路径
示例：
cd /path/to/document
pandoc 在线考试系统需求说明书.md -o 在线考试系统需求说明书.docx
方法二：在线转换工具
如果系统未安装 Pandoc，可以建议用户使用在线转换工具：
转换注意事项
- 中文字体：转换为 PDF 时需要指定中文字体（如 PingFang SC、SimSun）
- 表格格式：复杂表格在转换后可能需要手动调整
- 图片路径：如果文档中包含图片，确保图片路径正确
- 目录生成：使用
--toc 参数可以自动生成目录
- 样式定制：可以使用
--reference-doc 参数指定 Word 模板
用户调用示例
用户请求：
请把我的需求说明书转换成 Word 文档
处理流程：
- 确认需求说明书文件路径
- 检查系统是否安装 Pandoc（使用
which pandoc 命令）
- 如果已安装，执行转换命令
- 如果未安装，提示用户安装 Pandoc 或使用在线工具
- 转换完成后告知用户输出文件路径
用户请求：
请把需求说明书转换成 PDF，并生成目录
处理流程：
- 确认需求说明书文件路径
- 使用带目录的 PDF 转换命令
- 指定中文字体以支持中文显示
- 转换完成后告知用户输出文件路径
