项目结构
本文面向需要接手、排查或扩展 art-design-pro-server 的后端研发人员。目标是帮助你在后端工程中快速定位文件，避免只停留在 modules、config、scripts 等目录名称层面。
先看整体结构
下面这棵目录树，重点保留了和日常开发、联调、部署最相关的部分。
text
├── src
│ ├── main.ts # 应用启动入口，注册全局前缀、Swagger、拦截器、过滤器
│ ├── app.module.ts # 根模块，装配所有业务模块和全局基础设施
│ ├── bootstrap
│ │ └── configure-cors.ts # CORS 配置逻辑
│ ├── common # 公共层
│ │ ├── constants
│ │ │ └── pagination.constants.ts # 分页常量
│ │ ├── decorators
│ │ │ ├── skip-transform.decorator.ts
│ │ │ └── success-message.decorator.ts
│ │ ├── dto
│ │ │ ├── pagination-query.dto.ts # 通用分页查询 DTO
│ │ │ ├── time-range-query.dto.ts # 时间范围查询 DTO
│ │ │ └── ...
│ │ ├── middleware
│ │ │ └── request-id.middleware.ts # 请求 ID 中间件
│ │ ├── types
│ │ │ ├── api-response.interface.ts
│ │ │ ├── authenticated-user.interface.ts
│ │ │ └── ...
│ │ └── utils
│ │ ├── pagination.utils.ts # 分页工具
│ │ ├── query-parse.utils.ts # 查询参数解析
│ │ └── request-user.utils.ts # 从请求中提取用户信息
│ ├── config # 配置层
│ │ ├── modules
│ │ │ ├── app.config.ts # 应用级配置
│ │ │ ├── env.config.ts # 环境变量加载与校验
│ │ │ ├── logs.config.ts # 日志配置
│ │ │ ├── monitor.config.ts # 监控相关配置
│ │ │ ├── system.config.ts # 系统配置
│ │ │ └── throttle.config.ts # 限流配置
│ │ └── index.ts # 配置导出入口
│ ├── enum
│ │ └── config.enum.ts # 配置枚举
│ ├── filters
│ │ ├── all-exception.filter.ts # 全局异常过滤器
│ │ └── http-exception.filter.ts # HTTP 异常过滤器
│ ├── guards
│ │ ├── admin.guard.ts # 管理员守卫
│ │ └── jwt.guard.ts # JWT 守卫
│ ├── interceptors
│ │ └── transform.interceptor.ts # 统一响应拦截器
│ ├── modules # 业务模块
│ │ ├── auth # 认证模块
│ │ │ ├── dto
│ │ │ │ ├── refresh-token.dto.ts
│ │ │ │ └── signin-user.dto.ts
│ │ │ ├── repositories
│ │ │ │ └── user-session.repository.ts
│ │ │ ├── auth.controller.ts # 登录、刷新、登出、会话管理
│ │ │ ├── auth.module.ts
│ │ │ ├── auth.service.ts
│ │ │ └── jwt.strategy.ts
│ │ ├── user # 用户模块
│ │ │ ├── dto
│ │ │ │ ├── create-user.dto.ts
│ │ │ │ ├── update-user.dto.ts
│ │ │ │ ├── profile.dto.ts
│ │ │ │ └── ...
│ │ │ ├── repositories
│ │ │ │ └── user.repository.ts
│ │ │ ├── user.controller.ts
│ │ │ ├── user.module.ts
│ │ │ └── user.service.ts
│ │ ├── roles # 角色模块
│ │ │ ├── dto
│ │ │ ├── repositories
│ │ │ ├── roles.controller.ts
│ │ │ ├── roles.module.ts
│ │ │ └── roles.service.ts
│ │ ├── departments # 部门模块
│ │ ├── posts # 岗位模块
│ │ ├── menus # 菜单权限模块
│ │ │ ├── data # 菜单预置数据
│ │ │ ├── dto
│ │ │ ├── menu.controller.ts
│ │ │ ├── menu.module.ts
│ │ │ ├── menu.service.ts
│ │ │ └── menu.types.ts
│ │ ├── dicts # 字典模块
│ │ ├── site-settings # 站点配置模块
│ │ ├── system-params # 系统参数模块
│ │ ├── api-permissions # API 权限模块
│ │ │ ├── decorators # API 权限装饰器
│ │ │ ├── api-permissions.constants.ts
│ │ │ ├── api-permissions.controller.ts
│ │ │ ├── api-permissions.module.ts
│ │ │ ├── api-permissions.seed.ts
│ │ │ └── api-permissions.service.ts
│ │ ├── data-permissions # 数据权限模块
│ │ │ ├── data-permissions.constants.ts
│ │ │ ├── data-permissions.module.ts
│ │ │ └── data-permissions.service.ts
│ │ ├── crypto # 接口签名与加密模块
│ │ │ ├── api-security.middleware.ts
│ │ │ ├── api-security.service.ts
│ │ │ ├── api-security.utils.ts
│ │ │ ├── crypto.controller.ts
│ │ │ ├── crypto.module.ts
│ │ │ └── crypto.service.ts
│ │ ├── logs # 日志模块
│ │ │ ├── decorators # 操作日志装饰器
│ │ │ ├── dto
│ │ │ ├── interceptors
│ │ │ ├── logs.controller.ts
│ │ │ ├── logs.module.ts
│ │ │ ├── logs.service.ts
│ │ │ └── logs.utils.ts
│ │ ├── monitor # 监控模块
│ │ │ ├── dto
│ │ │ ├── services
│ │ │ ├── monitor.controller.ts
│ │ │ ├── monitor.module.ts
│ │ │ └── monitor.service.ts
│ │ ├── health # 健康检查模块
│ │ │ ├── indicators
│ │ │ ├── health.controller.ts
│ │ │ └── health.module.ts
│ │ ├── notifications # 通知模块
│ │ │ ├── dto
│ │ │ ├── notifications.controller.ts
│ │ │ ├── notifications.module.ts
│ │ │ ├── notifications.service.ts
│ │ │ └── notifications.realtime.service.ts
│ │ ├── feedback # 反馈模块
│ │ ├── files # 文件中心模块
│ │ │ ├── dto
│ │ │ │ ├── create-upload-ticket.dto.ts
│ │ │ │ ├── complete-upload.dto.ts
│ │ │ │ ├── query-files.dto.ts
│ │ │ │ └── ...
│ │ │ ├── file-folders.controller.ts
│ │ │ ├── files.controller.ts
│ │ │ ├── files.module.ts
│ │ │ ├── files.service.ts
│ │ │ └── files.storage.ts
│ │ ├── content # 内容管理模块
│ │ │ ├── dto
│ │ │ ├── content.controller.ts
│ │ │ ├── content-category.controller.ts
│ │ │ ├── content-tag.controller.ts
│ │ │ ├── content.module.ts
│ │ │ ├── content.service.ts
│ │ │ ├── content-category.service.ts
│ │ │ └── content-tag.service.ts
│ │ ├── mall # 商城模块
│ │ │ ├── dto
│ │ │ ├── orders.controller.ts
│ │ │ ├── orders.service.ts
│ │ │ ├── product-categories.controller.ts
│ │ │ ├── product-categories.service.ts
│ │ │ ├── products.controller.ts
│ │ │ ├── products.service.ts
│ │ │ └── mall.module.ts
│ │ ├── workflow # 工作流模块
│ │ │ ├── dto
│ │ │ ├── interfaces
│ │ │ ├── services
│ │ │ │ ├── workflow-approval.engine.ts
│ │ │ │ ├── workflow-definition.service.ts
│ │ │ │ ├── workflow-instance.service.ts
│ │ │ │ ├── workflow-task.service.ts
│ │ │ │ └── workflow-validation.service.ts
│ │ │ ├── workflow-categories.controller.ts
│ │ │ ├── workflow-definitions.controller.ts
│ │ │ ├── workflow-instances.controller.ts
│ │ │ ├── workflow-tasks.controller.ts
│ │ │ ├── workflow.constants.ts
│ │ │ ├── workflow-category.service.ts
│ │ │ └── workflow.module.ts
│ │ ├── scheduled-tasks # 定时任务模块
│ │ │ ├── dto
│ │ │ ├── scheduled-tasks.controller.ts
│ │ │ ├── scheduled-tasks.cron.ts
│ │ │ ├── scheduled-tasks.handlers.ts
│ │ │ ├── scheduled-tasks.module.ts
│ │ │ ├── scheduled-tasks.runner.service.ts
│ │ │ └── scheduled-tasks.service.ts
│ │ ├── security-audit # 安全审计模块
│ │ └── ai-assistant # AI 助手模块
│ ├── prisma
│ │ ├── prisma.module.ts # Prisma 模块
│ │ └── prisma.service.ts # Prisma 服务封装
│ └── scripts # 初始化和同步脚本
│ ├── load-env.ts # 脚本环境变量加载
│ ├── seed-default-data.ts # 默认数据初始化
│ ├── seed-dev-data.ts # 开发数据初始化
│ ├── seed-mall-demo-data.ts # 商城演示数据初始化
│ ├── seed-workflow-data.ts # 工作流数据初始化
│ ├── create-admin.ts # 创建管理员
│ ├── init-scheduled-tasks.ts # 初始化默认定时任务
│ ├── sync-role-permissions.ts # 同步角色权限
│ ├── role-permission-presets.ts # 角色权限预设
│ └── default-scheduled-tasks.ts # 默认任务定义
├── prisma
│ ├── schema.prisma # Prisma 数据模型
│ └── migrations # 数据库迁移
├── test
│ └── jest-e2e.json # e2e 测试配置
├── package.json # 脚本、依赖、测试配置
└── docker-compose.yml # Docker Compose 部署模板目录分层
第一层：启动与装配层
主要是：
main.tsapp.module.tsbootstrap
这层负责把应用真正启动起来，并把所有全局基础设施接好。
第二层：公共基础设施层
主要是：
commonconfigfiltersguardsinterceptorsprisma
这层决定：
- 环境变量加载方式
- 全局错误返回方式
- JWT 校验方式
- 数据库访问方式
第三层：业务模块层
主要是 modules。
这是后端最重要的一层，也是你最常改的一层。项目里大多数功能都遵循同一种结构：
text
controller 接口入口
dto 参数定义与校验
service 业务逻辑
module 模块装配复杂模块再继续拆：
repositoriesservicesinterfacesdecorators
第四层：数据与初始化层
主要是：
- 根目录
prisma src/scripts
这层直接影响：
- 数据库结构
- 默认数据
- 管理员账号
- 角色权限同步
- 定时任务初始化
建议阅读顺序
想理解一个接口
建议按这个顺序看：
*.controller.ts- 对应
dto *.service.tsrepository或 Prisma 调用
想理解一个模块
建议按这个顺序看：
*.module.ts- controller
- service
- dto / repository / 子 services
想理解整条登录链路
建议按这个顺序看：
main.tsapp.module.tsmodules/auth/*guards/jwt.guard.tsmodules/crypto/*- 用户与会话相关 repository / service
常见需求对应的入口
| 需求 | 优先查看 |
|---|---|
| 某个接口在哪里定义 | modules/*/*.controller.ts |
| 参数校验失败 | dto/ |
| 某个业务规则在哪里 | *.service.ts 或 services/ |
| 启动配置未生效 | config + .env* |
| 数据库结构不一致 | 根目录 prisma |
| 默认角色、管理员、任务数据异常 | src/scripts |
扩展开发建议
适合新增文件的地方
- 新模块：
src/modules/<module> - 新脚本：
src/scripts - 新公共 DTO / 工具：
src/common - 新配置：
src/config/modules
不建议随意堆逻辑的地方
main.tsapp.module.ts- 公共 guard / filter / interceptor
这些位置一旦混入过多业务逻辑，后续维护成本会迅速上升。
检查清单
接手后端项目后，建议确认：
- 能根据接口定位到 controller、DTO、service 和数据访问实现。
- 能区分启动装配层、公共基础设施层、业务模块层、数据与初始化层。
- 新增模块不会把项目专属逻辑写入
main.ts、app.module.ts或公共 guard/filter/interceptor。