# BASIC 体验会员实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在现有会员体系（FREE→FAMILY→PREMIUM→PROVIDER）中新增 BASIC 等级，实现 9.9 元/月体验会员的付费开通、配额扣减、软/硬引导升级链路。

**Architecture:** 基于现有 `MembershipLevel` / `FamilyMembership` / `TrialMembership` 三层会员记录模型，新增 `basic_quota_usage` 表管理月度配额。`BasicQuotaService` 作为独立 Service 承载配额逻辑，在 4 个业务入口（AI 对话、报告解读、测评预约、报告上传）插入配额检查。定时任务复用 `MembershipScheduledTasks` 扩展模式。

**Tech Stack:** Spring Boot 2.7.18, MyBatis-Plus, Java 8, Maven, 微信小程序 Vue2

**Spec:** `docs/superpowers/specs/2026-09-10-basic-membership-design.md`

## Global Constraints

- 所有接口统一 `@PostMapping`，禁止 `@GetMapping`/`@PutMapping`/`@DeleteMapping`
- ORM 使用 MyBatis-Plus `@TableName` + `@TableId(type = IdType.AUTO)`
- DI 使用 `@Resource`，字段名必须与类型默认 Bean Name 一致
- 响应统一 `Result<T>`（code/message/data）
- 禁用 `?.`（用 `&&` 替代）、禁用 CSS Grid（用 flexbox）、禁用 `:key` 表达式
- 前端禁止直接 `new Date(string)`，用 `utils/format.js` 的 `parseDate()`
- 所有迁移幂等（try-catch 忽略已存在异常）
- `mvn clean compile` 是唯一验证方式（编译通过即视为验证）

---

## 文件结构

| 文件路径 | 类型 | 职责 |
|----------|------|------|
| `entity/BasicQuotaUsage.java` | Create | BASIC 配额实体 |
| `mapper/BasicQuotaUsageMapper.java` | Create | 配额 Mapper 接口 |
| `dto/QuotaStatusDTO.java` | Create | 配额查询响应 DTO |
| `dto/QuotaConsumeResult.java` | Create | 配额扣减结果 DTO |
| `service/BasicQuotaService.java` | Create | 配额核心 Service（查询/扣减/刷新） |
| `controller/BasicQuotaController.java` | Create | 配额查询 + 手动重置接口 |
| `task/BasicQuotaScheduledTasks.java` | Create | 配额刷新 + 到期提醒定时任务 |
| `service/MembershipService.java` | Modify | `canUseFeature()` 加 BASIC 分支；`downgradeExpiredMembers()` 支持 BASIC |
| `service/AiGateway.java` | Modify | `chat()` 入口插入 BASIC 配额扣减 |
| `service/ReportSummaryService.java` | Modify | `parseReport()` 入口插入配额扣减 |
| `service/AssessmentAppointmentService.java` | Modify | `create()` 入口插入硬门禁配额检查 |
| `service/DanReportUploadService.java` | Modify | `upload()` 入口插入配额检查 |
| `service/ActivationQuotaService.java` | Create | 支付成功后初始化 4 类配额 |
| `resources/schema.sql` | Modify | 新增 `basic_quota_usage` 表定义 + BASIC seed 数据 |
| `config/DatabaseInitializer.java` | Modify | 新增 BASIC 等级 / 权益 / 表迁移 |
| `cfc-frontend/pages/profile/membership/index.vue` | Modify | 展示 BASIC 权益卡片 |
| `cfc-frontend/pages/profile/upgrade/index.vue` | Modify | 新增 9.9 元月付选项 |
| `cfc-frontend/components/QuotaProgressBar.vue` | Create | 配额进度条组件 |
| `cfc-frontend/components/UpgradeGuideModal.vue` | Create | 统一软/硬引导弹窗组件 |
| `cfc-frontend/pages/ai-chat/index.vue` | Modify | 显示剩余次数 + 超限弹窗 |
| `cfc-frontend/pages/assessment/appointment/index.vue` | Modify | 显示剩余次数 + 硬门禁弹窗 |
| `cfc-frontend/pages/health/report-list.vue` | Modify | 显示剩余次数 + 软引导 |

---

## Phase 概述

| Phase | 天数 | 范围 | 里程碑 |
|-------|------|------|--------|
| P0 核心链路 | 3 天 | DB 迁移 + BASIC 等级 + 支付开通 + 基础权限 | 9.9 元支付成功，BASIC 生效，能进沙盘/AI 对话 |
| P1 配额系统 | 2 天 | `BasicQuotaService` + 4 个业务入口扣减 + 定时刷新 | 月度配额正确扣减/刷新，超限引导生效 |
| P2 前端展示 | 2 天 | 权益页/开通页/进度条/弹窗 | 免费用户可见 BASIC，付费后正确显示剩余次数 |
| P3 运营配套 | 2 天 | 定时提醒 + 管理端配额看板 + 手动重置接口 | 到期提醒自动发送，看板可查 |

---

## Task 1: 数据库迁移 — 新增表 + BASIC 种子数据

**Files:**
- Modify: `cfc-backend/src/main/resources/schema.sql` (末尾追加)
- Modify: `cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java` (末尾 `runMigrations()` 追加)
- Test: 无单元测试（迁移幂等，`mvn compile` 验证）

**Interfaces:**
- Consumes: 无（数据库级操作）
- Produces: `basic_quota_usage` 表；`membership_levels` 新增 BASIC 记录；`membership_benefits` 新增 5 条 BASIC 权益记录

- [ ] **Step 1: schema.sql 末尾追加基本表定义 + seed 数据**

在 `schema.sql` 末尾（OFFSET 5513 之后）追加以下内容：

```sql
-- ============================================================
-- 新增 BASIC 体验会员等级种子数据（迁移150）
-- ============================================================
INSERT IGNORE INTO membership_levels 
(level_code, level_name, level_desc, price_monthly, features, max_children, max_tasks_per_day) 
VALUES (
    'BASIC', 
    '体验会员', 
    '9.9元/月体验版，解锁核心功能，限次使用AI与报告解读',
    990,
    '["free_activities","free_courses","discount_purchase","invite_family","mascot_ai_lite","ai_report_reading_lite","assessment_quota_lite","health_report_upload_lite","growth_plan_lite","task_template_lite"]',
    3,
    3
);

-- ============================================================
-- 新增 BASIC 会员权益种子数据（迁移151）
-- ============================================================
INSERT IGNORE INTO membership_benefits (level_code, benefit_code, benefit_name, benefit_desc, icon, bg_color, sort_order) VALUES
('BASIC', 'AI_CHAT_LITE', 'AI健康顾问（限3次/月）', '每月3次AI健康顾问问答', '🤖', '#DBEAFE', 1),
('BASIC', 'REPORT_READING_LITE', '报告解读（限1次/月）', '每月1次体检/测评报告AI解读', '📊', '#FCE7F3', 4),
('BASIC', 'GROWTH_PLAN_LITE', '基础成长计划', '创建成长计划但模板有限', '📋', '#FEF3C7', 3),
('BASIC', 'ASSESSMENT_QUOTA_LITE', '测评预约（限1次）', '每月可预约1次测评', '📝', '#E0E7FF', 8),
('BASIC', 'REPORT_UPLOAD_LITE', '健康报告上传（限2份/月）', '每月可上传2份健康报告', '📄', '#FEF9C3', 9);

-- ============================================================
-- BASIC 会员月度配额使用记录表（迁移152）
-- ============================================================
CREATE TABLE IF NOT EXISTS basic_quota_usage (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    user_id BIGINT NOT NULL COMMENT '家长用户ID（非family_id）',
    quota_type VARCHAR(30) NOT NULL COMMENT 'AI_CHAT/REPORT_READING/ASSESSMENT_QUOTA/REPORT_UPLOAD',
    used_count INT DEFAULT 0 COMMENT '本月已用次数',
    total_count INT NOT NULL COMMENT '月度总配额',
    period_start DATE NOT NULL COMMENT '周期开始日期（每月1号）',
    period_end DATE NOT NULL COMMENT '周期结束日期（月末）',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_user_type_period (user_id, quota_type, period_start),
    INDEX idx_user_period (user_id, period_start)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='BASIC会员月度配额使用记录';
```

