模板-需求说明书.md 11 KB

需求说明书 · 文档骨架与功能条目格式

一、文件要求

  • 文件名:需求说明书-{项目简称}-v{版本}.md
  • 存放:docs/01-需求/
  • 图:一律 mermaid,不贴截图(截图不可 diff、不可检索)
  • 所有输入输出写到字段级

二、文档骨架

# {项目名称} 需求说明书

## 0 文档信息
| 项 | 内容 |
|---|---|
| 版本 | v1.0 |
| 编写 | |
| AI 参与度 | L2 |
| 使用模型 | |
| 复核 | |
| 对应立项单 | |

### 版本变更历史
| 版本 | 章节 | 类型 | 变更说明 | 日期 | 变更人 |
|---|---|---|---|---|---|
| v1.0 | 全部 | C | 创建 | | |

> 类型:C 创建 / U 修改 / D 删除 / A 增加

## 1 项目背景与目标
### 1.1 业务背景(客户为什么现在要做这件事)
### 1.2 建设目标(必须可度量,不写"提升效率")
### 1.3 范围边界
- 本期做:
- **本期明确不做**:(这条最重要,防止后续扯皮)
### 1.4 对其它系统的影响
| 系统 | 影响方式 | 处理 |
|---|---|---|
| 老系统 XXX | 本系统上线后替代 | 数据迁移,旧系统停用 |
| HR 系统 | 需要接口对接 | 见接口需求章节 |
| 单点登录 | 需要接入 | 由客户 IT 提供配置 |

### 1.5 名词定义
客户内部叫法与我方理解的对照,详见 `glossary.md`。本节只列最容易混淆的三到五个。

## 2 用户与角色
### 2.1 角色清单
| 角色 | 职责 | 数据可见范围 | 关键操作权限 |
### 2.2 权限矩阵
| 操作 \ 角色 | A | B | C |

## 3 业务流程
### 3.1 主流程(mermaid flowchart + 文字说明)
### 3.2 分支与异常流

## 4 功能需求
### 4.1 功能清单
| 编号 | 功能名 | 优先级 | 来源类型 | 确认人 |
### 4.2 功能详述(每功能一节,含按钮清单)

## 5 数据需求
### 5.1 核心实体与关系(mermaid erDiagram)
### 5.2 数据量与增长预估
### 5.3 保留与归档

## 6 非功能需求
性能 / 并发 / 可用性 / 兼容性 / 安全 / 审计

## 7 接口需求
| 系统 | 方向 | 频率 | 数据格式 | 失败处理 |

## 8 验收标准
按功能列可验证条件

## 9 需求变更记录
| 日期 | 变更内容 | 原因 | 影响范围 | 确认人 |

## 附录 A 需求来源追溯表
| 需求编号 | 来源类型 | 具体依据 | 确认人 | 确认日期 |

## 附录 B 按钮总表
| 功能 | 按钮 | 前置校验摘要 | 跨业务影响 |

三、功能条目分两种类型

不是所有功能都长一个样。先判断它属于哪类,再按对应格式写。

每个功能条目必含:来源、来源类型、入口、页面原型、输入(字段级)、按钮清单、输出、异常处理、验收标准。

按情况必填:

项 什么时候必须写
历史数据 迭代项目必填,说明老系统已有数据怎么处理(迁移 / 不迁 / 清洗规则)
处理规则 有审批流、状态流转的功能必填
接口依赖 需要调外部系统时必填,并关联接口设计说明书编号

3.1 类型 A:数据管理类(以按钮为主体)

典型:用户管理、组织机构、字典维护、商品档案。特征是页面上有一排按钮,每个按钮对应一个动作。

格式:先给按钮清单总表,再逐个按钮详述。

### F-001 用户管理

**来源**:客户原话(2026-11-05 访谈,王主任:"用户要能停用,走了的人别删")
**来源类型**:客户原话
**入口**:系统设置 → 用户管理
**页面原型**:`prototype/pages/user-list.vue`

#### 按钮清单

