q792602257/FrameTour-BE
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2f88699bb00059bc9b96e16919829db7c119254b
FrameTour-BE/CLAUDE.md
Jerry Yan d34603062a feat(integration): 添加设备服务集成模块 
- 新增设备服务配置和相关客户端接口
- 实现设备和设备配置的管理功能- 添加设备监控和状态管理示例
- 优化错误处理和故障恢复机制
2025-08-30 23:30:12 +08:00

9.8 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

构建和开发命令

构建应用程序

# 清理构建（默认跳过测试）
mvn clean package

# 清理构建并执行测试
mvn clean package -DskipTests=false

# 运行应用程序
mvn spring-boot:run

测试命令

# 运行特定测试类
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

商品类型支持

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/         # 使用示例

配置管理

integration:
  scenic:
    enabled: true
    serviceName: zt-scenic
    connectTimeout: 5000
    readTimeout: 10000
  device:
    enabled: true
    serviceName: zt-device
    connectTimeout: 5000
    readTimeout: 10000

使用模式

所有集成服务使用统一的 handleResponse 模式进行错误处理，确保一致的异常包装和日志记录。

测试集成服务

# 运行特定集成测试
mvn test -Dtest=ScenicIntegrationServiceTest
mvn test -Dtest=DeviceIntegrationServiceTest

# 运行所有集成测试
mvn test -Dtest="com.ycwl.basic.integration.*Test"

调试集成问题

启用 Feign 客户端日志：

logging:
  level:
    com.ycwl.basic.integration: DEBUG