Просмотр исходного кода

feat(db): 优惠券分享转赠 T01 数据层——coupon_share 表(迁移494)+coupon_gift_transfer 扩展列(迁移495)

Agnes Agent 9 часов назад
Родитель
Сommit
98ca362871

+ 54 - 0
cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java

@@ -3636,6 +3636,13 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         // 新建 4 表(cf_team_share_config/cf_team_pool_order/cf_team_pool_share/cf_platform_revenue_log)
         // + ensureServiceConfig 播种 6 键 + F03c 种子(seedCfEarnRules / seedCfServiceConfig 内已含)
         migrateCfRewardV2TeamPool();
+
+        // 迁移494: 会员券分享转赠——创建 coupon_share 表(ARCH-CFC-COUPON-SHARE-GIFT-001 §4.1):
+        // 承载分享生命周期(PENDING/CLAIMED/REVOKED/EXPIRED,EXPIRED 懒判定),share_token 全局唯一
+        migrateCouponShareTable();
+
+        // 迁移495: coupon_gift_transfer 增列 share_token / claim_method(记录分享领取方式,§4.2)
+        addCouponGiftTransferShareColumns();
     }
 
 
@@ -16754,4 +16761,51 @@ log.info("迁移298: 已为无 openid 的 child 账号补齐 family_members 记
             log.warn("迁移491: data_export_request 表创建失败(忽略): {}", e.getMessage());
         }
     }
+
+    /**
+     * 迁移494: 创建会员券分享转赠记录表 coupon_share(ARCH-CFC-COUPON-SHARE-GIFT-001 §4.1)。
+     *
+     * <p>承载分享生命周期(PENDING/CLAIMED/REVOKED/EXPIRED,EXPIRED 懒判定不跑定时任务);
+     * {@code share_token} 全局唯一(uk_share_token 防碰撞);幂等(CREATE TABLE IF NOT EXISTS)。</p>
+     */
+    private void migrateCouponShareTable() {
+        try {
+            jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS coupon_share ("
+                    + "id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID', "
+                    + "share_token VARCHAR(64) NOT NULL COMMENT '全局唯一分享令牌(path/query传递)', "
+                    + "giver_user_id BIGINT NOT NULL COMMENT '赠送人用户ID(users.id)', "
+                    + "giver_family_id BIGINT NOT NULL COMMENT '赠送人家庭ID', "
+                    + "family_coupon_id BIGINT NOT NULL COMMENT '被分享的 family_coupon 实例ID', "
+                    + "coupon_id BIGINT NOT NULL COMMENT '券模板ID(coupon.id)', "
+                    + "status VARCHAR(16) NOT NULL DEFAULT 'PENDING' COMMENT 'PENDING/CLAIMED/REVOKED/EXPIRED(懒判定)', "
+                    + "claim_user_id BIGINT NULL COMMENT '领取人用户ID(users.id,领取前为NULL)', "
+                    + "claim_family_id BIGINT NULL COMMENT '领取人家庭ID(领取前为NULL)', "
+                    + "claim_time DATETIME NULL COMMENT '领取时间', "
+                    + "expire_at DATETIME NOT NULL COMMENT '分享有效期截止(创建时now+配置天数,默认7)', "
+                    + "created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', "
+                    + "updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', "
+                    + "UNIQUE KEY uk_share_token (share_token), "
+                    + "INDEX idx_giver_status (giver_user_id, status), "
+                    + "INDEX idx_family_coupon (family_coupon_id), "
+                    + "INDEX idx_status (status)"
+                    + ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='会员券分享转赠记录(分享生命周期)'");
+            log.info("迁移494: coupon_share 表已就绪(coupon.share.gift / ARCH-CFC-COUPON-SHARE-GIFT-001)");
+        } catch (Exception e) {
+            log.warn("迁移494: coupon_share 表创建失败(忽略): {}", e.getMessage());
+        }
+    }
+
+    /**
+     * 迁移495: coupon_gift_transfer 增列 share_token / claim_method(ARCH-CFC-COUPON-SHARE-GIFT-001 §4.2)。
+     *
+     * <p>记录领取方式:DIRECT=定向转赠 / SHARE=分享转赠;share_token 仅分享领取时回写(DIRECT 为 NULL)。
+     * ensureColumn 幂等,重复执行自动跳过。</p>
+     */
+    private void addCouponGiftTransferShareColumns() {
+        ensureColumn("coupon_gift_transfer", "share_token",
+                "VARCHAR(64) NULL COMMENT '分享令牌(分享转赠领取时回写 coupon_share.share_token, 定向转赠为NULL)'");
+        ensureColumn("coupon_gift_transfer", "claim_method",
+                "VARCHAR(16) NOT NULL DEFAULT 'DIRECT' COMMENT '领取方式: DIRECT=定向转赠 SHARE=分享转赠(存量行默认DIRECT)'");
+        log.info("迁移495: coupon_gift_transfer.share_token / claim_method 列已就绪");
+    }
 }

