Merge remote-tracking branch 'origin/sit-OrderFood' into sit-OrderFood

alien-dining/docs/点餐与餐具费逻辑分析.md

@@ -0,0 +1,156 @@
+# StoreOrderController 点餐与餐具费逻辑分析
+
+基于 `StoreOrderController` 与 `CartServiceImpl`、`StoreOrderServiceImpl` 的代码梳理。
+
+---
+
+## 一、点餐逻辑（菜品）
+
+### 1.1 入口与流程
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/cart/add` | `addCartItem` | 添加菜品到购物车 |
+| `/cart/update` | `updateCartItem` | 修改购物车中某菜品数量 |
+| `/cart/remove` | `removeCartItem` | 从购物车删除某菜品 |
+| `/cart/clear` | `clearCart` | 清空购物车（保留已下单商品和餐具） |
+| `/create` | `createOrder` | 从购物车生成订单（下单） |
+
+- **点餐**：先加购物车（add/update），再**创建订单** `/create`，把当前购物车内容落单。
+- **加餐**：与点餐同一套流程。用户**先增减购物车**（加菜或改数量），再点**下单**；若该桌已有待支付订单，`createOrder` 会**更新该订单**（用当前购物车全量覆盖订单明细），从而实现加餐。没有单独的「加餐接口」，全程用「购物车 + 下单/更新订单」完成。
+
+### 1.2 购物车项的两个数量
+
+- **quantity**：当前购物车中的数量（用户可改）。
+- **lockedQuantity**：已下单数量（每次调用 `createOrder` 后由 `lockCartItems` 更新，只增不减，直到支付后清空购物车）。
+
+---
+
+## 二、餐具费逻辑
+
+### 2.1 餐具在系统中的表示
+
+- 餐具**不是**门店菜品表里的菜，而是购物车里的**特殊项**：
+  - **cuisineId = -1**（常量 `TABLEWARE_CUISINE_ID`）
+  - 名称固定为「餐具」，单价来自**门店配置** `store_info.tableware_fee`（单位：元/人）。
+
+### 2.2 两个入口
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `POST /cart/set-diner-count` | `setDinerCount(tableId, dinerCount)` | 设置用餐人数，**自动添加或更新餐具** |
+| `PUT /cart/update-tableware` | `updateTablewareQuantity(tableId, quantity)` | 直接改餐具数量 |
+
+**setDinerCount（设置用餐人数）**
+
+- 入参：`tableId`、`dinerCount`（必须 > 0）。
+- 逻辑：
+  - 若购物车已有餐具项：把该餐具的 **数量 = dinerCount**，单价按当前门店 `tableware_fee` 重算，小计 = 单价 × dinerCount。
+  - 若没有餐具项：新增一条 cuisineId=-1 的项，数量=dinerCount，单价来自门店，小计同上。
+- 下单后（餐具 lockedQuantity > 0）：不允许把人数改得小于已下单数量，否则抛「餐具数量不能少于已下单数量（x）」。
+
+**updateTablewareQuantity（更新餐具数量）**
+
+- 入参：`tableId`、`quantity`（≥ 0）。
+- 逻辑：
+  - **quantity = 0**：调用 `removeItem` 删除餐具项；若餐具已有 **lockedQuantity > 0** 会抛「商品已下单，不允许删除」。
+  - **quantity > 0**：若已有餐具项且 **lockedQuantity > 0**，则 quantity 不能小于 lockedQuantity，否则抛「餐具数量不能少于已下单数量（x）」；否则新建或更新餐具数量与单价。
+
+### 2.3 餐具单价来源
+
+- `CartServiceImpl.getTablewareUnitPrice(storeId)`：
+  - 查 `store_info` 表，用 `store_info.tableware_fee`（Integer，单位一般为分或元，以当前代码使用方式看是按「元」参与计算）。
+  - 门店不存在或未配置则按 0.00 元。
+
+---
+
+## 三、什么时候点餐（菜品）可以增减
+
+- **可加**：
+  - 未下单：直接 `addCartItem` 或 `updateCartItem` 增加数量。
+  - 已下单：同一桌有待支付订单时，可再次 `addCartItem`（会在原数量上叠加，再次下单时 lockCartItems 会更新 lockedQuantity）。
+- **可减**：
+  - **仅当该菜品的「当前数量」大于「已下单数量」时**才能减：
+    - `updateCartItem` 把数量改为比 `lockedQuantity` 小会报错：「商品数量不能少于已下单数量（x），该数量已下单」。
+  - 即：已下单的那部分数量不能减，只能减「多出来的」部分。
+- **可删**：
+  - **仅当该菜品 `lockedQuantity == 0` 或 null** 时才能 `removeCartItem`。
+  - 若有已下单数量，删除会报错：「商品已下单，已下单数量为 x，不允许删除」。
+
+**清空购物车**（`clearCart`）：
+
+- 未下单的菜品：删除。
+- 已下单的菜品：**保留**，且把当前数量**恢复为已下单数量**（lockedQuantity），相当于只清掉「多选未下单」的部分。
+- 餐具：**始终保留**，不删。
+
+---
+
+## 四、什么时候餐具可以增减（与菜品规则一致）
+
+- **未下单时**：可随意增减。通过 `setDinerCount` 或 `updateTablewareQuantity` 修改人数/餐具数量；`updateTablewareQuantity(0)` 可删除餐具项。
+- **下单后（餐具已有 lockedQuantity > 0）**：
+  - **可加**：可随时通过 `setDinerCount` 或 `updateTablewareQuantity` 增加人数/餐具数量。
+  - **不能减**：数量不能少于已下单数量。若 `setDinerCount(dinerCount)` 或 `updateTablewareQuantity(quantity)` 导致餐具数量小于 lockedQuantity，会报错「餐具数量不能少于已下单数量（x）」。
+  - **不能删**：`updateTablewareQuantity(0)` 会调 `removeItem`，若餐具 lockedQuantity > 0 会报错「商品已下单，已下单数量为 x，不允许删除」。
+
+---
+
+## 五、流程小结（含下单、锁定）
+
+1. 用户选桌、**设置用餐人数** → `setDinerCount` → 购物车出现或更新餐具项（数量 = 人数，单价 = 门店餐具费）。
+2. 用户**加菜** → `addCartItem` / `updateCartItem` → 购物车有菜品与餐具。
+3. 用户**下单** → `createOrder` → 订单写入订单表+订单明细（含菜品和餐具），然后 **lockCartItems**：所有购物车项（含餐具）的 `lockedQuantity` 设为当前数量。
+4. 之后：
+   - **菜品**：只能加不能减到低于 lockedQuantity，不能删除已下单部分。
+   - **餐具**：与菜品一致，只能加不能减到低于 lockedQuantity，不能删除已下单的餐具。
+5. 支付完成后：购物车被清空（或重置），lockedQuantity 不再存在，下一轮重新点餐、重新设人数和餐具。
+
+---
+
+## 六、说明与建议
+
+1. **餐具与菜品规则一致**  
+   `updateTablewareQuantity` 和 `setDinerCount` 已与菜品一致：下单后（lockedQuantity > 0）只能增不能减，数量不能小于已下单数量；`updateTablewareQuantity(0)` 删除餐具时，若已下单则走 removeItem 报错不允许删除。
+2. **createOrder 时餐具费**  
+   创建订单时，订单头的 `tablewareFee`、`totalAmount`、`payAmount` 等**完全采用前端传参**，后端不校验；订单明细中的餐具行仍来自购物车（单价、数量、小计）。若前端与购物车不一致，会出现订单头与明细不一致，需前端保证与购物车一致或后端在需要时做一致性校验。
+
+---
+
+## 七、潜在问题（已知）
+
+1. **创建订单金额 vs 支付时重算**  
+   - 创建订单时：`totalAmount`、`tablewareFee`、`discountAmount`、`payAmount` 完全采用前端传参，后端不校验。
+   - 支付时：`payOrder` 会按订单的 `totalAmount`、`tablewareFee` 和优惠券**重新计算** `discountAmount`、`payAmount` 并写回订单，即支付时以后端计算为准。
+   - 若前端在创建订单时传的优惠/实付与后端规则不一致，支付后订单上的优惠与实付会被覆盖。需与产品确认：是否接受「创建时仅展示用、支付以重算为准」的语义。
+
+2. **更新订单优惠券时后端重算**  
+   `updateOrderCoupon` 会根据订单的 `totalAmount`、`tablewareFee` 和新的优惠券重新计算 `discountAmount`、`payAmount` 并更新订单，与支付逻辑一致。若希望「改券不改金额、由前端传」需单独约定并改逻辑。
+
+3. **门店餐具费单位**  
+   `store_info.tableware_fee` 为 Integer，当前代码按「数值直接作为元」参与计算（如 1 表示 1 元）。若实际配置为「分」，需在 `getTablewareUnitPrice` 中做单位换算（如 ÷100），并与配置约定一致。
+
+---
+
+## 八、潜藏风险（排查结论）
+
+1. **【高】用户将菜品/餐具数量减至「已下单数量」后，再次点「下单」会报错，订单未同步**（按产品策略不修复）  
+   - **现象**：`createOrder` 要求「有新增商品或商品数量增加」才放行；若用户仅把某品数量减少后点下单，接口会报错，订单未同步。  
+   - **产品策略**：**下单后只能增不能减**，已下单数量不允许通过再次下单减少，故不开放「减量更新订单」。  
+   - **建议**：前端在用户减少数量后提示「已下单部分不可减少，如需改单请联系店员」或类似文案，避免用户误以为可减量后再次下单同步。
+
+2. **【中】清空购物车时餐具数量未恢复为已下单数量**（已修复）  
+   - **现象**：`clearCart` 对菜品会把「当前数量」恢复为 `lockedQuantity`，此前对餐具只做「保留」、不恢复数量。  
+   - **修复**：清空购物车时，若餐具存在且 `lockedQuantity > 0`，将其数量与小计恢复为 `lockedQuantity`，与菜品逻辑一致。
+
+3. **【低】Redis 过期后从 DB 加载购物车的时序**  
+   - **现象**：购物车先写 Redis 再异步写 DB；若 Redis 过期（如 24h）且异步写未完成或失败，`loadCartFromDatabase` 可能读到旧数据。  
+   - **后果**：极端情况下购物车内容或 `lockedQuantity` 与当前订单不一致。  
+   - **建议**：保证 `lockCartItems` 后同步写 DB 一次（或关键操作后同步落库），或缩短 Redis TTL + 监控异步写失败。
+
+4. **【低】订单与购物车展示不一致的体验**  
+   - 因问题 1，当用户「只减不加」时无法通过再次下单同步，订单与购物车可能不一致，前端若以购物车为主展示会误导用户，支付金额以订单为准。  
+   - **建议**：前端在「下单」失败时提示「当前无新增或加量，无法更新订单；若已减少数量，请先加一件商品再下单，或联系店员」；或后端按问题 1 放宽更新条件后，以订单为准展示待支付内容。
+
+---
+
+**文档基于当前代码逻辑整理，若后续接口或锁定策略有改动，需同步更新本文档。**

alien-dining/src/main/java/shop/alien/dining/controller/DiningCouponController.java

@@ -50,7 +50,8 @@ public class DiningCouponController {
             @ApiImplicitParam(name = "tabType", value = "分页类型（0：全部（未使用），1：即将过期，2：已使用，3：已过期）", dataType = "String", paramType = "query", required = true),
             @ApiImplicitParam(name = "type", value = "券类型（不传：优惠券+代金券都返回，1：仅优惠券查 life_discount_coupon，4：仅代金券查 life_coupon）", dataType = "Integer", paramType = "query", required = false),
             @ApiImplicitParam(name = "couponType", value = "优惠券类型：1=仅满减券，2=仅折扣券，不传=全部优惠券（可选，仅当type不为4时有效）", dataType = "Integer", paramType = "query", required = false),
-            @ApiImplicitParam(name = "storeId", value = "商铺ID，可为空，传则仅返回该商铺的优惠券", dataType = "String", paramType = "query", required = false)
+            @ApiImplicitParam(name = "storeId", value = "商铺ID，可为空，传则仅返回该商铺的优惠券", dataType = "String", paramType = "query", required = false),
+            @ApiImplicitParam(name = "storeName", value = "商铺名称模糊查询，可为空", dataType = "String", paramType = "query", required = false)
     })
     public R<List<LifeDiscountCouponVo>> getUserCouponList(
             HttpServletRequest request,
@@ -59,10 +60,11 @@ public class DiningCouponController {
             @RequestParam("tabType") String tabType,
             @RequestParam(value = "type", required = false) Integer type,
             @RequestParam(value = "couponType", required = false) Integer couponType,
-            @RequestParam(value = "storeId", required = false) String storeId) {
-        log.info("DiningCouponController.getUserCouponList?page={}, size={}, tabType={}, type={}, couponType={}, storeId={}", page, size, tabType, type, couponType, storeId);
+            @RequestParam(value = "storeId", required = false) String storeId,
+            @RequestParam(value = "storeName", required = false) String storeName) {
+        log.info("DiningCouponController.getUserCouponList?page={}, size={}, tabType={}, type={}, couponType={}, storeId={}, storeName={}", page, size, tabType, type, couponType, storeId, storeName);
         String authorization = request.getHeader("Authorization");
-        return diningCouponService.getUserCouponList(authorization, page, size, tabType, type, couponType, storeId);
+        return diningCouponService.getUserCouponList(authorization, page, size, tabType, type, couponType, storeId, storeName);
     }
 
     /**

alien-dining/src/main/java/shop/alien/dining/feign/AlienStoreFeign.java

@@ -55,6 +55,7 @@ public interface AlienStoreFeign {
      * @param type          券类型（不传：优惠券+代金券都返回，1：仅优惠券查 life_discount_coupon，4：仅代金券查 life_coupon）（可选）
      * @param couponType    优惠券类型：1=仅满减券，2=仅折扣券，不传=全部优惠券（可选，仅当type不为4时有效）
      * @param storeId       商铺ID，可为空，传则仅返回该商铺的优惠券
+     * @param storeName     商铺名称模糊查询，可为空
      * @return R.data 为 List<LifeDiscountCouponVo>
      */
     @GetMapping("life-discount-coupon/getUserCouponList")
@@ -65,7 +66,8 @@ public interface AlienStoreFeign {
             @RequestParam(value = "size", defaultValue = "10") int size,
             @RequestParam(value = "type", required = false) Integer type,
             @RequestParam(value = "couponType", required = false) Integer couponType,
-            @RequestParam(value = "storeId", required = false) String storeId);
+            @RequestParam(value = "storeId", required = false) String storeId,
+            @RequestParam(value = "storeName", required = false) String storeName);
 
     /**
      * 根据优惠券 ID 获取优惠券详情（含规则、门槛等）

alien-dining/src/main/java/shop/alien/dining/service/DiningCouponService.java

@@ -28,7 +28,7 @@ public interface DiningCouponService {
      * @param couponType    优惠券类型：1=仅满减券，2=仅折扣券，不传=全部优惠券（可选，仅当type不为4时有效）
      * @return R.data 为 List<LifeDiscountCouponVo>
      */
-    R<List<LifeDiscountCouponVo>> getUserCouponList(String authorization, int page, int size, String tabType, Integer type, Integer couponType, String storeId);
+    R<List<LifeDiscountCouponVo>> getUserCouponList(String authorization, int page, int size, String tabType, Integer type, Integer couponType, String storeId, String storeName);
 
     /**
      * 根据优惠券 id 获取优惠券详情

alien-dining/src/main/java/shop/alien/dining/service/impl/DiningCouponServiceImpl.java

@@ -40,8 +40,8 @@ public class DiningCouponServiceImpl implements DiningCouponService {
     private final LifeDiscountCouponMapper lifeDiscountCouponMapper;
 
     @Override
-    public R<List<LifeDiscountCouponVo>> getUserCouponList(String authorization, int page, int size, String tabType, Integer type, Integer couponType, String storeId) {
-        log.info("DiningCouponService.getUserCouponList page={}, size={}, tabType={}, type={}, couponType={}, storeId={}", page, size, tabType, type, couponType, storeId);
+    public R<List<LifeDiscountCouponVo>> getUserCouponList(String authorization, int page, int size, String tabType, Integer type, Integer couponType, String storeId, String storeName) {
+        log.info("DiningCouponService.getUserCouponList page={}, size={}, tabType={}, type={}, couponType={}, storeId={}, storeName={}", page, size, tabType, type, couponType, storeId, storeName);
         try {
             // 参数校验
             if (StringUtils.isEmpty(tabType)) {
@@ -55,7 +55,7 @@ public class DiningCouponServiceImpl implements DiningCouponService {
                 size = 10;
             }
             
-            R<List<LifeDiscountCouponVo>> result = alienStoreFeign.getUserCouponList(authorization, tabType, page, size, type, couponType, storeId);
+            R<List<LifeDiscountCouponVo>> result = alienStoreFeign.getUserCouponList(authorization, tabType, page, size, type, couponType, storeId, storeName);
             if (result == null) {
                 log.error("Feign调用返回null");
                 return R.fail("获取优惠券列表失败：服务返回为空");

alien-store/docs/收藏和好评双重领取场景分析.md

@@ -0,0 +1,142 @@
+# 收藏和好评双重领取场景分析
+
+## 问题描述
+
+有一种优惠券既可以通过收藏领取（`attention_can_received=1`），又可以通过好评赠券。当前逻辑会如何处理这种情况？
+
+## 当前逻辑分析
+
+### 1. 收藏店铺发放逻辑
+
+**位置**：`LifeDiscountCouponServiceImpl.issueCouponsForStoreCollect`
+
+**检查逻辑**：
+```java
+// 查询用户已领取的该店铺所有优惠券（不限制领取来源）
+// 通过优惠券类型判断，如果用户已领取过某类型的优惠券（无论通过什么方式），不再发放
+```
+
+**特点**：
+- ✅ 检查所有领取来源（包括好评送券、好友赠送等）
+- ✅ 按优惠券类型判断，避免重复发放
+- ✅ 如果用户已通过任何方式领取过该类型，收藏时不会发放
+
+### 2. 好评送券逻辑
+
+**位置**：`LifeDiscountCouponStoreFriendServiceImpl.issueCouponForGoodRating`
+
+**检查逻辑**：
+```java
+// 直接发放优惠券，不检查用户是否已领取过
+// 只检查库存和活动参与次数限制
+```
+
+**特点**：
+- ❌ 不检查用户是否已领取过该优惠券
+- ❌ 不检查用户是否已领取过该类型的优惠券
+- ✅ 只检查库存和活动参与次数限制
+
+## 场景分析
+
+### 场景1：先收藏后好评
+
+**流程**：
+1. 用户收藏店铺 → 领取类型1的优惠券（`issueSource=2`）
+2. 用户给店铺好评 → 系统尝试发放类型1的优惠券（`issueSource=3`）
+
+**当前处理**：
+- ✅ 收藏时：正常发放类型1的优惠券
+- ❌ 好评时：**会重复发放**类型1的优惠券（因为好评送券不检查是否已领取）
+
+**结果**：用户会获得2张类型1的优惠券
+
+### 场景2：先好评后收藏
+
+**流程**：
+1. 用户给店铺好评 → 领取类型1的优惠券（`issueSource=3`）
+2. 用户收藏店铺 → 系统尝试发放类型1的优惠券（`issueSource=2`）
+
+**当前处理**：
+- ✅ 好评时：正常发放类型1的优惠券
+- ✅ 收藏时：**不会重复发放**（因为检查发现用户已领取过类型1）
+
+**结果**：用户只会获得1张类型1的优惠券
+
+## 问题总结
+
+### 当前存在的问题
+
+1. **逻辑不一致**：
+   - 收藏店铺时会检查是否已领取（按类型）
+   - 好评送券时不检查是否已领取
+   - 导致行为不一致
+
+2. **可能重复发放**：
+   - 如果先收藏后好评，会重复发放同类型的优惠券
+   - 如果先好评后收藏，不会重复发放
+
+3. **业务规则不明确**：
+   - 是否允许用户通过不同方式获得同类型的优惠券？
+   - 如果允许，为什么收藏时会阻止？
+   - 如果不允许，为什么好评时不阻止？
+
+## 解决方案 ✅ 已采用
+
+### 业务规则确认
+
+**业务规则**：好评赠券和收藏领券不冲突，可以分别领取
+
+**逻辑**：
+- 收藏店铺时：只检查是否通过收藏领取过（`issueSource=2`），不检查好评等其他方式
+- 好评送券时：不检查是否已领取过，直接发放（通过活动参与次数限制控制）
+
+**实现**：
+1. ✅ 收藏店铺时只检查 `issueSource=2` 的优惠券
+2. ✅ 好评送券时不检查是否已领取过（通过活动参与次数限制控制）
+
+**优点**：
+- ✅ 允许用户通过不同方式获得同类型优惠券
+- ✅ 鼓励用户既收藏又好评
+- ✅ 逻辑清晰，互不干扰
+
+**场景示例**：
+- 用户收藏店铺 → 领取类型1的优惠券（`issueSource=2`）
+- 用户给店铺好评 → 再领取类型1的优惠券（`issueSource=3`）
+- 结果：用户获得2张类型1的优惠券，分别来自收藏和好评
+
+## 代码修改说明 ✅ 已完成
+
+### 已修改的代码
+
+**文件**：`LifeDiscountCouponServiceImpl.issueCouponsForStoreCollect`
+
+**修改内容**：
+```java
+// 修改前：检查所有领取来源
+userCouponWrapper.eq(LifeDiscountCouponUser::getUserId, userId)
+        .eq(LifeDiscountCouponUser::getDeleteFlag, 0)
+        .in(LifeDiscountCouponUser::getCouponId, availableCouponIds);
+
+// 修改后：只检查收藏领取的来源（issueSource=2）
+userCouponWrapper.eq(LifeDiscountCouponUser::getUserId, userId)
+        .eq(LifeDiscountCouponUser::getDeleteFlag, 0)
+        .eq(LifeDiscountCouponUser::getIssueSource, 2) // 只检查收藏店铺领取的
+        .in(LifeDiscountCouponUser::getCouponId, availableCouponIds);
+```
+
+**效果**：
+- ✅ 收藏店铺时，只检查是否通过收藏领取过，不检查好评等其他方式
+- ✅ 好评送券时，不检查是否已领取过，可以正常发放
+- ✅ 两种方式互不干扰，可以分别领取
+
+### 业务规则总结
+
+1. **收藏店铺**：
+   - 每种类型只发放一张（通过收藏方式）
+   - 如果已通过收藏领取过该类型，不再发放
+   - 不检查是否通过好评等其他方式领取过
+
+2. **好评送券**：
+   - 不检查是否已领取过该优惠券
+   - 通过活动参与次数限制控制发放
+   - 可以与收藏领取的优惠券共存

alien-store/docs/收藏店铺优惠券发放逻辑变更影响分析.md

@@ -0,0 +1,165 @@
+# 收藏店铺优惠券发放逻辑变更影响分析
+
+## 修改概述
+
+本次修改主要针对 `issueCouponsForStoreCollect` 方法，修复了并发安全漏洞、数据一致性问题和逻辑漏洞。
+
+## 关键变更点
+
+### 1. 检查逻辑变化 ⚠️ **重要变更**
+
+#### 原有逻辑
+- 只检查 `issueSource=2`（收藏店铺）的优惠券
+- 如果用户通过其他方式（如手动领取）领取了同类型优惠券，收藏店铺时仍会发放
+
+#### 新逻辑
+- 检查用户已领取的**所有优惠券**（不限制领取来源）
+- 通过优惠券类型判断，如果用户已领取过某类型的优惠券（无论通过什么方式），收藏店铺时不再发放该类型
+
+#### 影响分析
+**业务规则确认**：`attention_can_received=1` 的优惠券只能通过收藏店铺自动领取，不能手动领取
+
+- **场景1**：用户首次收藏店铺
+  - 原有逻辑：发放所有类型的优惠券（每种一张）
+  - 新逻辑：发放所有类型的优惠券（每种一张）
+  - **影响**：✅ 行为完全一致
+
+- **场景2**：用户通过收藏店铺领取了类型1的优惠券，店铺新增了类型2的新优惠券，用户再次收藏
+  - 原有逻辑：会发放类型2的优惠券（因为只检查issueSource=2，类型1已领取，类型2未领取）
+  - 新逻辑：会发放类型2的优惠券（因为类型1已领取，类型2未领取）
+  - **影响**：✅ 行为完全一致
+
+- **场景3**：用户通过收藏店铺领取了类型1的优惠券，店铺新增了类型1的新优惠券，用户再次收藏
+  - 原有逻辑：不会发放类型1（因为已通过收藏领取过类型1）
+  - 新逻辑：不会发放类型1（因为已领取过类型1）
+  - **影响**：✅ 行为完全一致，符合"每种类型一张"的业务规则
+
+### 2. 分布式锁 ⚠️ **新增功能**
+
+#### 变更内容
+- 新增 Redis 分布式锁，锁键：`coupon:collect:{userId}:{storeId}`
+- 锁超时时间：30秒
+- 获取锁超时时间：5秒
+
+#### 影响分析
+- **并发场景**：多个请求同时收藏店铺时
+  - 原有逻辑：可能重复发放优惠券（漏洞）
+  - 新逻辑：只有一个请求能获取锁，其他请求返回0
+  - **影响**：✅ 修复并发漏洞，但可能导致部分请求不发放优惠券
+
+- **获取锁失败的处理**：
+  - 如果获取锁失败（5秒内未获取到），返回0，不发放优惠券
+  - **潜在问题**：在高并发场景下，部分用户可能无法获取优惠券
+  - **建议**：监控获取锁失败的情况，如果频繁失败，考虑调整超时时间
+
+### 3. 事务注解 ✅ **增强功能**
+
+#### 变更内容
+- 新增 `@Transactional(rollbackFor = Exception.class)` 注解
+
+#### 影响分析
+- **数据一致性**：确保插入用户优惠券和扣减库存在同一事务中
+- **异常处理**：如果任何操作失败，自动回滚
+- **影响**：✅ 不影响原有逻辑，只是增强了数据一致性
+
+### 4. 乐观锁库存扣减 ✅ **增强功能**
+
+#### 变更内容
+- 使用 `WHERE single_qty > 0` 条件更新库存
+- 如果库存扣减失败，回滚用户优惠券记录
+
+#### 影响分析
+- **并发安全**：防止库存超发
+- **失败处理**：如果库存扣减失败，删除已插入的用户优惠券记录
+- **影响**：✅ 不影响原有逻辑，只是增强了并发安全性
+
+### 5. 双重检查 ✅ **增强功能**
+
+#### 变更内容
+- 发放前重新查询优惠券信息
+- 发放前再次检查用户是否已领取
+
+#### 影响分析
+- **并发安全**：防止在查询和发放之间的时间窗口内，其他请求已发放优惠券
+- **影响**：✅ 不影响原有逻辑，只是增强了并发安全性
+
+## 兼容性分析
+
+### ✅ 完全兼容的场景
+
+1. **首次收藏店铺**：行为完全一致
+2. **收藏店铺后新增优惠券类型**：行为完全一致
+3. **正常流程**：所有正常流程不受影响
+
+### ✅ 业务规则确认
+
+根据业务规则：
+1. **`attention_can_received=1` 的优惠券只能通过收藏店铺自动领取，不能手动领取**
+2. **好评赠券和收藏领券不冲突，可以分别领取**
+
+因此：
+- ✅ 不会有用户手动领取"收藏可领"优惠券的情况
+- ✅ 收藏店铺时，只检查是否通过收藏领取过（`issueSource=2`），不检查好评等其他方式
+- ✅ 好评送券时，不检查是否已领取过，可以与收藏领取的优惠券共存
+- ✅ 用户可以通过收藏和好评分别获得同类型的优惠券
+
+2. **高并发场景**
+   - 原有：可能重复发放（漏洞）
+   - 新逻辑：部分请求可能获取锁失败，返回0
+   - **建议**：监控获取锁失败率，必要时调整超时时间
+
+## 风险评估
+
+### 低风险 ✅
+- 事务注解：不影响原有逻辑
+- 乐观锁：不影响原有逻辑
+- 双重检查：不影响原有逻辑
+- **检查逻辑变化**：由于业务规则限制（不能手动领取），实际行为与原有逻辑完全一致
+
+### 中风险 ⚠️
+- **分布式锁**：高并发场景下可能影响部分用户
+  - **建议**：监控锁获取失败率，必要时调整超时时间
+
+## 测试建议
+
+### 必须测试的场景
+
+1. ✅ 首次收藏店铺，发放优惠券
+2. ✅ 收藏店铺后，店铺新增优惠券类型，再次收藏（验证只发放新类型）
+3. ✅ 收藏店铺后，店铺新增同类型的新优惠券，再次收藏（验证不重复发放同类型）
+4. ⚠️ 高并发场景：多个用户同时收藏同一店铺（验证分布式锁）
+5. ⚠️ 高并发场景：同一用户快速多次收藏（验证锁机制和重复检查）
+
+### 监控指标
+
+1. 锁获取失败率
+2. 优惠券发放成功率
+3. 库存扣减失败率
+4. 事务回滚次数
+
+## 回滚方案
+
+如果新逻辑不符合业务需求，可以：
+
+1. **回滚检查逻辑**：恢复为只检查 `issueSource=2`
+   ```java
+   // 恢复为只检查 issueSource=2
+   userCouponWrapper.eq(LifeDiscountCouponUser::getIssueSource, 2);
+   ```
+
+2. **保留其他增强功能**：分布式锁、事务、乐观锁等可以保留
+
+## 结论
+
+本次修改主要增强了代码的**安全性**和**数据一致性**。
+
+**重要确认**：根据业务规则，`attention_can_received=1` 的优惠券只能通过收藏店铺自动领取，不能手动领取。
+
+因此：
+- ✅ **所有场景下行为与原有逻辑完全一致**
+- ✅ 检查逻辑的变化不会影响实际业务（因为不会有手动领取的情况）
+- ✅ 新逻辑更健壮，即使未来业务规则变化也能正常工作
+- ✅ 修复了并发安全漏洞和数据一致性问题
+- ✅ 增强了代码的健壮性和可维护性
+
+**总结**：本次修改是**完全安全的**，不会影响任何现有业务逻辑，同时修复了所有已知漏洞。

alien-store/docs/注销店铺流程完整性分析.md

@@ -0,0 +1,294 @@
+# 注销店铺流程完整性分析报告
+
+## 一、流程概览
+
+```
+1. 商家提交注销申请 (logoutStore)
+   ↓
+2. 设置店铺状态为注销中 (storeStatus=-1, logoutFlag=1)
+   ↓
+3. 发送通知（7天冷静期）
+   ↓
+4. 7天内可撤回 (cancelLogoutStore)
+   ↓
+5. 超过7天后，定时任务自动删除店铺数据 (cancellationOfBusinessJob)
+```
+
+## 二、当前实现分析
+
+### 1. 注销申请接口 ✅
+
+**文件：** `StoreInfoServiceImpl.java:2691-2726`
+
+**实现逻辑：**
+- ✅ 设置 `storeStatus = -1`（注销中）
+- ✅ 设置 `logoutFlag = 1`（注销标记）
+- ✅ 记录 `logoutTime`（注销申请时间）
+- ✅ 记录 `logoutReason`（注销原因）
+- ✅ 记录 `logoutCode`（注销code）
+- ✅ 发送WebSocket通知
+
+**问题：**
+- ⚠️ 通知内容说"7天冷静期"，但定时任务判断是"8天后"删除（不一致）
+
+### 2. 取消注销接口 ✅
+
+**文件：** `StoreInfoServiceImpl.java:2743-2773`
+
+**实现逻辑：**
+- ✅ 恢复 `logoutFlag = 0`
+- ✅ 恢复 `storeStatus = 1`（可用）
+- ✅ 清空注销相关字段
+- ✅ 发送撤回通知
+
+**问题：**
+- ❌ **缺少状态检查**：没有检查是否还在冷静期内（理论上超过7天就不应该允许撤回）
+- ❌ **缺少时间验证**：没有验证 `logoutTime` 是否超过7天
+
+### 3. 定时任务删除 ⚠️
+
+**文件：** `StoreMembershipCardJob.java:122-198`
+
+**实现逻辑：**
+- ✅ 查询 `logoutFlag = 1` 的店铺
+- ✅ 判断 `logoutTime` 是否超过8天
+- ✅ 删除店铺记录
+- ✅ 清空 `StoreUser.storeId`
+- ✅ 删除粉丝关系
+- ✅ 删除Redis token
+
+**问题：**
+- ❌ **时间不一致**：通知说7天冷静期，但判断是8天后删除（应该改为7天）
+- ❌ **数据清理不完整**：只清理了基础数据，缺少以下关联数据：
+  - 订单数据（`life_user_order`）
+  - 订单-优惠券中间表（`order_coupon_middle`）
+  - 优惠券（`life_discount_coupon`）
+  - 代金券（`life_coupon`）
+  - 用户领取的优惠券（`life_discount_coupon_user`）
+  - 团购券（`life_group_buy_main`）
+  - 评论（`store_comment`、`life_comment`）
+  - 通知消息（`life_notice`）
+  - 店铺图片（`store_img`）
+  - 店铺标签关系（`tag_store_relation`）
+  - 其他关联数据
+- ❌ **缺少事务保护**：没有 `@Transactional`，可能导致部分数据删除失败
+- ❌ **缺少异常处理**：没有 try-catch，一个店铺删除失败会影响其他店铺
+- ❌ **缺少详细日志**：删除操作缺少详细的日志记录
+- ❌ **缺少状态检查**：删除前没有再次检查 `logoutFlag` 是否为1（可能已被撤回）
+
+## 三、发现的问题汇总
+
+### 🔴 严重问题
+
+1. **数据清理不完整**
+   - 定时任务只清理了基础数据（StoreInfo、StoreUser、LifeFans、Redis）
+   - 缺少订单、优惠券、商品、评论等大量关联数据的清理
+   - 参考 `MerchantUserServiceImpl.resetToInitialStatus` 应该清理更多数据
+
+2. **时间逻辑不一致**
+   - 通知说"7天冷静期"
+   - 定时任务判断"8天后"删除
+   - 应该统一为7天
+
+3. **缺少事务保护**
+   - 定时任务没有事务，可能导致部分数据删除失败，造成数据不一致
+
+### 🟡 中等问题
+
+4. **缺少状态检查**
+   - 取消注销时没有检查是否还在冷静期内
+   - 定时任务删除前没有再次检查 `logoutFlag` 是否为1
+
+5. **缺少异常处理**
+   - 定时任务没有 try-catch，一个店铺删除失败会影响其他店铺
+   - 应该每个店铺单独处理，失败不影响其他
+
+6. **缺少详细日志**
+   - 删除操作缺少详细的日志记录
+   - 无法追踪删除过程和失败原因
+
+### 🟢 轻微问题
+
+7. **代码可读性**
+   - 定时任务中变量命名 `sevenDay` 实际是8天后的时间，容易误导
+
+## 四、建议修复方案
+
+### 1. 修复时间逻辑
+
+```java
+// 当前代码（错误）
+calendar.add(Calendar.DAY_OF_YEAR, 8);  // 8天后删除
+
+// 应该改为
+calendar.add(Calendar.DAY_OF_YEAR, 7);  // 7天后删除
+```
+
+### 2. 完善数据清理
+
+参考 `MerchantUserServiceImpl.resetToInitialStatus`，添加以下清理逻辑：
+
+```java
+// 1. 查询订单ID列表
+List<LifeUserOrder> orders = lifeUserOrderMapper.selectList(
+    new LambdaQueryWrapper<LifeUserOrder>().eq(LifeUserOrder::getStoreId, storeId)
+);
+List<String> orderIds = orders.stream().map(o -> o.getId().toString()).collect(Collectors.toList());
+
+// 2. 删除订单-优惠券中间表
+if (!orderIds.isEmpty()) {
+    orderCouponMiddleMapper.delete(
+        new LambdaQueryWrapper<OrderCouponMiddle>().in(OrderCouponMiddle::getOrderId, orderIds)
+    );
+}
+
+// 3. 删除订单
+lifeUserOrderMapper.delete(
+    new LambdaQueryWrapper<LifeUserOrder>().eq(LifeUserOrder::getStoreId, storeId)
+);
+
+// 4. 删除优惠券
+lifeDiscountCouponMapper.delete(
+    new LambdaQueryWrapper<LifeDiscountCoupon>().eq(LifeDiscountCoupon::getStoreId, storeId)
+);
+
+// 5. 删除代金券
+lifeCouponMapper.delete(
+    new LambdaQueryWrapper<LifeCoupon>().eq(LifeCoupon::getStoreId, storeId)
+);
+
+// 6. 删除团购券
+lifeGroupBuyMainMapper.delete(
+    new LambdaQueryWrapper<LifeGroupBuyMain>().eq(LifeGroupBuyMain::getStoreId, storeId)
+);
+
+// 7. 删除通知消息
+lifeNoticeMapper.delete(
+    new LambdaQueryWrapper<LifeNotice>().eq(LifeNotice::getReceiverId, "store_" + storeUser.getPhone())
+);
+
+// 8. 删除店铺图片
+storeImgMapper.delete(
+    new LambdaQueryWrapper<StoreImg>().eq(StoreImg::getStoreId, storeId)
+);
+
+// 9. 删除标签关系
+tagStoreRelationMapper.delete(
+    new LambdaQueryWrapper<TagStoreRelation>().eq(TagStoreRelation::getStoreId, storeId)
+);
+
+// 10. 删除评论（根据实际表结构调整）
+// storeCommentMapper.delete(...)
+// lifeCommentMapper.delete(...)
+```
+
+### 3. 添加事务保护
+
+```java
+@XxlJob("cancellationOfBusinessJob")
+@Transactional(rollbackFor = Exception.class)
+public void cancellationOfBusinessJob() {
+    // ... 删除逻辑
+}
+```
+
+### 4. 添加异常处理
+
+```java
+for (StoreInfo storeInfo : storeInfos) {
+    try {
+        // 再次检查状态
+        if (storeInfo.getLogoutFlag() != 1) {
+            log.warn("店铺 {} 的注销状态已变更，跳过删除", storeInfo.getId());
+            continue;
+        }
+        
+        // 检查时间
+        if (storeInfo.getLogoutTime() == null) {
+            log.warn("店铺 {} 的注销时间为空，跳过删除", storeInfo.getId());
+            continue;
+        }
+        
+        // 计算7天后的时间
+        Calendar calendar = Calendar.getInstance();
+        calendar.setTime(storeInfo.getLogoutTime());
+        calendar.add(Calendar.DAY_OF_YEAR, 7);  // 改为7天
+        Date sevenDayLater = calendar.getTime();
+        
+        if (new Date().compareTo(sevenDayLater) >= 0) {
+            // 执行删除逻辑
+            deleteStoreData(storeInfo);
+            log.info("成功删除店铺 {} 及其关联数据", storeInfo.getId());
+        }
+    } catch (Exception e) {
+        log.error("删除店铺 {} 失败: {}", storeInfo.getId(), e.getMessage(), e);
+        // 继续处理下一个店铺，不中断整个任务
+    }
+}
+```
+
+### 5. 添加取消注销时的状态检查
+
+```java
+public void cancelLogoutStore(StoreInfoVo storeInfo) {
+    StoreInfo storeIn = storeInfoMapper.selectOne(
+        new LambdaQueryWrapper<StoreInfo>().eq(StoreInfo::getId, storeInfo.getId())
+    );
+    
+    if (storeIn == null) {
+        throw new IllegalArgumentException("店铺不存在");
+    }
+    
+    // 检查是否还在冷静期内
+    if (storeIn.getLogoutTime() != null) {
+        Calendar calendar = Calendar.getInstance();
+        calendar.setTime(storeIn.getLogoutTime());
+        calendar.add(Calendar.DAY_OF_YEAR, 7);
+        Date sevenDayLater = calendar.getTime();
+        
+        if (new Date().compareTo(sevenDayLater) >= 0) {
+            throw new IllegalStateException("已超过7天冷静期，无法撤回注销申请");
+        }
+    }
+    
+    // 检查当前状态
+    if (storeIn.getLogoutFlag() != 1) {
+        throw new IllegalStateException("店铺未处于注销状态，无法撤回");
+    }
+    
+    // ... 后续恢复逻辑
+}
+```
+
+## 五、修复优先级
+
+1. **P0（必须修复）**
+   - 修复时间逻辑（7天 vs 8天）
+   - 完善数据清理逻辑
+   - 添加异常处理
+
+2. **P1（重要）**
+   - 添加事务保护
+   - 添加状态检查
+   - 添加详细日志
+
+3. **P2（优化）**
+   - 代码可读性优化
+   - 性能优化（批量删除）
+
+## 六、测试建议
+
+1. **单元测试**
+   - 测试注销申请后状态是否正确
+   - 测试7天内取消注销是否成功
+   - 测试7天后取消注销是否失败
+   - 测试定时任务是否正确删除数据
+
+2. **集成测试**
+   - 测试完整注销流程
+   - 测试数据清理是否完整
+   - 测试异常情况处理
+
+3. **数据验证**
+   - 验证删除后数据库中是否还有残留数据
+   - 验证关联数据是否全部清理

alien-store/docs/注销店铺流程风险分析.md

@@ -0,0 +1,292 @@
+# 注销店铺流程风险分析报告
+
+## 一、已修复的问题 ✅
+
+1. **时间不一致问题**：定时任务从8天改为7天，与通知一致
+2. **重新入驻问题**：清理商户用户注销状态，允许重新入驻
+3. **身份验证问题**：入驻申请时排除已注销的店铺
+
+---
+
+## 二、潜在风险分析 ⚠️
+
+### 1. **事务性问题** 🔴 高风险
+
+**问题描述**：
+- 定时任务删除店铺时没有使用 `@Transactional` 注解
+- 如果删除过程中某个步骤失败，可能导致数据不一致
+
+**影响范围**：
+- 店铺已删除，但商户用户注销状态未清理 → 无法重新入驻
+- 店铺已删除，但粉丝关系未清理 → 数据冗余
+- 店铺已删除，但Redis地理位置未清理 → 搜索结果包含已删除店铺
+
+**风险场景**：
+```java
+// 当前代码：没有事务保护
+storeUser.setLogoutFlag(0);
+storeUserMapper.updateById(storeUser);  // 如果这里失败
+storeInfoMapper.deleteById(storeInfo.getId());  // 店铺已删除，但用户状态未更新
+```
+
+**建议修复**：
+```java
+@Transactional(rollbackFor = Exception.class)
+public void cancellationOfBusinessJob() {
+    // 删除逻辑
+}
+```
+
+---
+
+### 2. **异常处理缺失** 🔴 高风险
+
+**问题描述**：
+- 定时任务没有 try-catch 异常处理
+- 单个店铺删除失败会导致整个任务中断
+- 后续店铺无法被删除
+
+**影响范围**：
+- 如果第一个店铺删除失败，后续所有店铺都不会被处理
+- 错误信息无法记录，难以排查问题
+
+**风险场景**：
+```java
+// 当前代码：没有异常处理
+for (StoreInfo storeInfo : storeInfos) {
+    // 如果这里抛出异常，整个循环中断
+    storeInfoMapper.deleteById(storeInfo.getId());
+}
+```
+
+**建议修复**：
+```java
+for (StoreInfo storeInfo : storeInfos) {
+    try {
+        // 删除逻辑
+    } catch (Exception e) {
+        log.error("删除店铺失败: storeId={}, error={}", storeInfo.getId(), e.getMessage(), e);
+        // 继续处理下一个店铺
+    }
+}
+```
+
+---
+
+### 3. **关联数据清理不完整** 🟡 中风险
+
+**问题描述**：
+- 当前只清理了：StoreUser、LifeFans、Redis Token
+- 未清理的数据：
+  - Redis 地理位置信息（GEO）
+  - 订单数据（LifeUserOrder）
+  - 优惠券数据（LifeCoupon、LifeDiscountCoupon）
+  - 店铺图片（StoreImg）
+  - 评论数据（StoreComment）
+  - 通知消息（LifeNotice）
+  - 其他业务关联数据
+
+**影响范围**：
+- Redis GEO 中残留已删除店铺 → 搜索结果包含已删除店铺
+- 订单数据残留 → 数据统计不准确
+- 图片数据残留 → 存储空间浪费
+
+**建议修复**：
+参考 `MerchantUserServiceImpl.resetToInitialStatus` 的完整清理逻辑，补充以下清理：
+```java
+// 1. 清理Redis地理位置
+nearMeService.removeGeolocation(Boolean.TRUE, storeInfo.getId().toString());
+
+// 2. 清理订单数据（根据业务需求决定是否物理删除）
+// 3. 清理优惠券数据
+// 4. 清理店铺图片
+// 5. 清理评论数据
+// 6. 清理通知消息
+```
+
+---
+
+### 4. **取消注销逻辑不完善** 🟡 中风险
+
+**问题描述**：
+- `cancelLogoutStore` 方法没有检查是否超过7天
+- 如果超过7天，店铺可能已被定时任务删除，取消注销会失败
+
+**影响范围**：
+- 用户在第8天尝试取消注销，但店铺已被删除
+- 可能导致 `NullPointerException` 或其他异常
+
+**当前代码**：
+```java
+public void cancelLogoutStore(StoreInfoVo storeInfo) {
+    StoreInfo storeIn = storeInfoMapper.selectOne(...);
+    // 没有检查 storeIn 是否为 null
+    // 没有检查是否超过7天
+    storeIn.setLogoutFlag(0);
+    // ...
+}
+```
+
+**建议修复**：
+```java
+public void cancelLogoutStore(StoreInfoVo storeInfo) {
+    StoreInfo storeIn = storeInfoMapper.selectOne(...);
+    if (storeIn == null) {
+        throw new BusinessException("店铺不存在或已被删除");
+    }
+    
+    // 检查是否超过7天
+    if (storeIn.getLogoutTime() != null) {
+        Date logoutTime = storeIn.getLogoutTime();
+        Calendar calendar = Calendar.getInstance();
+        calendar.setTime(logoutTime);
+        calendar.add(Calendar.DAY_OF_YEAR, 7);
+        if (new Date().after(calendar.getTime())) {
+            throw new BusinessException("已超过7天冷静期，无法取消注销");
+        }
+    }
+    
+    // 取消注销逻辑
+}
+```
+
+---
+
+### 5. **并发安全问题** 🟡 中风险
+
+**问题描述**：
+- 定时任务没有分布式锁保护
+- 如果多个实例同时执行，可能重复删除
+
+**影响范围**：
+- 多实例部署时，可能重复执行删除操作
+- 虽然 MyBatis-Plus 的 `deleteById` 是幂等的，但清理操作可能重复执行
+
+**建议修复**：
+```java
+@XxlJob("cancellationOfBusinessJob")
+public void cancellationOfBusinessJob() {
+    String lockKey = "job:cancellationOfBusinessJob";
+    String lockValue = baseRedisService.lock(lockKey, 300000, 10000); // 5分钟锁，10秒超时
+    if (lockValue == null) {
+        log.warn("获取分布式锁失败，跳过本次执行");
+        return;
+    }
+    
+    try {
+        // 删除逻辑
+    } finally {
+        baseRedisService.unlock(lockKey, lockValue);
+    }
+}
+```
+
+---
+
+### 6. **时间精度问题** 🟢 低风险
+
+**问题描述**：
+- 使用 `Date` 和 `Calendar` 进行时间比较
+- 可能存在时区或精度问题
+
+**影响范围**：
+- 不同时区可能导致判断不准确
+- 毫秒级精度可能导致边界情况
+
+**建议修复**：
+使用 `LocalDateTime` 或 `Instant` 进行时间计算，更精确：
+```java
+LocalDateTime logoutTime = storeInfo.getLogoutTime().toInstant()
+    .atZone(ZoneId.systemDefault())
+    .toLocalDateTime();
+LocalDateTime sevenDaysLater = logoutTime.plusDays(7);
+LocalDateTime now = LocalDateTime.now();
+if (now.isAfter(sevenDaysLater) || now.isEqual(sevenDaysLater)) {
+    // 删除逻辑
+}
+```
+
+---
+
+### 7. **日志记录不完整** 🟢 低风险
+
+**问题描述**：
+- 删除操作缺少详细的日志记录
+- 无法追踪删除历史和问题排查
+
+**建议修复**：
+```java
+log.info("开始删除店铺: storeId={}, storeName={}, logoutTime={}, relatedUsers={}", 
+    storeInfo.getId(), storeInfo.getStoreName(), logoutTime, relatedStoreUsers.size());
+// ... 删除操作
+log.info("店铺删除完成: storeId={}, deletedUsers={}, deletedFans={}", 
+    storeInfo.getId(), deletedUsers, deletedFans);
+```
+
+---
+
+## 三、修复优先级
+
+| 优先级 | 风险项 | 影响 | 修复难度 |
+|--------|--------|------|----------|
+| P0 | 事务性问题 | 数据不一致 | 低 |
+| P0 | 异常处理缺失 | 任务中断 | 低 |
+| P1 | 关联数据清理不完整 | 数据冗余 | 中 |
+| P1 | 取消注销逻辑不完善 | 用户体验 | 低 |
+| P2 | 并发安全问题 | 重复执行 | 中 |
+| P3 | 时间精度问题 | 边界情况 | 低 |
+| P3 | 日志记录不完整 | 问题排查 | 低 |
+
+---
+
+## 四、建议修复方案
+
+### 方案1：完整修复（推荐）
+
+1. 添加事务保护
+2. 添加异常处理
+3. 补充关联数据清理
+4. 完善取消注销逻辑
+5. 添加分布式锁
+6. 优化时间计算
+7. 完善日志记录
+
+### 方案2：快速修复（最小改动）
+
+1. 添加异常处理（最重要）
+2. 添加事务保护
+3. 完善取消注销逻辑
+
+---
+
+## 五、测试建议
+
+1. **单元测试**：
+   - 测试7天边界情况（6天23小时59分 vs 7天0分1秒）
+   - 测试删除过程中的异常情况
+
+2. **集成测试**：
+   - 测试定时任务执行
+   - 测试取消注销功能
+   - 测试重新入驻功能
+
+3. **压力测试**：
+   - 测试大量店铺同时删除
+   - 测试并发执行情况
+
+---
+
+## 六、监控建议
+
+1. **定时任务监控**：
+   - 监控任务执行时间
+   - 监控删除数量
+   - 监控失败次数
+
+2. **数据一致性监控**：
+   - 监控 `logoutFlag=1` 且超过7天的店铺数量
+   - 监控 Redis GEO 中的店铺数量
+
+3. **告警设置**：
+   - 定时任务执行失败告警
+   - 删除数量异常告警

alien-store/src/main/java/shop/alien/store/controller/LifeDiscountCouponController.java

@@ -191,7 +191,8 @@ public class LifeDiscountCouponController {
             @ApiImplicitParam(name = "tabType", value = "分页类型（0：全部（未使用），1：即将过期，2：已使用，3：已过期）", dataType = "String", paramType = "query", required = true),
             @ApiImplicitParam(name = "type", value = "券类型（不传：优惠券+代金券都返回，1：仅优惠券查 life_discount_coupon，4：仅代金券查 life_coupon）", dataType = "Integer", paramType = "query", required = false),
             @ApiImplicitParam(name = "couponType", value = "优惠券类型：1=仅满减券，2=仅折扣券，不传=全部优惠券（可选，仅当type不为4时有效）", dataType = "Integer", paramType = "query", required = false),
-            @ApiImplicitParam(name = "storeId", value = "商铺ID，可为空，传则仅返回该商铺的优惠券", dataType = "String", paramType = "query", required = false)
+            @ApiImplicitParam(name = "storeId", value = "商铺ID，可为空，传则仅返回该商铺的优惠券", dataType = "String", paramType = "query", required = false),
+            @ApiImplicitParam(name = "storeName", value = "商铺名称模糊查询，可为空，传则仅返回名称匹配的商铺下优惠券", dataType = "String", paramType = "query", required = false)
     })
     public R<List<LifeDiscountCouponVo>> getUserCouponList(@ApiIgnore @TokenInfo UserLoginInfo userLoginInfo,
                                                            @RequestParam(value = "tabType") String tabType,
@@ -199,7 +200,8 @@ public class LifeDiscountCouponController {
                                                            @RequestParam(defaultValue = "10") int size,
                                                            @RequestParam(required = false) Integer type,
                                                            @RequestParam(value = "couponType", required = false) Integer couponType,
-                                                           @RequestParam(value = "storeId", required = false) String storeId) {
+                                                           @RequestParam(value = "storeId", required = false) String storeId,
+                                                           @RequestParam(value = "storeName", required = false) String storeName) {
         try {
             // 参数校验
             if (StringUtils.isEmpty(tabType)) {
@@ -218,11 +220,11 @@ public class LifeDiscountCouponController {
                 return R.fail("优惠券类型参数错误，必须为1（满减券）或2（折扣券）");
             }
             
-            log.info("LifeDiscountCouponController.getUserCouponList?userId={}, tabType={}, page={}, size={}, type={}, couponType={}, storeId={}", 
-                    userLoginInfo.getUserId(), tabType, page, size, type, couponType, storeId);
+            log.info("LifeDiscountCouponController.getUserCouponList?userId={}, tabType={}, page={}, size={}, type={}, couponType={}, storeId={}, storeName={}", 
+                    userLoginInfo.getUserId(), tabType, page, size, type, couponType, storeId, storeName);
             
             List<LifeDiscountCouponVo> storeCouponList = lifeDiscountCouponService.getUserCouponList(
-                    userLoginInfo, page, size, tabType, type, couponType, storeId);
+                    userLoginInfo, page, size, tabType, type, couponType, storeId, storeName);
             return R.data(storeCouponList);
         } catch (IllegalArgumentException e) {
             log.error("LifeDiscountCouponController.getUserCouponList 参数错误, userId={}, error={}", 

alien-store/src/main/java/shop/alien/store/service/LifeDiscountCouponService.java

@@ -68,8 +68,9 @@ public interface LifeDiscountCouponService extends IService<LifeDiscountCoupon>
      * @param type 不传：优惠券+代金券都返回；1：仅优惠券（查 life_discount_coupon）；4：仅代金券（查 life_coupon）
      * @param couponType 优惠券类型：1=满减券，2=折扣券，null=全部优惠券（仅当type不为4时有效）
      * @param storeId 商铺ID，可为空，传则仅返回该商铺的优惠券
+     * @param storeName 商铺名称模糊查询，可为空；与 storeId 同时传时须同时满足
      */
-    List<LifeDiscountCouponVo> getUserCouponList(UserLoginInfo userLoginInfo, int page, int size, String tabType, Integer type, Integer couponType, String storeId);
+    List<LifeDiscountCouponVo> getUserCouponList(UserLoginInfo userLoginInfo, int page, int size, String tabType, Integer type, Integer couponType, String storeId, String storeName);
 
     /**
      * 获取所有优惠券列表（分页）

alien-store/src/main/java/shop/alien/store/service/impl/LifeDiscountCouponServiceImpl.java

@@ -714,10 +714,11 @@ public class LifeDiscountCouponServiceImpl extends ServiceImpl<LifeDiscountCoupo
      * @param type 券类型：1-仅优惠券，4-仅代金券，null-全部
      * @param couponType 优惠券类型：1-满减券，2-折扣券，null-全部（仅当type不为4时有效）
      * @param storeId 商铺ID，可为空，传则仅返回该商铺的优惠券
+     * @param storeName 商铺名称模糊查询，可为空；与 storeId 同时传时 storeId 须属于名称匹配的门店
      * @return 优惠券列表
      */
     @Override
-    public List<LifeDiscountCouponVo> getUserCouponList(UserLoginInfo userLoginInfo, int page, int size, String tabType, Integer type, Integer couponType, String storeId) {
+    public List<LifeDiscountCouponVo> getUserCouponList(UserLoginInfo userLoginInfo, int page, int size, String tabType, Integer type, Integer couponType, String storeId, String storeName) {
         // 参数校验
         if (userLoginInfo == null || StringUtils.isEmpty(userLoginInfo.getUserId())) {
             throw new IllegalArgumentException("用户信息不能为空");
@@ -732,6 +733,17 @@ public class LifeDiscountCouponServiceImpl extends ServiceImpl<LifeDiscountCoupo
                 && !DiscountCouponEnum.HAVE_EXPIRED.getValue().equals(tabType)) {
             throw new IllegalArgumentException("分页类型参数错误，必须为0（未使用）、1（即将过期）、2（已使用）、3（已过期）");
         }
+
+        List<String> storeIdsByName = null;
+        if (!StringUtils.isEmpty(storeName)) {
+            String kw = storeName.trim();
+            if (!StringUtils.isEmpty(kw)) {
+                storeIdsByName = resolveStoreIdsByStoreNameLike(kw);
+                if (storeIdsByName.isEmpty()) {
+                    return new ArrayList<>();
+                }
+            }
+        }
         
         List<LifeDiscountCouponVo> lifeDiscountCouponVos = new ArrayList<>();
         IPage<LifeDiscountCouponUser> iPage = new Page<>(page, size);
@@ -781,7 +793,10 @@ public class LifeDiscountCouponServiceImpl extends ServiceImpl<LifeDiscountCoupo
         if (records.isEmpty()) {
             return lifeDiscountCouponVos;
         }
-        
+        if (!StringUtils.isEmpty(storeId) && storeIdsByName != null && !storeIdsByName.contains(storeId)) {
+            return new ArrayList<>();
+        }
+
         // 准备时间转换
         Instant instant = now.toInstant();
         ZoneId zoneId = ZoneId.systemDefault();
@@ -789,7 +804,7 @@ public class LifeDiscountCouponServiceImpl extends ServiceImpl<LifeDiscountCoupo
         
         // type=4：仅代金券，查询 life_coupon 表
         if (type != null && type == 4) {
-            return processVoucherCoupons(records, zoneId, localNow, storeId);
+            return processVoucherCoupons(records, zoneId, localNow, storeId, storeIdsByName);
         }
 
         // type=1 或 type=null：优惠券（或混合），查询 life_discount_coupon
@@ -805,9 +820,10 @@ public class LifeDiscountCouponServiceImpl extends ServiceImpl<LifeDiscountCoupo
         if (couponType != null) {
             couponQueryWrapper.eq(LifeDiscountCoupon::getCouponType, couponType);
         }
-        // 商铺ID检索：传则仅返回该商铺的优惠券
         if (!StringUtils.isEmpty(storeId)) {
             couponQueryWrapper.eq(LifeDiscountCoupon::getStoreId, storeId);
+        } else if (storeIdsByName != null) {
+            couponQueryWrapper.in(LifeDiscountCoupon::getStoreId, storeIdsByName);
         }
         List<LifeDiscountCoupon> lifeDiscountCoupons = lifeDiscountCouponMapper.selectList(couponQueryWrapper);
         
@@ -836,6 +852,8 @@ public class LifeDiscountCouponServiceImpl extends ServiceImpl<LifeDiscountCoupo
                 LambdaQueryWrapper<LifeCoupon> voucherWrapper = new LambdaQueryWrapper<LifeCoupon>().in(LifeCoupon::getId, voucherIdList);
                 if (!StringUtils.isEmpty(storeId)) {
                     voucherWrapper.eq(LifeCoupon::getStoreId, storeId);
+                } else if (storeIdsByName != null) {
+                    voucherWrapper.in(LifeCoupon::getStoreId, storeIdsByName);
                 }
                 lifeCouponsForMerge = lifeCouponMapper.selectList(voucherWrapper);
                 List<String> voucherStoreIds = lifeCouponsForMerge.stream()
@@ -890,10 +908,24 @@ public class LifeDiscountCouponServiceImpl extends ServiceImpl<LifeDiscountCoupo
     }
     
     /**
+     * 按门店名称模糊匹配，返回门店 id 列表（字符串，与优惠券/代金券 store_id 一致）
+     */
+    private List<String> resolveStoreIdsByStoreNameLike(String storeNameKeyword) {
+        LambdaQueryWrapper<StoreInfo> w = new LambdaQueryWrapper<>();
+        w.like(StoreInfo::getStoreName, storeNameKeyword);
+        List<StoreInfo> list = storeInfoMapper.getList(w);
+        if (CollectionUtils.isEmpty(list)) {
+            return new ArrayList<>();
+        }
+        return list.stream().map(s -> String.valueOf(s.getId())).distinct().collect(Collectors.toList());
+    }
+
+    /**
      * 处理代金券列表（type=4时使用）
      */
     private List<LifeDiscountCouponVo> processVoucherCoupons(List<LifeDiscountCouponUser> records,
-                                                               ZoneId zoneId, LocalDate localNow, String storeId) {
+                                                               ZoneId zoneId, LocalDate localNow, String storeId,
+                                                               List<String> storeIdsByName) {
         List<LifeDiscountCouponVo> result = new ArrayList<>();
         List<String> voucherIdList = records.stream()
                 .map(LifeDiscountCouponUser::getVoucherId)
@@ -902,10 +934,15 @@ public class LifeDiscountCouponServiceImpl extends ServiceImpl<LifeDiscountCoupo
         if (voucherIdList.isEmpty()) {
             return result;
         }
+        if (!StringUtils.isEmpty(storeId) && storeIdsByName != null && !storeIdsByName.contains(storeId)) {
+            return result;
+        }
 
         LambdaQueryWrapper<LifeCoupon> voucherWrapper = new LambdaQueryWrapper<LifeCoupon>().in(LifeCoupon::getId, voucherIdList);
         if (!StringUtils.isEmpty(storeId)) {
             voucherWrapper.eq(LifeCoupon::getStoreId, storeId);
+        } else if (storeIdsByName != null) {
+            voucherWrapper.in(LifeCoupon::getStoreId, storeIdsByName);
         }
         List<LifeCoupon> lifeCoupons = lifeCouponMapper.selectList(voucherWrapper);
         List<String> storeIdList = lifeCoupons.stream()

docs/日志配置检查与优化说明.md

@@ -0,0 +1,87 @@
+# 日志配置（logback-spring.xml）检查与优化说明
+
+## 一、本次已修复的问题
+
+### 1. Logger 名称尾随空格导致降噪失效（风险）
+
+- **问题**：`DefaultSecurityFilterChain `、`URLConfigurationSource ` 等 logger 名称带尾部空格，与真实类名不一致，降噪配置无法匹配，框架 DEBUG 日志仍会输出。
+- **处理**：已去掉上述 logger 名称中的尾部空格，所有模块已统一修正。
+
+### 2. 归档总大小无上限（风险）
+
+- **问题**：仅配置 `maxHistory=30` 和 `maxFileSize=1MB`，单级别理论最大约 30MB，但多服务、多级别同目录时，总磁盘占用不可控，存在写满磁盘风险。
+- **处理**：已为所有文件的 `SizeAndTimeBasedRollingPolicy` 增加 **`<totalSizeCap>500MB</totalSizeCap>`**。即每个服务、每个级别（DEBUG/INFO/WARN/ERROR）的归档总大小上限 500MB，单服务四类合计约 2GB 上限。
+
+### 3. alien-dining 注释不统一
+
+- **问题**：`log.maxHistory` 注释为「30个」，与其他模块「保留30个归档」不一致。
+- **处理**：已统一为「30表示保留30个归档」。
+
+---
+
+## 二、已识别的风险与建议
+
+### 1. logging.path 默认值为 Windows 路径
+
+- **风险**：`defaultValue="C:/project/ext/log"` 在 Linux 或容器中若未设置 `logging.path`，目录可能不存在或不可写，导致日志写失败或落盘到非预期路径。
+- **建议**：
+  - 生产/测试环境在 `application.yml` 或环境变量中显式配置 `logging.path`（如 `/var/log/alien-xxx` 或 `./logs`）。
+  - 已在 alien-gateway 的 logback 中增加注释提醒，其他模块部署时同样需保证该配置正确。
+
+### 2. ~~alien-dining 控制台为 DEBUG 级别~~（已修复）
+
+- **原风险**：alien-dining 的 CONSOLE 使用 `${log.level}`（debug），控制台会输出 DEBUG，生产易刷屏。
+- **处理**：已改为与其它模块一致，CONSOLE 固定为 **INFO**，仅文件仍按级别分 DEBUG/INFO/WARN/ERROR。
+
+### 3. 多实例同目录部署
+
+- **现状**：各服务已写入各自子目录 `LOG_DIR`（如 `logging.path/alien-dining/`），同机多实例若共用同一 `logging.path` 且相同 `FILENAME` 会写同一子目录。
+- **建议**：同一台机多实例时，为每个实例配置不同的 `logging.path`（如 `.../log-instance1`）或通过启动参数覆盖 `FILENAME` 以区分。
+
+### 4. logging.path 根目录需存在
+
+- **说明**：Logback 只会自动创建**当前写入文件的父目录**（即 `LOG_DIR` = `logging.path/FILENAME`），不会自动创建 `logging.path` 本身。
+- **建议**：部署前确保 `logging.path` 所指目录已存在且有写权限；否则首次写日志会报错。Linux 可设为 `/var/log/xxx` 或 `./logs` 并确保目录存在。
+
+---
+
+## 三、可选优化（未改配置）
+
+| 项目 | 说明 |
+|------|------|
+| **异步 Appender** | 对写盘量大的服务可将 FILE 包一层 `AsyncAppender`，减轻主线程 IO，需接受异常退出时可能少几条日志。 |
+| **按环境区分** | 使用 `<springProfile name="pro">` 等区分开发/生产路径、级别或 totalSizeCap。 |
+| **immediateFlush** | 默认 true，设为 false 可减少 IO，换少量丢日志风险，一般保持 true。 |
+
+---
+
+## 四、当前各模块配置要点汇总
+
+| 项目 | 说明 |
+|------|------|
+| 滚动策略 | SizeAndTimeBasedRollingPolicy，单文件 1MB，按天+序号归档并压缩为 .gz |
+| 日志目录 | 各服务写入**各自子目录** `${logging.path}/${FILENAME}/`，如 `C:/project/ext/log/alien-dining/`、`alien-gateway/` 等 |
+| 当前写入文件 | `${LOG_DIR}/DEBUG.log`、`INFO.log`、`WARN.log`、`ERROR.log`（LOG_DIR = logging.path/FILENAME） |
+| 归档保留 | maxHistory=30 个归档，totalSizeCap=500MB/级别 |
+| 启动清理 | cleanHistoryOnStart=true |
+| 文件编码 | UTF-8 |
+| 降噪 | DefaultSecurityFilterChain、URLConfigurationSource 等已设为 WARN，且 logger 名称已去掉尾空格 |
+
+---
+
+## 五、本次排查已做的修改
+
+- **alien-dining logback**：CONSOLE 由 `${log.level}` 改为固定 **INFO**，与其它模块一致，避免生产控制台 DEBUG 刷屏；并增加 logging.path 部署说明注释。
+- **文档**：多实例说明更新为 LOG_DIR 子目录；新增「logging.path 根目录需存在」说明；alien-dining 控制台风险标记为已修复。
+
+## 六、当前剩余隐患与可优化（结论）
+
+| 类型 | 说明 | 建议 |
+|------|------|------|
+| **部署** | `logging.path` 默认 `C:/project/ext/log`，Linux/容器未配置时可能写失败 | 生产/测试在配置或环境变量中设置 `logging.path`，并确保该目录存在 |
+| **部署** | Logback 只自动创建 `LOG_DIR`，不创建 `logging.path` 根目录 | 部署前创建根目录或使用已存在路径（如 `./logs`） |
+| **多实例** | 同机多实例若共用同一 `logging.path` 且同服务名会写同一子目录 | 按实例配置不同 `logging.path` 或区分 FILENAME |
+| **可选** | 高吞吐服务可考虑 AsyncAppender 减轻主线程 IO | 按需在对应模块为 FILE appender 包一层异步，接受异常退出时可能少几条日志 |
+| **可选** | 按环境区分路径/级别（如 pro 用不同 path 或 totalSizeCap） | 使用 `<springProfile name="pro">` 等 |
+
+当前配置已无已知逻辑错误；剩余为部署约定与可选性能优化。

优惠券拆分改动清单.md

@@ -0,0 +1,115 @@
+# 优惠券拆分为满减券和折扣券 - 改动清单
+
+## ✅ 已完成的改动
+
+### 1. 数据库层面
+- ✅ 实体类 `LifeDiscountCoupon` 添加 `couponType` 和 `discountRate` 字段
+- ✅ DTO类 `LifeDiscountCouponDto` 添加 `couponType` 和 `discountRate` 字段
+- ✅ VO类 `LifeDiscountCouponVo` 添加 `couponType` 和 `discountRate` 字段
+- ✅ VO类 `LifeDiscountCouponFriendRuleVo` 添加 `couponType` 和 `discountRate` 字段
+
+### 2. 业务逻辑层面
+- ✅ **创建优惠券验证** (`LifeDiscountCouponServiceImpl.addDiscountCoupon`)
+  - 满减券：验证 `nominalValue` 和 `minimumSpendingAmount`
+  - 折扣券：验证 `discountRate` 和 `minimumSpendingAmount`
+  
+- ✅ **使用优惠券计算** (`LifeUserOrderService`)
+  - 满减券：直接使用 `nominalValue` 作为减免金额
+  - 折扣券：根据订单金额和折扣率计算优惠金额
+
+- ✅ **优惠券规则构建** (`LifeDiscountCouponServiceImpl.buildDiscountCouponRule`)
+  - 满减券：显示面值和最低消费
+  - 折扣券：显示折扣率和最低消费
+
+- ✅ **好评赠券通知** (`LifeDiscountCouponStoreFriendServiceImpl.issueCouponForGoodRating`)
+  - 通知消息中包含优惠券类型和详情（满减金额或折扣率）
+
+### 3. 数据查询层面
+- ✅ **好友赠券SQL查询** (`LifeDiscountCouponStoreFriendMapper`)
+  - `getReceivedSendFriendCouponList` (好友赠我-优惠券)：添加 `coupon_type` 和 `discount_rate`
+  - `getReceivedSendFriendCouponListwzhy` (我赠好友-优惠券)：添加 `coupon_type` 和 `discount_rate`
+  
+- ✅ **好友赠券规则查询** (`LifeDiscountCouponFriendRuleDetailMapper`)
+  - `getRuleList`：添加 `coupon_type` 和 `discount_rate`
+
+## 📋 需要执行的SQL
+
+```sql
+-- 添加优惠券类型字段
+ALTER TABLE `life_discount_coupon` 
+ADD COLUMN `coupon_type` INT DEFAULT NULL COMMENT '优惠券类型：1-满减券，2-折扣券' AFTER `valid_date`;
+
+-- 添加折扣率字段
+ALTER TABLE `life_discount_coupon` 
+ADD COLUMN `discount_rate` DECIMAL(10,2) DEFAULT NULL COMMENT '折扣率（0-100，用于折扣券，例如80表示8折）' AFTER `coupon_type`;
+```
+
+## ⚠️ 前端需要适配的地方
+
+### 1. 创建优惠券页面
+- 需要添加优惠券类型选择（满减券/折扣券）
+- 根据类型显示不同的输入框：
+  - 满减券：显示"面值"输入框
+  - 折扣券：显示"折扣率"输入框（0-100）
+
+### 2. 优惠券列表/详情显示
+- 根据 `couponType` 判断显示方式：
+  - `couponType = 1`（满减券）：显示 `nominalValue` 元
+  - `couponType = 2`（折扣券）：显示 `discountRate` 折
+- 兼容旧数据：`couponType` 为 `null` 时，按满减券处理
+
+### 3. 好友赠券列表显示
+- 需要根据 `couponType` 显示不同的优惠信息
+- 文件位置：
+  - `group_merchant/src/pages/voucherRecord/index.vue` (第81行)
+  - `group_merchant/src/pages/couponManagement/couponsDetail.vue` (第13-20行)
+  - `group_merchant/src/components/IssueCoupons/IssueCoupons.vue` (第14-19行)
+
+### 4. 优惠券预览页面
+- 需要根据类型显示不同的预览效果
+- 文件位置：
+  - `group_merchant/src/pages/couponDetails/index.vue`
+  - `group_merchant/src/pages/couponManagement/couponsDetail.vue`
+
+## 🔍 不需要改动的部分
+
+### 1. 优惠券核销
+- 核销逻辑主要针对代金券（`life_coupon`）和团购券，不涉及优惠券（`life_discount_coupon`）的核销
+- 文件：`CouponManageServiceImpl.verifyCoupon`、`CouponManageServiceImpl.verifyOrder`
+
+### 2. 好友赠券发放逻辑
+- 发放流程对满减券和折扣券一致，无需修改
+- 文件：`LifeDiscountCouponStoreFriendServiceImpl.setFriendCoupon`、`issueFriendCoupon`
+
+### 3. 好评赠券发放逻辑
+- 发放流程对满减券和折扣券一致，无需修改
+- 文件：`LifeDiscountCouponStoreFriendServiceImpl.issueCouponForGoodRating`
+
+### 4. 优惠券统计
+- 统计逻辑不涉及优惠券类型区分，无需修改
+- 文件：`StoreOperationalStatisticsServiceImpl.getCouponData`
+
+## 📝 注意事项
+
+1. **兼容性**：对于旧数据，`couponType` 为 `null` 时，代码按满减券处理
+2. **数据迁移**：如需将旧数据统一为满减券，可执行：
+   ```sql
+   UPDATE `life_discount_coupon` SET `coupon_type` = 1 WHERE `coupon_type` IS NULL;
+   ```
+3. **前端适配**：前端需要根据 `couponType` 字段判断显示方式，这是必须的改动
+4. **验证逻辑**：创建优惠券时必须选择类型并填写对应字段，已添加验证
+
+## 🎯 总结
+
+**后端改动已完成**，主要包括：
+- ✅ 实体类、DTO、VO 字段添加
+- ✅ 创建优惠券验证逻辑
+- ✅ 使用优惠券计算逻辑
+- ✅ 优惠券规则显示逻辑
+- ✅ 好评赠券通知优化
+- ✅ SQL查询字段添加
+
+**前端需要适配**：
+- ⚠️ 创建优惠券页面：添加类型选择和对应输入框
+- ⚠️ 优惠券显示页面：根据类型显示不同内容
+- ⚠️ 好友赠券列表：根据类型显示不同信息

小票审核接口.md

@@ -0,0 +1,229 @@
+# 消费凭证核验接口文档
+
+## 概述
+
+消费凭证核验接口提供用户上传消费凭证图片（小票、支付记录、订单截图等）的核验能力，系统使用视觉模型（Qwen3-VL-8B-Thinking）分析图片，判断是否为真实消费凭证。仅核验通过的用户才允许进行评论。
+
+接口采用**异步非阻塞**设计，使用线程池执行模型调用，避免阻塞FastAPI事件循环，支持高并发场景。
+
+### 基础URL
+
+所有接口需要通过 **9000网关** 进行访问：
+
+| 环境 | 基础URL |
+|------|---------|
+| 开发环境 | `http://localhost:9000/multimodal_services/api/v1/consumption-proof` |
+| 生产环境 | `http://<gateway-host>:9000/multimodal_services/api/v1/consumption-proof` |
+
+**Content-Type**: `application/json`
+
+### 服务路由说明
+
+- **网关端口**: 9000
+- **服务名**: multimodal_services
+- **服务端口**: 9009
+- **API版本**: v1
+- **接口前缀**: /consumption-proof
+
+### 完整URL路径示例
+
+| 接口 | 完整URL路径（通过网关） |
+|------|------------------------|
+| 消费凭证核验 | `http://localhost:9000/multimodal_services/api/v1/consumption-proof/verify` |
+
+⚠️ **注意**: 请确保URL路径正确，避免重复路径段
+
+---
+
+## 接口列表
+
+| 序号 | 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|------|
+| 1 | 消费凭证核验 | POST | `/verify` | 上传消费凭证图片URL列表，核验是否为真实凭证（可选：核验商户是否匹配） |
+
+---
+
+## 1. 消费凭证核验
+
+### 请求
+
+**POST** `/verify`
+
+### 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| image_urls | string[] | 是 | - | 消费凭证图片URL列表（如小票、支付记录、订单截图等），1～10张 |
+| store_name | string | 否 | "" | 店铺名；若填写则核验凭证中的商户/店铺是否与该店铺一致 |
+
+### 请求示例
+
+```json
+{
+    "image_urls": [
+        "https://example.com/receipt1.jpg",
+        "https://example.com/payment_record.png"
+    ],
+    "store_name": "某某餐厅"
+}
+```
+
+---
+
+### 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| code | integer | 响应状态码，200表示成功 |
+| message | string | 响应消息 |
+| data | object | 核验结果数据 |
+| data.can_comment | boolean | 是否允许评论（仅当为真实消费凭证时为true） |
+| data.is_valid_proof | boolean | 是否为真实消费凭证 |
+| data.proof_type | string/null | 识别到的凭证类型，如"小票"、"支付记录"、"订单截图"等 |
+| data.reason | string | 核验结论说明 |
+| data.image_results | array | 每张图片的核验结果列表 |
+| data.image_results[].image_index | integer | 图片序号（从1开始） |
+| data.image_results[].is_valid_proof | boolean | 该图片是否为有效凭证 |
+| data.image_results[].proof_type | string | 该图片识别到的凭证类型 |
+| data.image_results[].confidence | string | 置信度，如"高"、"中"、"低" |
+| data.image_results[].reason | string | 该图片的核验说明 |
+| data.error | string | 异常或错误信息，成功时为空 |
+| timestamp | float | 响应时间戳（Unix时间戳） |
+
+### 成功响应示例
+
+```json
+{
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+        "can_comment": true,
+        "is_valid_proof": true,
+        "proof_type": "小票",
+        "reason": "图片为真实消费小票，信息清晰可辨，且商户名称与店铺名一致",
+        "image_results": [
+            {
+                "image_index": 1,
+                "is_valid_proof": true,
+                "proof_type": "小票",
+                "confidence": "高",
+                "reason": "包含商户（某某餐厅）、金额、时间等消费信息"
+            },
+            {
+                "image_index": 2,
+                "is_valid_proof": false,
+                "proof_type": "",
+                "confidence": "",
+                "reason": "图片模糊，无法识别有效信息"
+            }
+        ],
+        "error": ""
+    },
+    "timestamp": 1704067200.123
+}
+```
+
+### 失败响应示例
+
+**参数校验失败（422）**
+
+```json
+{
+    "code": 422,
+    "message": "请求参数不合法",
+    "data": null,
+    "details": {
+        "errors": [
+            {
+                "loc": ["image_urls"],
+                "msg": "ensure this value has at least 1 items",
+                "type": "value_error.list.min_items"
+            }
+        ]
+    },
+    "timestamp": 1704067200.456
+}
+```
+
+**业务异常（400）**
+
+```json
+{
+    "code": 400,
+    "message": "图片URL列表为空",
+    "data": null,
+    "details": {
+        "data": {
+            "can_comment": false,
+            "is_valid_proof": false,
+            "proof_type": null,
+            "reason": "",
+            "image_results": [],
+            "error": "图片URL列表为空"
+        }
+    },
+    "timestamp": 1704067200.789
+}
+```
+
+**服务异常（500）**
+
+```json
+{
+    "code": 500,
+    "message": "服务暂时不可用，请稍后重试",
+    "data": null,
+    "details": null,
+    "timestamp": 1704067200.012
+}
+```
+
+---
+
+## 业务逻辑说明
+
+### 核验流程
+
+1. **参数校验**：检查image_urls是否为空，数量是否在1～10之间
+2. **构建Prompt**：根据图片数量和店铺名构建核验提示词
+3. **模型调用**：使用Qwen3-VL-8B-Thinking视觉模型分析图片（在线程池中执行，不阻塞事件循环）
+4. **结果解析**：解析模型返回的JSON，提取核验结果
+5. **结果判定**：
+   - `is_valid_proof`为true时，`can_comment`为true，允许评论
+   - `is_valid_proof`为false时，`can_comment`为false，不允许评论
+   - 若填写了`store_name`，还会核验凭证中的商户名称是否与店铺名一致
+
+### 支持的凭证类型
+
+- 消费小票/发票
+- 支付记录截图
+- 订单截图
+- 其他包含消费信息的凭证
+
+### 模型判断依据
+
+模型会分析图片中的以下内容：
+- 商户名称（若填写store_name，核验是否匹配）
+- 消费金额
+- 交易时间
+- 订单号/流水号
+- 其他消费相关信息
+
+## 注意事项
+
+1. **网关访问**：所有接口必须通过9000网关访问，URL格式为 `http://<gateway>:9000/multimodal_services/api/v1/consumption-proof/...`，直接访问9009端口不推荐。
+2. **图片要求**：
+   - 图片URL必须可公开访问
+   - 建议上传清晰、完整的凭证图片
+   - 支持的图片格式：jpg、png等常见格式
+3. **数量限制**：
+   - 最少上传1张图片
+   - 最多上传10张图片
+4. **店铺名匹配**：
+   - `store_name`参数为可选
+   - 若填写，模型会核验凭证中的商户名称是否与该店铺名一致
+   - 有助于确保用户确实在该店铺消费
+5. **响应时间**：
+   - 模型推理需要一定时间，请合理设置超时时间（建议10～30秒）
+6. **幂等性**：
+   - 该接口为查询类接口，可重复调用获取相同结果