# 模块需求卡生成规范

本规范用于后续生成各业务模块需求卡，统一采用 `港口码头主数据需求卡.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` 是否都有功能点、异常与边界、反例。
- 异常与边界是否包含处理方式，而不只是问题名称。
- 反例是否使用“不允许”口径。
- 编号是否连续且无重复。
- 是否覆盖新增、更新、导入、导出、启停、权限、审计等常见管理功能。
- 是否把用户明确禁止的能力写成了可用能力。
- 是否保持非表格格式。