jsowell-charger-web/docs/coupon-impl-progress.md

# 优惠券功能实现进度

**需求文档**: [PRD-积分兑换洗车券功能.md](./PRD-积分兑换洗车券功能.md)
**开始日期**: 2026-03-04
**当前版本**: v1.0（首期洗车券）

---

## 进度总览

| # | 子任务 | 状态 | 文件 |
|---|--------|------|------|
| 1 | Domain 实体类 | ✅ 完成 | `jsowell-pile/.../domain/` |
| 2 | Mapper 接口和 XML | ✅ 完成 | `jsowell-pile/.../mapper/` + `resources/mapper/pile/` |
| 3 | Service 层 | ✅ 完成 | `jsowell-pile/.../service/` |
| 4 | 管理后台 Controller | ✅ 完成 | `jsowell-admin/.../web/controller/pile/` |
| 5 | 用户端 API Controller | ✅ 完成 | `jsowell-admin/.../api/uniapp/customer/` |
| 6 | Quartz 过期归档任务 | ✅ 完成 | `jsowell-quartz/.../task/JsowellTask.java`（方法 `expireCoupons`） |

> 状态图例：⬜ 待开始 / 🔄 进行中 / ✅ 完成

---

## Task 1：Domain 实体类

**状态**: ✅ 完成

### 文件清单

| 文件 | 路径 |
|------|------|
| `CouponTemplate.java` | `jsowell-pile/src/main/java/com/jsowell/pile/domain/` |
| `CouponTemplateScope.java` | `jsowell-pile/src/main/java/com/jsowell/pile/domain/` |
| `MemberCoupon.java` | `jsowell-pile/src/main/java/com/jsowell/pile/domain/` |
| `CouponVerifyRecord.java` | `jsowell-pile/src/main/java/com/jsowell/pile/domain/` |

---

## Task 2：Mapper 接口和 XML

**状态**: ✅ 完成

### 文件清单

| 文件 | 路径 |
|------|------|
| `CouponTemplateMapper.java` | `jsowell-pile/src/main/java/com/jsowell/pile/mapper/` |
| `CouponTemplateScopeMapper.java` | `jsowell-pile/src/main/java/com/jsowell/pile/mapper/` |
| `MemberCouponMapper.java` | `jsowell-pile/src/main/java/com/jsowell/pile/mapper/` |
| `CouponVerifyRecordMapper.java` | `jsowell-pile/src/main/java/com/jsowell/pile/mapper/` |
| `CouponTemplateMapper.xml` | `jsowell-pile/src/main/resources/mapper/pile/` |
| `CouponTemplateScopeMapper.xml` | `jsowell-pile/src/main/resources/mapper/pile/` |
| `MemberCouponMapper.xml` | `jsowell-pile/src/main/resources/mapper/pile/` |
| `CouponVerifyRecordMapper.xml` | `jsowell-pile/src/main/resources/mapper/pile/` |

---

## Task 3：Service 层

**状态**: ✅ 完成

### 文件清单

| 文件 | 路径 |
|------|------|
| `CouponTemplateService.java` | `jsowell-pile/src/main/java/com/jsowell/pile/service/` |
| `CouponTemplateServiceImpl.java` | `jsowell-pile/src/main/java/com/jsowell/pile/service/impl/` |
| `MemberCouponService.java` | `jsowell-pile/src/main/java/com/jsowell/pile/service/` |
| `MemberCouponServiceImpl.java` | `jsowell-pile/src/main/java/com/jsowell/pile/service/impl/` |

### 核心方法

**CouponTemplateService**
- `listForAdmin(CouponTemplate query, String merchantId)` - 后台列表（带权限过滤）
- `add(CouponTemplate template, String loginMerchantId, boolean isPlatformAdmin)` - 新增（含 scope 校验）
- `edit(CouponTemplate template, String loginMerchantId, boolean isPlatformAdmin)` - 编辑（含冻结字段校验）
- `changeStatus(Long id, Integer status, String loginMerchantId)` - 上下架

**MemberCouponService**
- `listAvailableTemplates(String memberId, Long stationId, int pageNum, int pageSize)` - 用户可兑换列表
- `exchange(String memberId, Long templateId, String requestId)` - 兑换（原子：扣积分+生成券）
- `myList(String memberId, Integer status, int pageNum, int pageSize)` - 我的券包
- `detail(String memberId, String couponNo)` - 券详情
- `verify(String couponNo, Long storeId, String requestId, String operatorId)` - 核销

---

## Task 4：管理后台 Controller

**状态**: ✅ 完成

### 文件清单

| 文件 | 路径 |
|------|------|
| `CouponTemplateController.java` | `jsowell-admin/src/main/java/com/jsowell/web/controller/pile/` |
| `CouponRecordController.java` | `jsowell-admin/src/main/java/com/jsowell/web/controller/pile/` |

---

## Task 5：用户端 API Controller

**状态**: ✅ 完成

### 文件清单

| 文件 | 路径 |
|------|------|
| `CouponController.java` | `jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/` |

---

## Task 6：Quartz 过期归档任务

**状态**: ✅ 完成

方法 `expireCoupons()` 已合并到 `JsowellTask.java`，调用目标：`jsowellTask.expireCoupons()`，Cron：`0 5 0 * * ?`

---

## 关键设计决策

1. **兑换幂等**：`member_coupon.exchange_request_id` 唯一索引，捕获 `DuplicateKeyException` 返回已有结果
2. **库存扣减**：`UPDATE ... SET stock_remain=stock_remain-1 WHERE id=? AND (stock_remain>0 OR stock_remain=-1)`
3. **积分扣减**：复用现有 `MemberPointsInfoService.deductPoints()`，`type=3`（兑换消耗）
4. **scope 校验**：查询用户可见券时 JOIN `coupon_template_scope`，通过 `idx_scope_lookup` 索引反查
5. **过期判断**：查询侧用 `expire_time > NOW()` 动态判断，Quartz 仅做离线归档
6. **二维码安全**：券详情接口返回短时签名 token（HMAC-SHA256，5分钟有效），核销接口接受 token 或 couponNo 两种方式