# springboot-quick-start

**Repository Path**: ugoodu/springboot-quick-start

## Basic Information

- **Project Name**: springboot-quick-start
- **Description**: springboot轻量项目脚手架：环境openjdk17、springboot3.2.9
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpringBoot Quick Start

> 当前版本：**v1.12.0**（见 `pom.xml` 与 Git Tag）

基于 Spring Boot 3.2 + Redis SSO + 国密传输 + MyBatis-Plus 的企业级脚手架。

[`doc/SCAFFOLD-GUIDE.md`](doc/SCAFFOLD-GUIDE.md) 是上手第一站，覆盖 toB/toC 入口、样板替换、FAB 清单。

## 多端入口

**推荐先开 Hub**：[`doc/portal-hub`](doc/portal-hub) → http://localhost:5170（`node doc/portal-hub/serve.mjs`）
端口清单：[`doc/dev-portals.json`](doc/dev-portals.json)

| 端 | 目录 | 地址 | 技术栈 |
|----|------|------|--------|
| PC 管理台（toB） | [`doc/admin-web`](doc/admin-web) | http://localhost:5176 | React + Ant Design |
| H5 业务工作台（toB） | [`doc/uni-app-client`](doc/uni-app-client) | http://localhost:5173 | uni-app (Vue3) + Vite + Pinia |
| 用户端（toC） | [`doc/uni-app-customer`](doc/uni-app-customer) | http://localhost:5175 | uni-app (Vue3) + Vite + Pinia |
| API / Knife4j | 后端 | http://localhost:8080/doc.html | Spring Boot 3.2 |

开发模式下各端内置跨端互跳入口（PC 顶栏、H5 FAB/设置、toC 我的/登录页）。

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | Spring Boot 3.2.9 / Java 17 |
| 鉴权 | Redis SSO 会话 (`X-Sso-Token`) + BCrypt |
| 传输安全 | 国密 SM2/SM4 加密 + SM3 验签（可配置开关） |
| 存储安全 | AES 字段加密 + 日志脱敏 |
| ORM | MyBatis-Plus 3.5 + Flyway（47 个 migration） |
| 缓存 | Redis（SSO 会话、验证码、黑名单） |
| 文档 | Knife4j OpenAPI 3 |
| 任务调度 | XXL-Job（可选） |
| 前端（toB 管理台） | React 18 + Ant Design 5 + Vite |
| 前端（toB/C H5） | uni-app (Vue3) + Vite + Pinia + TypeScript |

## 核心能力

### 认证与授权

- **toB 账号密码登录**：验证码 + BCrypt + 失败锁定 + Token 黑名单 + 多端 SSO
- **toC 多方式登录**：账号密码 / 短信验证码 / 邮箱验证码 / 微信 OAuth，方式由后台 `sys_config` 动态控制
- **toC 注册**：邮箱验证码注册、手机号注册、微信自动注册，注册方式可后台按需启停
- **RBAC 权限模型**：用户 → 角色 → 菜单/按钮/接口资源，数据权限按组织部门范围收敛（ALL / DEPT / DEPT_CHILD / SELF）
- **多租户隔离**：自动创建租户 + 行级数据隔离

### 动态配置（sys_config）

系统配置表（`sys_config`）支持管理端实时修改，无需重启：

| 配置组 | 示例配置项 | 说明 |
|--------|-----------|------|
| 站点信息 | `site.info.app.name` | 应用名称、Logo、标语 |
| 认证方式 | `auth.methods` | JSON 列表控制 toC 端可用登录方式 |
| 注册开关 | `auth.email.register.enabled` / `auth.sms.register.enabled` | 按方式启用/禁用注册 |
| 微信 OAuth | `wechat.app-id` / `wechat.secret` / `wechat.oauth.enable` | 微信凭证 + 全局开关 |
| 邮件服务 | `mail.host` / `mail.port` / `mail.username` / `mail.enable` | 覆盖 YAML 的 SMTP 配置 |
| 短信服务 | `sms.enable` / `sms.provider` / `sms.access-key` | 覆盖 YAML 的短信配置 |
| 文件存储 | `file.storage.type`（local/oss）| 运行时切换后端，无需重启 |
| OSS 凭证 | `oss.endpoint` / `oss.access-key-id` / `oss.bucket-name` | 覆盖 YAML 的 OSS 配置 |

优先级：**sys_config 表 > YAML 配置 > 默认值**。

### Wire 加密与安全

