Browse Source

docs(coupon-share): 优惠券分享转赠 规格文档入库(PRD+架构设计)+ T04 QA 独立验证证据链

liaoxg 8 giờ trước cách đây
mục cha
commit
2a5fe2e6b3

+ 500 - 0
docs/superpowers/specs/2026-11-15-coupon-share-gift-arch-design.md

@@ -0,0 +1,500 @@
+# CFC 会员券「分享转赠」增量架构设计 + 任务拆分
+
+- **文档编号**:ARCH-CFC-COUPON-SHARE-GIFT-001
+- **架构师**:高见远(Gao / software-architect-3)
+- **日期**:2026-11-15
+- **上游**:`2026-11-15-coupon-share-gift-prd.md`(SPEC-CFC-COUPON-SHARE-GIFT-001)
+- **类型**:增量架构设计(在现有「定向转赠」之上新增「分享转赠」通道,**不修改定向转赠逻辑**)
+- **状态**:待评审 → 交工程师实现
+
+---
+
+## 0. 决策摘要(TL;DR)
+
+| 决策点 | 结论 |
+| --- | --- |
+| 分享时序(约束 A) | **两段式**:①点「分享」→ 异步 `POST /share/create` 拿 token 存页面 data → ②浮现「发送给好友」按钮(`open-type="share"`)→ ③`onShareAppMessage` 同步返回带 shareToken 的 path。**这是唯一可落地方案**(微信禁止代码调起转发面板 + `onShareAppMessage` 必须同步返回,异步 create 与同步回调天然有时序差,必须人为拆成两步)。 |
+| create 幂等 | 同一 `giverUserId + familyCouponId` 已有 **PENDING** 分享 → **返回同一 token(不新建、不报错)**;其余情况新建。领取/撤回/过期后再次 create 可新建(此时券已不在赠送人名下,入口天然不可达,防御性校验兜底)。 |
+| 朋友圈(onShareTimeline) | **明确不支持**。`onShareTimeline` 只能带 query 不能带 path,无法直达领取页;本版本不特化该方法,避免产生无效 token。 |
+| 家庭归属(约束 B) | 已注册用户**必有家庭**(登录/注册流程 `createUserAndFamily` / `ensureUserHasFamily` 分配 family_id);未注册用户点「确认领取」→ 走既有 `login-sheet` 登录引导(登录即注册、注册即带家庭)→ 登录后继续领取;claim 仅保留 `familyId == null` 的理论兜底「领取失败,请联系客服」。**无需**自动建家庭/拒绝无家庭用户。 |
+| 数据模型 | **新建 `coupon_share` 表**承载分享生命周期(PENDING/CLAIMED/REVOKED/EXPIRED);`coupon_gift_transfer` 扩展 `share_token` / `claim_method` 两列记录领取方式。 |
+| 迁移编号 | 迁移 **486**:建 `coupon_share` 表;迁移 **487**:`coupon_gift_transfer` 增列(`ensureColumn` 幂等)。⚠️ 开工前以当时 `origin/cfclub` 最新编号为基准顺延(见 §待明确事项-1)。 |
+| 任务批次 | T01 数据层 → T02 后端接口+单测 / T03 前端(T02、T03 在 T01 后可**并行**)→ T04 联调回归。 |
+
+---
+
+## 1. 方案总览(分享链路时序)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as 赠送人(小程序)
+    participant B as CFC后端
+    participant W as 微信
+    participant C as 接收人(小程序)
+
+    Note over A,B: 阶段一:赠送人发起分享(两段式)
+    A->>B: POST /api/coupon/gift/share/create {familyCouponId}
+    B->>B: 校验券归属/范围/可用 → 幂等查 PENDING → 生成 shareToken(唯一)
+    B-->>A: Result<{shareToken, sharePath, expireAt}>
+    A->>A: token 写入页面 data → 浮现「发送给好友」按钮(open-type="share")
+    A->>W: 用户点击按钮 → 微信转发面板(onShareAppMessage 同步返回 path 含 shareToken)
+
+    Note over W,C: 阶段二:接收人打开落地页
+    W->>C: 微信卡片 → /pages/coupon/share-claim?shareToken=xxx
+    C->>B: POST /api/coupon/gift/share/detail {shareToken}(匿名可访问)
+    B-->>C: Result<ShareDetailVO>(券面值/名称/赠送人/可用状态)
+    C->>C: 未登录可见;点「确认领取」→ 未登录则 openLoginSheet() 登录(登录即注册带家庭)
+
+    Note over C,B: 阶段三:确认领取(单事务)
+    C->>B: POST /api/coupon/gift/share/claim {shareToken}(已登录)
+    B->>B: 校验 token/self/同家庭/券可用 → 条件更新 PENDING→CLAIMED(影响1行)
+    B->>B: family_coupon.familyId 改接收方家庭 + is_gift=1
+    B->>B: 写 coupon_gift_transfer(status=GIFTED, claim_method=SHARE, share_token=...)
+    B->>B: 通知赠送人(模板 coupon_gift 或新 coupon_share_claimed) + 审计 grant_log(source="share:"+shareId)
+    B-->>C: Result<{transferId}>
+
+    Note over A,B: 阶段四(可选):领取前撤回
+    A->>B: POST /api/coupon/gift/share/revoke {shareToken}
+    B->>B: PENDING→REVOKED(PENDING 阶段券仍在赠送人名下,无需回退券实例)
+    B-->>A: Result<Void>
+```
+
+---
+
+## 2. 约束 A:微信分享「同步回调 vs 异步建 token」时序(核心难点)
+
+### 2.1 微信机制约束(不可绕过)
+
+1. 小程序**不能通过代码直接调起转发面板**:必须用户点击 `<button open-type="share">`。
+2. `onShareAppMessage`(页面转发回调)**是同步函数**,微信要求它同步返回 `{title, path, imageUrl}`;回调内**无法等待** `/share/create` 的异步 HTTP 返回。
+3. 结论:**shareToken 必须在用户点击转发按钮的那一刻已经存在于页面 data 中**。异步 create 与同步回调之间存在必然时序差,因此必须在交互上拆开「异步拿 token」与「同步转发」两个动作。
+
+### 2.2 候选方案评估
+
+| 方案 | 交互 | 可行性 | 缺陷 | 结论 |
+| --- | --- | --- | --- | --- |
+| ① 预创建(进入券列表时批量 create pending token) | 列表加载时就为所有可用券 create | 技术可行 | (a) 产生大量**孤儿 PENDING**:用户未点分享也占用分享位,7 天才能自动过期;(b) 与幂等语义冲突:预创建的 PENDING 会阻塞用户真正分享的二次 create,需要额外「复用/置废」逻辑;(c) 每次进列表都打接口、浪费配额 | ❌ 不采用 |
+| ② 单按钮内联异步(点「分享」等 create 返回后代码直接分享) | 一步 | **不可行** | 微信不支持代码调起转发面板;create 返回后无法自动弹出转发 | ❌ 不可行 |
+| ③ 两段式(**选定**):点「分享」→ create 拿 token → 浮现「发送给好友」按钮(open-type="share") → 再点一次真正转发 | 两步 | 完全可行 | 多一步:用户需点两次 | ✅ **采用** |
+
+### 2.3 选定方案(两段式)落地细节
+
+- `coupons.vue` 可用券卡片动作区 `:81-84`:在「使用」「转赠」旁新增「分享」按钮。
+- 点击「分享」→ `createCouponShare(coupon.id)` → 成功后将 token 存入 `data.shareTokenMap[coupon.id]` → 该卡片按钮区切换为「发送给好友」按钮(`open-type="share"`)。
+- 页面 `onShareAppMessage()`:从 `shareTokenMap` 取当前分享目标 token,返回 `{ title: '送你一张会员券…', path: '/pages/coupon/share-claim?shareToken=' + token, imageUrl: '' }`(范式同 `pages/promotion/invite.vue:130`)。
+- create 失败(如券已失效/重复分享位被占)→ `uni.showToast` 展示后端 message,不发生转发。
+- 该方案同时天然解决「同一券同一时间仅一个待领取分享」的产品约束(P0-2)。
+
+### 2.4 create 幂等语义(拍板)
+
+```
+输入: {familyCouponId}
+逻辑:
+  1. 登录用户 giver,取 giverFamilyId;
+  2. 查询 coupon_share WHERE giver_user_id=? AND family_coupon_id=? AND status='PENDING' LIMIT 1
+     → 存在: 直接返回该行 shareToken/expireAt(不新建、不累计、不报错)
+  3. 不存在: 校验券(family_coupon 属于 giverFamily && status=AVAILABLE;
+             coupon.applicableTo=MEMBERSHIP && ACTIVE && 未过期)→ 失败抛 IllegalArgumentException
+  4. 生成 shareToken(唯一,见 §4.1),insert PENDING 行(expireAt = now + 配置天数)
+返回: {shareToken, sharePath, expireAt}
+```
+
+- 领取后(CLAIMED)/已撤回(REVOKED)/已过期:同券再次 create 视为新分享(新建 PENDING)。此时券实例已转移/仍在赠送人名下——`create` 的券校验保证只在赠送人仍持有券时可建,无需特判。
+- 并发创建同一券:两个请求同时查无 PENDING → 都 insert。为防双 PENDING,使用**业务校验 + 唯一索引兜底**:`uk_family_coupon_pending (family_coupon_id)`? 不行——同券历史分享多行,无法对 family_coupon_id 建唯一。改为:**事务内 `SELECT ... FOR UPDATE`**(按 giver_user_id 或 family_coupon_id 加锁)或接受极小概率双 PENDING(产品允许?P0-2 说“同一时间仅一个待领取”)。**拍板**:`create` 方法加 `@Transactional`,查 PENDING 用 `LambdaQueryWrapper...last("FOR UPDATE")`(锁行),serialize 并发创建;再加 share_token 全局唯一索引防 token 碰撞。这样幂等与「一券一待领」都成立。
+
+### 2.5 onShareTimeline(朋友圈)评估
+
+- `onShareTimeline` 返回结构只有 `{title, query, imageUrl}`——**没有 path 字段**;朋友圈打开的是小程序当前页/首页,无法指定直达 `/pages/coupon/share-claim`,也就无法携带「作为落地页路径」的 shareToken。
+- 结论:**本版本明确不支持朋友圈分享领券**。不特化 `onShareTimeline`(保留微信默认行为),避免用户从朋友圈点开一个无法领券的空页面。若后续产品要求朋友圈渠道,需改为「二维码/小程序码海报」方案(另立需求,涉及图片生成,P2 范畴)。
+
+---
+
+## 3. 约束 B:接收人「未加入家庭」时的券归属(已结案)
+
+**核查结果**(读取 `UserService.wechatLogin` / `silentLogin` / `phoneLogin`:
+- 新用户注册(微信登录/静默登录/手机号登录)全部走 `createUserAndFamily(user)`;登录后还有 `ensureUserHasFamily(user)` 兜底 → **已注册用户必有 family_id**(`users.family_id` 非空)。
+- `LoginResultDTO.needsFamily = familyId == null || 0L` 仅为极端脏数据兜底,正常流程不会触发。
+- 定向转赠 `CouponGiftService.transfer` 里 `receiver.getFamilyId() == null → 拒绝` 属于历史防御逻辑,定向链路**保持不动**。
+
+**落地设计(遵循主理人决策)**:
+1. **未登录可浏览领取页**:`/share/detail` 为公开接口(加入 JwtInterceptor 匿名放行,见 §4.3.2),返回券信息与 `claimable` 状态,不依赖登录态。
+2. **领取须登录**:`/share/claim` 必须带 token(拦截器 401 统一处理);前端在「确认领取」点击时判定 `uni.getStorageSync('token')` 为空 → 调既有 `this.openLoginSheet({ onSuccess: ... })`(全局 `login-sheet` mixin,登录成功回调后自动继续领取)。登录/注册即带家庭,无需额外引导「加入家庭」。
+3. **claim 后端兜底**:仅保留极低概率兜底校验——`claimUser.getFamilyId() == null` 时返回「领取失败,请联系客服」,前端提示并引导重新登录。**不做**自动建家庭/拒绝加入家庭等复杂分支。
+
+**对 PRD POI-2 的落地口径**:与 PRD 建议一致——「领取不要求已是会员/已加入家庭(家庭人人有),只要求完成注册登录」。无需修正 PRD。
+
+---
+
+## 4. 数据模型最终方案(拍板)
+
+### 4.1 新表 `coupon_share`(承载分享生命周期)
+
+| 列 | 类型 | 约束/默认 | 说明 |
+| --- | --- | --- | --- |
+| id | BIGINT | PK, AUTO_INCREMENT | |
+| share_token | VARCHAR(64) | NOT NULL, **UNIQUE** `uk_share_token` | 全局唯一分享令牌,path/query 传递,生成规则 `CS` + 时间戳/随机串(范式:现有 `UUID.randomUUID().substring(0,8).toUpperCase()` 前缀组合,长度 ≤64) |
+| giver_user_id | BIGINT | NOT NULL | 赠送人 users.id |
+| giver_family_id | BIGINT | NOT NULL | 赠送人家庭 |
+| family_coupon_id | BIGINT | NOT NULL | 被分享的 family_coupon 实例 ID |
+| coupon_id | BIGINT | NOT NULL | 券模板 ID |
+| status | VARCHAR(16) | NOT NULL DEFAULT 'PENDING' | PENDING / CLAIMED / REVOKED / EXPIRED(EXPIRED 懒判定,不跑定时任务) |
+| claim_user_id | BIGINT | NULL | 领取人 users.id |
+| claim_family_id | BIGINT | NULL | 领取人家庭 |
+| claim_time | DATETIME | NULL | 领取时间 |
+| expire_at | DATETIME | NOT NULL | 分享有效期截止(now + 配置天数,默认 7) |
+| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | |
+| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | |
+
+索引:`INDEX idx_giver_status (giver_user_id, status)`(分享记录列表/幂等查询)、`INDEX idx_family_coupon (family_coupon_id)`(反向查券)、`INDEX idx_status (status)`(运维扫描)。
+
+### 4.2 扩展 `coupon_gift_transfer`(记录领取方式)
+
+| 列 | 类型 | 约束/默认 | 说明 |
+| --- | --- | --- | --- |
+| share_token | VARCHAR(64) | NULL | 分享领取时回写分享令牌(DIRECT 为 NULL) |
+| claim_method | VARCHAR(16) | NOT NULL DEFAULT 'DIRECT' | DIRECT=定向转赠 / SHARE=分享转赠(存量行默认 DIRECT,兼容) |
+
+> 注意 `gift_level INT NOT NULL`:分享链路无推荐层级,写入 `gift_level = 0`(服务端常量 `SHARE_GIFT_LEVEL = 0`),`listSent`/`listReceived` 展示时 giftLevelLabel 已按 2 判定「隔级」、其余「直推」——分享记录不走这两个接口,不影响展示;`claim_method=SHARE` 足以区分。
+
+### 4.3 迁移编号方案(486 / 487)
+
+按 AGENTS.md 工作流:迁移唯一入口 `DatabaseInitializer.runMigrations()`,`ensureColumn` 幂等,**同步 schema.sql**。
+
+| 迁移 | 内容 | 写法 |
+| --- | --- | --- |
+| **486** | 创建 `coupon_share` 表 | `try { jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS coupon_share (...)") } catch ... log.warn 幂等容忍`;同步 `schema.sql` 追加建表语句 |
+| **487** | `coupon_gift_transfer` 增列 | `ensureColumn("coupon_gift_transfer", "share_token", "VARCHAR(64) NULL COMMENT '分享令牌'")` + `ensureColumn("coupon_gift_transfer", "claim_method", "VARCHAR(16) NOT NULL DEFAULT 'DIRECT' COMMENT 'DIRECT=定向 SHARE=分享'")`;同步 `schema.sql` 的 `CREATE TABLE coupon_gift_transfer` + 注释 |
+
+⚠️ **迁移编号校验(开工时必做)**:本机工作树当前实测最新迁移编号为 **463**(`DatabaseInitializer.java` grep `迁移[0-9]+` 最大值),与任务简报「最新 485」不一致——原因:主线 `origin/cfclub` 有 CI 自动提交持续漂移,本机工作树含大量他人 WIP 未合入。**工程师开工前**:先在**独立 worktree** 上 `git fetch origin/cfclub` 并 grep 最新迁移编号,若已 ≥486,则本设计 486/487 顺延为 `max+1`/`max+2`(保证唯一递增)。设计默认按 486/487 编写。
+
+---
+
+## 5. 接口契约最终版(PRD §3.3 补齐)
+
+统一:前缀 `/api/coupon/gift/share`,全部 `@PostMapping`,响应统一 `Result<T>`(code 200 成功 / 500 业务错误 / 404 资源不存在 / 401 未登录由拦截器返回)。入参统一 `Map<String,Object>` + `ParamUtils.getLong/getString`(项目既有风格)。
+
+| 方法 | 路径 | 登录 | 入参 | 返回 |
+| --- | --- | --- | --- | --- |
+| POST | `/api/coupon/gift/share/create` | 是 | `{ familyCouponId }` | `Result<{ shareToken, sharePath, expireAt }>` |
+| POST | `/api/coupon/gift/share/detail` | **否(公开)** | `{ shareToken }` | `Result<ShareDetailVO>` |
+| POST | `/api/coupon/gift/share/claim` | 是 | `{ shareToken }` | `Result<{ transferId }>` |
+| POST | `/api/coupon/gift/share/revoke` | 是 | `{ shareToken }` | `Result<Void>` |
+| POST | `/api/coupon/gift/share/list` | 是 | `{}` | `Result<List<ShareRecordVO>>` |
+
+### 5.1 create
+
+```
+入参: { familyCouponId: Long }
+成功 data: { shareToken: String, sharePath: "/pages/coupon/share-claim?shareToken=xxx", expireAt: String(ISO8601) }
+业务错误(500 + message,前端原样 toast):
+  - "参数不完整"
+  - "请先加入家庭"(赠送人无家庭兜底)
+  - "该优惠券不可用或不属于你"
+  - "优惠券已失效" / "优惠券已过期" / "仅会员专属券可分享"
+幂等: 同 giver+familyCouponId 已有 PENDING → 直接返回既有 shareToken(不报错)
+```
+
+### 5.2 detail(公开——匿名可浏览)
+
+```
+入参: { shareToken }
+成功 data(ShareDetailVO):
+{
+  shareToken, status: "PENDING|CLAIMED|REVOKED|EXPIRED",
+  couponName, couponValue, couponType, minSpend, validUntil,
+  giverNickname, giverAvatar,
+  expireAt, claimable: boolean(是否可点领取)
+}
+错误:
+  - 404 "分享不存在或已失效"(token 无记录)
+```
+
+实现要点:`claimable = (status==PENDING && expireAt>now && 券模板 ACTIVE && 未过券有效期)`;无论登录与否都可调用;登录用户额外返回 `viewerCanClaim`(是否自己/同家庭)供前端预置灰——简单起见前端以 claim 返回为准,detail 只给 `claimable`。
+
+### 5.3 claim(并发防重领 = 本次设计核心)
+
+```
+入参: { shareToken }
+成功 data: { transferId }
+错误(500 + message):
+  - "分享不存在或已失效"
+  - "该分享已被领取"          ← 条件更新影响 0 行 / 已是 CLAIMED
+  - "该分享已撤回"
+  - "该分享已过期"
+  - "优惠券已失效"
+  - "不能领取自己分享的券"
+  - "不能领取同家庭成员的券"
+  - "领取失败,请联系客服"     ← familyId 空的理论兜底
+```
+
+**并发防重领 SQL(Mapper 写法)**——核心:用**条件更新 + 影响行数**判定,保证"一个 token 只能被领一次":
+
+```java
+// CouponShareMapper 直接走 MyBatis-Plus LambdaUpdateWrapper(无需自定义 XML):
+int updated = couponShareMapper.update(null, new LambdaUpdateWrapper<CouponShare>()
+        .eq(CouponShare::getShareToken, shareToken)
+        .eq(CouponShare::getStatus, "PENDING")
+        .set(CouponShare::getStatus, "CLAIMED")
+        .set(CouponShare::getClaimUserId, claimUserId)
+        .set(CouponShare::getClaimFamilyId, claimFamilyId)
+        .set(CouponShare::getClaimTime, now));
+if (updated != 1) {
+    throw new IllegalArgumentException("该分享已被领取"); // 并发第二个请求/已被别人领走/已撤回
+}
+```
+
+等价 SQL(供 DBA 审阅):`UPDATE coupon_share SET status='CLAIMED', claim_user_id=?, claim_family_id=?, claim_time=? WHERE share_token=? AND status='PENDING'`——**影响行数=1 才继续**。
+
+**事务边界(claim 单事务,`@Transactional`)**:
+① 校验(share 行存在性/self/同家庭/券可用——含 `SELECT ... FOR UPDATE` 防 create 与 claim 竞态无必要,claim 用条件更新已原子)→ ② **条件更新 PENDING→CLAIMED(影响 1 行才继续)** → ③ `family_coupon.familyId` 改领取人家庭 + `is_gift=1`(`familyCouponMapper.updateById(fc)`)→ ④ 插入 `coupon_gift_transfer`(status=GIFTED、claim_method=SHARE、share_token、gift_level=0)→ ⑤ 通知赠送人 → ⑥ `family_coupon_grant_log`(grant_type=GIFT_TRANSFER、source="share:"+shareId)。②~⑥ 任一失败整体回滚(②的条件更新随事务回滚,一致性不破)。
+
+### 5.4 revoke
+
+```
+入参: { shareToken }
+成功: Result<Void>
+错误:
+  - "分享不存在" / "无权操作该分享"(非赠送人)
+  - "该分享已被领取,无法撤回"(CLAIMED 终态)
+  - "该分享已撤回"
+说明: PENDING 阶段券仍在赠送人名下 → 仅置 status=REVOKED(+ updated_at),**不动券实例**(与定向 transfer.revoke 回退券不同)
+```
+
+### 5.5 list(我的分享记录,P1-2 用)
+
+```
+入参: {}
+成功 data(List<ShareRecordVO>): [{ shareToken, couponName, couponValue, status, expireAt, claimTime, createdAt, claimNickname }]
+排序: created_at DESC
+```
+
+---
+
+## 6. 复用与抽取(保证不破坏定向转赠)
+
+### 6.1 抽取共享方法(从 `CouponGiftService.transfer` 抽取)
+
+share 与 transfer 共有的尾段(券实例转移 + transfer 记录 + 通知 + 审计)从 `CouponGiftService.transfer`(现行 208-306 行)抽取为**新方法**,定向 `transfer()` 改为调用它(行为不变,`claimMethod=DIRECT`):
+
+```java
+// CouponGiftService 新增(public,供 CouponShareService 复用电话)
+/**
+ * 提交券实例转移 + transfer 记录 + 通知 + 审计流水。
+ * 调用方必须在事务中(@Transactional 传播 REQUIRED 合并)。
+ *
+ * @param giverUserId     赠送人 users.id
+ * @param giverFamilyId   赠送人家庭
+ * @param receiverUserId  接收人 users.id
+ * @param receiverFamilyId 接收人家庭(券实例最终归属)
+ * @param couponId        券模板 id
+ * @param familyCouponId  family_coupon 实例 id
+ * @param giftLevel       推荐层级(定向:1/2,分享:0)
+ * @param claimMethod     "DIRECT" | "SHARE"
+ * @param shareToken      分享领取时回写,定向为 null
+ * @param remark          留言(可空)
+ * @return transferId
+ */
+public Long commitTransfer(Long giverUserId, Long giverFamilyId,
+                           Long receiverUserId, Long receiverFamilyId,
+                           Long couponId, Long familyCouponId,
+                           Integer giftLevel, String claimMethod,
+                           String shareToken, String remark);
+```
+
+要点:
+- `transfer()` 前置校验(赠送人/券校验/接收人校验/推荐树校验)**原样保留**,只把 254-301 行尾段替换为 `return commitTransfer(...)`;`claimMethod="DIRECT"`、`shareToken=null`、`giftLevel=referral.getLevel()`。
+- `commitTransfer` 内部:`fc.setFamilyId + setIsGift(1) + updateById` → 组装 `CouponGiftTransfer`(新增字段 `setShareToken`/`setClaimMethod`)insert → 通知(模板 `coupon_gift`)→ grant log(`source="transfer:"+id` 维持;分享用 `"share:"+shareId` 由 CouponShareService 自行写或由 commitTransfer 透传 source 前缀——**简化**:`commitTransfer` 的 grant log source 仍用 `"transfer:"+transferId`,分享链路同样记 GIFT_TRANSFER,审计口径与定向一致,PC 查询/对账无差别)。
+- `revoke(transferId, userId)`、`markUsedByFamilyCouponId`:**不改**。分享券领取后即成为普通 GIFTED 记录,核销走既有 `markUsedByFamilyCouponId` 置 USED(`CouponService.markUsed` 回调)——自动兼容。
+
+### 6.2 分享侧专属方法(新 `CouponShareService`)
+
+```java
+@Service
+public class CouponShareService {
+    @Resource private CouponShareMapper couponShareMapper;
+    @Resource private FamilyCouponMapper familyCouponMapper;
+    @Resource private CouponMapper couponMapper;
+    @Resource private UserMapper userMapper;
+    @Resource private CouponGiftService couponGiftService;   // 复用 commitTransfer
+    @Resource private NotificationDispatchService notificationDispatchService;
+    @Resource private FamilyCouponGrantLogMapper familyCouponGrantLogMapper;
+
+    public Map<String,Object> create(Long giverUserId, Long familyCouponId);           // 幂等
+    public Map<String,Object> detail(String shareToken, Long viewerUserId /*可空*/);
+    public Long claim(Long claimUserId, String shareToken);                            // @Transactional
+    public void revoke(Long giverUserId, String shareToken);
+    public List<Map<String,Object>> list(Long giverUserId);
+    private static final int SHARE_GIFT_LEVEL = 0;
+    private static final int DEFAULT_EXPIRE_DAYS = 7; // 可配置 coupon.share.expire-days
+}
+```
+
+---
+
+## 7. 前端设计
+
+### 7.1 新页面 `/pages/coupon/share-claim`(落地领取页)
+
+注册:`pages.json` 新增分包 `{ "root": "pages/coupon", "pages": [{ "path": "share-claim", "style": { "navigationBarTitleText": "好友送你一张会员券" } }] }`(跟随 `pages/invite` 分包先例,分享 path 指向分包页面微信兼容)。
+
+结构:
+```
+<template>
+  <view class="page">
+    <login-sheet ref="loginSheet" @success="onSheetLoginSuccess" />   <!-- 登录浮层 -->
+    loading / 失效态 / 正常态
+    正常态: 券卡片(面值/名称/条件/有效期) + 赠送人昵称头像 + [确认领取](primary)
+    失效态: 券卡片置灰 + 文案(按 status 区分: 已被领取/已撤回/已过期/券已失效/分享不存在) + [知道了]
+  </view>
+</template>
+onLoad(options):
+  this.shareToken = options.shareToken
+  this.detail = await getCouponShareDetail(this.shareToken)  // 匿名可调
+  渲染状态
+onConfirmClaim():
+  if (!uni.getStorageSync('token')) { this.openLoginSheet({ onSuccess: this.doClaim }); return }
+  this.doClaim()
+doClaim():
+  res = await claimCouponShare(this.shareToken)
+  code===200 → toast「领取成功」→ 跳转券包或返回
+  否则 → 按 res.message 展示失效态(按钮置灰)
+```
+
+- 前端禁止:可选链、CSS Grid、`:key` 表达式、`new Date(string)`(用 `utils/format.js` 的 `parseDate()`)。
+- 登录利用既有机制:`login-sheet` 组件 + `login-sheet` mixin(全局注册于 main.js),页面挂 `<login-sheet>` 后直接 `this.openLoginSheet()`;`api.js` 对 401 已有静默续期/排队重放机制,无需自造。
+
+### 7.2 `coupons.vue` 改造点
+
+- 模板 `:81-84`(`tabIndex === 0 && AVAILABLE` 的 `.coupon-actions`):`<button class="share-btn" @click="prepareShare(coupon)">分享</button>` 与「使用」「转赠」并列;券已生成 token 时该按钮替换为 `<button class="share-btn" open-type="share" @tap="setShareTarget(coupon)">发送给好友</button>`。
+- `data` 新增:`shareTokenMap: {}`(couponId → token)、`shareTarget: null`。
+- methods:
+  - `prepareShare(coupon)`:若 `shareTokenMap[coupon.id]` 已存在直接置 `shareTarget`;否则 `createCouponShare(coupon.id)`(uni.showLoading)→ 成功写 map 并 `shareTarget=coupon`;失败 toast 后端 message。
+  - `setShareTarget(coupon)`:记录当前分享目标(供 `onShareAppMessage` 取 token)。
+  - `onShareAppMessage()`:`var t = this.shareTokenMap[this.shareTarget && this.shareTarget.id]`;有 t → 返回 `{ title:'送你一张「'+coupon.name+'」会员券,快来领取', path:'/pages/coupon/share-claim?shareToken='+t, imageUrl:'' }`;无 → 返回默认(不分享)。
+- 备注:关于「两次点击」——第一次点「分享」完成 create 后按钮变为「发送给好友」(open-type="share"),第二次点击才触发微信转发面板(约束 A 结论必选)。
+
+### 7.3 `gift-coupon.vue`「分享记录」tab(P1-2,建议随 P0 一并做)
+
+- `:102` `tabs` 增加 `{ name: '分享记录' }`;`switchTab` 逻辑不变。
+- 新 tab 渲染 `shareList`:复用 `sent-item` 卡片样式,展示 `couponName / statusLabel(status)(待领取/已领取/已撤回/已过期) / expireAt / claimNickname`;PENDING 行提供「撤回」按钮调 `revokeCouponShare`。
+- `loadShares()` 调 `getCouponShareList()`。
+- 若排期紧可裁剪(P1),不影响 P0 闭环;**建议做**(改动 ~60 行,均为列表渲染)。
+
+### 7.4 `utils/api.js` 新增(`:2696` 会员优惠券转赠段之后)
+
+```js
+// ===== 会员券分享转赠 =====
+export const createCouponShare = (familyCouponId) => request('/api/coupon/gift/share/create', 'POST', { familyCouponId })
+export const getCouponShareDetail = (shareToken) => request('/api/coupon/gift/share/detail', 'POST', { shareToken })
+export const claimCouponShare = (shareToken) => request('/api/coupon/gift/share/claim', 'POST', { shareToken })
+export const revokeCouponShare = (shareToken) => request('/api/coupon/gift/share/revoke', 'POST', { shareToken })
+export const getCouponShareList = () => request('/api/coupon/gift/share/list', 'POST', {})
+```
+
+### 7.5 登录态处理(既有机制,不自造)
+
+- `api.js` 请求层已内置:401 → 静默续期(`silentRelogin`)→ 失败 `reLaunch('/pages/login/login')`;页面侧统一用全局 `login-sheet` mixin 的 `this.openLoginSheet({ onSuccess })`。
+- 落地页挂 `<login-sheet>`;`/share/claim` 未登录直接命中 401 由请求层处理;前端预判 `token` 为空先弹登录浮层、登录成功回调里再发 claim——**两条路径都成立**。
+
+---
+
+## 8. 文件清单(新增/修改,相对路径 + 意图 + 预估行数)
+
+| 文件 | 类型 | 意图 | 预估 |
+| --- | --- | --- | --- |
+| `cfc-backend/src/main/java/com/etotem/cfc/entity/CouponShare.java` | 新增 | 分享表实体(@TableName("coupon_share")/@TableId AUTO) | +80 |
+| `cfc-backend/src/main/java/com/etotem/cfc/entity/CouponGiftTransfer.java` | 修改 | 新增 `shareToken`/`claimMethod` 字段 | +10 |
+| `cfc-backend/src/main/java/com/etotem/cfc/mapper/CouponShareMapper.java` | 新增 | Mapper 接口(继承 BaseMapper<CouponShare>) | +10 |
+| `cfc-backend/src/main/java/com/etotem/cfc/service/CouponShareService.java` | 新增 | create/detail/claim/revoke/list + 幂等/并发/事务 | +280 |
+| `cfc-backend/src/main/java/com/etotem/cfc/service/CouponGiftService.java` | 修改 | 抽取 `commitTransfer`;transfer 改调之(行为不变) | ±40 |
+| `cfc-backend/src/main/java/com/etotem/cfc/controller/CouponGiftController.java` | 修改 | 新增 5 个 share 端点(方法级 @PostMapping) | +70 |
+| `cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java` | 修改 | 迁移 486(建 coupon_share)、487(增列 ensureColumn) | +70 |
+| `cfc-backend/src/main/resources/schema.sql` | 修改 | 同步 coupon_share 建表 + coupon_gift_transfer 两列 | +25 |
+| `cfc-backend/src/main/java/com/etotem/cfc/config/JwtInterceptor.java` | 修改 | PUBLIC_PATHS 增加 `/api/coupon/gift/share/detail`(匿名浏览) | +1 |
+| `cfc-backend/src/test/java/com/etotem/cfc/unit/CouponShareClaimContractTest.java` | 新增 | 契约单测(Mockito 风格) | +260 |
+| `docs/superpowers/api/API_REFERENCE.md` | 修改 | 登记 5 接口(AGENTS.md 要求新增接口前查/登记) | +40 |
+| `cfc-frontend/pages/coupon/share-claim.vue` | 新增 | 落地领取页 | +260 |
+| `cfc-frontend/pages.json` | 修改 | 注册分包 root=pages/coupon + share-claim 页 | +10 |
+| `cfc-frontend/pages/profile-extra/coupons.vue` | 修改 | 分享按钮/发送给好友按钮/onShareAppMessage/token map | ±60 |
+| `cfc-frontend/pages/membership/gift-coupon.vue` | 修改 | 分享记录 tab(P1-2) | ±60 |
+| `cfc-frontend/utils/api.js` | 修改 | 5 个新接口封装 | +10 |
+
+---
+
+## 9. 任务拆分(有序,含依赖/并行/验收)
+
+> 工程实现纪律(写给工程师):**严禁**在 `E:/cfc` 主树 checkout/stash/reset/add -A/clean(他人 WIP 约 1093 处);基于 `origin/cfclub` 建**独立 worktree**,单文件逐一入库;主线 CI 自动提交持续漂移,迁移编号、rebase 基准开工时再核。
+
+| 任务 | 内容 | 依赖 | 验收标准 | 可并行 |
+| --- | --- | --- | --- | --- |
+| **T01 数据层** | CouponShare 实体 + Mapper;CouponGiftTransfer 增字段;DatabaseInitializer 迁移 486/487;schema.sql 同步;API_REFERENCE 接口登记(契约先行) | 无 | `mvn clean compile` 通过;测试库重复执行迁移幂等(第二次 0 报错);schema.sql 与迁移一致;API_REFERENCE 5 接口登记 | — |
+| **T02 后端接口 + 单测** | CouponGiftService 抽取 commitTransfer(transfer 改调);CouponShareService;CouponGiftController 5 端点;JwtInterceptor 公开 detail;契约单测 | T01 | `mvn test` 通过;契约测试覆盖 §10.1 全部场景;定向转赠契约(若有存量)回归 GREEN;curl 冒烟 create/detail/claim/revoke/list 主流程 | 与 T03 并行 |
+| **T03 前端落地页 + 入口** | share-claim.vue + pages.json 注册;coupons.vue 分享入口 + onShareAppMessage;api.js 封装;gift-coupon 分享记录 tab(P1-2) | T01 | 微信开发者工具:未登录可浏览领取页;点领取弹登录浮层;分享→「发送给好友」→ 转发 path 含 token;失效态文案正确 | 与 T02 并行 |
+| **T04 联调/回归** | 端到端验证 PRD §6 九场景 + 定向转赠全链路回归 + 并发防重领验证 | T02, T03 | PRD §6 全部预期达成;定向转赠(coupons→gift-coupon→transfer/revoke/sent)行为与改动前一致;双端并发领同 token 仅一人成功 | — |
+
+依赖图:
+
+```mermaid
+graph LR
+    T01[T01 数据层] --> T02[T02 后端接口+单测]
+    T01 --> T03[T03 前端落地页+入口]
+    T02 --> T04[T04 联调回归]
+    T03 --> T04[T04 联调回归]
+```
+
+并行提示:T02 与 T03 均在 T01 后立即并行开工(接口契约以 T01 登记的 API_REFERENCE 为准,前端可先行 mock)。
+
+---
+
+## 10. 测试要求
+
+### 10.1 后端契约单测场景清单(`CouponShareClaimContractTest`,纯 Mockito 无 Spring 上下文,风格参考 `ShopCouponClaimContractTest`)
+
+1. **create 正常**:返回 shareToken/sharePath/expireAt;`coupon_share` insert 1 行 PENDING,expireAt = now + 7 天。
+2. **create 幂等**:同 giver+familyCouponId 已有 PENDING → 返回既有 token,不新增行。
+3. **create 校验**:券不属于我 / 非 MEMBERSHIP / 非 ACTIVE / 已过期 → 对应文案。
+4. **detail 正常**:PENDING → 返回券信息 + claimable=true(匿名可调)。
+5. **detail 失效态**:CLAIMED/REVOKED/EXPIRED / token 不存在 → claimable=false + 对应状态。
+6. **claim 成功**:条件更新影响 1 行 → family_coupon.familyId 变更 + is_gift=1;transfer 记录 status=GIFTED、claimMethod=SHARE、shareToken 回写、giftLevel=0;通知与 grant log 各触发 1 次。
+7. **claim 并发防重领**:模拟条件更新影响 0 行(第二次 claim)→ 抛「该分享已被领取」,transfer 不重复写。
+8. **claim 校验**:领取人=赠送人 / 同家庭 / 已撤回 / 已过期 / 券失效 → 各自文案;claim 请求无 familyId → 「领取失败,请联系客服」。
+9. **revoke**:PENDING→REVOKED(不动券);CLAIMED 后 revoke → 报错;非赠送人 revoke → 无权。
+10. **list**:仅返回本人分享记录,按 created_at 倒序。
+
+### 10.2 前端验证方式(微信开发者工具手测)
+
+- 未登录:落地页可浏览;点领取弹登录浮层;登录成功自动续领。
+- 登录:券列表「分享」→ loading →「发送给好友」→ 转发面板出现;接收方打开领取成功。
+- 失效态:被领/已撤回/过期/券失效 四种文案与置灰。
+- 回归:定向转赠三步流程(recipients/my-coupons/transfer/revoke/sent)不变。
+
+---
+
+## 11. 共享知识(跨文件约定)
+
+- **字段命名**:DB 列 snake_case;Java 实体驼峰(MyBatis-Plus 自动映射);前端 JS/DTO 驼峰 `shareToken`/`claimMethod`/`familyCouponId`;接口返回统一 camelCase。
+- **响应**:统一 `Result<T>`;code=200 成功;500 业务错误(`message` 即用户可见文案,前端直接 toast,不硬编码);404 token 不存在;401 由拦截器统一处理(前端请求层静默续期/跳登录)。
+- **错误文案常量**:集中在 `CouponShareService` 的 `private static final String`(如 `MSG_ALREADY_CLAIMED = "该分享已被领取"`),测试与 Controller 复用。
+- **状态机**:`coupon_share.status`: PENDING → CLAIMED(终态)/ REVOKED / EXPIRED(懒判定);`coupon_gift_transfer.status` 沿用 GIFTED→USED/REVOKED。
+- **时间**:后端存 DATETIME(ISO8601 返回),前端展示用 `utils/format.js` 的 `parseDate()` 与 `yyyy-MM-dd HH:mm:ss` 格式,禁 `new Date(string)`、禁 `toLocaleString`。
+- **小程序禁用**:可选链 `?.`、CSS Grid、`:key` 表达式、Composition API。
+- **DI**:`@Resource` 替代 `@Autowired`;**接口**:新增路由前 grep 查重;统一 `@PostMapping`。
+- **迁移**:编号全局唯一递增、`ensureColumn` 幂等、同步 schema.sql、迁移可重复执行。
+- **审计**:分享与定向统一记 `family_coupon_grant_log.grant_type=GIFT_TRANSFER`(source 区分 `transfer:id` / 分享沿用 `transfer:id` 亦可,便于对账)。
+
+---
+
+## 12. 待明确事项(供主理人/产品拍板,≤5 条)
+
+| # | 事项 | 默认建议 |
+| --- | --- | --- |
+| 1 | **迁移编号基数不一致**:任务简报 485 vs 本机工作树实测 463(主线 CI 持续漂移) | 设计按 486/487;**开工时以 `origin/cfclub` 最新编号顺延 `max+1`/`max+2`**,工程师在 worktree 内 grep 复核 |
+| 2 | P1-2 分享记录 tab 是否随 P0 一起交付 | **做**(改动小,且在 gift-coupon.vue 一处完成,避免二次触碰该文件) |
+| 3 | 朋友圈(onShareTimeline)渠道 | **本期不支持**(无法携带 path);如需,另立小程序码海报需求(P2) |
+| 4 | token 有效期配置项 | `coupon.share.expire-days` 默认 7;本期先落常量 + application.yml/db config 占位,改配置走运营口后可放开 |
+| 5 | 是否需要「自动过期」定时任务 | **不做**:detail/claim 懒判定 + 列表 DISPLAY 过滤(PENDING 且未过期)即可,避免新增调度器 |
+
+---
+
+*(本文档为纯设计产物,未修改任何业务代码文件;落盘于主工作树 docs 目录下,工程师实现须用独立 worktree 单文件入库。)*

+ 194 - 0
docs/superpowers/specs/2026-11-15-coupon-share-gift-prd.md

@@ -0,0 +1,194 @@
+# CFC 会员券「分享转赠」增量 PRD
+
+- **文档编号**:SPEC-CFC-COUPON-SHARE-GIFT-001
+- **产品经理**:许清楚(Xu)
+- **日期**:2026-11-15
+- **类型**:增量 PRD(在现有「定向转赠」之上**新增**分享转赠通道,不替换)
+- **状态**:草案(待架构评审 / POI 决策)
+
+---
+
+## 1. 项目信息
+
+| 项 | 值 |
+| --- | --- |
+| 语言 | 中文 |
+| 技术栈 | 小程序(uni-app / Vue)+ Spring Boot 后端 |
+| 项目标识 | `cfc_coupon_share_gift` |
+| 原始需求复述 | CFC 会员券新增「分享转赠」通道:用户点转赠时**调用微信小程序分享功能**,将「优惠券领取页」分享给微信好友;接收人打开分享页,在页面上点「确认领取」后领取优惠券。原有「定向转赠」(选推荐下级赠送)完整保留,本次为新增功能。 |
+
+---
+
+## 2. 产品定义
+
+### 2.1 产品目标(一句话)
+
+**让用户把会员券当作一份「礼物」分享给微信好友**——既帮助会员盘活闲置会员券资产、完成券资产的社会化流转(促活/留量),又通过好友打开领取页为平台带来新用户进入与券核销转化(获客/转化),同时不破坏现有定向转赠链路。
+
+### 2.2 用户故事
+
+1. **作为会员(赠送人)**,我想从券列表/券详情把一张可用会员券「分享转赠」给微信好友,这样好友能通过微信卡片打开领取页领券。
+2. **作为微信好友(接收人)**,我想打开分享卡片看到券面值/名称/赠送人/剩余可用信息,并点「确认领取」,这样我就能把这张券领进自己的券包。
+3. **作为接收人**,当券已被他人领取 / 已被赠送人撤回 / 已过期 / 已失效时,我希望页面给出明确提示,避免误操作。
+4. **作为赠送人**,我想在好友领取前撤回分享,这样券能退回我的券包、避免被不需要的人领走。
+5. **作为非会员接收人**,我希望领取后也能用这张券购买会员,这样券对我仍然有价值。
+
+---
+
+## 3. 技术规范
+
+### 3.1 需求池
+
+#### P0(Must have,本次核心闭环)
+
+| 编号 | 需求 | 验收标准 / 可测量 |
+| --- | --- | --- |
+| P0-1 | **赠送人发起分享(入口 + 调起微信分享)**:券列表/券详情卡片新增「分享」入口,与现有「转赠」(定向)按钮并列;点击后生成领取标识(shareToken)并调起微信分享(`onShareAppMessage`),分享卡片 `path` 携带 shareToken,`title`/`imageUrl` 定制化 | 可用券卡片出现「分享」与「转赠」两个并列按钮;点击「分享」调起微信转发面板;分享卡片 path 含 shareToken;title 含券名称/赠送人信息 |
+| P0-2 | **后端创建分享**:`POST /api/coupon/gift/share/create`,根据 familyCouponId 生成唯一 shareToken,记录分享,返回 token | 接口返回 shareToken;同一券在同一时间仅存在一个「待领取」分享;token 全局唯一、幂等(重复创建返回同一或报错) |
+| P0-3 | **接收人落地页**:微信卡片进入小程序领取页(新页面,如 `/pages/coupon/share-claim`),`onLoad` 读取 shareToken,调用 `POST /api/coupon/gift/share/detail` 拉取券信息 | 领取页展示券面值/名称/赠送人昵称/剩余可用时间;异常 token 展示失效态 |
+| P0-4 | **确认领取**:点「确认领取」→ `POST /api/coupon/gift/share/claim`,将 `family_coupon` 券实例 familyId 改为接收方家庭 + `is_gift=1`,写 `coupon_gift_transfer` 记录(status=GIFTED、领取方式=SHARE),发通知、审计流水 | 领取成功后接收人券包出现该券;transfer 记录 status=GIFTED 且领取方式=SHARE;赠送人收到「已被领取」通知;审计流水完整 |
+| P0-5 | **领取校验与错误态**:shareToken 幂等(一个分享只能领取一次,他人先领则提示已被领取);领取人不能是自己;已撤回/券已失效/已过期时页面给出明确提示 | 二次领取返回「该分享已被领取」;领取人=赠送人返回「不能领取自己分享的券」;已撤回/过期/失效分别有对应文案与失效态 UI |
+| P0-6 | **入口区分**:现有「转赠」(定向,跳 `gift-coupon`)按钮完整保留;新增「分享」入口文案与去向明确区分 | 「转赠」仍跳转定向转赠页;「分享」调起微信分享;两入口视觉/文案可辨识 |
+| P0-7 | **同家庭不可领取**:领取人与赠送人属于同一家庭时拒绝领取 | 返回「不能领取同家庭成员的券」 |
+
+#### P1(Should have,体验增强)
+
+| 编号 | 需求 | 说明 |
+| --- | --- | --- |
+| P1-1 | **撤回分享**:赠送人在好友领取前可撤回分享(置分享状态 REVOKED,券退回可再次使用) | 领取成功后不可撤回;撤回后接收人页面显示「分享已撤回」 |
+| P1-2 | **分享记录展示**:`gift-coupon` 页新增「分享记录」tab,展示分享状态(待领取/已领取/已撤回/已过期) | 复用现有「赠送记录」tab 结构扩展 |
+| P1-3 | **未登录/未注册接收人处理**:新用户进入领取页可查看券信息,但点「确认领取」时引导登录;登录后继续领取 | 未登录不阻断浏览,仅阻断领取动作 |
+| P1-4 | **分享 token 有效期**:默认 7 天,可配置;过期后不可领取 | 建议走配置项,便于运营调整 |
+
+#### P2(Nice to have,长期增强)
+
+| 编号 | 需求 | 说明 |
+| --- | --- | --- |
+| P2-1 | **管理员后台查看分享记录**:列表/状态/统计(发起量、领取量、核销量、转化率) | 复用现有 admin 接口模式 |
+| P2-2 | **领取页品牌化设计**:领取页视觉与 CFC 品牌一致(含动效) | 视觉体验 |
+| P2-3 | **分享卡片自定义图片**:imageUrl 使用券面视觉图,提升打开率 | A/B 可测 |
+
+### 3.2 数据模型建议(供架构师决策)
+
+> 结论:**建议新建独立分享表承载分享生命周期,`coupon_gift_transfer` 扩展列记录领取方式**。理由:定向转赠链路保持不动;分享链路有独立生命周期(创建→待领取→已领取/已撤回/已过期)且与 transfer 关系为一对一/一对多(一个分享可被多次查看、最终一次领取);领取成功后落 transfer 记录,便于统一查询。
+
+建议表结构(示意,最终由架构师定):
+
+**新表 `coupon_share`**(或 `coupon_gift_share`):
+- `id` / `shareToken`(唯一) / `giverUserId` / `giverFamilyId` / `familyCouponId` / `couponId`
+- `status`(PENDING / CLAIMED / REVOKED / EXPIRED)
+- `claimUserId` / `claimFamilyId` / `claimTime`
+- `expireAt` / `createdAt` / `remark`
+
+**扩展 `coupon_gift_transfer`**:
+- `shareToken`(可空) / `claimMethod`(`DIRECT` 定向 / `SHARE` 分享)
+- 复用 `coupon_gift_transfer` 现有迁移能力(`ensureColumn` 幂等),需同步 `schema.sql`。
+
+### 3.3 接口契约(建议,供架构师定)
+
+| 方法 | 路径 | 入参 | 返回 |
+| --- | --- | --- | --- |
+| POST | `/api/coupon/gift/share/create` | `{ familyCouponId }` | `Result<{ shareToken, sharePath, expireAt }>` |
+| POST | `/api/coupon/gift/share/detail` | `{ shareToken }` | `Result<ShareDetail>`(券面值/名称/赠送人/剩余可用/状态) |
+| POST | `/api/coupon/gift/share/claim` | `{ shareToken }` | `Result<Void>` |
+| POST | `/api/coupon/gift/share/revoke` | `{ shareToken }` | `Result<Void>` |
+| POST | `/api/coupon/gift/share/list` | `{}` | `Result<List<ShareRecord>>` |
+
+> 注:统一 `@PostMapping`、统一响应 `Result<T>`;DB 迁移唯一入口 `DatabaseInitializer.runMigrations()`(当前最新迁移编号 485,用 `ensureColumn` 幂等,必须同步 `schema.sql`)。
+
+### 3.4 UI 设计稿(文字线框)
+
+#### A. 赠送人发起分享交互
+
+```
+[券卡片]
+┌──────────────────────────────────┐
+│ ¥50   │ 会员体验券              │
+│ 会员券 │ 满99元可用 · 会员专享    │
+│       │ 有效期至 2026.12.31      │
+│       │  [使用]  [转赠]  [分享] │  ← 新增「分享」按钮与「转赠」并列
+└──────────────────────────────────┘
+点击「分享」→ 生成 shareToken → 调起微信转发面板
+```
+
+#### B. 接收人领取页(正常态)
+
+```
+┌──────────────────────────────────┐
+│  ← 返回                          │
+│        🎁 好友送你一张会员券      │
+│  ┌────────────────────────────┐  │
+│  │  ¥50                        │  │
+│  │  会员体验券                  │  │
+│  │  满99元可用 · 会员专享        │  │
+│  │  有效期至 2026.12.31        │  │
+│  └────────────────────────────┘  │
+│  赠送人:小浠(会员)             │
+│  [ 确认领取 ]  ← 主按钮          │
+│  提示:领取后可用于购买会员       │
+└──────────────────────────────────┘
+```
+
+#### C. 接收人领取页(失效态)
+
+```
+┌──────────────────────────────────┐
+│  ← 返回                          │
+│        🎁 分享已失效              │
+│  ┌────────────────────────────┐  │
+│  │  ¥50  (置灰)                │  │
+│  │  会员体验券                  │  │
+│  └────────────────────────────┘  │
+│  ⚠ 已被领取 / 已撤回 / 已过期    │  ← 按场景文案区分
+│  [ 知道了 ]                      │
+└──────────────────────────────────┘
+```
+
+---
+
+## 4. POI(关键待确认 / 决策点)
+
+| # | 决策点 | 建议 |
+| --- | --- | --- |
+| POI-1 | 分享 token 有效期 | 默认 **7 天**,走配置项可调(如 `coupon.share.expire-days`) |
+| POI-2 | 领取人是否要求已注册/已加入家庭? | 建议:**未登录可查看领取页,但领取须登录**;新用户点「确认领取」引导登录后继续领取;**不要求**领取人已加入家庭,领取即获券(与定向转赠一致,非会员也可用于购买会员) |
+| POI-3 | 领取后赠送人是否可撤回? | 建议:**领取成功前可撤回,领取后不可**(状态机 PENDING→CLAMED 后锁定) |
+| POI-4 | 分享入口放哪? | 建议:**券列表/券详情卡片加「分享」按钮并列「转赠」**为主路径(即点即发,无需表单页);`gift-coupon` 页**不加发起分享 tab**,仅新增「分享记录」tab(P1-2) |
+| POI-5 | 扩展原表 vs 新建分享表? | 建议:**新建 `coupon_share` 表**承载分享 token/状态/有效期;`coupon_gift_transfer` 仅扩展 `shareToken`/`claimMethod` 列记录领取方式(最终由架构师定) |
+
+---
+
+## 5. 边界与规则
+
+1. **同家庭不可领取**:领取人与赠送人同家庭时拒绝(`P0-7`)。
+2. **一单一人**:一个分享 token 只能被领取一次,领取后状态锁定。
+3. **可分享券范围**:建议与定向转赠一致——**仅 `MEMBERSHIP` 适用且状态为 `AVAILABLE` 的会员券**可分享(复用 `getGiftableCoupons` 的过滤逻辑)。理由:定向转赠已限定会员券范围,分享作为同域通道应保持一致,避免口径分裂。
+4. **一单一券**:一次分享对应一张 `family_coupon` 券实例,领取后该实例 familyId 变更、`is_gift=1`,与定向转赠规则一致。
+5. **非会员接收人**:领取后也可用该券购买会员(与定向转赠一致)。
+6. **状态机**:`PENDING → CLAIMED | REVOKED | EXPIRED`;CLAMED 为终态(不可撤回);EXPIRED 由有效期定时/懒判定触发。
+7. **前端规约**(AGENTS.md,架构阶段必须遵守):后端统一 `@PostMapping`、响应统一 `Result<T>`;DB 迁移唯一入口 `DatabaseInitializer.runMigrations()`(最新迁移 485,`ensureColumn` 幂等,同步 `schema.sql`);小程序禁可选链 `?.`、禁 CSS Grid、禁 `:key` 表达式、禁直接 `new Date(string)`(用 `parseDate()`)。
+8. **兼容性**:现有「定向转赠」全链路(`coupons.vue` 转赠按钮 → `gift-coupon.vue` 三步流程 → `POST /api/coupon/gift/*`)**保持不动**,本次仅新增分享通道,不修改其逻辑。
+
+---
+
+## 6. 验收场景(关键用例)
+
+| 场景 | 预期 |
+| --- | --- |
+| 赠送人点「分享」调起微信分享 | 微信转发面板弹出,卡片 path 含 shareToken |
+| 好友打开领取页(正常) | 展示券面值/名称/赠送人/剩余可用;点「确认领取」成功 |
+| 好友打开领取页但被他人先领 | 提示「该分享已被领取」,按钮置灰 |
+| 好友打开领取页但已撤回 | 提示「分享已撤回」,按钮置灰 |
+| 好友打开领取页但券已过期/失效 | 提示「券已失效」,按钮置灰 |
+| 领取人是赠送人自己 | 提示「不能领取自己分享的券」 |
+| 领取人与赠送人同家庭 | 提示「不能领取同家庭成员的券」 |
+| 赠送人撤回分享(领取前) | 券退回可用;接收人页面显示已撤回 |
+| 非会员接收人领取 | 领取成功;可用该券购买会员 |
+
+---
+
+## 7. 架构阶段提示(供 software-architect 参考)
+
+- 本次为**增量**:新增分享通道,复用现有 `CouponGiftService` 的券实例变更(familyId 改 + is_gift=1)、transfer 记录写入、通知、审计逻辑;建议抽取共享方法避免重复。
+- 小程序新页面建议路径:`/pages/coupon/share-claim`(接收人领取页);分享参数用 `shareToken` 通过 `path` 传递(参考 `invite.vue` 的 `onShareAppMessage` 范式)。
+- 数据模型决策点见 §3.2 / POI-5,最终由架构师确定。

+ 125 - 0
docs/superpowers/verification/2026-11-16-coupon-share-t04-qa.md

@@ -0,0 +1,125 @@
+# T04 优惠券分享转赠 —— QA 独立证据链报告(fresh-eyes)
+
+- **验证人**:software-qa-engineer(独立验证者,不采信 T02/T03 实现者自证)
+- **日期**:2026-11-16
+- **被验基线**:`origin/cfclub`(worktree `E:/tmp/t04-cs`,HEAD `c0b59005b`)
+- **被验提交**:T01 数据层 `98ca36287` / T02 后端 `2ceab5553` / T03 前端 `9dc097eab`
+- **契约源**:PRD `docs/superpowers/specs/2026-11-15-coupon-share-gift-prd.md` §6(9 场景)+ arch-design §10.1(契约单测 10 场景)+ API_REFERENCE §4.32
+
+---
+
+## 0. 结论摘要
+
+| 项 | 判定 |
+|---|---|
+| 三提交祖先链 / 改动范围 | **PASS**:`98ca36287`/`2ceab5553`/`9dc097eab` 均在 `origin/cfclub` 祖先链;改动仅限数据层/后端/前端各自文件,无越界 |
+| 前后端契约一致性(5 端点) | **PASS**:路径/HTTP 方法/入参/返回结构完全一致 |
+| 后端契约单测独立实测 | **PASS**:`Tests run: 24, Failures: 0, Errors: 0, Skipped: 0`,BUILD SUCCESS(EXIT=0) |
+| PRD §6 九场景覆盖 | **8/9 有契约测试证据;1/9(非会员接收人领取)仅代码层证据**(功能正确、缺专项测试) |
+| 并发双领防重领 | **PASS**:条件更新影响行数=1 的原子防重领断言真实存在 |
+| 定向转赠回归(transfer→commitTransfer 抽取) | **PASS(代码等价)**:前置校验保留、尾段参数逐一对应;**但无自动化回归测试**(遗留风险) |
+| 前端静态路径(三态/两段式/401 续领) | **PASS**:代码层成立;**无 Jest 组件测 / 无 e2e spec / 无真机证据**(遗留风险) |
+| uni-app 硬约束 | **PASS**:3 个改动的 .vue + api.js 无可选链/CSS Grid/`:key` 表达式 |
+
+**综合路由:NoOne(全 PASS,功能正确)**,但附 5 项遗留风险(见 §7),核心是「非会员领取」缺专项测试、前端/e2e 测试资产缺失、`transfer()` 无回归测试。
+
+---
+
+## 1. 改动范围核验(独立 git 取证)
+
+```
+T01 98ca36287  6 文件:DatabaseInitializer(迁移494/495) + CouponShare 实体 + CouponShareMapper
+                + CouponGiftTransfer(+2列) + schema.sql + API_REFERENCE.md
+T02 2ceab5553  6 文件:JwtInterceptor + CouponGiftController + CouponGiftService(抽 commitTransfer)
+                + CouponShareService(448行) + ParamUtils + CouponShareClaimContractTest(592行)
+T03 9dc097eab  5 文件:pages.json + pages/coupon/share-claim.vue + gift-coupon.vue
+                + profile-extra/coupons.vue + utils/api.js(+17)
+```
+
+- 数据层/后端/前端三层改动边界清晰,无越界改无关文件。
+- 迁移编号 494/495 相对 `DatabaseInitializer` 现有编号顺延(幂等 `CREATE TABLE IF NOT EXISTS` / `ensureColumn`),符合工程纪律。
+
+## 2. 前后端契约一致性(API 5 端点,逐项比对)
+
+| 端点 | HTTP | api.js 前端调用 | Controller | 入参 | 一致 |
+|---|---|---|---|---|---|
+| `/api/coupon/gift/share/create` | POST | `createCouponShare(familyCouponId)` → `{familyCouponId}` | `@PostMapping("/share/create")` | familyCouponId | ✅ |
+| `/api/coupon/gift/share/detail` | POST | `getCouponShareDetail(shareToken)` → `{shareToken}` | `@PostMapping("/share/detail")` | shareToken | ✅ |
+| `/api/coupon/gift/share/claim` | POST | `claimCouponShare(shareToken)` | `@PostMapping("/share/claim")` | shareToken | ✅ |
+| `/api/coupon/gift/share/revoke` | POST | `revokeCouponShare(shareToken)` | `@PostMapping("/share/revoke")` | shareToken | ✅ |
+| `/api/coupon/gift/share/list` | POST | `getCouponShareList()` → `{}` | `@PostMapping("/share/list")` | — | ✅ |
+
+- 统一 `Result<T>`;`detail` 匿名可浏览(JwtInterceptor L90-91 白名单含 `/share/detail`);create/claim/revoke/list 在 LOGIN_REQUIRED_PATHS(L163-166)。**5/5 完全一致。**
+
+## 3. 后端契约单测独立实测(不采信实现者数字)
+
+在干净 worktree `E:/tmp/t04-cs`(c0b59005b)独立执行:
+
+```
+mvn -o test -Dtest=CouponShareClaimContractTest -DskipTests=false
+→ Tests run: 24, Failures: 0, Errors: 0, Skipped: 0
+→ BUILD SUCCESS(EXIT=0,耗时约 6 分钟)
+```
+
+24 个测试与 arch-design §10.1 **十场景逐一映射(拆分后共 24 个 @Test)**:
+
+| §10.1 场景 | 测试方法 | 覆盖 |
+|---|---|---|
+| 1 create 正常 | `create_正常` | ✅ |
+| 2 create 幂等 | `create_幂等` | ✅ |
+| 3 create 校验 | `create_校验_券不属于我` / `_非会员券` / `_券已失效` / `_券已过期` | ✅ |
+| 4 detail 正常(匿名) | `detail_正常` | ✅ |
+| 5 detail 失效态 | `detail_失效态_已领取` / `_已撤回` / `_过期懒判定` / `_不存在` | ✅ |
+| 6 claim 成功 | `claim_成功` | ✅ |
+| 7 claim 并发防重领 | `claim_并发防重领` | ✅ |
+| 8 claim 校验 | `claim_校验_自己分享` / `_同家庭` / `_已撤回` / `_已过期` / `_券失效` / `_无家庭` | ✅ |
+| 9 revoke | `revoke_正常` / `_已领取不可撤回` / `_非赠送人` / `_已撤回` | ✅ |
+| 10 list 倒序 | `list_倒序` | ✅ |
+
+## 4. PRD §6 九场景映射(team-lead 指定交付物)
+
+| # | PRD §6 场景 | 预期 | 证据等级 | 证据位置 |
+|---|---|---|---|---|
+| 1 | 赠送人点「分享」调起微信分享 | 转发面板弹出,path 含 shareToken | **有契约测试证据(后端 token 生成)+ 前端仅代码层证据**;真机转发无法环境实测 | `CouponShareService.create()`;`coupons.vue prepareShare/onShareAppMessage` |
+| 2 | 好友打开领取页(正常) | 展示券信息;点确认领取成功 | **有契约测试证据**(detail_正常 + claim_成功)+ 前端代码层 | `detail_正常`/`claim_成功`;`share-claim.vue` 正常态 |
+| 3 | 好友打开但被他人先领 | 提示「该分享已被领取」,按钮置灰 | **有契约测试证据(后端)**;置灰仅代码层 | `detail_失效态_已领取`/`claim_校验_已领取`;`isInvalid` |
+| 4 | 好友打开但已撤回 | 提示「分享已撤回」,按钮置灰 | **有契约测试证据(后端)**;置灰仅代码层 | `detail_失效态_已撤回`/`claim_校验_已撤回`/`revoke_*` |
+| 5 | 好友打开但券已过期/失效 | 提示「券已失效」,按钮置灰 | **有契约测试证据(后端)**;置灰仅代码层 | `detail_失效态_过期懒判定`/`claim_校验_已过期`/`_券失效` |
+| 6 | 领取人是赠送人自己 | 提示「不能领取自己分享的券」 | **有契约测试证据** | `claim_校验_自己分享`(MSG_SELF_CLAIM) |
+| 7 | 领取人与赠送人同家庭 | 提示「不能领取同家庭成员的券」 | **有契约测试证据** | `claim_校验_同家庭`(MSG_SAME_FAMILY) |
+| 8 | 赠送人撤回分享(领取前) | 券退回可用;页面显示已撤回 | **有契约测试证据**(revoke_正常 且断言 `familyCouponMapper never updateById`→券实例不动);「退回可用」为代码层推论 | `revoke_正常`/`revoke_已领取不可撤回` |
+| 9 | **非会员接收人领取** | 领取成功;可用该券购买会员 | **仅代码层证据(功能正确,缺专项测试)** | 见 §4.1 |
+
+### 4.1 场景 9「非会员接收人领取」专项说明(重要)
+
+- **PRD 原文(§6 第 9 行 / §5-5 / POI-2)明确预期是「领取成功;可用该券购买会员」,不是「拒绝非会员」**。
+- 代码实证:`CouponShareService.claim()` 校验链为——参数→分享存在→非本人→领取人有 familyId→非同家庭→未撤回→未领取→未过期→券 ACTIVE→券有效期→券实例属赠送人且 AVAILABLE→条件更新影响行数=1→`commitTransfer`。**全程无 `memberLevel`/会员等级校验** → 非会员可正常领取,与 PRD 意图**一致**。
+- 测试覆盖:`claim_成功` 桩数据 `user(id, familyId)` **未设置会员等级**,隐式覆盖「非会员领取成功」路径;**但无专项 @Test 显式断言「memberLevel=FREE/PROVIDER 且无会员资格的用户领取成功、transfer 落 GIFTED」**。
+- 判定:**功能 PASS;测试资产缺口(建议补专项用例,见 §7-1)。**
+
+## 5. 并发双领防重领(独立核验)
+
+- 实现:`CouponShareService.claim()` 用 `LambdaUpdateWrapper.eq(shareToken).eq(status,PENDING).set(status=CLAIMED...)` 条件更新,**影响行数必须 =1**,否则抛 `MSG_ALREADY_CLAIMED`(“该分享已被领取”)→ 一个 token 只能被领一次,DB 层原子性(`UNIQUE KEY uk_share_token` + status 条件)。
+- 测试 `claim_并发防重领`:mock `couponShareMapper.update(null, wrapper)` 返回 **0** → 断言抛 `MSG_ALREADY_CLAIMED`、`verify(couponGiftService, never()).commitTransfer(...)`、`never()` 写 grant log / 发通知。**断言真实存在且已实测通过。**
+- 迁移 DDL:`UNIQUE KEY uk_share_token`(迁移494)、`INDEX idx_giver_status`/`idx_status` 已核。
+
+## 6. 定向转赠回归(transfer → commitTransfer 抽取等价性)
+
+- `CouponGiftService.transfer()`(L209)前置校验**保留不动**;尾段(L254-255)改为调用 `commitTransfer(giverUserId, giverFamilyId, receiverUserId, receiver.getFamilyId(), ..., "DIRECT", null, remark)`。
+- 新 `commitTransfer`(L280,`@Transactional`):参数空检 → coupon 失效检 → fc 归属检 → `setIsGift(1)` + `updateById` → transfer 记录(新增 `claimMethod`/`shareToken` 列)→ 通知 → grant log。参数与旧尾段逐一对应。
+- `CouponShareService.claim()` 复用同一 `commitTransfer(..., giftLevel=0, "SHARE", shareToken, null)`。
+- **证据等级:代码 diff 等价性 PASS;但两个 Service 的 transfer 主路径均无自动化回归测试**(`CouponShareClaimContractTest` 通过 mock `CouponGiftService` 间接验证调用参数,未跑真实 `commitTransfer` 内部逻辑)。
+
+## 7. 遗留风险清单(非阻断)
+
+1. **场景 9 缺专项契约测试**:建议补 `claim_非会员领取成功`(user 显式 memberLevel=FREE/PROVIDER 或未设等级 → 断言成功 + transfer status=GIFTED、claimMethod=SHARE)。
+2. **前端测试资产缺失(与 test-case 台账自述一致)**:`cfc-frontend/pages/coupon/__tests__/share-claim.spec.js` **不存在**;三态/两段式/401 续领仅有静态代码层证据。`tests/e2e/api/coupon-share-contract.spec.js` **不存在**(R225 台账标注「待 T02 入库后转断言」,T02 已入库但仍未补)。
+3. **`CouponGiftService.transfer()` 抽取后无回归测试**:定向转赠全链路(coupons→gift-coupon→transfer/revoke/sent)无自动化覆盖,仅 diff 等价性。
+4. **PRD / arch-design 文档未入库**:`2026-11-15-coupon-share-gift-prd.md` 与 `-arch-design.md` 仅存在于主工作树 `E:/cfc/docs/...`,`origin/cfclub` 无对应文档(worktree 内 glob 检索不到)→ 追溯链在仓库外,建议补入库。
+5. **真机分享链路未实测**:微信转发面板、朋友圈/小程序码 channel 等仅代码层成立,需开发者工具手测(T03 验收亦标注手测)。
+
+## 8. 环境与约束说明
+
+- **Safer 说明**:本次验证全程在独立 worktree `E:/tmp/t04-cs`(c0b59005b = origin/cfclub)执行 git/mvn;唯一写入 `E:/cfc` 的文件为本报告(team-lead 指定路径);未修改任何 `src/test`/`src/main`/前端业务文件。
+- PRD/arch-design 原文在主工作树只读读取(两份 2026-11-15 spec 未入库,worktree 内无副本)。
+- 单测为纯 Mockito 契约级(无 Spring/DB),`mvn -o` 离线模式下 24/24 通过。