业务后台系统技术说明文档

本文档由 Sisyphus AI 助手生成，用于帮助 AI 代理快速理解本项目结构、架构和关键实现细节。

1. 项目概述

属性	值
项目名称	business-webapi
Artifact ID	business-webapi
Group ID	com.hz3r.infrastructure
版本	1.0.0
描述	园区管理系统后端 API 服务
基础框架	Spring Boot 3.1.2
Java 版本	17
打包方式	Spring Boot Jar
端口	8030
API 文档	`/manager/doc.html` (SpringDoc Swagger UI)

2. 技术栈

2.1 核心框架

Spring Boot 3.1.2 - 应用程序框架
Spring Web - REST API
Spring Security - 认证授权
Spring Data Redis - 缓存
MyBatis Plus 3.5.14 - ORM (支持 Spring Boot 3)
MySQL Connector 8.4.0 - 数据库驱动

2.2 认证相关

java-jwt 4.5.0 (Auth0) - JWT 解析
jjwt 0.11.5 (io.jsonwebtoken) - JWT 生成
Kaptcha 2.3.2 - 图形验证码

2.3 工具库

Hutool 5.8.8 - Java 工具集
FastJSON 2.0.53 - JSON 序列化
FastJSON2 2.0.53 - JSON 序列化 (新版)
EasyExcel 3.1.1 - Excel 读写
Apache POI 5.5.1 - Office 文档
Apache Commons (Lang3, Collections4, Text, Pool2) - Apache 工具集
Vavr 0.10.4 - 函数式编程

2.4 第三方 SDK

MinIO 8.5.2 - 对象存储
Alipay SDK 4.40.576.ALL - 支付宝支付
阿里云短信 Dysmsapi 4.1.1 - SMS
海康威视 Artemis HTTP Client 1.1.13 - 视频监控
海康威视 AKSK SDK 1.2.1 / 2.0.0 - 设备接入
JNA 3.0.9 - Java Native Access

2.5 数据库迁移

Flyway (通过 Spring Boot 内置) - 数据库版本化管理

3. 项目结构

