Files

Jerry Yan 9fef17bae5 docs(CLAUDE.md): 更新价格查询系统指导文档

- 新增价格查询系统的核心架构、关键组件、商品类型支持等内容
- 详细说明价格计算流程和优惠券系统
- 添加分页查询和统计功能的说明
- 新增开发模式下的操作指南，包括添加新商品类型和优惠券类型的步骤
- 介绍自定义TypeHandler的使用和测试策略

2025-08-18 04:34:13 +08:00

6.5 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）

核心业务模块

工厂模式实现

三个主要工厂类管理第三方集成：

StorageFactory (com.ycwl.basic.storage.StorageFactory)
- 管理：本地存储、AWS S3、阿里云 OSS 存储适配器
- 配置节：storage.configs[]
PayFactory (com.ycwl.basic.pay.PayFactory)
- 管理：微信支付、聪明支付适配器
- 配置节：pay.configs[]
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 自动配置启动器：

支持多供应商的命名配置
通过配置进行默认供应商选择
针对不同环境的特定配置文件

常见开发模式

添加新的存储/支付/人脸识别供应商

实现相应接口（IStorageAdapter、IPayAdapter、IFaceBodyAdapter）
在相应的类型枚举中添加枚举值
更新工厂的 switch 表达式
如需要，添加配置类
在 application.yml 中更新新供应商配置

身份验证上下文

在整个应用程序中使用 BaseContextHandler.getUserId() 获取当前已认证用户 ID。

API 响应模式

所有 API 都返回 ApiResponse<T> 包装器，通过 CustomExceptionHandle 进行一致的错误处理。

添加新的定时任务

在 com.ycwl.basic.task 包中创建类
添加 @Component 和 @Profile("prod") 注解
使用 @Scheduled 进行基于 cron 的执行
遵循现有的错误处理和日志记录模式

价格查询系统 (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: 一体机打印

价格计算流程

接收PriceCalculationRequest（包含商品列表和用户ID）
查找商品基础配置和分层定价
处理套餐商品（BundleProductItem）
自动应用最优优惠券
返回PriceCalculationResult（包含原价、最终价格、优惠详情）

优惠券系统

CouponType: PERCENTAGE（百分比）、FIXED_AMOUNT（固定金额）
CouponStatus: CLAIMED（已领取）、USED（已使用）、EXPIRED（已过期）
支持商品类型限制 (applicableProducts JSON字段)
最小消费金额和最大折扣限制
时间有效期控制

分页查询功能

所有管理接口都支持分页查询，使用PageHelper实现：

优惠券配置分页：支持按状态、名称筛选
领取记录分页：支持按用户、优惠券、状态、时间范围筛选

统计功能

基础统计：领取数、使用数、可用数
详细统计：使用率、平均使用天数
时间范围统计：指定时间段的整体数据分析

开发模式

添加新商品类型

在ProductType枚举中添加新类型
在PriceProductConfig表中配置default配置
根据需要添加分层定价（PriceTierConfig）
更新前端产品类型映射

添加新优惠券类型

在CouponType枚举中添加类型
在CouponServiceImpl中实现计算逻辑
更新applicableProducts验证规则

自定义TypeHandler使用

项目使用自定义TypeHandler处理复杂JSON字段：

BundleProductListTypeHandler：处理套餐商品列表JSON序列化

测试策略

单元测试：每个服务类都有对应测试类
配置验证测试：DefaultConfigValidationTest验证default配置
JSON序列化测试：验证复杂对象的数据库存储
分页功能测试：验证PageHelper集成

6.5 KiB Raw Blame History