7.3 KiB
7.3 KiB
模块需求卡生成规范
本规范用于后续生成各业务模块需求卡，统一采用 港口码头主数据需求卡.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。
八、生成流程
- 先理解用户提供的模块说明和现有参考需求卡。
- 梳理模块核心对象、关键字段、数据来源、允许操作、不允许操作。
- 按业务能力拆分
REQ编号。 - 在标题下生成
## 目录，覆盖所有REQ项和## 通用规则。 - 为每个
REQ编写三行：功能点、异常与边界、反例。 - 汇总重复规则到
## 通用规则。 - 检查是否误用表格、是否遗漏用户强调的禁止项、是否出现互相矛盾描述，并确认目录链接与正文一致。
九、质量检查清单
- 是否在标题下生成
## 目录。 - 目录是否覆盖所有
REQ项和## 通用规则。 - 目录顺序是否与正文顺序一致，链接是否可跳转。
- 每个
REQ是否只有一个明确功能主题。 - 每个
REQ是否都有功能点、异常与边界、反例。 - 异常与边界是否包含处理方式，而不只是问题名称。
- 反例是否使用“不允许”口径。
- 编号是否连续且无重复。
- 是否覆盖新增、更新、导入、导出、启停、权限、审计等常见管理功能。
- 是否把用户明确禁止的能力写成了可用能力。
- 是否保持非表格格式。