feat(pricing): 添加优惠券用户领取数量限制功能

- 新增用户领取数量限制字段 userClaimLimit
- 区分已领取数量 claimedQuantity 和已使用数量 usedQuantity
- 添加用户领取次数统计方法 countUserCouponClaims
- 实现领取上限检查逻辑和错误码 CLAIM_LIMIT_REACHED
- 更新数据库表结构和索引优化建议
- 完善文档说明和版本更新记录

src/main/java/com/ycwl/basic/pricing/CLAUDE.md

@@ -122,8 +122,54 @@ public enum CouponStatus { CLAIMED("claimed", ...), USED("used", ...), EXPIRED("
 - 商品类型限制：通过 JSON 字段（结合 `ProductTypeListTypeHandler`）控制适用商品
 - 消费限制：支持最小消费金额、最大折扣限制
 - 时效性：基于时间的有效期控制
+- **用户领取数量限制**：通过 `userClaimLimit` 字段控制单个用户可领取优惠券的最大数量(v1.0.0新增)
+- **库存精细化管理**：区分 `claimedQuantity`(已领取数量) 和 `usedQuantity`(已使用数量)
 - 统计分析：完整的使用统计与分析能力
 
+#### 优惠券数量管理机制 (v1.0.0更新)
+```java
+// PriceCouponConfig 实体新增字段
+private Integer userClaimLimit;    // 每个用户可领取数量限制(NULL表示不限制)
+private Integer claimedQuantity;   // 已领取数量(区分于已使用数量)
+private Integer usedQuantity;      // 已使用数量(实际消耗时更新)
+
+// 领取流程检查顺序
+1. 检查优惠券是否存在且启用
+2. 检查有效期
+3. 检查总量库存: claimedQuantity < totalQuantity
+4. 检查用户领取限制: countUserClaims(userId, couponId) < userClaimLimit
+5. 创建领取记录并更新 claimedQuantity + 1
+```
+
+#### 用户领取限制配置示例
+```java
+// 场景1: 新人专享券,每人限领1张
+{
+  "couponName": "新人专享券",
+  "userClaimLimit": 1,
+  "totalQuantity": 1000
+}
+
+// 场景2: 活动券,每人限领3张
+{
+  "couponName": "618促销券",
+  "userClaimLimit": 3,
+  "totalQuantity": 5000
+}
+
+// 场景3: 不限制领取次数
+{
+  "couponName": "会员专享券",
+  "userClaimLimit": null,  // 或 0
+  "totalQuantity": 10000
+}
+```
+
+#### 错误码扩展
+- `CLAIM_LIMIT_REACHED`: 用户已达到该优惠券的领取上限
+- `COUPON_OUT_OF_STOCK`: 优惠券库存不足(基于claimedQuantity检查)
+- `ALREADY_CLAIMED`: 用户已领取过(兼容旧逻辑)
+
 ### 3. 商品配置管理
 
 #### API端点（摘）
@@ -550,9 +596,22 @@ public class PriceCalculationResult {
 - `price_product_config`: 商品价格基础配置（包含 `can_use_coupon`、`can_use_voucher`、`can_use_one_price` 优惠控制字段）
 - `price_tier_config`: 分层定价配置
 - `price_bundle_config`: 套餐配置
-- `price_coupon_config`: 优惠券配置
+- `price_coupon_config`: 优惠券配置（**v1.0.0新增**: `user_claim_limit` 用户领取限制, `claimed_quantity` 已领取数量）
 - `price_coupon_claim_record`: 优惠券领取记录
 
+### price_coupon_config 表字段说明 (v1.0.0更新)
+```sql
+-- 核心数量管理字段
+total_quantity INT          -- 发行总量
+claimed_quantity INT        -- 已领取数量(v1.0.0新增,领取时+1)
+used_quantity INT           -- 已使用数量(实际使用时+1)
+user_claim_limit INT        -- 每个用户可领取数量限制(v1.0.0新增,NULL表示不限制)
+
+-- 字段关系
+-- claimed_quantity >= used_quantity (已领取 >= 已使用)
+-- claimed_quantity <= total_quantity (已领取 <= 总量)
+```
+
 ### 新增表结构
 - `price_voucher_batch_config`: 券码批次配置表
 - `price_voucher_code`: 券码表
@@ -562,6 +621,10 @@ public class PriceCalculationResult {
 
 ### 索引优化（示例）
 ```sql
+-- 优惠券领取记录查询优化 (v1.0.0新增)
+CREATE INDEX idx_user_coupon ON price_coupon_claim_record(user_id, coupon_id);
+CREATE INDEX idx_coupon_status ON price_coupon_claim_record(coupon_id, status);
+
 -- 券码查询优化
 CREATE INDEX idx_voucher_code ON price_voucher_code(code);
 CREATE INDEX idx_face_scenic ON price_voucher_code(face_id, scenic_id);
@@ -579,10 +642,37 @@ CREATE INDEX idx_print_face_scenic ON voucher_print_record(face_id, scenic_id);
 - 券码表可能数据量较大，考虑按景区维度分表或归档
 - 定期清理已删除的过期数据
 - 使用数据完整性检查 SQL 验证统计数据准确性
+- **优惠券领取记录表查询优化** (v1.0.0): 为 `(user_id, coupon_id)` 添加复合索引以加速用户领取次数统计
 
 ## 兼容性与注意事项
 
 - 本模块使用 PageHelper（优惠券相关）与 MyBatis‑Plus（券码/一口价等）并存，请根据对应 Service/Mapper 选择分页与查询方式。
 - 优惠优先级及叠加规则以各 Provider 与业务配置为准，避免在外层重复实现优先级判断逻辑。
 - 若扩展新的优惠类型，务必实现 `IDiscountProvider` 并在 `IDiscountDetectionService` 中完成注册（当前实现通过组件扫描自动注册并排序）。
+- **优惠券数量管理** (v1.0.0): 现有代码已调整为领取时更新 `claimedQuantity`,使用时更新 `usedQuantity`。如业务需求不同,请调整 `CouponServiceImpl.claimCoupon()` 和 `CouponServiceImpl.useCoupon()` 逻辑。
+
+## 版本更新记录
+
+### v1.0.0 (2025-11-16)
+**优惠券用户领取数量限制功能**
+
+新增特性:
+- ✅ 支持为每个优惠券配置用户领取数量限制 (`userClaimLimit`)
+- ✅ 区分已领取数量 (`claimedQuantity`) 和已使用数量 (`usedQuantity`)
+- ✅ 新增错误码 `CLAIM_LIMIT_REACHED` 处理超限场景
+- ✅ 新增统计方法 `PriceCouponClaimRecordMapper.countUserCouponClaims()`
+
+数据库变更:
+- 表 `price_coupon_config` 新增字段 `user_claim_limit INT`
+- 表 `price_coupon_config` 新增字段 `claimed_quantity INT`
+- 建议索引 `idx_user_coupon ON price_coupon_claim_record(user_id, coupon_id)`
+
+受影响文件:
+- `entity/PriceCouponConfig.java`
+- `mapper/PriceCouponClaimRecordMapper.java`
+- `service/impl/CouponServiceImpl.java`
+- `dto/CouponClaimResult.java`
+- `dto/CouponInfo.java`
+
+迁移指南: 详见 `docs/coupon-user-claim-limit-guide.md`
 

src/main/java/com/ycwl/basic/pricing/dto/CouponClaimResult.java

@@ -98,6 +98,7 @@ public class CouponClaimResult {
     public static final String ERROR_COUPON_INACTIVE = "COUPON_INACTIVE";
     public static final String ERROR_COUPON_OUT_OF_STOCK = "COUPON_OUT_OF_STOCK";
     public static final String ERROR_ALREADY_CLAIMED = "ALREADY_CLAIMED";
+    public static final String ERROR_CLAIM_LIMIT_REACHED = "CLAIM_LIMIT_REACHED";
     public static final String ERROR_INVALID_PARAMS = "INVALID_PARAMS";
     public static final String ERROR_SYSTEM_ERROR = "SYSTEM_ERROR";
 }

src/main/java/com/ycwl/basic/pricing/dto/CouponInfo.java

@@ -35,4 +35,9 @@ public class CouponInfo {
      * 实际优惠金额
      */
     private BigDecimal actualDiscountAmount;
+
+    /**
+     * 每个用户可领取数量限制(NULL表示不限制)
+     */
+    private Integer userClaimLimit;
 }

src/main/java/com/ycwl/basic/pricing/entity/PriceCouponConfig.java

@@ -61,6 +61,16 @@ public class PriceCouponConfig {
      */
     private Integer usedQuantity;
 
+    /**
+     * 已领取数量(区分于已使用数量)
+     */
+    private Integer claimedQuantity;
+
+    /**
+     * 每个用户可领取数量限制(NULL表示不限制)
+     */
+    private Integer userClaimLimit;
+
     /**
      * 生效时间
      */

src/main/java/com/ycwl/basic/pricing/mapper/PriceCouponClaimRecordMapper.java

@@ -36,6 +36,13 @@ public interface PriceCouponClaimRecordMapper extends BaseMapper<PriceCouponClai
     PriceCouponClaimRecord selectUserCouponRecord(@Param("userId") Long userId,
                                                   @Param("couponId") Long couponId);
 
+    /**
+     * 统计用户领取某优惠券的次数（所有状态）
+     */
+    @Select("SELECT COUNT(*) FROM price_coupon_claim_record " +
+            "WHERE user_id = #{userId} AND coupon_id = #{couponId} AND deleted = 0")
+    int countUserCouponClaims(@Param("userId") Long userId, @Param("couponId") Long couponId);
+
     /**
      * 更新优惠券使用状态
      */

src/main/java/com/ycwl/basic/pricing/service/impl/CouponServiceImpl.java

@@ -194,6 +194,7 @@ public class CouponServiceImpl implements ICouponService {
         info.setDiscountType(coupon.getCouponType());
         info.setDiscountValue(coupon.getDiscountValue());
         info.setActualDiscountAmount(actualDiscountAmount);
+        info.setUserClaimLimit(coupon.getUserClaimLimit());
         return info;
     }
     
@@ -230,20 +231,31 @@ public class CouponServiceImpl implements ICouponService {
             }
             
             // 5. 检查库存（如果有总量限制）
-            if (coupon.getTotalQuantity() != null && coupon.getUsedQuantity() != null) {
+            if (coupon.getTotalQuantity() != null && coupon.getClaimedQuantity() != null) {
-                if (coupon.getUsedQuantity() >= coupon.getTotalQuantity()) {
+                if (coupon.getClaimedQuantity() >= coupon.getTotalQuantity()) {
                     return CouponClaimResult.failure(CouponClaimResult.ERROR_COUPON_OUT_OF_STOCK, "优惠券已领完");
                 }
             }
 
-            // 6. 检查用户是否已经领取过该优惠券
+            // 6. 检查用户领取数量限制
+            if (coupon.getUserClaimLimit() != null && coupon.getUserClaimLimit() > 0) {
+                int userClaimCount = couponClaimRecordMapper.countUserCouponClaims(
+                        request.getUserId(), request.getCouponId());
+                if (userClaimCount >= coupon.getUserClaimLimit()) {
+                    return CouponClaimResult.failure(
+                            CouponClaimResult.ERROR_CLAIM_LIMIT_REACHED,
+                            "您已达到该优惠券的领取上限(" + coupon.getUserClaimLimit() + "张)");
+                }
+            }
+
+            // 7. 检查用户是否已经领取过该优惠券（兼容旧逻辑，双重保护）
             PriceCouponClaimRecord existingRecord = couponClaimRecordMapper.selectUserCouponRecord(
                     request.getUserId(), request.getCouponId());
             if (existingRecord != null) {
                 return CouponClaimResult.failure(CouponClaimResult.ERROR_ALREADY_CLAIMED, "您已经领取过该优惠券");
             }
 
-            // 7. 创建领取记录
+            // 8. 创建领取记录
             Date claimTime = new Date();
             PriceCouponClaimRecord claimRecord = new PriceCouponClaimRecord();
             claimRecord.setCouponId(request.getCouponId());
@@ -255,7 +267,7 @@ public class CouponServiceImpl implements ICouponService {
             claimRecord.setUpdateTime(claimTime);
             claimRecord.setDeleted(0);
 
-            // 8. 插入领取记录
+            // 9. 插入领取记录
             int insertResult = couponClaimRecordMapper.insert(claimRecord);
             if (insertResult <= 0) {
                 log.error("插入优惠券领取记录失败: userId={}, couponId={}",
@@ -263,17 +275,17 @@ public class CouponServiceImpl implements ICouponService {
                 return CouponClaimResult.failure(CouponClaimResult.ERROR_SYSTEM_ERROR, "领取失败，请稍后重试");
             }
 
-            // 9. 更新优惠券已使用数量（如果有总量限制）
+            // 10. 更新优惠券已领取数量（区分于已使用数量）
             if (coupon.getTotalQuantity() != null) {
-                int updatedUsedQuantity = (coupon.getUsedQuantity() == null ? 0 : coupon.getUsedQuantity()) + 1;
+                int updatedClaimedQuantity = (coupon.getClaimedQuantity() == null ? 0 : coupon.getClaimedQuantity()) + 1;
-                coupon.setUsedQuantity(updatedUsedQuantity);
+                coupon.setClaimedQuantity(updatedClaimedQuantity);
                 couponConfigMapper.updateById(coupon);
             }
 
             log.info("优惠券领取成功: userId={}, couponId={}, claimRecordId={}",
                     request.getUserId(), request.getCouponId(), claimRecord.getId());
 
-            // 10. 返回成功结果
+            // 11. 返回成功结果
             return CouponClaimResult.success(claimRecord, coupon);
             
         } catch (Exception e) {