You've already forked FrameTour-BE
292 lines
9.8 KiB
Markdown
292 lines
9.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## 构建和开发命令
|
|
|
|
### 构建应用程序
|
|
```bash
|
|
# 清理构建（默认跳过测试）
|
|
mvn clean package
|
|
|
|
# 清理构建并执行测试
|
|
mvn clean package -DskipTests=false
|
|
|
|
# 运行应用程序
|
|
mvn spring-boot:run
|
|
```
|
|
|
|
### 测试命令
|
|
```bash
|
|
# 运行特定测试类
|
|
mvn test -Dtest=FaceCleanerTest
|
|
|
|
# 运行特定包的测试
|
|
mvn test -Dtest="com.ycwl.basic.storage.adapters.*Test"
|
|
|
|
# 运行所有测试
|
|
mvn test -DskipTests=false
|
|
```
|
|
|
|
### 开发环境配置
|
|
应用程序使用 Spring 配置文件：
|
|
- 默认激活配置文件：`dev`
|
|
- 生产环境配置文件：`prod`（启用定时任务）
|
|
- 配置文件：`application-dev.yml`、`application-prod.yml`
|
|
|
|
## 架构概览
|
|
|
|
这是一个 Spring Boot 3.3.5 应用程序（Java 21），采用多租户架构，通过不同的 API 端点为不同的客户端类型提供服务。
|
|
|
|
### 控制器架构
|
|
- **移动端 APIs** (`/api/mobile/`)：面向移动应用的客户端端点
|
|
- **PC 端 APIs** (`/api/`)：Web 仪表板/管理面板端点
|
|
- **任务 APIs** (`/task/`)：后台工作和渲染任务端点
|
|
- **外部 APIs**：专用集成（打印机、代理、viid、vpt、wvp）
|
|
|
|
### 核心业务模块
|
|
|
|
#### 工厂模式实现
|
|
三个主要工厂类管理第三方集成：
|
|
|
|
1. **StorageFactory** (`com.ycwl.basic.storage.StorageFactory`)
|
|
- 管理：本地存储、AWS S3、阿里云 OSS 存储适配器
|
|
- 配置节：`storage.configs[]`
|
|
|
|
2. **PayFactory** (`com.ycwl.basic.pay.PayFactory`)
|
|
- 管理：微信支付、聪明支付适配器
|
|
- 配置节：`pay.configs[]`
|
|
|
|
3. **FaceBodyFactory** (`com.ycwl.basic.facebody.FaceBodyFactory`)
|
|
- 管理：阿里云、百度人脸识别适配器
|
|
- 配置节：`facebody.configs[]`
|
|
|
|
#### 适配器模式
|
|
每个工厂使用标准化接口：
|
|
- `IStorageAdapter`：文件操作（上传/下载/删除/ACL）
|
|
- `IPayAdapter`：支付生命周期（创建/回调/退款）
|
|
- `IFaceBodyAdapter`：人脸识别操作
|
|
|
|
#### 定时任务系统
|
|
`com.ycwl.basic.task` 包中的后台任务（仅生产环境）：
|
|
- `VideoTaskGenerator`：人脸识别和视频处理
|
|
- `FaceCleaner`：人脸和存储清理任务
|
|
- `DynamicTaskGenerator`：带延迟队列的动态任务创建
|
|
- `ScenicStatsTask`：统计数据聚合
|
|
|
|
### 数据库和持久化
|
|
- **MyBatis Plus**：具有自动 CRUD 操作的 ORM
|
|
- **MapperScan**：扫描 `com.ycwl.basic.mapper` 及子包
|
|
- **数据库**：MySQL 配合 HikariCP 连接池
|
|
- **Redis**：会话管理和缓存
|
|
|
|
### 主要库和依赖
|
|
- Spring Boot 3.3.5 启用 Java 21 虚拟线程
|
|
- MyBatis Plus 3.5.5 用于数据库操作
|
|
- JWT (jjwt 0.9.0) 用于身份验证
|
|
- 微信支付 SDK 用于支付处理
|
|
- 阿里云 OSS 和 AWS S3 用于文件存储
|
|
- 阿里云和百度 SDK 用于人脸识别
|
|
- OpenTelemetry 用于可观测性（开发环境中禁用）
|
|
|
|
### 业务逻辑组织
|
|
- **Service 层**：`service` 包中的业务逻辑实现
|
|
- **Biz 层**：`biz` 包中的高级业务编排
|
|
- **Repository 模式**：`repository` 包中的数据访问抽象
|
|
- **自定义异常**：特定领域的异常处理
|
|
|
|
### 配置管理
|
|
每个模块使用 Spring Boot 自动配置启动器：
|
|
- 支持多供应商的命名配置
|
|
- 通过配置进行默认供应商选择
|
|
- 针对不同环境的特定配置文件
|
|
|
|
## 常见开发模式
|
|
|
|
### 添加新的存储/支付/人脸识别供应商
|
|
1. 实现相应接口（`IStorageAdapter`、`IPayAdapter`、`IFaceBodyAdapter`）
|
|
2. 在相应的类型枚举中添加枚举值
|
|
3. 更新工厂的 switch 表达式
|
|
4. 如需要，添加配置类
|
|
5. 在 application.yml 中更新新供应商配置
|
|
|
|
### 身份验证上下文
|
|
在整个应用程序中使用 `BaseContextHandler.getUserId()` 获取当前已认证用户 ID。
|
|
|
|
### API 响应模式
|
|
所有 API 都返回 `ApiResponse<T>` 包装器，通过 `CustomExceptionHandle` 进行一致的错误处理。
|
|
|
|
### 添加新的定时任务
|
|
1. 在 `com.ycwl.basic.task` 包中创建类
|
|
2. 添加 `@Component` 和 `@Profile("prod")` 注解
|
|
3. 使用 `@Scheduled` 进行基于 cron 的执行
|
|
4. 遵循现有的错误处理和日志记录模式
|
|
|
|
### 多端API架构
|
|
应用程序通过路径前缀区分不同的客户端：
|
|
- **移动端**: `/api/mobile/*` - 针对移动应用优化的接口
|
|
- **PC管理端**: `/api/*` - Web管理面板接口
|
|
- **任务处理**: `/task/*` - 后台任务和渲染服务接口
|
|
- **外部集成**: 专用集成接口（打印机、代理、viid、vpt、wvp等）
|
|
|
|
每个端点都有对应的Controller包结构，确保API的职责分离和维护性。
|
|
|
|
## 价格查询系统 (Pricing Module)
|
|
|
|
### 核心架构
|
|
价格查询系统是一个独立的业务模块，位于 `com.ycwl.basic.pricing` 包中，提供商品定价、优惠券管理和价格计算功能。
|
|
|
|
#### 关键组件
|
|
- **PriceCalculationController** (`/api/pricing/calculate`)：价格计算API
|
|
- **CouponManagementController** (`/api/pricing/admin/coupons/`)：优惠券管理API
|
|
- **PricingConfigController** (`/api/pricing/config/`)：价格配置管理API
|
|
|
|
#### 商品类型支持
|
|
```java
|
|
ProductType枚举定义了支持的商品类型：
|
|
- VLOG_VIDEO: Vlog视频
|
|
- RECORDING_SET: 录像集
|
|
- PHOTO_SET: 照相集
|
|
- PHOTO_PRINT: 照片打印
|
|
- MACHINE_PRINT: 一体机打印
|
|
```
|
|
|
|
#### 价格计算流程
|
|
1. 接收PriceCalculationRequest（包含商品列表和用户ID）
|
|
2. 查找商品基础配置和分层定价
|
|
3. 处理套餐商品（BundleProductItem）
|
|
4. 自动应用最优优惠券
|
|
5. 返回PriceCalculationResult（包含原价、最终价格、优惠详情）
|
|
|
|
#### 优惠券系统
|
|
- **CouponType**: PERCENTAGE（百分比）、FIXED_AMOUNT（固定金额）
|
|
- **CouponStatus**: CLAIMED（已领取）、USED（已使用）、EXPIRED（已过期）
|
|
- 支持商品类型限制 (`applicableProducts` JSON字段)
|
|
- 最小消费金额和最大折扣限制
|
|
- 时间有效期控制
|
|
|
|
#### 分页查询功能
|
|
所有管理接口都支持分页查询，使用PageHelper实现：
|
|
- 优惠券配置分页：支持按状态、名称筛选
|
|
- 领取记录分页：支持按用户、优惠券、状态、时间范围筛选
|
|
|
|
#### 统计功能
|
|
- 基础统计：领取数、使用数、可用数
|
|
- 详细统计：使用率、平均使用天数
|
|
- 时间范围统计：指定时间段的整体数据分析
|
|
|
|
### 开发模式
|
|
|
|
#### 添加新商品类型
|
|
1. 在ProductType枚举中添加新类型
|
|
2. 在PriceProductConfig表中配置default配置
|
|
3. 根据需要添加分层定价（PriceTierConfig）
|
|
4. 更新前端产品类型映射
|
|
|
|
#### 添加新优惠券类型
|
|
1. 在CouponType枚举中添加类型
|
|
2. 在CouponServiceImpl中实现计算逻辑
|
|
3. 更新applicableProducts验证规则
|
|
|
|
#### 自定义TypeHandler使用
|
|
项目使用自定义TypeHandler处理复杂JSON字段：
|
|
- `BundleProductListTypeHandler`：处理套餐商品列表JSON序列化
|
|
|
|
### 测试策略
|
|
- 单元测试：每个服务类都有对应测试类
|
|
- 配置验证测试：DefaultConfigValidationTest验证default配置
|
|
- JSON序列化测试：验证复杂对象的数据库存储
|
|
- 分页功能测试：验证PageHelper集成
|
|
|
|
## 关键架构模式
|
|
|
|
### Repository 层模式
|
|
项目使用Repository层抽象数据访问逻辑：
|
|
- Repository接口定义数据访问契约
|
|
- Mapper接口处理MyBatis Plus的数据库映射
|
|
- Service层通过Repository访问数据，避免直接依赖Mapper
|
|
|
|
### 异常处理架构
|
|
- **全局异常处理**: `CustomExceptionHandle` 提供统一的异常处理和响应格式
|
|
- **业务异常**: 自定义异常类继承RuntimeException，携带业务错误码
|
|
- **集成异常**: `IntegrationException` 专门处理外部服务调用异常
|
|
|
|
### 配置驱动的扩展性
|
|
通过配置文件驱动的多供应商支持：
|
|
- 存储：本地、AWS S3、阿里云 OSS
|
|
- 支付：微信支付、聪明支付
|
|
- 人脸识别：阿里云、百度
|
|
每个供应商通过统一接口访问，配置切换无需代码修改。
|
|
|
|
### 业务层架构
|
|
- **Service层**: 核心业务逻辑实现
|
|
- **Biz层**: 高级业务流程编排，组合多个Service
|
|
- **Controller层**: HTTP请求处理和响应转换
|
|
- **Repository层**: 数据访问抽象
|
|
|
|
### 认证和会话管理
|
|
- **JWT**: 使用jjwt库进行身份验证
|
|
- **Redis**: 存储会话信息和缓存
|
|
- **BaseContextHandler**: 提供当前用户上下文访问
|
|
|
|
## 微服务集成架构 (Integration Package)
|
|
|
|
### 核心架构
|
|
位于 `com.ycwl.basic.integration` 包，使用 Spring Cloud OpenFeign 和 Nacos 实现外部微服务集成。
|
|
|
|
#### 通用基础设施
|
|
- **IntegrationProperties**: 所有集成的集中配置管理
|
|
- **FeignErrorDecoder**: 自定义错误解码器，统一错误处理
|
|
- **IntegrationException**: 标准化集成异常
|
|
- **CommonResponse/PageResponse**: 外部服务响应包装器
|
|
|
|
#### 已实现的服务集成
|
|
- **Scenic Integration** (`integration.scenic`): ZT-Scenic 微服务集成
|
|
- **Device Integration** (`integration.device`): ZT-Device 微服务集成
|
|
|
|
#### 集成模式
|
|
每个外部服务按以下结构组织：
|
|
```
|
|
service/
|
|
├── client/ # Feign 客户端
|
|
├── config/ # 服务特定配置
|
|
├── dto/ # 数据传输对象
|
|
├── service/ # 业务逻辑层
|
|
└── example/ # 使用示例
|
|
```
|
|
|
|
### 配置管理
|
|
```yaml
|
|
integration:
|
|
scenic:
|
|
enabled: true
|
|
serviceName: zt-scenic
|
|
connectTimeout: 5000
|
|
readTimeout: 10000
|
|
device:
|
|
enabled: true
|
|
serviceName: zt-device
|
|
connectTimeout: 5000
|
|
readTimeout: 10000
|
|
```
|
|
|
|
### 使用模式
|
|
所有集成服务使用统一的 `handleResponse` 模式进行错误处理，确保一致的异常包装和日志记录。
|
|
|
|
### 测试集成服务
|
|
```bash
|
|
# 运行特定集成测试
|
|
mvn test -Dtest=ScenicIntegrationServiceTest
|
|
mvn test -Dtest=DeviceIntegrationServiceTest
|
|
|
|
# 运行所有集成测试
|
|
mvn test -Dtest="com.ycwl.basic.integration.*Test"
|
|
```
|
|
|
|
### 调试集成问题
|
|
启用 Feign 客户端日志：
|
|
```yaml
|
|
logging:
|
|
level:
|
|
com.ycwl.basic.integration: DEBUG
|
|
``` |