业务需求文档模板

文档定位

本文档提供一份面向业务模块的需求说明模板，用于：

在写模块需求时提前补齐开发和代码生成所需的关键信息
把实体层约定、数据状态能力、删除顺序、前后端对齐约束写清楚
降低开发者、代码生成器或自动化工具因为需求输入不完整而自行猜测的概率

它不是强制的一字不差模板，但以下关键段落建议保留。

建议结构

1. 模块目标

模块名称
业务对象名称
目标用户
核心场景

2. 输入资料

SQL 文件路径
设计总览路径
关联基础需求路径
目标模块目录

3. 业务对象与字段

按实体分别列出：

主表 / 从表
关键字段
AO 创建 / 编辑入参字段及必填性
唯一约束
排序字段
逻辑删除字段
敏感字段

AO 必填性需要明确到字段级，供开发者、代码生成器或自动化工具同步生成 OpenAPI 与 Jakarta Validation 注解：

AO 类	字段	类型	是否必填	校验注解	说明
`XxxAO`	`xxxName`	`String`	是	`@NotBlank`	名称不能为空白
`XxxAO`	`sortWeight`	`Integer`	是	`@NotNull`	排序值必须提交
`XxxBatchAO`	`targetIdSet`	`Set<String>`	是	`@NotEmpty`	批量目标集合不能为空

如果字段在 @Schema(requiredMode = RequiredMode.REQUIRED) 中标记必填，必须同步写出对应的 jakarta.validation.constraints 注解；不要只维护 OpenAPI 必填标记。

4. 数据状态能力开关

这一段必须写清楚，供生成代码时直接判断。

固定规则：

AbstractTenantBaseEntity、AbstractTenantBaseTreeEntity、AbstractTenantBaseAccountEntity、AbstractTenantBaseOwnerEntity 基类只默认提供 DataStatusFeature.FIXED
除 FIXED 外，当前可用开关为 ENABLED、DEFAULT、PRIMARY、LOCKED、PUBLISHED，必须由最终实体类显式打开
需求文档未声明的开关，生成代码时不要默认开启
如果最终实体不需要额外开关，可以不声明 @EnableDataStatus，此时只保留基类的 FIXED

推荐按下面的表填写：

实体类	是否继承 `AbstractTenantBase*Entity`	需要开启的开关	说明
`Xxx`	是	`ENABLED, DEFAULT`	支持启停，新增默认启用
`XxxCategory`	是	`ENABLED, PUBLISHED, DEFAULT`	支持启停、发布、默认项
`XxxLog`	否	无	日志实体不走数据状态能力

可选开关值：

ENABLED
DEFAULT
PRIMARY
LOCKED
PUBLISHED

5. 标准能力范围

按实体或模块说明是否需要：

CRUD
分页查询
详情查询
回收站查询
状态切换
排序
账号状态
自定义动作

6. 共享扩展与转换层

这一段建议显式写清楚，避免生成代码时把共享认证能力和对象转换层生成错位。

至少说明：

模块是否接入统一认证链
如果接入统一认证链，是否复用 IAccountAuthenticationService、IReactiveAccountAuthenticationService、ISecurityAuthoritiesService、IReactiveSecurityAuthoritiesService
主体模块自己的 Manager 只需要保留哪些能力，例如 loadByUsername(...)、accountToSecurityUser(...)、主体特有查询、模块私有异常映射
哪些数据栈需要生成对象转换实现，例如 jpa / jdbc / mybatis-flex / r2dbc
转换实现是否统一放在实现模块的 converter/ 包
是否同时存在 MyBatis-Flex 持久化 mapper/ 与对象转换 converter/
是否需要接入 CreateManager / UpdateManager / FindByIdManager / OrderManager 一类抽象，以及对应的 getCreateEntityConverter()、getUpdateEntityConverter()、getEntityVoConverter()

7. 删除顺序与清理规则

必须明确：

主表与依赖表
删除顺序
哪些关系清理落在 afterLogicDelete
哪些恢复补偿落在 afterRecovery

8. 分层落点

至少说明：

哪些规则落在 Controller
哪些规则落在 Service
哪些规则落在 Manager
哪些规则落在 Repository / EntityManager
生成代码的类级 Javadoc 需要说明哪些职责边界和业务规则，尤其是唯一性、状态流转、删除保护、级联清理、外部同步、审计或权限边界
代码格式、Javadoc、@author、字段注释、@Schema 与字段声明统一遵守 code-style-guide.md

9. 前后端对齐

至少说明：

控制器根路径
resourceKey
页面入口
页面路由
按钮权限点
权限清单节点类型：catalog / menu / page / api / button
如果存在一级大目录，权限清单节点类型必须包含 catalog，并说明该模块挂在哪个大目录下
menu / page 需要写清前端访问路径和真实组件路径，供后续动态路由使用；api 写后端接口路径；button 不写 permissionUrl / component / icon
权限排序：按 orderWeight DESC 设计，建议顺序为辅助查询 API、列表查询、CRUD、状态操作、回收站操作
权限说明口径：写给授权人员看，使用业务语言，不使用 idSet、query、commonParameters 等后端参数名
前端需要的列表字段、查询字段、详情字段
创建字段、编辑字段
默认排序
是否需要回收站
是否需要状态切换
是否需要账号能力
是否需要导入与导出
如果需要导入与导出，AO / VO 对应哪些字段参与，Excel 列头中文名是什么
是否要求 webmvc 与 webflux 两条线都暴露同等能力

10. 租户、权限、事务与集成边界

按实体写明租户模式、读写范围和操作身份；区分 API 权限与数据范围。按业务动作写明事务边界、失败回滚、重复请求及并发竞争语义。

需要缓存或事件时，明确 key 的上下文维度、失效范围、提交时序和失败处理；不需要时写“不适用”。这些字段描述本模块的业务选择，通用规范见规则索引。

11. 验收与测试

至少说明：

Happy path
Negative path
排序与状态切换验证点
删除与恢复验证点

可复制片段

## 共享扩展与转换层

- 是否接入统一认证链：是
- 共享认证契约：复用 `IAccountAuthenticationService`、`IReactiveAccountAuthenticationService`
- 权限快照契约：复用 `ISecurityAuthoritiesService`、`IReactiveSecurityAuthoritiesService`
- 主体模块 Manager 保留能力：`loadByUsername(...)`、`accountToSecurityUser(...)`、主体特有查询
- 需要生成对象转换实现的数据栈：`jdbc`、`mybatis-flex`
- 转换实现落点：统一放在 `converter/` 包，类名使用 `XxxConverter`
- MyBatis-Flex 是否同时存在持久化 `mapper/`：是；`mapper/` 仅承载持久化接口，对象转换单独放 `converter/`
- 是否需要接入统一转换方法：是，需要实现 `getCreateEntityConverter()`、`getUpdateEntityConverter()`、`getEntityVoConverter()`

## 数据状态能力开关

固定规则：

- `AbstractTenantBase*Entity` 基类只默认提供 `DataStatusFeature.FIXED`
- 其他开关必须由最终实体类显式打开
- 需求文档未声明的开关，生成代码时不要默认开启

| 实体类 | 是否继承 `AbstractTenantBase*Entity` | 需要开启的开关 | 说明 |
| --- | --- | --- | --- |
| `AccessCredential` | 是 | `ENABLED, DEFAULT` | 支持启停，新增默认启用 |
| `AccessCredentialGroup` | 是 | `ENABLED` | 只支持启停 |

最后更新：2026-05-15