- **国密双层加密**：SM2 加密 SM4 密钥，SM4 加密报文，SM3 验签 + 时间戳防重放
- **数据库加密**：敏感字段（手机号、邮箱）AES 入库加密
- **可插拔模块**：Redis / OSS / 定时任务 / i18n / 加密 均可 yml 开关
- **限流与防护**：IP 限流 / 接口幂等 / IP 黑名单 / 验证码频率限制

### 通知中心

- 邮件通知（SMTP，支持 sys_config 动态配置或模拟模式）
- 短信通知（占位，支持 sys_config 配置后接入运营商 SDK）
- 企业微信通知（占位）
- 通知日志 `sys_notify_log` 全量记录

### 文件存储

- **存储策略可切换**：`file.storage.type`（sys_config）控制 OSS / 本地，无需重启
- **本地存储**：上传至本地磁盘，通过 `/static/upload/` 直链访问
- **阿里云 OSS**：需 `module.oss.enable=true` + 配置凭证（支持 sys_config 覆盖 YAML）
- FileUtil 门面模式自动选择后端：OSS 不可用时自动降级为本地

### AI 模块

- 多 Provider 管理（OpenAI 兼容）
- AI 应用 / 知识库管理
- 对话接口

### 业务脚手架

一键生成表 + RBAC + controller.biz / service.biz + pages/biz：

```bash
node scripts/scaffold-module.cjs DemoItem 演示条目
```

仓库含样板模块 **业务单据**（`BizOrder`）和 **员工档案**（`BizStaffProfile`）。

## 快速开始

