新模块扩展方式

本文面向准备继续做项目定制开发的后端研发人员。目标不仅是说明如何新建文件，也包括帮助新模块沿用当前仓库已经形成的结构、权限和初始化方式。

扩展一个模块前，先回答两个问题

这是平台通用能力，还是项目专属业务

平台通用能力：适合做成独立可复用模块
项目专属业务：也建议单独模块化，不要直接塞进已有通用模块

这个模块是否需要权限、菜单、数据隔离

在商业版里，新增模块通常不只是建表和写接口，还要同步考虑：

菜单
API 权限
按钮动作
数据权限

推荐的最小模块结构

text

src/modules/<module>
├── <module>.module.ts
├── <module>.controller.ts
├── <module>.service.ts
└── dto/

如果业务开始变复杂，再继续拆：

repositories/
services/
interfaces/
decorators/

推荐的扩展顺序

第一步：先补数据模型

先在 Prisma schema 中补实体关系和字段定义，再设计接口形态和 DTO。

第二步：生成并应用迁移

确保数据库结构和代码是一起演进的。

第三步：搭建模块骨架

先把：

module
controller
service
dto

搭出来，再逐步填业务细节。

第四步：注册到 `AppModule`

否则服务启动后接口根本不会暴露。

第五步：补权限和菜单

这是最容易被遗漏的一步，但对商业版项目非常重要。

什么时候应该拆 repository

建议在下面场景拆：

查询逻辑明显变复杂
同一数据访问逻辑被多个 service 复用
需要把查询组织和业务流程分开

什么时候应该拆多个 service

当一个模块已经出现多条清晰业务主线时，比如：

定义
实例
任务
校验

这时继续把所有逻辑压在一个 service 中，会提高后续维护成本。当前工作流模块可以作为参考。

扩展模块时的推荐自检

开发完成后，建议至少确认：

AppModule 已注册
Swagger 已能看到接口
DTO 校验正常
菜单和权限已补齐
前端已能接入该模块

模块扩展建议

通用底座不要频繁破坏式重写
项目专属业务尽量独立模块化
统一保留响应格式、鉴权方式、异常处理风格
让新模块沿用当前项目已有规范扩展，避免另起一套接口、权限或响应风格

检查清单

新增模块完成后，建议确认：

数据模型、迁移、DTO、controller、service 和 module 注册均已完成。
Swagger 可看到新接口，前端可按既有 /api/v1 规则接入。
菜单权限、API 权限、按钮权限和必要的数据权限已同步。
初始化脚本或使用说明已说明新模块所需的默认数据。