目录结构

后端结构

分层说明

目录	职责
sz-build	构建父 POM，继承 Spring Boot 父工程，集中管理第三方依赖版本、构建插件版本和部分构建策略
sz-common	通用能力模块，与业务无关，可被任意服务按需引入（数据库、缓存、日志、OSS、Excel 等）
sz-module	业务逻辑模块，承载具体的 Service / Mapper / Controller 实现，不直接启动
sz-service	可独立部署的 SpringBoot 服务，引用 sz-module 和 sz-common 完成最终装配

当前后端不再保留独立的 sz-dependencies 目录。第三方依赖版本已收敛到 sz-build/pom.xml，内部模块版本则由根 pom.xml 的 dependencyManagement 统一管理。

sz-boot-parent/
├── sz-build                                # 构建父 POM 与格式化规则	// [!code highlight]
│   ├── pom.xml                                 # 继承 Spring Boot，管理第三方依赖与构建插件版本
│   └── baeldung-style.xml                      # Spotless/Eclipse Java 格式化规则
├── config                                  # 外置配置模板（dev/local/preview/prod 等）
├── data                                    # 本地资源数据目录（LOCAL 资源存储，可选但建议预留）
├── logs                                    # 运行日志目录（本地启动或部署后生成）
├── sz-common                               # 通用模块集合（与业务无关，按需引入）	// [!code highlight]
│   ├── sz-common-core                          # 核心通用模块（异常、工具、实体、枚举）
│   ├── sz-common-db-core                       # 数据库核心（雪花ID、数据权限抽象、TypeHandler）
│   ├── sz-common-db-mysql                      # MySQL 方言实现（与 db-postgresql 二选一）
│   ├── sz-common-db-postgresql                 # PostgreSQL 方言实现（与 db-mysql 二选一）
│   ├── sz-common-db-mongodb                    # MongoDB 操作模块
│   ├── sz-common-db-redis                      # Redis 缓存模块
│   ├── sz-common-resource                      # 资源处理模块（OSS URL 填充等）
│   ├── sz-common-excel                         # Excel 导入导出模块
│   ├── sz-common-log                           # 操作日志模块
│   ├── sz-common-oss                           # OSS 对象存储模块（支持 S3 协议）
│   ├── sz-common-mq                            # 消息队列模块
│   ├── sz-common-security                      # 鉴权模块（Sa-Token 封装）
│   └── sz-common-wechat                        # 微信生态模块（小程序等，可选引入）//
├── sz-module                               # 业务逻辑模块（不可独立部署）	// [!code highlight]
│   ├── sz-module-common                        # 跨服务共享的业务常量、字典常量、公共 VO
│   ├── sz-module-admin                         # sz-admin 后台管理业务实现（RBAC、系统管理等）
│   ├── sz-module-audit                         # 审计日志业务模块
│   └── sz-module-generator                     # 代码生成器业务模块
└── sz-service                              # 可独立部署的 SpringBoot 服务	// [!code highlight]
    ├── sz-service-admin                        # sz-admin 核心服务（引用 sz-module-admin）// [!code highlight]
    └── sz-service-websocket                    # WebSocket 独立服务（支持多节点部署）// [!code highlight]

sz-build 与依赖版本管理

当前 sz-build 是后端工程的构建父 POM，不再只是单纯的 BOM 目录。根 pom.xml 通过下面的方式继承它：

<parent>
    <groupId>com.sz</groupId>
    <artifactId>sz-build</artifactId>
    <version>${revision}</version>
    <relativePath>./sz-build/pom.xml</relativePath>
</parent>

sz-build/pom.xml 负责继承 spring-boot-starter-parent，并统一管理 Spring Boot、Sa-Token、MyBatis-Flex、Jackson、AWS S3 SDK、构建插件等第三方版本。根 pom.xml 则负责声明当前聚合模块，并通过 dependencyManagement 收敛 sz-common、sz-module、sz-service 内部模块版本。

旧版本中的 sz-dependencies 目录已经不再作为当前主线结构存在。阅读旧文档、旧脚本或历史提交时，如果看到 sz-dependencies，可以理解为旧体系中的依赖版本管理入口；在 v2.0.0 当前结构中，应以 sz-build/pom.xml 和根 pom.xml 为准。

