From 9fef17bae5a3f66399766b414621d4096a19adf1 Mon Sep 17 00:00:00 2001
From: Jerry Yan <792602257@qq.com>
Date: Mon, 18 Aug 2025 04:34:13 +0800
Subject: [PATCH] =?UTF-8?q?docs(CLAUDE.md):=20=E6=9B=B4=E6=96=B0=E4=BB=B7?=
 =?UTF-8?q?=E6=A0=BC=E6=9F=A5=E8=AF=A2=E7=B3=BB=E7=BB=9F=E6=8C=87=E5=AF=BC?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

diff --git a/CLAUDE.md b/CLAUDE.md
index 63c9ce5..6c92571 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-本文件为 Claude Code (claude.ai/code) 在此代码仓库中工作时提供指导。
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## 构建和开发命令
 
@@ -120,4 +120,71 @@ mvn test -DskipTests=false
 1. 在 `com.ycwl.basic.task` 包中创建类
 2. 添加 `@Component` 和 `@Profile("prod")` 注解
 3. 使用 `@Scheduled` 进行基于 cron 的执行
-4. 遵循现有的错误处理和日志记录模式
\ No newline at end of file
+4. 遵循现有的错误处理和日志记录模式
+
+## 价格查询系统 (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集成
\ No newline at end of file