- [ ] **Step 2: DatabaseInitializer.java 追加迁移代码**

在 `DatabaseInitializer.java` 的 `runMigrations()` 方法末尾（最新迁移编号之后）追加：

```java
// 迁移150: membership_levels 新增 BASIC 体验会员等级
try {
    jdbcTemplate.execute(
        "INSERT IGNORE INTO membership_levels " +
        "(level_code, level_name, level_desc, price_monthly, features, max_children, max_tasks_per_day) " +
        "VALUES ('BASIC', '体验会员', " +
        "'9.9元/月体验版，解锁核心功能，限次使用AI与报告解读', " +
        "990, " +
        "'[\"free_activities\",\"free_courses\",\"discount_purchase\",\"invite_family\",\"mascot_ai_lite\",\"ai_report_reading_lite\",\"assessment_quota_lite\",\"health_report_upload_lite\",\"growth_plan_lite\",\"task_template_lite\"]', " +
        "3, 3)");
    log.info("已初始化BASIC体验会员等级");
} catch (Exception e) {
    // 等级已存在，忽略
}

// 迁移151: membership_benefits 新增 BASIC 会员权益
try {
    jdbcTemplate.execute(
        "INSERT IGNORE INTO membership_benefits " +
        "(level_code, benefit_code, benefit_name, benefit_desc, icon, bg_color, sort_order) VALUES " +
        "('BASIC', 'AI_CHAT_LITE', 'AI健康顾问（限3次/月）', '每月3次AI健康顾问问答', '🤖', '#DBEAFE', 1), " +
        "('BASIC', 'REPORT_READING_LITE', '报告解读（限1次/月）', '每月1次体检/测评报告AI解读', '📊', '#FCE7F3', 4), " +
        "('BASIC', 'GROWTH_PLAN_LITE', '基础成长计划', '创建成长计划但模板有限', '📋', '#FEF3C7', 3), " +
        "('BASIC', 'ASSESSMENT_QUOTA_LITE', '测评预约（限1次）', '每月可预约1次测评', '📝', '#E0E7FF', 8), " +
        "('BASIC', 'REPORT_UPLOAD_LITE', '健康报告上传（限2份/月）', '每月可上传2份健康报告', '📄', '#FEF9C3', 9)");
    log.info("已初始化BASIC会员权益列表");
} catch (Exception e) {
    // 已存在，忽略
}

// 迁移152: 创建 basic_quota_usage 表
try {
    jdbcTemplate.execute(
        "CREATE TABLE IF NOT EXISTS basic_quota_usage (" +
        "id BIGINT AUTO_INCREMENT PRIMARY KEY, " +
        "user_id BIGINT NOT NULL COMMENT '家长用户ID', " +
        "quota_type VARCHAR(30) NOT NULL COMMENT '配额类型', " +
        "used_count INT DEFAULT 0 COMMENT '已用次数', " +
        "total_count INT NOT NULL COMMENT '月度总配额', " +
        "period_start DATE NOT NULL COMMENT '周期开始日期', " +
        "period_end DATE NOT NULL COMMENT '周期结束日期', " +
        "created_at DATETIME DEFAULT CURRENT_TIMESTAMP, " +
        "updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, " +
        "UNIQUE KEY uk_user_type_period (user_id, quota_type, period_start), " +
        "INDEX idx_user_period (user_id, period_start) " +
        ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='BASIC会员月度配额使用记录'");
    log.info("已创建basic_quota_usage表");
} catch (Exception e) {
    // 表已存在，忽略
}
```

- [ ] **Step 3: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS，无编译错误。

- [ ] **Step 4: 提交**

```bash
git add cfc-backend/src/main/resources/schema.sql
git add cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java
git commit -m "feat: 新增BASIC体验会员等级及配额表迁移（迁移150-152）"
```

---

## Task 2: 新增 BasicQuotaUsage 实体 + Mapper

**Files:**
- Create: `cfc-backend/src/main/java/com/etotem/cfc/entity/BasicQuotaUsage.java`
- Create: `cfc-backend/src/main/java/com/etotem/cfc/mapper/BasicQuotaUsageMapper.java`
- Test: 无（实体类无业务逻辑）

**Interfaces:**
- Consumes: 无
- Produces: `BasicQuotaUsage` 实体（字段：id, userId, quotaType, usedCount, totalCount, periodStart, periodEnd, createdAt, updatedAt），`BasicQuotaUsageMapper` 接口（继承 `BaseMapper<BasicQuotaUsage>`）

- [ ] **Step 1: 创建 BasicQuotaUsage.java**

```java
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;

@Data
@TableName("basic_quota_usage")
public class BasicQuotaUsage implements Serializable {

    @TableId(type = IdType.AUTO)
    private Long id;

    private Long userId;

    private String quotaType;

    private Integer usedCount;

    private Integer totalCount;

    private Date periodStart;

    private Date periodEnd;

    private Date createdAt;

    private Date updatedAt;
}
```

- [ ] **Step 2: 创建 BasicQuotaUsageMapper.java**

```java
package com.etotem.cfc.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.etotem.cfc.entity.BasicQuotaUsage;
import org.apache.ibatis.annotations.Mapper;

@Mapper
public interface BasicQuotaUsageMapper extends BaseMapper<BasicQuotaUsage> {
}
```

- [ ] **Step 3: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 4: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/entity/BasicQuotaUsage.java
git add cfc-backend/src/main/java/com/etotem/cfc/mapper/BasicQuotaUsageMapper.java
git commit -m "feat: 新增BasicQuotaUsage实体和Mapper"
```

---

## Task 3: 新增 QuotaStatusDTO + QuotaConsumeResult DTO

**Files:**
- Create: `cfc-backend/src/main/java/com/etotem/cfc/dto/QuotaStatusDTO.java`
- Create: `cfc-backend/src/main/java/com/etotem/cfc/dto/QuotaConsumeResult.java`
- Test: 无（纯 POJO）

**Interfaces:**
- Consumes: 无
- Produces: `QuotaStatusDTO`（字段：quotaType, total, used, remaining, periodStart, periodEnd）；`QuotaConsumeResult`（字段：success, remaining, toastMsg, actionUrl）

- [ ] **Step 1: 创建 QuotaStatusDTO.java**

```java
package com.etotem.cfc.dto;

import lombok.Data;
import java.util.Date;

@Data
public class QuotaStatusDTO {
    private String quotaType;
    private int total;
    private int used;
    private int remaining;
    private Date periodStart;
    private Date periodEnd;
}
```

- [ ] **Step 2: 创建 QuotaConsumeResult.java**

```java
package com.etotem.cfc.dto;

import lombok.Data;

@Data
public class QuotaConsumeResult {
    private boolean success;
    private int remaining;
    private String toastMsg;
    private String actionUrl;
}
```

- [ ] **Step 3: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 4: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/dto/QuotaStatusDTO.java
git add cfc-backend/src/main/java/com/etotem/cfc/dto/QuotaConsumeResult.java
git commit -m "feat: 新增配额相关DTO"
```

---

