# 业务后台系统技术说明文档 > 本文档由 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) ```yaml 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 ```bash ./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://:8030/manager Doc: http://: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)