201 lines
7.3 KiB
Markdown
201 lines
7.3 KiB
Markdown
# 模块需求卡生成规范
|
|
|
|
本规范用于后续生成各业务模块需求卡，统一采用 `港口码头主数据需求卡.md` 的非表格条目式格式。需求卡应便于产品、前端、后端、测试共同理解，重点描述功能行为、异常边界和反例，不写成测试用例表格。
|
|
|
|
## 一、文件命名
|
|
|
|
- 文件名格式：`{模块名称}需求卡.md`
|
|
- 示例：`港口码头主数据需求卡.md`、`币种汇率管理需求卡.md`
|
|
- 模块名称应使用业务侧可识别名称，避免仅使用接口名、表名或英文缩写。
|
|
|
|
## 二、文档结构
|
|
|
|
需求卡固定包含以下结构：
|
|
|
|
```md
|
|
# {模块名称}需求卡
|
|
|
|
## 目录
|
|
|
|
- [REQ-{模块编码}-01 {功能标题}](#req-模块编码-01-功能标题)
|
|
- [REQ-{模块编码}-02 {功能标题}](#req-模块编码-02-功能标题)
|
|
- [通用规则](#通用规则)
|
|
|
|
REQ-{模块编码}-01 {功能标题}
|
|
|
|
- 功能点：{对该功能的简要概括描述}
|
|
- 异常与边界：①{异常或边界 1}；②{异常或边界 2}；③{异常或边界 3}。
|
|
- 反例：①{不允许的规则或错误用法 1}；②{不允许的规则或错误用法 2}；③{不允许的规则或错误用法 3}。
|
|
|
|
REQ-{模块编码}-02 {功能标题}
|
|
|
|
- 功能点：{对该功能的简要概括描述}
|
|
- 异常与边界：①{异常或边界 1}；②{异常或边界 2}。
|
|
- 反例：①{不允许的规则或错误用法 1}；②{不允许的规则或错误用法 2}。
|
|
|
|
## 通用规则
|
|
|
|
- {模块通用规则 1}
|
|
- {模块通用规则 2}
|
|
- {模块通用规则 3}
|
|
```
|
|
|
|
目录生成要求：
|
|
|
|
- 标题后必须立即生成 `## 目录`。
|
|
- 目录必须包含所有 `REQ` 需求项和 `## 通用规则`，顺序与正文保持一致。
|
|
- 目录使用 Markdown 链接，锚点与正文标题保持可跳转对应关系。
|
|
- 后续新增、删除、调整 `REQ` 项时，必须同步更新目录。
|
|
|
|
## 三、编号规则
|
|
|
|
- 每个功能描述使用 `REQ-{模块编码}-{两位序号}`。
|
|
- `{模块编码}` 使用 3 到 8 位大写英文，优先取模块英文简称。
|
|
- 序号从 `01` 开始递增，不跳号。
|
|
- 同一模块内编号不得重复。
|
|
|
|
示例：
|
|
|
|
- 港口/码头主数据：`REQ-PORT-01`
|
|
- 币种汇率管理：`REQ-CURR-01`
|
|
- 车辆管理：`REQ-VEH-01`
|
|
|
|
## 四、功能拆分规则
|
|
|
|
功能拆分应围绕用户可感知的业务能力展开，一个编号只描述一个清晰功能点。
|
|
|
|
优先拆分以下类型：
|
|
|
|
- 列表展示
|
|
- 条件查询
|
|
- 新增或手工录入
|
|
- 编辑或更新
|
|
- 启用
|
|
- 停用
|
|
- 删除或禁止删除
|
|
- 批量导入
|
|
- 模板下载
|
|
- 批量导出
|
|
- 状态流转
|
|
- 编码或唯一性规则
|
|
- 必填和格式校验
|
|
- 业务关联校验
|
|
- 权限控制
|
|
- 审计追踪
|
|
|
|
不得把多个互相独立的操作硬塞进同一个需求项。例如“新增、编辑、删除”应拆成多个 `REQ`，除非它们确实共享同一套规则且业务风险很低。
|
|
|
|
## 五、字段写作规范
|
|
|
|
### 1. 功能点
|
|
|
|
用于描述该功能“做什么”，要求简短、明确、面向业务。
|
|
|
|
写法要求：
|
|
|
|
- 使用一句话概括功能。
|
|
- 说明操作对象和业务目的。
|
|
- 可列出关键字段，但不要堆砌全部数据库字段。
|
|
- 不写技术实现细节，例如组件名、接口路径、方法名。
|
|
|
|
推荐写法：
|
|
|
|
- `功能点：支持手工新增港口主数据，录入港口编码、港口名称、所属城市、经纬度、备注等信息，默认数据来源为手工导入，默认状态为启用。`
|
|
|
|
不推荐写法：
|
|
|
|
- `功能点：调用 /submit 接口保存表单。`
|
|
- `功能点：点击按钮打开弹窗，然后 avue-crud 触发 rowSave。`
|
|
|
|
### 2. 异常与边界
|
|
|
|
用于描述系统遇到异常、极端输入、权限限制、业务冲突时应如何处理。
|
|
|
|
写法要求：
|
|
|
|
- 使用 `①②③` 分点描述。
|
|
- 每点应描述“条件 + 处理方式”。
|
|
- 优先覆盖必填、格式、范围、重复、引用、权限、接口失败、文件格式、状态冲突等场景。
|
|
- 不只写“提示错误”，要尽量说明何时提示、是否阻止提交、是否刷新列表、是否保持原状态。
|
|
|
|
推荐写法：
|
|
|
|
- `异常与边界：①编码为空时阻止提交并提示；②重复编码时由后端校验并返回明确原因；③接口提交失败时保留用户输入，方便修正后重新提交。`
|
|
|
|
不推荐写法：
|
|
|
|
- `异常与边界：报错。`
|
|
- `异常与边界：需要校验。`
|
|
|
|
### 3. 反例
|
|
|
|
用于描述明确不允许发生的行为、错误用法或违反规则的输入。
|
|
|
|
写法要求：
|
|
|
|
- 使用 `①②③` 分点描述。
|
|
- 反例应直接表达“不允许什么”。
|
|
- 可以写非法输入示例，如 `CNSH1`、`-1`、`181`。
|
|
- 反例不写系统应如何处理，处理方式放在“异常与边界”。
|
|
|
|
推荐写法：
|
|
|
|
- `反例：①录入无上级港口的码头；②将 CNSHG 作为码头编码；③上级港口为 CNSHG 时录入 CNNGB-CT1。`
|
|
|
|
不推荐写法：
|
|
|
|
- `反例：用户乱填。`
|
|
- `反例：后台报错。`
|
|
|
|
## 六、通用规则写作规范
|
|
|
|
文末必须保留 `## 通用规则`，用于汇总跨多个功能项重复出现的模块级规则。
|
|
|
|
通用规则适合放：
|
|
|
|
- 编码规则
|
|
- 必填规则
|
|
- 金额、经纬度、备注等统一校验
|
|
- 数据来源规则
|
|
- 启停和删除约束
|
|
- 权限和审计约束
|
|
- 新增、更新、导入后刷新规则
|
|
|
|
通用规则不应替代具体功能项。若某规则会影响具体操作，应同时在对应 `REQ` 的“异常与边界”或“反例”中体现。
|
|
|
|
## 七、内容约束
|
|
|
|
- 不使用表格。
|
|
- 不写测试步骤、预期结果、测试数据列。
|
|
- 不写接口路径、组件名、代码方法名，除非用户明确要求。
|
|
- 不写冗长背景介绍，首屏直接进入需求卡内容。
|
|
- 不凭空增加用户未提及且现有业务无法推断的复杂能力。
|
|
- 当需求明确“不支持删除”时，应单独拆出“禁止删除”需求项，并在通用规则中再次强调。
|
|
- 当涉及导入时，通常需要同时拆出“批量导入”和“模板下载”。
|
|
- 当涉及状态时，通常需要分别拆出“启用”和“停用”。
|
|
- 当涉及用户可见审计字段时，优先使用姓名字段，避免直接展示用户 ID。
|
|
|
|
## 八、生成流程
|
|
|
|
1. 先理解用户提供的模块说明和现有参考需求卡。
|
|
2. 梳理模块核心对象、关键字段、数据来源、允许操作、不允许操作。
|
|
3. 按业务能力拆分 `REQ` 编号。
|
|
4. 在标题下生成 `## 目录`，覆盖所有 `REQ` 项和 `## 通用规则`。
|
|
5. 为每个 `REQ` 编写三行：功能点、异常与边界、反例。
|
|
6. 汇总重复规则到 `## 通用规则`。
|
|
7. 检查是否误用表格、是否遗漏用户强调的禁止项、是否出现互相矛盾描述，并确认目录链接与正文一致。
|
|
|
|
## 九、质量检查清单
|
|
|
|
- 是否在标题下生成 `## 目录`。
|
|
- 目录是否覆盖所有 `REQ` 项和 `## 通用规则`。
|
|
- 目录顺序是否与正文顺序一致，链接是否可跳转。
|
|
- 每个 `REQ` 是否只有一个明确功能主题。
|
|
- 每个 `REQ` 是否都有功能点、异常与边界、反例。
|
|
- 异常与边界是否包含处理方式，而不只是问题名称。
|
|
- 反例是否使用“不允许”口径。
|
|
- 编号是否连续且无重复。
|
|
- 是否覆盖新增、更新、导入、导出、启停、权限、审计等常见管理功能。
|
|
- 是否把用户明确禁止的能力写成了可用能力。
|
|
- 是否保持非表格格式。
|