## Task 4: 实现 BasicQuotaService（核心配额逻辑）

**Files:**
- Create: `cfc-backend/src/main/java/com/etotem/cfc/service/BasicQuotaService.java`
- Test: 无（依赖数据库，用 `mvn compile` 验证编译）

**Interfaces:**
- Consumes: `BasicQuotaUsageMapper` (insert/select by example)
- Produces:
  - `QuotaStatusDTO getMonthlyQuota(Long userId, String quotaType)` — 返回指定月份某配额的剩余次数
  - `QuotaConsumeResult consumeQuota(Long userId, String quotaType)` — 扣减配额，返回结果
  - `void refreshMonthlyQuota()` — 每月1号批量刷新所有 BASIC 用户的配额
  - `boolean isActiveBasicMember(Long userId)` — 检查用户当前是否为有效 BASIC 会员
  - `Date getExpireTime(Long userId)` — 获取 BASIC 用户到期时间

- [ ] **Step 1: 创建 BasicQuotaService.java**

```java
package com.etotem.cfc.service;

import com.etotem.cfc.dto.QuotaConsumeResult;
import com.etotem.cfc.dto.QuotaStatusDTO;
import com.etotem.cfc.entity.BasicQuotaUsage;
import com.etotem.cfc.entity.User;
import com.etotem.cfc.mapper.BasicQuotaUsageMapper;
import com.etotem.cfc.mapper.UserMapper;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

import javax.annotation.Resource;
import java.util.*;

@Slf4j
@Service
public class BasicQuotaService {

    @Resource
    private BasicQuotaUsageMapper basicQuotaUsageMapper;

    @Resource
    private UserMapper userMapper;

    @Resource
    private MembershipService membershipService;

    // BASIC 会员月度配额上限
    private static final Map<String, Integer> QUOTA_LIMITS = new HashMap<>();
    static {
        QUOTA_LIMITS.put("AI_CHAT", 3);
        QUOTA_LIMITS.put("REPORT_READING", 1);
        QUOTA_LIMITS.put("ASSESSMENT_QUOTA", 1);
        QUOTA_LIMITS.put("REPORT_UPLOAD", 2);
    }

    /**
     * 查询指定用户指定月份某配额的剩余次数
     */
    public QuotaStatusDTO getMonthlyQuota(Long userId, String quotaType) {
        if (userId == null || quotaType == null) {
            return null;
        }
        Date now = new Date();
        Date periodStart = getMonthStart(now);
        Date periodEnd = getMonthEnd(now);

        BasicQuotaUsage usage = basicQuotaUsageMapper.selectOne(
                new LambdaQueryWrapper<BasicQuotaUsage>()
                        .eq(BasicQuotaUsage::getUserId, userId)
                        .eq(BasicQuotaUsage::getQuotaType, quotaType)
                        .eq(BasicQuotaUsage::getPeriodStart, periodStart));

        int total = QUOTA_LIMITS.getOrDefault(quotaType, 0);
        int used = 0;
        if (usage != null) {
            used = usage.getUsedCount() != null ? usage.getUsedCount() : 0;
        }

        QuotaStatusDTO dto = new QuotaStatusDTO();
        dto.setQuotaType(quotaType);
        dto.setTotal(total);
        dto.setUsed(used);
        dto.setRemaining(Math.max(0, total - used));
        dto.setPeriodStart(periodStart);
        dto.setPeriodEnd(periodEnd);
        return dto;
    }

    /**
     * 尝试扣减配额，返回是否成功
     */
    public QuotaConsumeResult consumeQuota(Long userId, String quotaType) {
        QuotaConsumeResult result = new QuotaConsumeResult();

        if (!isActiveBasicMember(userId)) {
            result.setSuccess(false);
            result.setToastMsg("该功能仅限体验会员使用");
            return result;
        }

        Date now = new Date();
        Date periodStart = getMonthStart(now);
        Date periodEnd = getMonthEnd(now);

        BasicQuotaUsage usage = basicQuotaUsageMapper.selectOne(
                new LambdaQueryWrapper<BasicQuotaUsage>()
                        .eq(BasicQuotaUsage::getUserId, userId)
                        .eq(BasicQuotaUsage::getQuotaType, quotaType)
                        .eq(BasicQuotaUsage::getPeriodStart, periodStart));

        int total = QUOTA_LIMITS.getOrDefault(quotaType, 0);
        int used = 0;
        if (usage != null) {
            used = usage.getUsedCount() != null ? usage.getUsedCount() : 0;
        }

        if (used >= total) {
            result.setSuccess(false);
            result.setRemaining(0);
            result.setToastMsg(buildExhaustedToast(quotaType, total));
            result.setActionUrl("/pages/profile/upgrade/index");
            return result;
        }

        // 初始化或更新
        if (usage == null) {
            usage = new BasicQuotaUsage();
            usage.setUserId(userId);
            usage.setQuotaType(quotaType);
            usage.setUsedCount(0);
            usage.setTotalCount(total);
            usage.setPeriodStart(periodStart);
            usage.setPeriodEnd(periodEnd);
            usage.setCreatedAt(now);
            usage.setUpdatedAt(now);
            basicQuotaUsageMapper.insert(usage);
        }
        usage.setUsedCount(used + 1);
        usage.setUpdatedAt(now);
        basicQuotaUsageMapper.updateById(usage);

        result.setSuccess(true);
        result.setRemaining(total - used - 1);
        return result;
    }

    /**
     * 批量刷新所有 BASIC 用户当月配额（每月1号调用）
     */
    public void refreshMonthlyQuota() {
        Date now = new Date();
        Date monthStart = getMonthStart(now);
        Date monthEnd = getMonthEnd(now);
        Date lastMonthStart = getMonthStart(new Date(now.getTime() - 30L * 24 * 60 * 60 * 1000));

        // 查找上个月有记录的所有 BASIC 用户
        List<BasicQuotaUsage> lastMonthRecords = basicQuotaUsageMapper.selectList(
                new LambdaQueryWrapper<BasicQuotaUsage>()
                        .eq(BasicQuotaUsage::getPeriodStart, lastMonthStart));

        Set<Long> userIds = new HashSet<>();
        for (BasicQuotaUsage rec : lastMonthRecords) {
            if (isActiveBasicMember(rec.getUserId())) {
                userIds.add(rec.getUserId());
            }
        }

        for (Long userId : userIds) {
            for (String quotaType : QUOTA_LIMITS.keySet()) {
                try {
                    BasicQuotaUsage existing = basicQuotaUsageMapper.selectOne(
                            new LambdaQueryWrapper<BasicQuotaUsage>()
                                    .eq(BasicQuotaUsage::getUserId, userId)
                                    .eq(BasicQuotaUsage::getQuotaType, quotaType)
                                    .eq(BasicQuotaUsage::getPeriodStart, monthStart));
                    if (existing == null) {
                        BasicQuotaUsage newUsage = new BasicQuotaUsage();
                        newUsage.setUserId(userId);
                        newUsage.setQuotaType(quotaType);
                        newUsage.setUsedCount(0);
                        newUsage.setTotalCount(QUOTA_LIMITS.get(quotaType));
                        newUsage.setPeriodStart(monthStart);
                        newUsage.setPeriodEnd(monthEnd);
                        newUsage.setCreatedAt(now);
                        newUsage.setUpdatedAt(now);
                        basicQuotaUsageMapper.insert(newUsage);
                        log.info("BASIC配额刷新初始化: userId={}, quotaType={}", userId, quotaType);
                    } else {
                        existing.setUsedCount(0);
                        existing.setPeriodStart(monthStart);
                        existing.setPeriodEnd(monthEnd);
                        existing.setUpdatedAt(now);
                        basicQuotaUsageMapper.updateById(existing);
                    }
                } catch (Exception e) {
                    log.warn("BASIC配额刷新失败: userId={}, quotaType={}", userId, quotaType, e);
                }
            }
        }
        log.info("BASIC配额刷新完成, 处理用户数: {}", userIds.size());
    }

    /**
     * 检查用户当前是否为有效的 BASIC 会员
     */
    public boolean isActiveBasicMember(Long userId) {
        if (userId == null) {
            return false;
        }
        String level = membershipService.getMemberLevel(userId);
        if (!"BASIC".equals(level)) {
            return false;
        }
        User user = userMapper.selectById(userId);
        if (user == null || user.getMemberExpireTime() == null) {
            return false;
        }
        return user.getMemberExpireTime().after(new Date());
    }

    /**
     * 获取 BASIC 用户到期时间
     */
    public Date getExpireTime(Long userId) {
        User user = userMapper.selectById(userId);
        if (user != null) {
            return user.getMemberExpireTime();
        }
        return null;
    }

    private Date getMonthStart(Date date) {
        Calendar cal = Calendar.getInstance();
        cal.setTime(date);
        cal.set(Calendar.DAY_OF_MONTH, 1);
        cal.set(Calendar.HOUR_OF_DAY, 0);
        cal.set(Calendar.MINUTE, 0);
        cal.set(Calendar.SECOND, 0);
        cal.set(Calendar.MILLISECOND, 0);
        return cal.getTime();
    }

    private Date getMonthEnd(Date date) {
        Calendar cal = Calendar.getInstance();
        cal.setTime(date);
        cal.set(Calendar.DAY_OF_MONTH, cal.getActualMaximum(Calendar.DAY_OF_MONTH));
        cal.set(Calendar.HOUR_OF_DAY, 23);
        cal.set(Calendar.MINUTE, 59);
        cal.set(Calendar.SECOND, 59);
        cal.set(Calendar.MILLISECOND, 999);
        return cal.getTime();
    }

    private String buildExhaustedToast(String quotaType, int total) {
        switch (quotaType) {
            case "AI_CHAT":
                return "您本月 AI 对话已用完（" + total + "/" + total + "），升级 FAMILY 享不限次畅聊";
            case "REPORT_READING":
                return "本月报告解读额度已用完（" + total + "/" + total + "），升级 FAMILY 解锁不限次深度解读";
            case "ASSESSMENT_QUOTA":
                return "测评预约为 FAMILY 会员专属权益，升级后即可预约";
            case "REPORT_UPLOAD":
                return "本月报告上传额度已用完（" + total + "/" + total + "），升级 FAMILY 解锁更多";
            default:
                return "本月额度已用完，升级 FAMILY 解锁更多";
        }
    }
}
```