+ 6 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/CouponGiftTransfer.java

@@ -47,6 +47,12 @@ public class CouponGiftTransfer implements Serializable {
     /** GIFTED=已赠送(可撤回) / USED=已被接收方使用 / REVOKED=已撤回 */
     private String status;
 
+    /** 分享令牌:分享转赠(claimMethod=SHARE)领取时回写的 coupon_share.share_token;定向转赠为 NULL */
+    private String shareToken;
+
+    /** 领取方式:DIRECT=定向转赠 / SHARE=分享转赠(存量行默认 DIRECT,兼容历史数据) */
+    private String claimMethod;
+
     /** 赠送留言 */
     private String remark;
 

+ 67 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/CouponShare.java

@@ -0,0 +1,67 @@
+package com.etotem.cfc.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.util.Date;
+
+/**
+ * 会员券「分享转赠」记录(分享生命周期表)。
+ *
+ * <p>承载分享链路的完整状态机:{@code PENDING(待领取) → CLAIMED(已领取,终态) /
+ * REVOKED(已撤回) / EXPIRED(已过期,懒判定不跑定时任务)}。分享采用「两段式」:
+ * 先异步 {@code POST /api/coupon/gift/share/create} 生成全局唯一 {@code shareToken},
+ * 再同步 {@code onShareAppMessage} 携带 token 转发;接收人打开落地页后凭 token
+ * 浏览/领取。领取时 {@code shareToken} 会回写到 {@code coupon_gift_transfer.share_token},
+ * 与定向转赠(DIRECT)在 {@code coupon_gift_transfer.claim_method} 上区分。</p>
+ *
+ * <p>幂等与并发:同一 {@code giverUserId + familyCouponId} 已存在 PENDING 分享时,
+ * create 直接返回既有 token(不新建);claim 用「条件更新影响 1 行」原子防重领;
+ * {@code shareToken} 有全局唯一索引 {@code uk_share_token} 防碰撞。</p>
+ */
+@Data
+@TableName("coupon_share")
+public class CouponShare implements Serializable {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 全局唯一分享令牌(path/query 传递,生成规则 CS + 时间戳/随机串,长度 ≤64) */
+    private String shareToken;
+
+    /** 赠送人用户ID (users.id) */
+    private Long giverUserId;
+
+    /** 赠送人家庭ID */
+    private Long giverFamilyId;
+
+    /** 被分享的 family_coupon 实例ID */
+    private Long familyCouponId;
+
+    /** 券模板ID (coupon.id) */
+    private Long couponId;
+
+    /** PENDING=待领取 / CLAIMED=已领取(终态) / REVOKED=已撤回 / EXPIRED=已过期(懒判定) */
+    private String status;
+
+    /** 领取人用户ID (users.id),领取前为 NULL */
+    private Long claimUserId;
+
+    /** 领取人家庭ID,领取前为 NULL */
+    private Long claimFamilyId;
+
+    /** 领取时间,领取前为 NULL */
+    private Date claimTime;
+
+    /** 分享有效期截止(创建时 now + 配置天数,默认 7) */
+    private Date expireAt;
+
+    /** 创建时间 */
+    private Date createdAt;
+
+    /** 更新时间 */
+    private Date updatedAt;
+}

+ 16 - 0
cfc-backend/src/main/java/com/etotem/cfc/mapper/CouponShareMapper.java

@@ -0,0 +1,16 @@
+package com.etotem.cfc.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.etotem.cfc.entity.CouponShare;
+import org.apache.ibatis.annotations.Mapper;
+
+/**
+ * 会员券分享转赠记录 Mapper。
+ *
+ * <p>继承 {@link BaseMapper},提供常规 CRUD;claim 并发防重领走
+ * MyBatis-Plus {@code LambdaUpdateWrapper} 条件更新 + 影响行数判定,
+ * 无需自定义 XML。</p>
+ */
+@Mapper
+public interface CouponShareMapper extends BaseMapper<CouponShare> {
+}

+ 23 - 1
cfc-backend/src/main/resources/schema.sql

@@ -4958,8 +4958,10 @@ CREATE TABLE IF NOT EXISTS coupon_gift_transfer (
     receiver_family_id BIGINT NOT NULL COMMENT '接收人家庭ID',
     coupon_id BIGINT NOT NULL COMMENT '券模板ID(coupon.id)',
     family_coupon_id BIGINT NOT NULL COMMENT '被转移的 family_coupon 实例ID',
-    gift_level INT NOT NULL COMMENT '推荐层级 1=直推 2=隔级',
+    gift_level INT NOT NULL COMMENT '推荐层级 0=分享转赠 1=直推 2=隔级',
     status VARCHAR(16) NOT NULL DEFAULT 'GIFTED' COMMENT 'GIFTED/USED/REVOKED',
+    share_token VARCHAR(64) NULL COMMENT '分享令牌(分享转赠领取时回写 coupon_share.share_token, 定向转赠为NULL)',
+    claim_method VARCHAR(16) NOT NULL DEFAULT 'DIRECT' COMMENT '领取方式: DIRECT=定向转赠 SHARE=分享转赠(存量行默认DIRECT)',
     remark VARCHAR(255) NULL COMMENT '赠送留言',
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
     used_at DATETIME NULL,
@@ -4969,6 +4971,26 @@ CREATE TABLE IF NOT EXISTS coupon_gift_transfer (
     INDEX idx_family_coupon (family_coupon_id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='会员优惠券转赠记录';
 
+CREATE TABLE IF NOT EXISTS coupon_share (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    share_token VARCHAR(64) NOT NULL COMMENT '全局唯一分享令牌(path/query传递)',
+    giver_user_id BIGINT NOT NULL COMMENT '赠送人用户ID(users.id)',
+    giver_family_id BIGINT NOT NULL COMMENT '赠送人家庭ID',
+    family_coupon_id BIGINT NOT NULL COMMENT '被分享的 family_coupon 实例ID',
+    coupon_id BIGINT NOT NULL COMMENT '券模板ID(coupon.id)',
+    status VARCHAR(16) NOT NULL DEFAULT 'PENDING' COMMENT 'PENDING/CLAIMED/REVOKED/EXPIRED(懒判定)',
+    claim_user_id BIGINT NULL COMMENT '领取人用户ID(users.id,领取前为NULL)',
+    claim_family_id BIGINT NULL COMMENT '领取人家庭ID(领取前为NULL)',
+    claim_time DATETIME NULL COMMENT '领取时间',
+    expire_at DATETIME NOT NULL COMMENT '分享有效期截止(创建时now+配置天数,默认7)',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    UNIQUE KEY uk_share_token (share_token),
+    INDEX idx_giver_status (giver_user_id, status),
+    INDEX idx_family_coupon (family_coupon_id),
+    INDEX idx_status (status)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='会员券分享转赠记录(分享生命周期)';
+
 CREATE TABLE IF NOT EXISTS family_coupon_grant_log (
     id BIGINT AUTO_INCREMENT PRIMARY KEY,
     family_id BIGINT NOT NULL COMMENT '受赠家庭ID',

+ 12 - 0
docs/superpowers/api/API_REFERENCE.md

@@ -1083,6 +1083,18 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `POST /api/coupon/checkout-list` | 结算页可兑换未拥有券 |
 | `POST /api/coupon/available-templates` | 领券中心可取券模板:上架(status 空/ACTIVE)、有效期内、未领完(total_count 空/≤0 视为不限量,否则 used_count<total_count)、grant_type 为空(非自动发放/兑换)、family_id 为空(全平台模板)、本家庭未领取(family_coupon 任意状态有记录即排除)。返回 `List<Coupon>`(字段为 `id` 等模板字段),与 `/claim` 去重口径对齐(COUPON-C3) |
 
+**会员券分享转赠(`/api/coupon/gift/share/*`,ARCH-CFC-COUPON-SHARE-GIFT-001 §5)**
+
+> 在「定向转赠」之上新增「分享转赠」通道,不修改定向转赠逻辑。统一 `@PostMapping`,响应统一 `Result<T>`(code 200 成功 / 500 业务错误 / 404 资源不存在 / 401 未登录由拦截器返回),入参统一 `Map<String,Object>` + `ParamUtils`。契约先行登记,供 T02(后端接口)/T03(前端落地页)并行开工。
+
+| 路径 | 登录 | 入参 | 返回 data | 主要错误(500 + message,前端原样 toast) |
+|------|------|------|-----------|------------------------------------------|
+| `POST /api/coupon/gift/share/create` | 是 | `{ familyCouponId: Long }` | `{ shareToken, sharePath: "/pages/coupon/share-claim?shareToken=xxx", expireAt(ISO8601) }` | "参数不完整"、"请先加入家庭"、"该优惠券不可用或不属于你"、"优惠券已失效"、"优惠券已过期"、"仅会员专属券可分享";幂等:同 giver+familyCouponId 已有 PENDING → 返回既有 token(不报错) |
+| `POST /api/coupon/gift/share/detail` | **否(公开,匿名可浏览)** | `{ shareToken }` | `ShareDetailVO`: `{ shareToken, status(PENDING/CLAIMED/REVOKED/EXPIRED), couponName, couponValue, couponType, minSpend, validUntil, giverNickname, giverAvatar, expireAt, claimable(boolean) }` | 404 "分享不存在或已失效"(token 无记录) |
+| `POST /api/coupon/gift/share/claim` | 是 | `{ shareToken }` | `{ transferId: Long }` | "分享不存在或已失效"、"该分享已被领取"、"该分享已撤回"、"该分享已过期"、"优惠券已失效"、"不能领取自己分享的券"、"不能领取同家庭成员的券"、"领取失败,请联系客服";并发防重领:条件更新 PENDING→CLAIMED 影响 1 行才继续(一个 token 只能被领一次) |
+| `POST /api/coupon/gift/share/revoke` | 是 | `{ shareToken }` | `Void` | "分享不存在"、"无权操作该分享"、"该分享已被领取,无法撤回"、"该分享已撤回";仅置 status=REVOKED,不动券实例 |
+| `POST /api/coupon/gift/share/list` | 是 | `{}` | `List<ShareRecordVO>`: `[{ shareToken, couponName, couponValue, status, expireAt, claimTime, createdAt, claimNickname }]`(created_at DESC) | — |
+
 ---
 
 ### 4.33 CF 值分佣(`/api/commission/cf/*`)