# 需求说明书 · 文档骨架与功能条目格式 ## 一、文件要求 - 文件名:`需求说明书-{项目简称}-v{版本}.md` - 存放:`docs/01-需求/` - 图:一律 mermaid,不贴截图(截图不可 diff、不可检索) - 所有输入输出写到字段级 ## 二、文档骨架 ```markdown # {项目名称} 需求说明书 ## 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:数据管理类(以按钮为主体) 典型:用户管理、组织机构、字典维护、商品档案。特征是页面上有一排按钮,每个按钮对应一个动作。 **格式:先给按钮清单总表,再逐个按钮详述。** ```markdown ### 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:业务流程类(以规则为主体) 典型:请假审批、报销、工单流转。特征是有一条按顺序推进的链路。 ```markdown ### 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 条 - 会改动其他业务的数据或状态 - 涉及金额、权限、状态流转 - 有幂等性要求(重复点击怎么办) 其余的,总表里一行写清就够。 ## 五、常见不合格写法对照 | 不合格 | 问题 | 改法 | |---|---|---| | 输入:用户信息 | 没到字段级 | 展开成具体字段表 | | 处理规则:按公司规定审批 | 规则不可执行 | 写明天数区间与对应审批人 | | 有增删改查功能 | 按钮没列清 | 按按钮清单逐个列 | | 禁用:修改状态 | 没说影响谁 | 补「对其他业务的影响」 | | 影响:可能影响其他模块 | 等于没说 | 点名具体页面和字段 | | 输出:保存到数据库 | 没说哪张表、哪些字段 | 写表名与关键字段 | | 异常处理:报错提示 | 没说什么错、提示什么 | 列异常清单与提示文案 | | 验收标准:操作便捷 | 不可验证 | 改成可观测的行为 | | 性能:响应快 | 不可验证 | 写具体秒数或并发数 |