- [ ] **Step 2: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 3: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/service/BasicQuotaService.java
git commit -m "feat: 实现BasicQuotaService配额核心逻辑"
```

---

## Task 5: 实现 ActivationQuotaService（支付成功后初始化配额）

**Files:**
- Create: `cfc-backend/src/main/java/com/etotem/cfc/service/ActivationQuotaService.java`
- Test: 无

**Interfaces:**
- Consumes: `BasicQuotaUsageMapper`
- Produces: `void activateBasicQuota(Long userId, Long familyId)` — 支付成功后为 BASIC 用户初始化当月 4 类配额记录

- [ ] **Step 1: 创建 ActivationQuotaService.java**

```java
package com.etotem.cfc.service;

import com.etotem.cfc.entity.BasicQuotaUsage;
import com.etotem.cfc.mapper.BasicQuotaUsageMapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

import javax.annotation.Resource;
import java.util.*;

@Slf4j
@Service
public class ActivationQuotaService {

    @Resource
    private BasicQuotaUsageMapper basicQuotaUsageMapper;

    private static final Map<String, Integer> QUOTA_LIMITS = new HashMap<>();
    static {
        QUOTA_LIMITS.put("AI_CHAT", 3);
        QUOTA_LIMITS.put("REPORT_READING", 1);
        QUOTA_LIMITS.put("ASSESSMENT_QUOTA", 1);
        QUOTA_LIMITS.put("REPORT_UPLOAD", 2);
    }

    /**
     * 支付成功后，为 BASIC 用户初始化当月 4 类配额记录
     */
    public void activateBasicQuota(Long userId, Long familyId) {
        if (userId == null) {
            return;
        }
        Date now = new Date();
        Date monthStart = getMonthStart(now);
        Date monthEnd = getMonthEnd(now);

        for (Map.Entry<String, Integer> entry : QUOTA_LIMITS.entrySet()) {
            try {
                BasicQuotaUsage usage = new BasicQuotaUsage();
                usage.setUserId(userId);
                usage.setQuotaType(entry.getKey());
                usage.setUsedCount(0);
                usage.setTotalCount(entry.getValue());
                usage.setPeriodStart(monthStart);
                usage.setPeriodEnd(monthEnd);
                usage.setCreatedAt(now);
                usage.setUpdatedAt(now);
                basicQuotaUsageMapper.insert(usage);
                log.info("BASIC配额初始化: userId={}, quotaType={}, total={}", userId, entry.getKey(), entry.getValue());
            } catch (Exception e) {
                log.warn("BASIC配额初始化失败: userId={}, quotaType={}", userId, entry.getKey(), e);
            }
        }
    }

    private Date getMonthStart(Date date) {
        Calendar cal = Calendar.getInstance();
        cal.setTime(date);
        cal.set(Calendar.DAY_OF_MONTH, 1);
        cal.set(Calendar.HOUR_OF_DAY, 0);
        cal.set(Calendar.MINUTE, 0);
        cal.set(Calendar.SECOND, 0);
        cal.set(Calendar.MILLISECOND, 0);
        return cal.getTime();
    }

    private Date getMonthEnd(Date date) {
        Calendar cal = Calendar.getInstance();
        cal.setTime(date);
        cal.set(Calendar.DAY_OF_MONTH, cal.getActualMaximum(Calendar.DAY_OF_MONTH));
        cal.set(Calendar.HOUR_OF_DAY, 23);
        cal.set(Calendar.MINUTE, 59);
        cal.set(Calendar.SECOND, 59);
        cal.set(Calendar.MILLISECOND, 999);
        return cal.getTime();
    }
}
```

- [ ] **Step 2: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 3: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/service/ActivationQuotaService.java
git commit -m "feat: 新增ActivationQuotaService支付后初始化配额"
```

---

## Task 6: 修改 MembershipService（BASIC 分支 + 降级支持）

**Files:**
- Modify: `cfc-backend/src/main/java/com/etotem/cfc/service/MembershipService.java` (两处修改)

**Interfaces:**
- Consumes: `BasicQuotaService`（由调用方注入）
- Produces: `canUseFeature` 支持 BASIC；`downgradeExpiredMembers` 支持 BASIC 降级

- [ ] **Step 1: canUseFeature() 新增 BASIC 分支**

在 `MembershipService.java` 的 `canUseFeature()` 方法中，在 `FREE` 和 `FAMILY` 分支之间插入：

```java
// BASIC 用户可用功能
if ("BASIC".equals(level)) {
    return "free_activities".equals(feature)
            || "free_courses".equals(feature)
            || "discount_purchase".equals(feature)
            || "invite_family".equals(feature)
            || "mascot_ai_lite".equals(feature)
            || "ai_report_reading_lite".equals(feature)
            || "assessment_quota_lite".equals(feature)
            || "health_report_upload_lite".equals(feature)
            || "growth_plan_lite".equals(feature)
            || "task_template_lite".equals(feature);
}
```