| 按钮 | 位置 | 显示条件 | 前置校验 | 处理逻辑 | 对其他业务的影响 |
|---|---|---|---|---|---|
| 新增 | 页面顶部 | 有「用户新增」权限 | 必填项完整;账号不重复 | 插入用户记录,初始状态=启用 | 所属组织人数 +1 |
| 查询 | 页面顶部 | 无 | 无 | 按条件分页查询,默认创建时间倒序 | 无 |
| 修改 | 行内 | 有权限 且 状态=启用 | 账号不可改;手机号格式 | 更新用户信息,写变更日志 | 若改了所属部门,原部门与新部门人数都要重算 |
| 禁用 | 行内 | 有权限 且 状态=启用 | 用户状态是启用的 | 把用户状态改成禁用 | 组织机构选择负责人时要把禁用的用户过滤掉 |
| 启用 | 行内 | 有权限 且 状态=禁用 | 用户状态是禁用的 | 把用户状态改成启用 | 恢复出现在负责人候选列表中 |
| 重置密码 | 行内 | 有权限 且 状态=启用 | 无 | 密码重置为初始密码,标记首次登录须改密 | 无 |
| 导出 | 页面顶部 | 有「用户导出」权限 | 查询结果不为空 | 导出当前查询结果为 xlsx | 无 |

#### 按钮详述(仅复杂按钮需要展开)

##### B-004 禁用

**显示条件**:有「用户禁用」权限 且 用户状态=启用
**前置校验**
| # | 校验 | 不通过提示 |
|---|---|---|
| 1 | 用户状态必须是启用 | 该用户已是禁用状态 |
| 2 | 不能禁用自己 | 不能禁用自己的账号 |
| 3 | 不能禁用最后一名启用的超级管理员 | 系统须保留至少一名启用的超级管理员 |

**处理逻辑**
1. `user.status` 置为 0(禁用)
2. 写操作日志:操作人、时间、被禁用用户、原状态
3. 若该用户是某组织负责人,该组织负责人置空,并通知系统管理员

**对其他业务的影响**
- 组织机构选择负责人:候选人列表过滤掉禁用用户
- 待办任务:该用户名下未办结的待办转交其上级
- 登录:禁用用户无法登录;已登录会话立即失效
- 报表:历史数据中该用户的操作记录保留,不做处理

**幂等性**:重复点击禁用,第二次提示"该用户已是禁用状态",不产生重复日志

**验收标准**:上述 3 条前置校验逐条可验;禁用后该用户无法登录;组织负责人候选列表不再出现该用户

3.2 类型 B:业务流程类(以规则为主体)

典型:请假审批、报销、工单流转。特征是有一条按顺序推进的链路。

### F-003 请假申请

**来源**:客户原话(2026-11-05 访谈,王主任:"年假要能一次请完,别再分两次")
**来源类型**:客户原话

**功能描述**:员工提交请假单,按请假天数走不同审批链。

**入口**:移动端首页「请假」图标;PC 端 我的-考勤-请假

**输入**
| 字段 | 类型 | 必填 | 长度 | 校验规则 | 默认值 |
|---|---|---|---|---|---|
| 请假类型 | 枚举 | 是 | — | 年假/事假/病假/调休 | — |
| 开始时间 | datetime | 是 | — | 不早于当日 00:00 | 当前时间 |
| 结束时间 | datetime | 是 | — | 晚于开始时间 | 开始时间+1天 |
| 请假天数 | 小数 | 是 | 5,1 | 自动计算,0.5 步进 | 自动 |
| 事由 | 文本 | 是 | 200 | 不少于 5 字 | — |
| 附件 | 文件 | 否 | 10MB | 病假必传 | — |

**按钮清单**
| 按钮 | 位置 | 显示条件 | 前置校验 | 处理逻辑 | 对其他业务的影响 |
|---|---|---|---|---|---|
| 提交 | 表单底部 | 状态=草稿 | 见下方处理规则 1~6 | 落库并启动审批流 | 占用年假余额(预扣) |
| 保存草稿 | 表单底部 | 状态=草稿 | 无 | 仅落库,不启动流程 | 无 |
| 撤回 | 详情页 | 状态=审批中 且 首节点未处理 | 审批人未操作 | 终止流程,退回草稿 | 释放预扣的年假余额 |

