需求说明书-{项目简称}-v{版本}.mddocs/01-需求/# {项目名称} 需求说明书
## 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 按钮总表
| 功能 | 按钮 | 前置校验摘要 | 跨业务影响 |
不是所有功能都长一个样。先判断它属于哪类,再按对应格式写。
每个功能条目必含:来源、来源类型、入口、页面原型、输入(字段级)、按钮清单、输出、异常处理、验收标准。
按情况必填:
| 项 | 什么时候必须写 |
|---|---|
| 历史数据 | 迭代项目必填,说明老系统已有数据怎么处理(迁移 / 不迁 / 清洗规则) |
| 处理规则 | 有审批流、状态流转的功能必填 |
| 接口依赖 | 需要调外部系统时必填,并关联接口设计说明书编号 |
典型:用户管理、组织机构、字典维护、商品档案。特征是页面上有一排按钮,每个按钮对应一个动作。
格式:先给按钮清单总表,再逐个按钮详述。
### F-001 用户管理
**来源**:客户原话(2026-11-05 访谈,王主任:"用户要能停用,走了的人别删")
**来源类型**:客户原话
**入口**:系统设置 → 用户管理
**页面原型**:`prototype/pages/user-list.vue`
#### 按钮清单
| 按钮 | 位置 | 显示条件 | 前置校验 | 处理逻辑 | 对其他业务的影响 |
|---|---|---|---|---|---|
| 新增 | 页面顶部 | 有「用户新增」权限 | 必填项完整;账号不重复 | 插入用户记录,初始状态=启用 | 所属组织人数 +1 |
| 查询 | 页面顶部 | 无 | 无 | 按条件分页查询,默认创建时间倒序 | 无 |
| 修改 | 行内 | 有权限 且 状态=启用 | 账号不可改;手机号格式 | 更新用户信息,写变更日志 | 若改了所属部门,原部门与新部门人数都要重算 |
| 禁用 | 行内 | 有权限 且 状态=启用 | 用户状态是启用的 | 把用户状态改成禁用 | 组织机构选择负责人时要把禁用的用户过滤掉 |
| 启用 | 行内 | 有权限 且 状态=禁用 | 用户状态是禁用的 | 把用户状态改成启用 | 恢复出现在负责人候选列表中 |
| 重置密码 | 行内 | 有权限 且 状态=启用 | 无 | 密码重置为初始密码,标记首次登录须改密 | 无 |
| 导出 | 页面顶部 | 有「用户导出」权限 | 查询结果不为空 | 导出当前查询结果为 xlsx | 无 |
#### 按钮详述(仅复杂按钮需要展开)
##### B-004 禁用
**显示条件**:有「用户禁用」权限 且 用户状态=启用
**前置校验**
| # | 校验 | 不通过提示 |
|---|---|---|
| 1 | 用户状态必须是启用 | 该用户已是禁用状态 |
| 2 | 不能禁用自己 | 不能禁用自己的账号 |
| 3 | 不能禁用最后一名启用的超级管理员 | 系统须保留至少一名启用的超级管理员 |
**处理逻辑**
1. `user.status` 置为 0(禁用)
2. 写操作日志:操作人、时间、被禁用用户、原状态
3. 若该用户是某组织负责人,该组织负责人置空,并通知系统管理员
**对其他业务的影响**
- 组织机构选择负责人:候选人列表过滤掉禁用用户
- 待办任务:该用户名下未办结的待办转交其上级
- 登录:禁用用户无法登录;已登录会话立即失效
- 报表:历史数据中该用户的操作记录保留,不做处理
**幂等性**:重复点击禁用,第二次提示"该用户已是禁用状态",不产生重复日志
**验收标准**:上述 3 条前置校验逐条可验;禁用后该用户无法登录;组织负责人候选列表不再出现该用户
典型:请假审批、报销、工单流转。特征是有一条按顺序推进的链路。
### 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 条规则逐条可验;余额不足、重复提交两种拦截有明确提示文案
判断标准:把这一节单独发给开发,他能不问你就开始写代码,才算写到位。
这是最容易写串的地方,写串了开发就会做错:
| 字段 | 回答的问题 | 例子 |
|---|---|---|
| 显示条件 | 按钮看不看得见 | 无权限的用户,根本看不到「禁用」按钮 |
| 前置校验 | 点了之后能不能成功 | 按钮看得见,但点了提示"不能禁用自己" |
| 处理逻辑 | 成功后系统做了什么 | 状态改为禁用、写日志、清组织负责人 |
三者混在一起写的典型后果:把"不能禁用自己"写成显示条件,结果按钮直接不显示,用户不知道为什么不让他点。
这一栏是最容易漏的,也是后期扯皮的根源。按四个方向推:
| 方向 | 问什么 |
|---|---|
| 数据被谁引用 | 这个字段/状态在哪些查询、报表、下拉框里被用到 |
| 状态变化影响谁 | 状态改了之后,哪些地方的列表/候选/统计要跟着变 |
| 下游系统 | 有没有同步给其他系统,同步失败怎么办 |
| 历史数据 | 已产生的历史记录要不要跟着改(通常不改,但要说清) |
判断标准:写完之后问一句"这个按钮点下去,还有哪个页面会变",答不上来就是没写全。
按钮漏一个,开发就少做一个,最后验收才发现。三个检查动作:
最容易漏的四类:导出、批量操作、状态互逆操作(禁用/启用、启用/停用)、隐藏的二次确认入口。
不是每个按钮都要展开。满足任一条就展开:
其余的,总表里一行写清就够。
| 不合格 | 问题 | 改法 |
|---|---|---|
| 输入:用户信息 | 没到字段级 | 展开成具体字段表 |
| 处理规则:按公司规定审批 | 规则不可执行 | 写明天数区间与对应审批人 |
| 有增删改查功能 | 按钮没列清 | 按按钮清单逐个列 |
| 禁用:修改状态 | 没说影响谁 | 补「对其他业务的影响」 |
| 影响:可能影响其他模块 | 等于没说 | 点名具体页面和字段 |
| 输出:保存到数据库 | 没说哪张表、哪些字段 | 写表名与关键字段 |
| 异常处理:报错提示 | 没说什么错、提示什么 | 列异常清单与提示文案 |
| 验收标准:操作便捷 | 不可验证 | 改成可观测的行为 |
| 性能:响应快 | 不可验证 | 写具体秒数或并发数 |