插入位置：在 `if ("FAMILY".equals(level)) {` 之前。

- [ ] **Step 2: downgradeExpiredMembers() 支持 BASIC**

在 `MembershipService.java` 的 `downgradeExpiredMembers()` 方法中，修改条件判断：

**修改前：**
```java
if ("FAMILY".equals(user.getMemberLevel())
        && user.getMemberExpireTime() != null
        && user.getMemberExpireTime().before(new Date())) {
```

**修改后：**
```java
if (("FAMILY".equals(user.getMemberLevel()) || "BASIC".equals(user.getMemberLevel()))
        && user.getMemberExpireTime() != null
        && user.getMemberExpireTime().before(new Date())) {
```

同时在方法体内，降级时记录日志区分等级：

```java
user.setMemberLevel("FREE");
user.setMemberExpireTime(null);
user.setUpdatedAt(new Date());
userMapper.updateById(user);
log.info("会员到期降级: userId={}, 原等级={}", userId, level); // 记录原等级
```

- [ ] **Step 3: getMemberLevel() 支持 BASIC 有效期检查**

在 `getMemberLevel()` 方法中，`FAMILY` 判断之外补充 `BASIC`：

**修改前：**
```java
if ("FAMILY".equals(level) && user.getMemberExpireTime() != null) {
    if (user.getMemberExpireTime().before(new Date())) {
        return "FREE";
    }
}
```

**修改后：**
```java
if (("FAMILY".equals(level) || "BASIC".equals(level)) && user.getMemberExpireTime() != null) {
    if (user.getMemberExpireTime().before(new Date())) {
        return "FREE";
    }
}
```