src/main/java/com/hz3r/
├── infrastructure/park/              # 主包 - 园区管理系统核心
│   ├── BusinessWebapiApplication.java   # Spring Boot 启动类
│   ├── client/                          # 外部客户端调用
│   ├── config/                          # 配置类
│   ├── domain/                          # 领域模型
│   │   ├── beb/                         # 业务实体(?)
│   │   ├── constant/                    # 常量
│   │   ├── entity/                     # 数据库实体
│   │   ├── enums/                     # 枚举
│   │   └── vo/                         # 值对象 DTO
│   ├── excel/                          # Excel 工具
│   ├── hikvision/                      # 海康威视集成
│   ├── job/                            # 定时任务
│   ├── kafka/                          # Kafka 消息
│   ├── listener/                        # Spring 事件监听器
│   ├── mapper/                         # MyBatis Mapper
│   ├── security/                       # 安全相关 (TokenAuthenticationFilter, UserDetails)
│   ├── service/                        # 业务服务层
│   │   ├── access/                    # 访客通行
│   │   ├── adc/                       # 广告/支付聚合
│   │   ├── agc/                       # (AGC 相关)
│   │   ├── app/                       # APP 端
│   │   ├── artemis/                    # 海康 Artemis
│   │   ├── business/                  # 通用业务
│   │   ├── hik/                      # 海康
│   │   ├── icCard/                   # IC 卡
│   │   ├── meter/                    # 水电表
│   │   ├── meterbillnew/              # 水电账单(新)
│   │   ├── payment/                  # 支付
│   │   ├── share/                    # 分享
│   │   ├── tenant/                   # 租户管理
│   │   ├── visitor/                  # 访客
│   │   ├── sys/                     # 系统管理
│   │   └── wehcat/                  # 微信(?)
│   └── web/                          # Web 层 (Controller)
│       ├── controller/
│       │   ├── access/               # 通行 Controller
│       │   ├── adc/                 # ADC Controller (聚合支付/广告)
│       │   ├── agc/                 # AGC Controller
│       │   ├── artemis/             # Artemis Controller
│       │   ├── front/               # 前端 Controller
│       │   ├── hikvision/          # 海康 Controller
│       │   ├── icCard/            # IC 卡 Controller
│       │   ├── index/              # 首页
│       │   ├── lease/             # 租赁 Controller
│       │   ├── login/             # 登录
│       │   ├── merchant/          # 商户
│       │   ├── meter/            # 水电表
│       │   ├── meterapp/         # 水电表 APP
│       │   ├── openapi/          # 开放 API
│       │   ├── payment/          # 支付
│       │   ├── sys/              # 系统
│       │   ├── tenant/           # 租户
│       │   └── visitor/           # 访客
│       ├── event/                  # 事件控制器
│       └── scheduler/             # 调度器
├── authorization/                   # 认证授权模块
│   ├── app/                       # APP Token
│   │   ├── AppTokenManager.java
│   │   ├── AppTokenManagerImpl.java
│   │   └── AppTokenModel.java
│   └── front/                     # 前端 Token
│       ├── FrontTokenManager.java
│       ├── FrontTokenManagerImpl.java
│       └── FrontTokenModel.java
├── config/                         # 全局配置
│   ├── BusiRedisConfig.java
│   ├── BusiRedisFastJson2JsonSerializer.java
│   ├── LocalDateTimeConfiguration.java
│   ├── MybatisPlusConfiguration.java
│   ├── RestTemplateConfig.java
│   ├── SpringDocConfig.java
│   └── WebConfiguration.java
├── domain/                          # 通用领域模型
├── exception/                      # 全局异常
├── schedule/                        # 调度任务
├── utils/                          # 工具类
│   ├── BusiServiceUtils.java       # 业务服务工具
│   ├── BusiSvcCUDUtils.java       # 增删改工具
│   ├── BusiSvcQueryUtils.java     # 查询工具
│   ├── CaptchaUtils.java          # 验证码工具
│   ├── DPCUtils.java              # 数据处理
│   ├── EnumGroupingUtils.java      # 枚举分组
│   ├── JwtTokenProvider.java     # JWT Token Provider
│   ├── JwtUtil.java             # JWT 工具
│   ├── LocalDateTimeUtil.java    # 日期时间工具
│   ├── LocalOrderNoGenerator.java # 订单号生成
│   ├── MeterDevOnlineUtils.java   # 设备在线状态
│   ├── MiscUtils.java            # 杂项工具
│   ├── MyDbOpsUtils.java        # 数据库操作
│   ├── MyEntityUtils.java       # 实体工具
│   ├── MyLocalDateTimeUtils.java # 日期时间
│   ├── MyNumberUtils.java       # 数字工具
│   ├── MyOssUtils.java       # OSS 工具
│   ├── MyShortIdUtils.java   # 短 ID
│   ├── MyStrUtils.java      # 字符串
│   ├── ObjectConversion.java # 对象转换
│   ├── PercentageUtils.java # 百分比
│   ├── RedisCache.java      # Redis 缓存
│   ├── RedisUtil.java       # Redis 工具
│   ├── RedisUtils.java     # Redis 工具
│   ├── RequestUtil.java    # 请求工具
│   ├── RestTemplateUtil.java # HTTP 客户端
│   ├── SecurityUtils.java   # 安全工具
│   ├── SpringBeanUtils.java # Spring Bean
│   ├── TenantSortUtils.java # 租户排序
│   ├── ThreadLocalUtil.java # ThreadLocal
│   └── meter/              # 水电表相关工具
│       ├── Base64.java
│       ├── CaptchaConfig.java
│       ├── DateDimensionUtils.java
│       ├── JwtUtils.java
│       └── RedisCache.java
├── web/                            # Web 通用层
│   ├── advice/                    # 异常拦截 (ThrowableAdvice)
│   ├── controller/
│   │   ├── FileContentExchangeController.java  # 文件交换
│   │   └── OssController.java               # OSS
│   └── interceptor/
│       ├── AppTokenInterceptor.java   # APP Token 拦截
│       ├── FrontTokenInterceptor.java # 前端 Token 拦截
│       └── RequestIdInterceptor.java # 请求 ID 拦截
└── aop/                           # AOP 切面
    ├── IVoLogInfo.java
    └── ProjDocItem.java

4. 数据库

引擎: MySQL 8.x
ORM: MyBatis Plus 3.5.14 (支持 Spring Boot 3)
连接池: Druid (Spring Boot 内置 HikariCP)
Mapper 扫描路径: com.hz3r.infrastructure.park.**.mapper
表名/列名格式: 反引号包裹 (处理数据库关键词如 type, index)
迁移工具: Flyway
Flyway 脚本路径: src/main/resources/db.flyway/

4.1 配置文件优先级 (profile)

文件	用途
`application.yml`	主配置
`application-dev.yml`	开发环境 (默认激活)
`application-test.yml`	测试环境
`application-prod.yml`	生产环境
`application-local.yml`	本地环境
`application-ut.yml`	单元测试

5. 核心功能模块

5.1 认证授权

模块	说明	Token 存储
`authorization.app`	APP 端认证	Redis
`authorization.front`	前端 Web 认证	Redis

登录限制: 5 次失败后锁定 15 分钟。

5.2 业务模块

