|
|
@@ -0,0 +1,270 @@
|
|
|
+# 需求说明书 · 文档骨架与功能条目格式
|
|
|
+
|
|
|
+## 一、文件要求
|
|
|
+
|
|
|
+- 文件名:`需求说明书-{项目简称}-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 条
|
|
|
+- 会改动其他业务的数据或状态
|
|
|
+- 涉及金额、权限、状态流转
|
|
|
+- 有幂等性要求(重复点击怎么办)
|
|
|
+
|
|
|
+其余的,总表里一行写清就够。
|
|
|
+
|
|
|
+## 五、常见不合格写法对照
|
|
|
+
|
|
|
+| 不合格 | 问题 | 改法 |
|
|
|
+|---|---|---|
|
|
|
+| 输入:用户信息 | 没到字段级 | 展开成具体字段表 |
|
|
|
+| 处理规则:按公司规定审批 | 规则不可执行 | 写明天数区间与对应审批人 |
|
|
|
+| 有增删改查功能 | 按钮没列清 | 按按钮清单逐个列 |
|
|
|
+| 禁用:修改状态 | 没说影响谁 | 补「对其他业务的影响」 |
|
|
|
+| 影响:可能影响其他模块 | 等于没说 | 点名具体页面和字段 |
|
|
|
+| 输出:保存到数据库 | 没说哪张表、哪些字段 | 写表名与关键字段 |
|
|
|
+| 异常处理:报错提示 | 没说什么错、提示什么 | 列异常清单与提示文案 |
|
|
|
+| 验收标准:操作便捷 | 不可验证 | 改成可观测的行为 |
|
|
|
+| 性能:响应快 | 不可验证 | 写具体秒数或并发数 |
|