```bash
# 1. 启动 MySQL(3307) + Redis(6379)
# 2. 修改 application-dev.yml 数据库密码
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

- API 文档：http://localhost:8080/doc.html
- 默认账号：`admin` / `ugoodu`（Flyway V4 初始化）
- 演示账号：`demo` / `ugoodu`（只读偏管理）
- 业务账号：`operator` / `ugoodu`（仅业务菜单，V24）

## 前端开发

### 管理台（admin-web）

```bash
cd doc/admin-web
npm install
npm run dev          # http://localhost:5176
```

### 用户端（uni-app-customer）

```bash
cd doc/uni-app-customer
npm install
npm run dev:h5       # http://localhost:5175
```

支持密码登录、短信验证码登录、邮箱验证码登录、微信 OAuth 登录。登录方式由后台 `auth.methods` 和 `wechat.oauth.enable` 动态控制。

### 工作台（uni-app-client）

```bash
cd doc/uni-app-client
npm install
npm run dev:h5       # http://localhost:5173
```

### 开发入口 Hub

```bash
node doc/portal-hub/serve.mjs    # http://localhost:5170
```

Hub 聚合所有端入口，包含多端互跳链接。

## CI 门禁与本地检查

```bash
./scripts/ci-local.sh          # 或 .\scripts\ci-local.ps1
```

GitHub Actions：`.github/workflows/ci.yml`（push/PR 触发）。
Docker 构建默认执行 `mvn test`。

## 安全基线（公开路径）

`config/public-paths.yml` 仅白名单登录/文档/探活等公开接口。
业务 REST 统一前缀 **`/api/v1`**（见 `ApiVersionWebConfig`）。
`/api/v1/file/**`、`/api/v1/task/**` 需登录并验证权限。

## 主要接口

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/auth/getPubKey` | 获取 SM2 公钥与加密开关状态 |
| `GET` | `/api/v1/auth/captcha` | 图形验证码 |
| `GET` | `/api/v1/auth/methods` | 获取启用的 toC 登录方式列表 |
| `GET` | `/api/v1/auth/register-methods` | 获取启用的 toC 注册方式状态 |
| `POST` | `/api/v1/auth/login` | 账号密码登录 |
| `POST` | `/api/v1/auth/refresh` | 会话续期 |
| `GET` | `/api/v1/auth/current` | 当前登录用户信息 |
| `POST` | `/api/v1/auth/logout` | 登出 |
| `POST` | `/api/v1/auth/sms/send-code` | 发送短信验证码 |
| `POST` | `/api/v1/auth/sms/login` | 短信验证码登录/自动注册 |
| `POST` | `/api/v1/auth/email/send-code` | 发送邮箱验证码 |
| `POST` | `/api/v1/auth/email/login` | 邮箱验证码登录/自动注册 |
| `GET` | `/api/v1/auth/oauth/wechat/config` | 获取微信 OAuth AppId |
| `POST` | `/api/v1/auth/oauth/wechat/login` | 微信授权登录/自动注册 |
| `POST` | `/api/v1/auth/register/send-code` | 注册-发送邮箱验证码 |
| `POST` | `/api/v1/auth/register` | 邮箱验证码注册 |
| `POST` | `/api/v1/auth/sms/register` | 手机号短信注册 |
| `POST` | `/api/v1/auth/forgot-password` | 忘记密码-发送验证码 |
| `POST` | `/api/v1/auth/reset-password` | 验证码重置密码 |
| `GET` | `/api/v1/site/info` | 站点信息（名称、Logo） |
| `POST` | `/api/v1/file/upload` | 单文件上传（OSS/本地，由 sys_config 控制） |
| `POST` | `/api/v1/file/delete` | 删除文件（OSS/本地） |
| `GET/POST/PUT/DELETE` | `/api/v1/sys-user/**` | 用户管理 CRUD |
| `GET/POST/PUT/DELETE` | `/api/v1/sys-role/**` | 角色管理 |
| `GET` | `/api/v1/sys-dept/tree` | 组织部门树 |
| `GET/POST/PUT` | `/api/v1/sys-config/**` | 系统配置管理 |
| `GET/POST/DELETE` | `/api/v1/sys-notice/**` | 系统通知 |
| `GET` | `/api/v1/db-meta/tables` | 数据库表结构查询 |
| `GET` | `/api/v1/db-meta/tables/{tableName}/data` | 表数据分页查询 |

完整 API 请访问 Knife4j 文档：http://localhost:8080/doc.html

## 数据库版本管理（Flyway）

共 **47 个 migration**（46 scaffold + 1 biz），覆盖：

| 范围 | 迁移号 | 内容 |
|------|--------|------|
| 基础表 | V1-V7 | sys_user、RBAC、字段扩展、密码修正 |
| RBAC 权限 | V8, V11, V12, V15, V16, V18 | 角色、资源、菜单、文件/任务权限 |
| 业务脚手架 | V21-V26 | 业务菜单、BizOrder 样板、BizStaffProfile、字典 |
| toC 注册登录 | V27, V44-V47 | CUSTOMER 角色、站点配置、微信登录、服务配置、文件存储配置 |
| 多租户 | V31-V33 | sys_tenant、租户预置、业务表租户字段 |
| AI 模块 | V35-V43 | AI 应用、Provider、知识库 |
| 审计/通知 | V10, V13-V14, V20, V29-V30 | 通知日志、操作日志、字典/菜单配置 |
| 数据权限 | V17, V19 | 部门数据范围 |
| 会话管理 | V28 | 角色最大会话数 |

## 项目结构

```
src/main/java/ugoodu/com/
├── annotation/            # 自定义注解（权限、限流、操作日志等）
├── common/                # 常量、Result、ResultCode、RBAC 常量
├── component/
│   ├── sso/               # SSO 过滤器、会话存储、票据管理
│   └── file/              # 文件管理组件
├── config/                # 配置（安全/Redis/MyBatis/国密/AI/通知/OSS/存储等）
├── controller/
│   ├── biz/               # 业务控制器（BizOrder、BizStaffProfile）
│   └── ...                # 系统控制器（Auth、SysUser、Role、Config 等）
├── entity/
│   ├── db/                # 数据库实体
│   ├── dto/               # 入参 DTO
│   └── vo/                # 出参 VO
├── enums/                 # 枚举（用户状态、删除标记、文档状态等）
├── exception/             # 全局异常 + AuthException
├── mapper/                # MyBatis Mapper
├── notify/                # 通知中心（Facade/Service/Sender）
│   └── sender/            # Mail/SMS/WeCom 发送器
├── storage/               # 文件存储抽象（OSS / 本地）
├── service/
│   ├── biz/               # 业务服务
│   ├── datascope/         # 数据权限范围
│   ├── impl/              # 服务实现
│   └── perm/              # 权限注册
├── util/                  # 工具类（国密、Redis、脱敏、AES、配置解析）
└── web/                   # Web 层（过滤器、拦截器）

doc/
├── admin-web/             # PC 管理台前端（React + Ant Design）
├── uni-app-client/        # H5 业务工作台（uni-app）
├── uni-app-customer/      # 用户端 toC（uni-app）
├── portal-hub/            # 开发入口 Hub 聚合页
└── SCAFFOLD-GUIDE.md      # 脚手架使用指南

api-json/                  # OpenAPI 导出 + Postman 联调集合
docker/                    # Docker Compose 多实例部署
scripts/                   # CI、模块生成、分层打包等脚本
```

## 加密配置

`config/dev/db-crypto.yml`：

```yaml
api-crypto:
  enable: true          # dev 默认开启
  sign-enable: true
  sign-timeout-ms: 300000
  sign-secret: dev-sign-secret-change-in-prod
```

关闭传输加密（仅本地调试）：将 `enable` / `sign-enable` 改为 `false`。

**加密调用逻辑**：[`doc/crypto-call-logic.md`](doc/crypto-call-logic.md)

### 请求头

| Header | 说明 |
|--------|------|
| `X-Encrypt-Key` | SM2 加密的 SM4 密钥 |
| `X-Timestamp` | 毫秒时间戳 |
| `X-Nonce` | 随机串（防重放） |
| `X-Sign` | SM3 签名 |
| `X-Sso-Token` | SSO 会话凭证 |

## 国际化

错误码与 `@Valid` 校验文案：`config/i18n/messages*.properties`，通过 `?lang=` 切换。

| lang | 语言包 |
|------|--------|
| `zh_CN`（默认） | `messages_zh_CN.properties` |
| `zh_TW` | `messages_zh_TW.properties` |
| `zh_HK` | `messages_zh_HK.properties` |
| `en_US` | `messages_en_US.properties` |
| `th_TH` | `messages_th_TH.properties` |

## 可选模块

| 模块 | yml 开关 | 说明 |
|------|----------|------|
| XXL-Job | `module.schedule.enable` | 分布式任务调度 |
| 阿里云 OSS | `module.oss.enable` | 对象存储（关闭时文件上传自动降级为本地存储） |
| 通知模块 | `module.notify.enable` | 邮件/短信/企微通知 |
| AI 模块 | `module.ai.enable` | AI 对话与应用管理 |

## 密钥与环境变量

| 变量 | 用途 |
|------|------|
| `MYSQL_PASSWORD` | 数据库密码 |
| `REDIS_HOST` / `REDIS_PASSWORD` | Redis 连接 |
| `DB_AES_SECRET` / `DB_AES_IV` | 字段 AES 加密 |
| `API_CRYPTO_*` / `SM2_*` | 国密传输 |
| `WECHAT_APP_ID` / `WECHAT_SECRET` | 微信 OAuth |
| `SPRING_MAIL_HOST` / `SPRING_MAIL_USERNAME` / `SPRING_MAIL_PASSWORD` | 邮件 SMTP |
| `SMS_ACCESS_KEY` / `SMS_ACCESS_SECRET` | 短信服务 |
| `AI_API_KEY` / `AI_BASE_URL` / `AI_MODEL` | AI 模块（OpenAI 兼容 API） |
| `FILE_STORAGE_TYPE` / `MODULE_OSS_ENABLE` | 文件存储方式 |

Docker：`cp docker/.env.example docker/.env`。生产：复制 `application-prod.yml.example`。

## 测试

```bash
mvn test
```

## Docker（分层增量 + 多实例 SSO）

`docker/docker-compose.yml` 提供完整分布式验证栈：

| 组件 | 说明 |
|------|------|
| MySQL 8 | 持久化数据，Flyway 自动迁移 |
| Redis 7 | SSO 会话、验证码、Token 黑名单（多实例共享） |
| boot-app-1 / boot-app-2 | 两个无状态应用实例 |
| Nginx | `:8080` 入口，`least_conn` 负载均衡 |

```bash
# 一键多实例
cd docker && cp .env.example .env && docker compose up -d --build

# 仅构建镜像
docker build -t boot-prod-demo:1.0 .

# 分层解包（增量发版）
.\scripts\package-layered.ps1   # Windows
```

| 镜像层 | 变化频率 |
|--------|----------|
| dependencies | 极低（改 pom 才变） |
| spring-boot-loader | 极低 |
| snapshot-dependencies | 低 |
| application | 高（日常发版） |

## 业务模块脚手架

一键生成表 + RBAC + controller.biz / service.biz + pages/biz：

```bash
node scripts/scaffold-module.cjs DemoItem 演示条目
```

## Postman 导入

导出 OpenAPI：

```bash
mvn spring-boot:run -Dspring-boot.run.profiles=dev
./scripts/export-api-docs.sh   # 输出 api-json/openapi.json
```

联调集合：[`api-json/postman-collection.json`](api-json/postman-collection.json)

## License

MIT