模块	Controller 包	说明
租户管理	`tenant/`	租户、部门、员工管理
访客管理	`visitor/`	预约、通行权限
水电表	`meter/`	水电表账单、缴费
支付	`adc/`	支付宝聚合支付
通行	`access/`	门禁通行
IC 卡	`icCard/`	IC 卡管理
海康视频	`artemis/` `hikvision/`	视频监控集成

5.3 开放接口

springdoc-openapi: /v3/api-docs → /manager/doc.html
OpenAPI 3.0 规范

6. 配置文件 (application.yml)

server:
  port: 8030
spring:
  application.name: business-webapi
  profiles.active: dev
  jackson.property-naming-strategy: LOWER_CAMEL_CASE
mybatis-plus:
  global-config.db-config.column-format: "`%s`"
park.api.title: 园区管理系统 API文档
data.appName: 义乌蓝宇数码园区
data.sms-cloud: # 阿里云短信配置
data.login-limit.max-fail-count: 5
data.login-limit.lock-minutes: 15

7. 构建与部署

7.1 Maven

./mvnw clean package    # 构建
./mvnw spring-boot:run  # 运行

7.2 Docker

Dockerfile - 标准 Spring Boot 镜像
Dockerfile-jar - Fat JAR 镜像
docker-compose.yml - 本地开发环境

7.3 CI/CD

.gitlab-ci.yml - GitLab CI 流水线
.ci-build_script.sh - Linux 构建脚本
.ci-build_script.dev.sh - 开发环境构建

7.4 部署脚本

文件	用途
`jar-quick-delivery.sh`	Linux 一键��署
`jar-quick-delivery.bat`	Windows 一键部署
`jar-deploy.sh`	JAR 部署脚本

7.5 本地原生库

lib/win32/ - Windows 原生 DLL (海康 SDK)
- HCNetSDK.dll, HCCore.dll - 海康 SDK
- hpr.dll, hlog.dll - 海康日志
- libcrypto, libssl - OpenSSL

8. 依赖仓库

nexus.hz3r.cn/repository/maven-public/

(杭州幻视科技公司内部 Maven 仓库)

9. 启动日志

--------------------------启动成功--------------------------------
  Application 'business-webapi' is running!
  Login:   http://<host>:8030/manager
  Doc:     http://<host>:8030/manager/doc.html

10. 关键设计模式

设计	说明
分层架构	Controller → Service → Mapper
Redis Token	APP/前端 Token 管理，存储在 Redis
聚合支付	`adc/` 下多个支付通道聚合 (支付宝)
海康集成	`artemis/` HTTP API + 本地 JNA SDK
请求追踪	`RequestIdInterceptor` 为每个请求生成唯一请求 ID
统一异常	`ThrowableAdvice` 全局异常拦截
AOP 日志	`ProjDocItem` + `IVoLogInfo` 切面日志

11. 数据库表生成代码说明

代码	来源	说明
代码模板	Ba1att或IBa1att开头的代码文件	Ba1attATemplateTable.java，Ba1attATemplateTableVo.java，Ba1attATemplateTableBEB.java，Ba1attATemplateTableMapperBEB.java，Ba1attATemplateTableMapper.java，IBa1attATemplateTableService.java，Ba1attATemplateTableServiceImpl.java，Ba1attATemplateTableController.java，Ba1attATemplateTableMapper.xml
类型属性命名	表字段名称	首字母小写驼峰命名策略
静态属性DATA_CODE	表名	数据代码，表名第一个单词小写
静态属性REL_UP	表名	上级数据引用当前数据的KEY，表名第一个单词小写 + `_id`
实体类型属性自动填充策略	表字段描述	检查表字段描述中//${xxx}//部分，如果其中包含 IF，则 insert 时自动填充，包含 IFU，则 update 时自动填充，包含 IFIU，则 insert 和 update 时自动填充
VO类型属性必填校验	表字段描述	检查表字段描述中//${xxx}//部分，如果其中包含 NR，则忽略必填，否则更具数据中字段是否必填设置 springboot 的 validation 规则

本文档版本: 1.0.0 生成时间: 2026-04-30 适用 AI: Sisyphus (OhMyOpenCode)

TECH-DOC.md 17 KB Permalink History Raw

业务后台系统技术说明文档

1. 项目概述

2. 技术栈

2.1 核心框架

2.2 认证相关

2.3 工具库

2.4 第三方 SDK

2.5 数据库迁移

3. 项目结构

4. 数据库

4.1 配置文件优先级 (profile)

5. 核心功能模块

5.1 认证授权

5.2 业务模块

5.3 开放接口

6. 配置文件 (application.yml)

7. 构建与部署

7.1 Maven

7.2 Docker

7.3 CI/CD

7.4 部署脚本

7.5 本地原生库

8. 依赖仓库

9. 启动日志

10. 关键设计模式

11. 数据库表生成代码说明

TECH-DOC.md 17 KB

Permalink History Raw