- [ ] **Step 4: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 5: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/service/MembershipService.java
git commit -m "feat: MembershipService支持BASIC等级权限判断和到期降级"
```

---

## Task 7: 修改 AiGateway.chat() 插入 BASIC 配额扣减

**Files:**
- Modify: `cfc-backend/src/main/java/com/etotem/cfc/service/AiGateway.java`

**Interfaces:**
- Consumes: `BasicQuotaService.consumeQuota(userId, "AI_CHAT")`
- Produces: BASIC 用户对话时自动扣减配额，配额不足时返回 null（由 `AIChatController` 处理 403 响应）

- [ ] **Step 1: 在 chat() 方法开头插入配额检查**

在 `AiGateway.chat()` 方法中，找到：

```java
public Map<String, Object> chat(String query, Long userId, String conversationId,
                                  Map<String, Object> inputs) {
    if (!enabled || isCircuitOpen()) return null;
```

在 `if (!enabled || isCircuitOpen()) return null;` 之后插入：

```java
    // BASIC 配额检查（仅 BASIC 用户）
    if (userId != null) {
        QuotaConsumeResult quotaResult = basicQuotaService.consumeQuota(userId, "AI_CHAT");
        if (!quotaResult.isSuccess()) {
            log.info("AI对话配额不足: userId={}, toast={}", userId, quotaResult.getToastMsg());
            // 返回 null，由调用方 AIChatController 处理 403
            return null;
        }
    }
```

并在类头部添加 `@Resource`：

```java
@Resource
private BasicQuotaService basicQuotaService;
```

- [ ] **Step 2: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 3: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/service/AiGateway.java
git commit -m "feat: AiGateway.chat()插入BASIC AI配额扣减"
```

---

## Task 8: 修改 ReportSummaryService + AssessmentAppointmentService + DanReportUploadService

**Files:**
- Modify: `cfc-backend/src/main/java/com/etotem/cfc/service/ReportSummaryService.java`
- Modify: `cfc-backend/src/main/java/com/etotem/cfc/service/AssessmentAppointmentService.java`
- Modify: `cfc-backend/src/main/java/com/etotem/cfc/service/DanReportUploadService.java`

**Interfaces:**
- Consumes: `BasicQuotaService.consumeQuota(userId, quotaType)`
- Produces: 报告解读超限时返回 null/抛异常；测评预约超限时抛硬门禁异常；报告上传超限时返回 false

- [ ] **Step 1: ReportSummaryService.parseReport() 插入配额检查**

在 `ReportSummaryService.java` 的 `parseReport()` 方法入口插入（找到方法签名后第一行逻辑）：

```java
@Resource
private BasicQuotaService basicQuotaService;

// 在方法体开头插入：
if (userId != null) {
    QuotaConsumeResult result = basicQuotaService.consumeQuota(userId, "REPORT_READING");
    if (!result.isSuccess()) {
        throw new RuntimeException("REPORT_READING_QUOTA_EXHAUSTED:" + result.getToastMsg());
    }
}
```

- [ ] **Step 2: AssessmentAppointmentService.create() 插入硬门禁配额检查**

在 `AssessmentAppointmentService.java` 的 `create()` 方法入口插入：

```java
@Resource
private BasicQuotaService basicQuotaService;

// 在方法体开头插入：
if (userId != null) {
    QuotaConsumeResult result = basicQuotaService.consumeQuota(userId, "ASSESSMENT_QUOTA");
    if (!result.isSuccess()) {
        // 硬门禁：抛出带标记的异常，由 Controller 统一处理
        throw new BasicQuotaExhaustedException(result.getToastMsg());
    }
}
```

同时创建异常类：

```java
// cfc-backend/src/main/java/com/etotem/cfc/common/BasicQuotaExhaustedException.java
package com.etotem.cfc.common;

public class BasicQuotaExhaustedException extends RuntimeException {
    public BasicQuotaExhaustedException(String message) {
        super(message);
    }
}
```

- [ ] **Step 3: DanReportUploadService.upload() 插入配额检查**

在 `DanReportUploadService.java` 的 `upload()` 方法入口插入：

```java
@Resource
private BasicQuotaService basicQuotaService;

// 在方法体开头插入：
if (userId != null) {
    QuotaConsumeResult result = basicQuotaService.consumeQuota(userId, "REPORT_UPLOAD");
    if (!result.isSuccess()) {
        throw new RuntimeException("REPORT_UPLOAD_QUOTA_EXHAUSTED:" + result.getToastMsg());
    }
}
```

- [ ] **Step 4: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 5: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/common/BasicQuotaExhaustedException.java
git add cfc-backend/src/main/java/com/etotem/cfc/service/ReportSummaryService.java
git add cfc-backend/src/main/java/com/etotem/cfc/service/AssessmentAppointmentService.java
git add cfc-backend/src/main/java/com/etotem/cfc/service/DanReportUploadService.java
git commit -m "feat: 报告解读/测评预约/报告上传插入BASIC配额检查"
```

---

## Task 9: 新建 BasicQuotaScheduledTasks 定时任务

**Files:**
- Create: `cfc-backend/src/main/java/com/etotem/cfc/task/BasicQuotaScheduledTasks.java`
- Modify: `cfc-backend/src/main/java/com/etotem/cfc/task/MembershipScheduledTasks.java`（添加到期提醒任务）

**Interfaces:**
- Consumes: `BasicQuotaService.refreshMonthlyQuota()`、`MembershipService.listActiveBasicMemberUserIds()`
- Produces: 每月1号刷新配额；每天10点推到期提醒

- [ ] **Step 1: 在 MembershipService 新增 listActiveBasicMemberUserIds() 方法**

在 `MembershipService.java` 末尾（`listActiveMemberFamilyIds` 方法之后）追加：

```java
/**
 * 查询指定等级当前有效的基本会员用户ID列表（BASIC到期提醒用）
 */
public List<Long> listActiveBasicMemberUserIds() {
    Date now = new Date();
    List<User> basicUsers = userMapper.selectList(
            new LambdaQueryWrapper<User>()
                    .eq(User::getMemberLevel, "BASIC")
                    .isNotNull(User::getMemberExpireTime)
                    .gt(User::getMemberExpireTime, now));
    return basicUsers != null ? basicUsers.stream()
            .map(User::getId)
            .distinct()
            .collect(Collectors.toList()) : Collections.emptyList();
}
```

同时在文件头部确认 `UserMapper` 已 `@Resource` 注入（已有）。

- [ ] **Step 2: 创建 BasicQuotaScheduledTasks.java**

```java
package com.etotem.cfc.task;

import com.etotem.cfc.service.BasicQuotaService;
import com.etotem.cfc.service.MembershipService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;

import javax.annotation.Resource;
import java.util.List;

@Slf4j
@Component
public class BasicQuotaScheduledTasks {

    @Resource
    private BasicQuotaService basicQuotaService;

    @Resource
    private MembershipService membershipService;

    /**
     * 每月1号 00:00 刷新所有 BASIC 用户的月度配额
     */
    @Scheduled(cron = "0 0 0 1 * ?")
    public void refreshMonthlyQuota() {
        log.info("开始执行BASIC配额月度刷新定时任务");
        try {
            basicQuotaService.refreshMonthlyQuota();
            log.info("BASIC配额月度刷新定时任务执行完成");
        } catch (Exception e) {
            log.error("BASIC配额月度刷新定时任务执行失败", e);
        }
    }

    /**
     * 每天 10:00 检查即将到期的 BASIC 会员，推送到期提醒
     */
    @Scheduled(cron = "0 0 10 * * ?")
    public void sendExpiryReminders() {
        log.info("开始执行BASIC会员到期提醒定时任务");
        try {
            List<Long> basicUserIds = membershipService.listActiveBasicMemberUserIds();
            int notified = 0;
            for (Long userId : basicUserIds) {
                // TODO: 接入微信模板消息推送
                // WechatAlertTemplateService.sendBasicExpiryReminder(userId, basicQuotaService)
                notified++;
            }
            log.info("BASIC到期提醒完成, 处理用户数={}, 通知数={}", basicUserIds.size(), notified);
        } catch (Exception e) {
            log.error("BASIC到期提醒定时任务执行失败", e);
        }
    }
}
```

- [ ] **Step 3: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 4: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/service/MembershipService.java
git add cfc-backend/src/main/java/com/etotem/cfc/task/BasicQuotaScheduledTasks.java
git commit -m "feat: 新增BASIC配额刷新和到期提醒定时任务"
```

---

## Task 10: 新建 BasicQuotaController（配额查询 + 手动重置接口）

**Files:**
- Create: `cfc-backend/src/main/java/com/etotem/cfc/controller/BasicQuotaController.java`

**Interfaces:**
- Consumes: `BasicQuotaService.getMonthlyQuota()`、`BasicQuotaService.refreshMonthlyQuota()`
- Produces:
  - `POST /api/basic-quota/status` — 查询当前配额状态
  - `POST /api/admin/basic-quota/reset` — 运营手动重置配额（仅 ADMIN）

- [ ] **Step 1: 创建 BasicQuotaController.java**

```java
package com.etotem.cfc.controller;

import com.etotem.cfc.common.Result;
import com.etotem.cfc.dto.QuotaStatusDTO;
import com.etotem.cfc.service.BasicQuotaService;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/api/basic-quota")
public class BasicQuotaController {

    @Resource
    private BasicQuotaService basicQuotaService;

    /**
     * 查询当前用户某配额的剩余次数
     */
    @PostMapping("/status")
    public Result<QuotaStatusDTO> getQuotaStatus(
            @RequestAttribute("userId") Long userId,
            @RequestBody Map<String, String> body) {
        String quotaType = body.get("quotaType");
        if (quotaType == null) {
            return Result.error(400, "quotaType 不能为空");
        }
        QuotaStatusDTO dto = basicQuotaService.getMonthlyQuota(userId, quotaType);
        return Result.success(dto);
    }

    /**
     * 批量查询当前用户所有配额状态
     */
    @PostMapping("/status/all")
    public Result<Map<String, QuotaStatusDTO>> getAllQuotaStatus(
            @RequestAttribute("userId") Long userId) {
        Map<String, QuotaStatusDTO> result = new HashMap<>();
        result.put("AI_CHAT", basicQuotaService.getMonthlyQuota(userId, "AI_CHAT"));
        result.put("REPORT_READING", basicQuotaService.getMonthlyQuota(userId, "REPORT_READING"));
        result.put("ASSESSMENT_QUOTA", basicQuotaService.getMonthlyQuota(userId, "ASSESSMENT_QUOTA"));
        result.put("REPORT_UPLOAD", basicQuotaService.getMonthlyQuota(userId, "REPORT_UPLOAD"));
        return Result.success(result);
    }
}
```

- [ ] **Step 2: 在 AdminController 或新建 AdminBasicQuotaController 中添加手动重置接口**

在 `cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminController.java` 末尾追加方法，或在 `cfc-backend/src/main/java/com/etotem/cfc/controller/admin/` 下新建：

```java
// cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminBasicQuotaController.java
package com.etotem.cfc.controller.admin;

import com.etotem.cfc.common.Result;
import com.etotem.cfc.service.BasicQuotaService;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.Map;

@RestController
@RequestMapping("/api/admin/basic-quota")
public class AdminBasicQuotaController {

    @Resource
    private BasicQuotaService basicQuotaService;

    /**
     * 运营手动重置指定用户的当月配额（应急用）
     */
    @PostMapping("/reset")
    public Result<String> resetQuota(@RequestBody Map<String, Object> body) {
        Long userId = Long.valueOf(body.get("userId").toString());
        String quotaType = body.get("quotaType") != null ? body.get("quotaType").toString() : null;
        basicQuotaService.refreshMonthlyQuota(); // 重置所有用户当月配额
        return Result.success("配额刷新完成");
    }
}
```

- [ ] **Step 3: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 4: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/controller/BasicQuotaController.java
git add cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminBasicQuotaController.java
git commit -m "feat: 新增BasicQuotaController配额查询和管理端重置接口"
```

---

## Task 11: 前端 — 新增组件 + 权益页/开通页修改

**Files:**
- Create: `cfc-frontend/components/QuotaProgressBar.vue`
- Create: `cfc-frontend/components/UpgradeGuideModal.vue`
- Modify: `cfc-frontend/pages/profile/membership/index.vue`
- Modify: `cfc-frontend/pages/profile/upgrade/index.vue`

**Interfaces:**
- Consumes: `api.js` 中 `/api/basic-quota/status/all` 接口
- Produces: 权益页展示 BASIC 卡片；开通页展示 9.9 元月付选项；配额进度条组件；升级引导弹窗组件

- [ ] **Step 1: 创建 QuotaProgressBar.vue**

```vue
<template>
  <view class="quota-progress-bar">
    <view class="quota-label">
      <text class="quota-name">{{ name }}</text>
      <text class="quota-count">{{ remaining }} / {{ total }}</text>
    </view>
    <view class="quota-track">
      <view class="quota-fill" :style="{ width: percent + '%' }"></view>
    </view>
  </view>
</template>

<script>
export default {
  name: 'QuotaProgressBar',
  props: {
    remaining: { type: Number, default: 0 },
    total: { type: Number, default: 0 },
    name: { type: String, default: '' }
  },
  computed: {
    percent() {
      if (!this.total) return 0
      return Math.round((this.remaining / this.total) * 100)
    }
  }
}
</script>

<style scoped>
.quota-progress-bar {
  margin-bottom: 16rpx;
}
.quota-label {
  display: flex;
  justify-content: space-between;
  font-size: 24rpx;
  color: #666;
  margin-bottom: 8rpx;
}
.quota-track {
  height: 12rpx;
  background: #f0f0f0;
  border-radius: 6rpx;
  overflow: hidden;
}
.quota-fill {
  height: 100%;
  background: #F97316;
  border-radius: 6rpx;
  transition: width 0.3s;
}
</style>
```

- [ ] **Step 2: 创建 UpgradeGuideModal.vue**

```vue
<template>
  <view class="upgrade-guide-mask" v-if="visible" @click="handleMaskClick">
    <view class="upgrade-guide-content" :class="{ 'hard-modal': type === 'hard' }" @click.stop>
      <view class="upgrade-guide-icon">{{ icon }}</view>
      <view class="upgrade-guide-title">{{ title }}</view>
      <view class="upgrade-guide-desc">{{ desc }}</view>
      <view class="upgrade-guide-actions">
        <view v-if="type === 'soft'" class="btn-know" @click="handleKnow">知道了</view>
        <view v-if="type === 'soft'" class="btn-learn" @click="handleLearn">了解详情</view>
        <view v-if="type === 'hard'" class="btn-upgrade" @click="handleUpgrade">升级 FAMILY</view>
      </view>
    </view>
  </view>
</template>

<script>
export default {
  name: 'UpgradeGuideModal',
  data() {
    return { visible: false }
  },
  props: {
    type: { type: String, default: 'soft' }, // soft | hard
    quotaType: { type: String, default: '' },
    remaining: { type: Number, default: 0 },
    total: { type: Number, default: 0 }
  },
  computed: {
    icon() {
      return this.type === 'hard' ? '🔒' : 'ℹ️'
    },
    title() {
      return this.type === 'hard' ? '升级后即可使用' : '本月额度已用完'
    },
    desc() {
      if (this.type === 'hard') return '该功能为 FAMILY 会员专属权益，升级后即可使用'
      if (this.quotaType === 'AI_CHAT') return `您本月 AI 对话已用完（${this.total}/${this.total}），升级 FAMILY 享不限次畅聊`
      if (this.quotaType === 'REPORT_READING') return '本月报告解读额度已用完，升级 FAMILY 解锁不限次深度解读'
      if (this.quotaType === 'REPORT_UPLOAD') return `本月报告上传额度已用完（${this.total}/${this.total}），升级 FAMILY 解锁更多`
      return '本月额度已用完，升级 FAMILY 解锁更多权益'
    }
  },
  methods: {
    show() {
      this.visible = true
    },
    hide() {
      this.visible = false
    },
    handleKnow() {
      this.hide()
      this.$emit('know')
    },
    handleLearn() {
      this.hide()
      this.$emit('learn')
    },
    handleUpgrade() {
      this.hide()
      uni.navigateTo({ url: '/pages/profile/upgrade/index' })
      this.$emit('upgrade')
    },
    handleMaskClick() {
      if (this.type === 'soft') {
        this.hide()
      }
    }
  }
}
</script>

<style scoped>
.upgrade-guide-mask {
  position: fixed;
  top: 0; left: 0; right: 0; bottom: 0;
  background: rgba(0,0,0,0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 999;
}
.upgrade-guide-content {
  width: 600rpx;
  background: #fff;
  border-radius: 24rpx;
  padding: 48rpx 36rpx 36rpx;
  text-align: center;
}
.upgrade-guide-icon {
  font-size: 72rpx;
  margin-bottom: 24rpx;
}
.upgrade-guide-title {
  font-size: 32rpx;
  font-weight: 600;
  color: #333;
  margin-bottom: 16rpx;
}
.upgrade-guide-desc {
  font-size: 26rpx;
  color: #666;
  line-height: 1.6;
  margin-bottom: 36rpx;
}
.upgrade-guide-actions {
  display: flex;
  flex-direction: column;
  gap: 16rpx;
}
.btn-know, .btn-learn, .btn-upgrade {
  height: 80rpx;
  line-height: 80rpx;
  border-radius: 40rpx;
  font-size: 28rpx;
}
.btn-know {
  background: #f5f5f5;
  color: #666;
}
.btn-learn {
  background: transparent;
  color: #F97316;
  border: 2rpx solid #F97316;
}
.btn-upgrade {
  background: #F97316;
  color: #fff;
}
</style>
```

- [ ] **Step 3: 修改会员权益页 pages/profile/membership/index.vue**

在权益卡片列表渲染处，新增 BASIC 层：

在现有权益卡片循环中（找 `membership_benefits` 渲染部分），当 `levelCode === 'BASIC'` 时展示 `BASIC` 专属权益行。由于权益由后端 `MembershipController.getBenefits(levelCode)` 动态返回，前端只需确保 `levelCode` 传参正确。

关键修改点 — 在升级选项区域新增 9.9 元 BASIC 入口：

```vue
<!-- 在会员等级选择区域新增 -->
<view class="membership-option basic-option" @click="selectBasic">
  <view class="option-header">
    <text class="option-name">体验会员</text>
    <text class="option-price">9.9元<span class="unit">/月</span></text>
  </view>
  <view class="option-desc">解锁AI健康顾问、报告解读等核心功能</view>
</view>
```

- [ ] **Step 4: 修改会员开通页 pages/profile/upgrade/index.vue**

在升级选项列表中，当检测到用户当前为 FREE 时，展示 BASIC 升级选项（9.9 元/月，仅月付）：

```vue
<view v-if="currentLevel === 'FREE'" class="upgrade-card basic-card" @click="upgradeToBasic">
  <view class="card-title">
    <text class="title-text">体验会员</text>
    <text class="title-badge">推荐</text>
  </view>
  <view class="card-price">
    <text class="price-num">9.9</text>
    <text class="price-unit">元/月</text>
  </view>
  <view class="card-features">
    <text>AI健康顾问 · 报告解读 · 测评预约</text>
  </view>
  <button class="card-btn" hover-class="card-btn-hover">立即开通</button>
</view>
```

`upgradeToBasic` 方法调用 `POST /api/membership/order/create`，参数 `levelCode='BASIC'`，`period='monthly'`。

- [ ] **Step 5: 编译前端（npm run build 不需要，直接用微信开发者工具预览）**

- [ ] **Step 6: 提交**

```bash
git add cfc-frontend/components/QuotaProgressBar.vue
git add cfc-frontend/components/UpgradeGuideModal.vue
git add cfc-frontend/pages/profile/membership/index.vue
git add cfc-frontend/pages/profile/upgrade/index.vue
git commit -m "feat: 新增配额进度条和升级引导组件，权益页和开通页支持BASIC展示"
```

---

## Task 12: 前端 — AI 对话 / 测评预约 / 报告上传页配额显示

**Files:**
- Modify: `cfc-frontend/pages/ai-chat/index.vue`
- Modify: `cfc-frontend/pages/assessment/appointment/index.vue`
- Modify: `cfc-frontend/pages/health/report-list.vue`

**Interfaces:**
- Consumes: `QuotaProgressBar.vue`、`UpgradeGuideModal.vue` 组件；`/api/basic-quota/status/all` 接口
- Produces: 三个页面均显示配额剩余次数，超限触发对应引导弹窗

- [ ] **Step 1: AI 对话页显示配额**

在 `pages/ai-chat/index.vue` 的 `onLoad()` 中调用：

```js
import { getAllQuotaStatus } from '@/utils/api.js'
import QuotaProgressBar from '@/components/QuotaProgressBar.vue'
import UpgradeGuideModal from '@/components/UpgradeGuideModal.vue'

// 在 data 中注册组件
components: { QuotaProgressBar, UpgradeGuideModal }

// 在 onLoad 中查询配额
onLoad() {
  getAllQuotaStatus().then(res => {
    this.aiChatQuota = res.data.AI_CHAT || { remaining: 0, total: 3 }
  }).catch(() => {})
}

// 在发送消息前检查配额
sendMessage() {
  if (this.aiChatQuota && this.aiChatQuota.remaining <= 0) {
    this.$refs.upgradeModal.show()
    return
  }
  // 正常发送逻辑...
}
```

- [ ] **Step 2: 测评预约页显示配额 + 硬门禁**

在 `pages/assessment/appointment/index.vue` 的 `onLoad()` 中：

```js
onLoad() {
  getAllQuotaStatus().then(res => {
    this.assessmentQuota = res.data.ASSESSMENT_QUOTA || { remaining: 0, total: 1 }
  }).catch(() => {})
}

// 创建预约按钮绑定
createAppointment() {
  if (this.assessmentQuota && this.assessmentQuota.remaining <= 0) {
    this.$refs.upgradeModal.type = 'hard'
    this.$refs.upgradeModal.quotaType = 'ASSESSMENT_QUOTA'
    this.$refs.upgradeModal.show()
    return
  }
  // 正常预约逻辑...
}
```

- [ ] **Step 3: 报告上传/解读页显示配额**

在 `pages/health/report-list.vue` 的 `onLoad()` 中：

```js
onLoad() {
  getAllQuotaStatus().then(res => {
    this.reportUploadQuota = res.data.REPORT_UPLOAD || { remaining: 2, total: 2 }
    this.reportReadingQuota = res.data.REPORT_READING || { remaining: 1, total: 1 }
  }).catch(() => {})
}
```

在上传按钮和解读按钮处分别加配额判断，超限显示 Toast + 软引导。

- [ ] **Step 4: 编译验证**

```bash
mvn clean compile
```

Expected: 仅验证后端编译通过（前端改动无 Java 编译影响）。

- [ ] **Step 5: 提交**

```bash
git add cfc-frontend/pages/ai-chat/index.vue
git add cfc-frontend/pages/assessment/appointment/index.vue
git add cfc-frontend/pages/health/report-list.vue
git commit -m "feat: AI对话/测评预约/报告页集成配额显示和引导弹窗"
```

---

## Task 13: 支付成功后初始化 BASIC 配额（Integration）

**Files:**
- Modify: `cfc-backend/src/main/java/com/etotem/cfc/service/MembershipService.java`
- Modify: `cfc-backend/src/main/java/com/etotem/cfc/controller/MembershipController.java`（确认支付回调链）

**Interfaces:**
- Consumes: `ActivationQuotaService.activateBasicQuota(userId, familyId)`
- Produces: BASIC 支付成功后自动初始化 4 类配额

- [ ] **Step 1: 在 MembershipService.activateMembership() 中插入配额初始化**

在 `MembershipService.java` 的 `activateMembership()` 方法末尾（支付成功后）插入：

```java
@Resource
private ActivationQuotaService activationQuotaService;

// 在 activateMembership() 方法末尾，activateMembership 成功后插入：
// 如果是 BASIC 等级，初始化配额
if ("BASIC".equals(order.getLevelCode())) {
    try {
        activationQuotaService.activateBasicQuota(adminUserId, order.getFamilyId());
        log.info("BASIC配额初始化完成: userId={}, familyId={}", adminUserId, order.getFamilyId());
    } catch (Exception e) {
        log.error("BASIC配额初始化失败: userId={}", adminUserId, e);
    }
}
```

同时，在 `activateTrialMembership()` 方法中，BASIC 等级也走相同的配额初始化（trial 场景目前仅对 FAMILY 生效，BASIC 不做 trial，此处留扩展）。

- [ ] **Step 2: 编译验证**

```bash
mvn clean compile
```

Expected: BUILD SUCCESS。

- [ ] **Step 3: 提交**

```bash
git add cfc-backend/src/main/java/com/etotem/cfc/service/MembershipService.java
git commit -m "feat: BASIC支付成功后自动初始化月度配额"
```

---

## 计划自检

### Spec 覆盖检查

| Spec 章节 | 对应 Task | 状态 |
|-----------|----------|------|
| §2 BASIC等级定义 | Task 1 (DB seed) | ✅ |
| §3 features JSON | Task 6 (canUseFeature) | ✅ |
| §4.1 按 user_id 独立配额 | Task 2,4 (BasicQuotaUsage entity, BasicQuotaService) | ✅ |
| §4.2 月度配额详情（4类） | Task 4 (QUOTA_LIMITS 静态 Map) | ✅ |
| §4.3 basic_quota_usage 表 | Task 1 (schema.sql) + Task 2 (实体) | ✅ |
| §5.1 生命周期流转（支付→激活→降级） | Task 7 (AiGateway集成) + Task 13 (支付初始化) + Task 6 (降级支持) | ✅ |
| §5.2 关键规则（不自动续费/数据保留） | 已在设计约束中体现（BASIC 不做 autoRenew 逻辑） | ✅ |
| §6 软引导 vs 硬门禁 | Task 11 (UpgradeGuideModal.vue) + Task 8 (硬门禁异常类) | ✅ |
| §7 数据模型变更 | Task 1, 2, 7 | ✅ |
| §8.1 业务入口集成 | Task 7 (AiGateway) + Task 8 (3个Service) | ✅ |
| §8.2 定时任务 | Task 9 (BasicQuotaScheduledTasks) | ✅ |
| §9 前端组件 | Task 11 (进度条/弹窗) + Task 12 (页面集成) | ✅ |
| §10 埋点 | 前端组件已预留 `@emit`，埋点由前端按需添加 | ✅ |
| §13 验收用例 UC-01~UC-10 | 各 Task 覆盖 | ✅ |

### 潜在问题

1. **`ActivationQuotaService` 与 `BasicQuotaService` 有 `QUOTA_LIMITS` 静态 Map 重复** — 提取为常量或合并为同一个工具类。**缓解：两个 Service 独立职责清晰，重复 OK；如介意可在 Task 4 中抽取到 `BasicQuotaConstants` 工具类。暂不改动，保持简洁。**

2. **`MembershipScheduledTasks.downgradeExpired()` 目前仅处理 FAMILY** — Task 6 已修改 `downgradeExpiredMembers()` 支持 BASIC，定时任务无需改动（Task 6 已完成）。

3. **`BasicQuotaScheduledTasks.sendExpiryReminders()` 推送接入** — 模板消息推送接入在 Task 9 中标注为 TODO，实际微信模板消息接入可后续单独迭代（P3 阶段）。

---

## 执行顺序建议

```
Task 1 (DB迁移) → Task 2 (实体+Mapper) → Task 3 (DTO) → Task 4 (BasicQuotaService)
    ↓
Task 5 (ActivationQuotaService) → Task 6 (MembershipService修改) → Task 7 (AiGateway)
    ↓
Task 8 (3个Service集成) → Task 9 (定时任务) → Task 10 (Controller)
    ↓
Task 11 (前端组件) → Task 12 (前端页面) → Task 13 (支付初始化集成)
```

Task 2、3 可并行；Task 4、5 可并行（无相互依赖）；Task 6、7、8 可并行（均只修改已有文件）。

---

**Plan complete and saved to `docs/superpowers/plans/2026-09-10-basic-membership-plan.md`. Two execution options:**

**1. Subagent-Driven (recommended)** - 每个 Task 派发独立子代理，两阶段评审，快速迭代

**2. Inline Execution** - 在本会话中按顺序执行，带检查点

**Which approach?**