feat(membership): 赠会员进度接口补充 remaining 字段与实付口径文案

- GiftMembershipProgress 新增 remaining(@TableField exist=false)，接口返回还差多少达标
- MembershipController 计算 remaining = max(0, threshold - accumulatedAmount)
- cart/checkout 改读后端 remaining，消除前端重复业务计算
- checkout 补充「仅原价实付订单计入」说明文案
- API_REFERENCE 章节号 4.38→4.43 避免重复，补 remaining 字段与无家庭返回说明

cfc-backend/src/main/java/com/etotem/cfc/controller/MembershipController.java

@@ -447,7 +447,9 @@ public class MembershipController {
         // 读取全局阈值
         String thresholdStr = sysConfigService.getValue("gift_membership_threshold");
         int threshold = thresholdStr != null ? Integer.parseInt(thresholdStr) : 0;
+        int accumulated = progress.getAccumulatedAmount() != null ? progress.getAccumulatedAmount() : 0;
         progress.setThreshold(threshold);
+        progress.setRemaining(Math.max(0, threshold - accumulated));
         return Result.success(progress);
     }
 

cfc-backend/src/main/java/com/etotem/cfc/entity/GiftMembershipProgress.java

@@ -32,6 +32,9 @@ public class GiftMembershipProgress implements Serializable {
     @TableField(exist = false)
     private Integer threshold;           // 阈值(分)，由接口动态填入
 
+    @TableField(exist = false)
+    private Integer remaining;           // 还差多少达标(分)，已达标为0
+
     private Date createdAt;
 
     private Date updatedAt;

cfc-frontend/pages/shop/cart/cart.vue

@@ -211,9 +211,8 @@ export default {
       return this.giftProgress.threshold / 100
     },
     giftRemainingYuan() {
-      if (!this.giftProgress || !this.giftProgress.threshold || !this.giftProgress.accumulatedAmount) return 0
-      var remaining = this.giftProgress.threshold - this.giftProgress.accumulatedAmount
-      return remaining > 0 ? remaining / 100 : 0
+      if (!this.giftProgress || !this.giftProgress.remaining) return 0
+      return this.giftProgress.remaining / 100
     },
     giftProgressPercent() {
       if (!this.giftProgress || !this.giftProgress.threshold || this.giftProgress.threshold <= 0) return 0

cfc-frontend/pages/shop/checkout/checkout.vue

@@ -172,6 +172,7 @@
           <text class="gift-progress-accumulated">已累 {{ giftAccumulatedYuan }} 元</text>
           <text class="gift-progress-remaining">还差 {{ giftRemainingYuan }} 元送会员</text>
         </view>
+        <text class="gift-progress-note">仅原价实付订单计入累计，使用积分、优惠券或折扣的订单不计入</text>
         <view v-if="giftProgress.grantedLevel" class="gift-progress-level">
           <text>达标将赠送 {{ giftProgress.grantedLevel === 'FAMILY' ? '家庭会员' : giftProgress.grantedLevel }} 权益</text>
         </view>
@@ -514,9 +515,8 @@ export default {
       return this.giftProgress.threshold / 100
     },
     giftRemainingYuan() {
-      if (!this.giftProgress || !this.giftProgress.threshold || !this.giftProgress.accumulatedAmount) return 0
-      var remaining = this.giftProgress.threshold - this.giftProgress.accumulatedAmount
-      return remaining > 0 ? remaining / 100 : 0
+      if (!this.giftProgress || !this.giftProgress.remaining) return 0
+      return this.giftProgress.remaining / 100
     },
     giftProgressPercent() {
       if (!this.giftProgress || !this.giftProgress.threshold || this.giftProgress.threshold <= 0) return 0
@@ -1792,6 +1792,12 @@ showOnlineSlotPicker: function() {
   font-size: 22rpx;
   color: #F97316;
 }
+.gift-progress-note {
+  display: block;
+  margin-top: 8rpx;
+  font-size: 20rpx;
+  color: #9A3412;
+}
 .gift-granted-section {
   background: #F0FDF4;
   border-radius: 16rpx;

docs/superpowers/api/API_REFERENCE.md

@@ -1354,7 +1354,7 @@ interactionType 取值：`PHONE` / `WECHAT` / `MEETING` / `OTHER`。
 
 ---
 
-### 4.38 商品赠送会员（`/api/membership/gift-membership-progress`）
+### 4.43 商品赠送会员（`/api/membership/gift-membership-progress`）
 
 家庭维度累计「赠会员商品」原价实付金额，达到阈值后自动赠送会员。
 
@@ -1377,7 +1377,8 @@ interactionType 取值：`PHONE` / `WECHAT` / `MEETING` / `OTHER`。
     "grantedLevel": null,
     "grantedOrderNo": null,
     "grantedAt": null,
-    "threshold": 198000
+    "threshold": 198000,
+    "remaining": 40000
   }
 }
 ```
@@ -1387,11 +1388,13 @@ interactionType 取值：`PHONE` / `WECHAT` / `MEETING` / `OTHER`。
 | `accumulatedAmount` | Integer | 累计赠会员商品原价金额（分），仅统计无积分/无券/无折扣的实付订单 |
 | `granted` | Integer | 1=已赠送 0=未赠送 |
 | `grantedLevel` | String | 已赠送的会员等级（当前全局配置默认 `FAMILY`） |
-| `threshold` | Integer | 阈值（分），由 `sys_config.gift_membership_threshold` 动态填入；无家庭时返回 `0` |
+| `threshold` | Integer | 阈值（分），由 `sys_config.gift_membership_threshold` 动态填入 |
+| `remaining` | Integer | 还差多少达标（分）= `max(0, threshold - accumulatedAmount)`，已达标为 `0` |
 
-> **注意**：`threshold` 为 `@TableField(exist = false)` 非数据库列，仅接口返回用。
+> **注意**：`threshold`、`remaining` 为 `@TableField(exist = false)` 非数据库列，仅接口返回用。
+> **无家庭时**：接口返回空对象，`threshold`/`remaining`/`accumulatedAmount` 均为 `null`（此时不存在赠会员累计口径），前端据此隐藏进度条。
 > 阈值单位为分（1980 元 = 198000 分），实际生效值以 `sys_config` 表中 `gift_membership_threshold` 为准（`insertSysConfigSeed` 仅在缺失时插入，不覆盖已有配置）。
 
 ---
 
-*文档最后更新：2026-09-13*
+*文档最后更新：2026-09-29*