扩展性说明

框架采用"按需引入"的扩展模式，新增业务能力无需修改任何现有模块，推荐方式如下：

1. 在 sz-common 下封装与业务无关的通用能力模块（或直接在业务模块中引入第三方依赖）
2. 在 sz-module 下新建独立的业务模块，将业务 Service / Mapper / Controller 实现放入其中，与框架自带的 sz-module-admin 并列，互不干扰；官方 sz-module-audit、sz-module-generator 就是这类结构的参考
3. 在 sz-service-admin（或新建服务）的 pom.xml 中引入对应业务模块即可生效

为什么建议在 sz-module 下新建模块，而不是直接写在 sz-module-admin 里？

sz-module-admin 是框架官方维护的 RBAC 核心模块，跟随官方版本迭代更新。将自己的业务代码独立为新模块，可以做到：

• 与官方代码完全隔离，升级框架时无冲突
• 业务模块可以独立测试、独立版本管理
• 多个业务团队可以并行开发不同模块，互不影响

示例：审计模块的后端结构

以 v2.0.0 已内置的 sz-module-audit 为例，它没有写入 sz-module-admin，而是作为独立业务模块由启动服务装配：

sz-boot-parent/
├── sz-module
│   ├── sz-module-common        # 框架公共常量（不动）
│   ├── sz-module-admin         # 框架 RBAC 核心（不动，跟随官方升级）
│   ├── sz-module-audit         # 审计日志业务模块
│   │   ├── pom.xml
│   │   └── src/main
│   │       ├── java/com/sz/audit
│   │       │   ├── config
│   │       │   └── controller
│   │       └── resources
│   │           ├── mapper
│   │           └── db/changelog
│   └── sz-module-generator     # 代码生成器业务模块
└── sz-service
    └── sz-service-admin
        └── pom.xml             # 引入 sz-module-audit 依赖

sz-service-admin/pom.xml 中引入审计模块：

<!-- 引入审计日志业务模块 -->
<dependency>
    <groupId>com.sz</groupId>
    <artifactId>sz-module-audit</artifactId>
    <version>${revision}</version>
</dependency>

审计模块还会通过 ApiPrefixRegister 注册 /audit 前缀，并维护自己的 module-audit-changelog.xml。完整拆解见 独立业务模块接入指南。

现有框架内置扩展示例：

扩展功能	引入方式	代码位置
微信小程序登录	sz-service-admin 引入 sz-common-wechat	com.sz.applet.*（位于 sz-module-admin）
PostgreSQL 支持	替换 sz-common-db-mysql 为 sz-common-db-postgresql	见 数据库兼容性文档
WebSocket 服务	独立部署 sz-service-websocket	sz-service/sz-service-websocket
审计日志	引入 sz-module-audit	Springdoc OpenAPI 中审计相关分组
代码生成器	引入 sz-module-generator	Springdoc OpenAPI 中 generator工具 分组

前端结构

提示

在业务开发中，普通页面仍可重点关注 /src/api 和 /src/views；较大或可组合业务建议放入 /src/modules，并通过 /src/core 与 /src/editions 注册。创建后端 module、API 前缀、前端模块和菜单映射的完整步骤见 独立业务模块接入指南。

这样设计的目的，是把“业务页面”“框架底座能力”和“产品组合入口”拆开：小功能继续按传统方式快速开发，大功能可以作为独立模块注册和复用，派生项目也可以只替换登录适配器或启用指定模块，而不必改动框架主流程。

Directory	描述
/src/api/types	描述接口对象的 TypeScript 类型，用于约束数据形状，类似 Java 实体对象的强类型定义。
/src/api/modules	按业务域组织 API 调用，v2.0.0 中配合 adminHttp、generatorHttp 等客户端使用。
/src/views	传统页面目录，适合普通 CRUD、存量页面和动态路由解析的兜底路径。
/src/modules	可组合业务模块目录，推荐承载代码生成器、SSO、商城等较大业务域或派生项目模块。
/src/core	登录适配器、模块注册、菜单组件解析等底座能力，不直接承载具体业务页面。
/src/editions	产品 edition 组合入口，决定当前产品启用哪些模块、使用哪套登录适配器。

前端模块化设计说明