**处理规则**(按顺序,含边界)
1. 天数 ≤ 1 天 且 类型为事假 → 直属主管审批
2. 天数 ≤ 3 天 → 直属主管 → 部门经理
3. 天数 > 3 天 → 直属主管 → 部门经理 → 人事
4. 年假余额不足时,提交即拦截,提示剩余天数
5. 病假超过 2 天必须上传证明,否则不允许提交
6. 同一时间段重复提交 → 拦截并提示已存在的单据

**输出**
- 页面:提交成功页,显示单号与当前审批人
- 落库:`leave_apply` 主表 + `leave_apply_flow` 审批流水表
- 下游:审批通过后写考勤台账,同步 HR 系统

**异常处理**
| 异常 | 处理 |
|---|---|
| 审批人离职 | 转其上级,记录转派日志 |
| HR 系统超时 | 本地挂起,定时重试 3 次,仍失败告警 |

**验收标准**:上述 6 条规则逐条可验;余额不足、重复提交两种拦截有明确提示文案

判断标准:把这一节单独发给开发,他能不问你就开始写代码,才算写到位。

四、按钮清单规范

4.1 三个字段千万别混

这是最容易写串的地方,写串了开发就会做错:

字段 回答的问题 例子
显示条件 按钮看不看得见 无权限的用户,根本看不到「禁用」按钮
前置校验 点了之后能不能成功 按钮看得见,但点了提示"不能禁用自己"
处理逻辑 成功后系统做了什么 状态改为禁用、写日志、清组织负责人

三者混在一起写的典型后果:把"不能禁用自己"写成显示条件,结果按钮直接不显示,用户不知道为什么不让他点。

4.2 「对其他业务的影响」怎么推

这一栏是最容易漏的,也是后期扯皮的根源。按四个方向推:

方向 问什么
数据被谁引用 这个字段/状态在哪些查询、报表、下拉框里被用到
状态变化影响谁 状态改了之后,哪些地方的列表/候选/统计要跟着变
下游系统 有没有同步给其他系统,同步失败怎么办
历史数据 已产生的历史记录要不要跟着改(通常不改,但要说清)

判断标准:写完之后问一句"这个按钮点下去,还有哪个页面会变",答不上来就是没写全。

4.3 防止漏按钮的检查法

按钮漏一个,开发就少做一个,最后验收才发现。三个检查动作:

  1. 对着原型数:打开原型页,从左到右、从上到下,见一个记一个,不凭记忆
  2. 套标准组合:列表页至少要有 新增 / 查询 / 导出 / (行内)修改 / 删除或禁用;表单页要有 提交 / 取消 / 保存草稿
  3. 按状态机推:凡是状态会变的,每一个"从 A 到 B"的转换都要有一个按钮或一个操作入口,包括审批通过/驳回

最容易漏的四类:导出、批量操作、状态互逆操作(禁用/启用、启用/停用)、隐藏的二次确认入口。

4.4 什么时候要展开「按钮详述」

不是每个按钮都要展开。满足任一条就展开:

  • 前置校验超过 2 条
  • 会改动其他业务的数据或状态
  • 涉及金额、权限、状态流转
  • 有幂等性要求(重复点击怎么办)

其余的,总表里一行写清就够。

五、常见不合格写法对照

不合格 问题 改法
输入:用户信息 没到字段级 展开成具体字段表
处理规则:按公司规定审批 规则不可执行 写明天数区间与对应审批人
有增删改查功能 按钮没列清 按按钮清单逐个列
禁用:修改状态 没说影响谁 补「对其他业务的影响」
影响:可能影响其他模块 等于没说 点名具体页面和字段
输出:保存到数据库 没说哪张表、哪些字段 写表名与关键字段
异常处理:报错提示 没说什么错、提示什么 列异常清单与提示文案
验收标准:操作便捷 不可验证 改成可观测的行为
性能:响应快 不可验证 写具体秒数或并发数