v2.0.0 前端的目录设计并不是要求所有页面都迁移到 src/modules，而是提供两种开发路径：

1. 轻量页面路径：普通系统管理页面、简单 CRUD、一次性业务页面，继续放在 src/views，API 放在 src/api/modules。这种方式开发成本低，也能兼容原有动态路由解析方式。
2. 模块化业务路径：当业务具备独立领域、可选启用、派生项目复用、团队并行开发等特征时，建议放入 src/modules/<domain>，再通过 src/core 提供的模块注册能力接入系统。

如果需要完整落地一个新业务域，先阅读 独立业务模块接入指南，再回到本页核对目录职责即可。

这种拆分可以带来几个直接效果：

• 降低升级冲突：官方维护的基础能力、业务模块、派生产品组合入口边界更清晰，后续同步框架代码时更容易定位差异。
• 支持产品组合：src/editions 可以决定启用哪些模块和登录适配器，同一套框架可以组合成默认后台、SSO 版本或其他派生版本。
• 保持菜单兼容：后端菜单中的 component 字段不需要因为页面迁移而频繁调整，前端会按“模块显式注册 -> src/modules 约定路径 -> src/views 兜底”的顺序解析页面组件。
• 方便渐进迁移：存量页面可以继续留在 src/views，新模块或复杂业务再逐步迁移到 src/modules，不需要一次性重构整个前端工程。

示例：toolbox 代码生成器模块

以代码生成器为例，v2.0.0 将生成器页面迁移到 src/modules/toolbox/views/generator/index.vue，并在 src/modules/toolbox/register.ts 中显式注册：

import { defineModule } from '@/core';

export const toolboxModule = defineModule({
  name: 'toolbox',
  components: {
    '/toolbox/generator/index': () => import('./views/generator/index.vue')
  }
});

默认后台 edition 在 src/editions/admin.ts 中启用该模块：

import { moduleRegistry } from '@/core';
import { toolboxModule } from '@/modules/toolbox/register';

export const ADMIN_EDITION = {
  id: 'admin',
  name: 'sz-admin',
  setup(): void {
    moduleRegistry.register(toolboxModule);
  }
};

这样后端菜单仍然可以继续使用 /toolbox/generator/index 作为 component 值。前端解析菜单组件时会优先命中 toolboxModule.components 中的显式映射；如果未注册，也会尝试查找 /src/modules/toolbox/views/generator/index.vue；最后再回退到 /src/views/toolbox/generator/index.vue。因此，迁移后的模块既能保持旧菜单兼容，又能作为独立业务模块被不同 edition 选择性启用。

sz-admin/
├── public                                      # 静态资源文件（该文件夹不会被打包）
│   └── favicon.ico
├── src
│   ├── api										# API 接口管理
│   ├── assets									# 静态资源文件				
│   ├── components								# 全局组件
│   ├── config									# 全局配置项	
│   ├── core									# 登录适配器、模块注册、菜单组件解析
│   ├── directives								# 全局指令文件
│   ├── editions								# 产品 edition 组合入口
│   ├── hooks									# 常用 Hooks 封装
│   ├── languages								# 语言国际化 i18n
│   ├── layouts									# 框架布局模块	
│   ├── modules									# 可组合业务模块（如 toolbox/generator）
│   ├── router									# 路由管理
│   ├── stores									# pinia store
│   ├── styles									# 全局样式文件
│   ├── typings									# 全局 ts 声明
│   ├── utils									# 常用util工具库
│   ├── views									# 项目所有页面
│   ├── App.vue									# 项目主组件
│   └── main.ts									# 项目入口文件
├── env.d.ts									# 指定 ts 识别 vue
├── index.html									# 入口 html
├── package.json								# 依赖包管理			// [!code highlight]
├── pnpm-lock.yaml								# pnpm依赖包版本锁
├── pnpm-workspace.yaml							# pnpm 工作区与补丁依赖声明
├── tsconfig.app.json							# 应用程序代码的特定配置，用于浏览器环境。
├── tsconfig.json								# typescript 全局配置
├── tsconfig.node.json							# Node.js 环境的特定配置，用于服务器端代码或构建脚本。
├── vite.config.mts							    # vite 全局配置文件		// [!code highlight]
└── README.md