2026-10-23-basic-membership-spec-revision.md 20 KB

9.9 元体验会员(BASIC)权益口径修正 开发计划

面向 AI 代理的工作者: 必需子技能:使用 subagent-driven-development(推荐)或 executing-plans 逐任务实现本计划。步骤使用复选框(- [ ])语法跟踪进度。

协作模式(用户 2026-10-23 定): 每个任务由一个执行智能体完成、另一个独立核验智能体验证;执行与核验不得为同一会话。核验通过后该任务才可标记完成。

目标: 按用户定稿的新口径修正 9.9 元体验会员(BASIC)权益实现——AI 对话与饮食拍照识别改为每天 3 次、每日任务不限、开放指定商品会员价、测评预约去掉会员配额(改为凭已购测评额度)、去掉"AI 顾问"命名、报告上传全员开放、报告解读保留每月 1 次。

架构: 配额制度集中在 BasicQuotaService(日/月双周期 + 按等级分流),业务入口(AI 网关/报告解读/测评预约)只做门禁调用;等级与权益元数据走 membership_levels/membership_benefits(迁移 382 + schema.sql 双写);会员价复用既有 products.member_price + min_discount_level 机制并补 BASIC;前端仅改配额展示文案与失败提示。

技术栈: Spring Boot 2.7.18 + MyBatis-Plus + Java 8 + MySQL 8.0(后端 cfc-backend);uni-app + Vue2(小程序 cfc-frontend)。验证方式: cd E:/cfc/cfc-backend && mvn clean compile -q 编译通过;前端以代码审查 + 关键 diff 核对为主(uni-app 需 HBuilderX/CLI 构建,沙箱内不强制)。


需求口径(单一事实源,用户 2026-10-23 逐条定稿)

# 权益 口径 对应实现
1 家庭成员 可添加 3 人 max_children=3(不变)
2 AI 对话 每天 3 次(原"AI健康顾问"月配额,更名 + 改日配额) AI_CHAT 日配额;FAMILY+ 不限次
3 每日任务 不限(原 3 个/日) max_tasks_per_day=0(0=不限,无强制点,仅展示)
4 指定商品会员价 享受(原无) discount_purchase 生效:products.member_price + min_discount_level(NULL 时默认 BASIC)
5 饮食拍照识别 每天 3 次(原月配额) FOOD_RECOGNIZE 日配额;FAMILY+ 不限次
6 测评预约 不是特殊功能(原 BASIC 1 次/月硬门禁) 移除 ASSESSMENT_QUOTA 配额与 assessment_quota_lite;预约凭已购测评额度(AssessmentQuotaService,不动)
7 AI 顾问 没有该功能命名/权益 权益展示名"AI健康顾问"→"AI 对话";BASIC 保留对话入口(否则"AI 对话 3 次/天"无入口)
8 报告上传 全员开放,无会员限制 移除 health_report_upload_lite(本就无强制点,配额早在迁移 352 移除)
9 报告解读 保留每月 1 次(用户拍板) REPORT_READING 月配额不变;FAMILY+ 不限次

等级分流总规则(consumeMemberQuota): FAMILY 及以上(level_order > BASIC)不限次直接放行;BASIC 走配额;FREE 对 AI_CHAT/FOOD_RECOGNIZE 拒绝(与前端入口门禁一致),对 REPORT_READING 维持既有扣减口径(上传已对全员开放,不静默放开也不硬拦)。


当前草稿实现状态(重要)

编排智能体已按上述口径完成全部代码草稿(未编译、未提交、未验证),工作区即最新口径实现。执行智能体不应从零重写,而应:① git diff review 草稿与附录文件清单的逐项对照;② 修正缺陷;③ 完成本任务的编译/审查自验。核验智能体独立验收。

草稿已改文件(12 个):

文件 改动要点
cfc-backend/.../service/BasicQuotaService.java 整文件重写:QUOTA_LIMITS(AI_CHAT=3/FOOD_RECOGNIZE=3/REPORT_READING=1) + QUOTA_PERIODS(日/月);getMonthlyQuota→getQuotaStatus;新增 consumeMemberQuota(userId,type,rejectFree) 等级分流;refreshMonthlyQuota→refreshQuotas(只建不重置);新增 initUserQuotaRecords;unlimited 标记;toast 改"今日"
cfc-backend/.../dto/QuotaStatusDTO.java 新增 unlimited 字段
cfc-backend/.../service/AiGateway.java AI_CHAT 改调 consumeMemberQuota(userId,"AI_CHAT",true)
cfc-backend/.../controller/HealthReportController.java REPORT_READING 改调 consumeMemberQuota(proxyUploaderId,"REPORT_READING",false)
cfc-backend/.../service/AssessmentAppointmentService.java 移除 ASSESSMENT_QUOTA 硬门禁 + 无用字段
cfc-backend/.../service/MembershipService.java ① BASIC 分支移除 assessment_quota_lite/health_report_upload_lite;② 对比表 5 行更新(AI 对话/每天3次、商品折扣=指定商品会员价、测评预约不限、食材识别每天3次);③ activateMembership 接通 BASIC 配额初始化
cfc-backend/.../service/ActivationQuotaService.java 瘦身为委托 basicQuotaService.initUserQuotaRecords(消除两处配额表不一致)
cfc-backend/.../task/BasicQuotaScheduledTasks.java 月度刷新→每日 refreshQuotas()(cron 0 0 0 * * ?)
cfc-backend/.../controller/BasicQuotaController.java status/all 增加 FOOD_RECOGNIZE;单查改 getQuotaStatus
cfc-backend/.../service/ProductOrderService.java getEligibleMemberPrice:min_discount_level 为空时默认 BASIC(修复 FREE 也享会员价的漏洞)
cfc-backend/.../dto/ActivityDTO.java resolveMemberPrice 纳入 BASIC
cfc-backend/.../config/DatabaseInitializer.java 新增迁移 382 applyBasicMembership20261023Spec() 并在 runMigrations() 调用
cfc-backend/src/main/resources/schema.sql BASIC 种子同步新口径(features 9 项、max_tasks_per_day=0、权益 5 条)
cfc-frontend/pages/ai/chat.vue 配额条改"今日AI对话剩余" + unlimited 判断 + 发送拦截加 unlimited 判断
cfc-frontend/pages/ai/components/UpgradeGuideModal.vue 标题/文案按日/月配额分化,新增 FOOD_RECOGNIZE 文案
cfc-frontend/pages/growth/diet-checkin.vue 新增 loadFoodRecognizeQuota + 配额提示条 + 识别失败 toast(403 提示不再静默)

规范提醒

  • 后端接口统一 @PostMapping;响应统一 Result<T>;DI 用 @Resource
  • 迁移必须 try-catch 包裹、幂等(INSERT IGNORE / 条件 UPDATE);迁移方法在 runMigrations() 有序调用,编号顺延(本次为 382)
  • schema.sql 与迁移双写保持一致(新库安装走 schema.sql,老库升级走迁移)
  • 每任务完成后 mvn clean compile 通过方可交核验
  • Git 纪律: 提交作者 zxyj-web <agent@zxyj-w.com>;分支 cfclub;严禁 git add tools/xaf_agent_hub/config.json(含敏感凭证且未 gitignore);只提交本计划相关文件,不夹带无关改动
  • 前端改的是源码(pages/、components/);dist/、unpackage/ 为旧构建产物,不手改,重新编译由用户侧 HBuilderX 完成
  • 已知遗留(不在本计划范围,已向用户flag):MembershipService.listActiveBasicMemberUserIds() 仍返回空列表(到期提醒空转);resolveMemberPrice 未含 LIFETIME;BasicQuotaExhaustedException 已成死类

任务分解

任务 1:配额内核改造(BasicQuotaService + QuotaStatusDTO)

文件: cfc-backend/src/main/java/com/etotem/cfc/service/BasicQuotaService.java、cfc-backend/src/main/java/com/etotem/cfc/dto/QuotaStatusDTO.java

步骤:

  • Review 草稿:QUOTA_LIMITS 仅含 AI_CHAT=3 / FOOD_RECOGNIZE=3 / REPORT_READING=1(ASSESSMENT_QUOTA 必须已移除)
  • QUOTA_PERIODS:AI_CHAT/FOOD_RECOGNIZE=DAILY,REPORT_READING=MONTHLY;periodStart/periodEnd 按类型取日/月边界(日 00:00:00.000–23:59:59.999)
  • consumeQuota 按类型周期定位记录、查不到即新建(懒重置:跨周期自动换新)
  • consumeMemberQuota(userId, quotaType, rejectFree):level_order>BASIC 放行不落记录;==BASIC 扣配额;<BASIC 且 rejectFree 拒绝(toast+actionUrl);userId null/0 放行
  • consumeFoodRecognizeQuota 委托 consumeMemberQuota(...,"FOOD_RECOGNIZE",true)
  • getQuotaStatus:FAMILY+ 置 unlimited=true(前端据此隐藏进度条、不拦截)
  • refreshQuotas():只创建当前周期缺失记录,不得重置周期内已有用量;initUserQuotaRecords(userId) 供开通初始化
  • toast 文案:AI_CHAT/FOOD_RECOGNIZE 用"今日…已用完(3/3)",REPORT_READING 用"本月…已用完(1/1)"
  • mvn clean compile 通过

验收标准: 编译通过;QUOTA_LIMITS/QUOTA_PERIODS 与需求口径表逐项一致;日配额跨天自动恢复(周期 key=当天 00:00);FAMILY 用户 getQuotaStatus 返回 unlimited=true。

核验要点: 核验智能体逐条比对需求口径表;重点验算 getDayEnd/getMonthEnd 边界(23:59:59.999)与唯一键 (user_id, quota_type, period_start) 在月初 1 号日/月周期重合时不会读到旧记录(依赖任务 4 的清理 SQL)。


任务 2:业务入口门禁分流(AiGateway / HealthReportController / AssessmentAppointmentService)

文件: 上述三个 service/controller

步骤:

  • AiGateway.chat():AI_CHAT 改 consumeMemberQuota(userId,"AI_CHAT",true);保留 userId=0 系统任务旁路;配额不足仍 return null
  • HealthReportController.triggerAiAnalysis():REPORT_READING 改 consumeMemberQuota(proxyUploaderId,"REPORT_READING",false)
  • AssessmentAppointmentService.createAppointment():删除 ASSESSMENT_QUOTA 扣减与 BasicQuotaExhaustedException 抛出;删除不再使用的 basicQuotaService 字段;预约真实门禁是 AssessmentQuotaService.consumeQuota(quotaId, memberId)(已购额度),保持不动
  • mvn clean compile 通过

验收标准: BASIC 用户 AI 对话第 4 次/天返回 null(前端软引导);FAMILY 用户任意次数不被拦;FREE 直调 API 被拒;测评预约不再有会员级配额拦截;AssessmentAppointmentController 其他方法无连带破坏。

核验要点: 确认 AssessmentQuotaService(购买驱动额度池)未被误改;确认 AiGateway 其余逻辑(熔断/PII 脱敏)未动。


任务 3:会员中心(MembershipService canUseFeature + 对比表 + 开通初始化)

文件: cfc-backend/src/main/java/com/etotem/cfc/service/MembershipService.java、.../service/ActivationQuotaService.java

步骤:

  • canUseFeature BASIC 分支:保留 free_activities/free_courses/discount_purchase/invite_family/mascot_ai_lite/ai_report_reading_lite/growth_plan_lite/task_template_lite/referral_commission(9 项);移除 assessment_quota_lite、health_report_upload_lite
  • 对比表 getMembershipCompareData:①"AI健康顾问"行更名 "AI 对话",BASIC="每天3次";② 商品折扣行 BASIC="指定商品会员价";③ 测评预约行 BASIC="不限次数"(去掉 getQuotaLimit("ASSESSMENT_QUOTA") 调用);④ 食材图片解析行 BASIC="每天3次";⑤ 每日任务上限行随 max_tasks_per_day=0 自动显示"—"(不限)
  • activateMembership:"BASIC".equals(order.getLevelCode()) 时调 activationQuotaService.activateBasicQuota(adminUserId, familyId),try-catch 包裹不阻断开通主流程
  • ActivationQuotaService 委托 basicQuotaService.initUserQuotaRecords(userId)(不再自带 QUOTA_LIMITS)
  • mvn clean compile 通过

验收标准: BASIC features 与迁移 382 后的 DB 值一致(9 项);对比表 5 行文案与新口径一致;BASIC 支付成功后 basic_quota_usage 落 3 类当前周期记录(AI_CHAT/FOOD_RECOGNIZE 当日、REPORT_READING 当月,used=0)。

核验要点: 对比表是用户可见承诺,逐格核对;确认 getQuotaLimit("ASSESSMENT_QUOTA") 已无调用(返回 0 会被误显示)。


任务 4:数据库迁移 382 + schema.sql 双写

文件: cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java、cfc-backend/src/main/resources/schema.sql

步骤:

  • runMigrations() 中 removeReportUploadQuota() 之后调用 applyBasicMembership20261023Spec()
  • 迁移体(try-catch 三段,全部幂等):① UPDATE membership_levels BASIC 行:level_desc='9.9元/月体验版:AI对话每天3次、饮食识别每天3次、报告解读每月1次,享指定商品会员价'、features=9 项 JSON、max_tasks_per_day=0;② benefits:AI_CHAT_LITE 更名"AI对话(限3次/天)"、删 ASSESSMENT_QUOTA_LITE、INSERT IGNORE 增 FOOD_RECOGNIZE_LITE 与 MEMBER_PRICE;③ DELETE FROM basic_quota_usage WHERE quota_type IN ('ASSESSMENT_QUOTA','AI_CHAT','FOOD_RECOGNIZE')(切日制度,防月初周期重合撞唯一键;REPORT_READING 记录保留)
  • schema.sql BASIC 种子同步(level_desc/features 9 项/max_tasks_per_day=0;benefits 5 条:AI_CHAT_LITE、FOOD_RECOGNIZE_LITE、REPORT_READING_LITE、GROWTH_PLAN_LITE、MEMBER_PRICE)
  • mvn clean compile 通过

验收标准: 迁移可重复执行不报错;新库(schema.sql)与老库(迁移 382)终态一致;membership_benefits BASIC 恰好 5 条;旧 AI_CHAT/FOOD_RECOGNIZE 月记录已清。

核验要点: 核对迁移与 schema.sql 的 features JSON 逐字符一致(顺序也一致);确认 REPORT_READING_LITE 未被误删(用户拍板保留);确认迁移编号未与既有 351/352/360/381 冲突。


任务 5:配额状态接口与定时任务(BasicQuotaController + BasicQuotaScheduledTasks)

文件: 上述两个类

步骤:

  • BasicQuotaController:单查改调 getQuotaStatus;status/all 返回 AI_CHAT/FOOD_RECOGNIZE/REPORT_READING 三项(去掉 ASSESSMENT_QUOTA)
  • BasicQuotaScheduledTasks:refreshMonthlyQuota→refreshQuotas,cron 由 0 0 0 1 * ?(每月 1 号)改 0 0 0 * * ?(每日 00:00),语义改为"兜底创建当前周期记录"
  • mvn clean compile 通过

验收标准: 前端 /api/basic-quota/status/all 三类配额均返回且 FAMILY 带 unlimited=true;定时任务不会重置周期内用量(否则日配额会被每天清零重发——重点回归!)。

核验要点: 回归验算:若 10:00 已用 2 次 AI_CHAT,00:00 任务执行后当天记录 used 仍为 2(任务只建不重置)。


任务 6:指定商品会员价机制(ProductOrderService + ActivityDTO)

文件: 上述两个类

步骤:

  • ProductOrderService.getEligibleMemberPrice:min_discount_level 为 NULL 时默认按 BASIC 判定(修复 FREE 也享会员价的漏洞);等级比较用 getLevelOrder
  • ActivityDTO.resolveMemberPrice:会员等级集合纳入 BASIC(FAMILY/PREMIUM 保持不变;PROVIDER 仍不享)
  • mvn clean compile 通过

验收标准: BASIC 购买"设置 member_price 且 min_discount_level 为空/BASIC"的商品得会员价;FREE 得原价;FAMILY+ 得会员价;min_discount_level=FAMILY 的商品 BASIC 得原价。活动(activities)会员价对 BASIC 生效。

核验要点: 两个调用点(单商品下单 line≈263、多商品下单 line≈762)行为一致;确认修复不波及特价活动流程(特价覆盖会员价逻辑不变)。


任务 7:前端配额展示与提示(chat.vue / UpgradeGuideModal.vue / diet-checkin.vue)

文件: cfc-frontend/pages/ai/chat.vue、cfc-frontend/pages/ai/components/UpgradeGuideModal.vue、cfc-frontend/pages/growth/diet-checkin.vue

步骤:

  • chat.vue:配额条 name="今日AI对话剩余";外层 v-if="aiChatQuota && !aiChatQuota.unlimited";发送前拦截条件加 !this.aiChatQuota.unlimited &&(漏改会导致 FAMILY 被误拦——重点回归)
  • UpgradeGuideModal.vue:title 按 quotaType 分化(AI_CHAT/FOOD_RECOGNIZE→"今日额度已用完",其余"本月额度已用完");desc 增加 FOOD_RECOGNIZE 文案;AI_CHAT 文案改"今日"
  • diet-checkin.vue:import 增 getAllQuotaStatus;data 增 foodRecognizeQuota;onLoad 调 loadFoodRecognizeQuota(不得破坏既有 loadHistory 方法体——草稿阶段曾误删其开头,需回归);媒体工具栏下增加权提示条(v-if 含 !unlimited && total>0);recognize 失败分支 else if (recognizeRes.data.msg) 弹 toast(403 配额提示不再静默);样式 .recognize-quota-hint/.recognize-quota-text
  • 代码审查:三个文件的模板/脚本/style 结构完整,无语法错误(uni-app 编译由用户侧完成)

验收标准: BASIC 在 AI 对话页见"今日AI对话剩余 X/3"、饮食打卡页见"今日还可识别 X/3 次";FAMILY 两处均不展示;配额耗尽时弹窗/ toast 文案与后端一致。

核验要点: 逐处核对 unlimited 判断是否加全(漏一处即误拦 FAMILY 或误显示);核对 loadHistory/loadFoodRecognizeQuota 两方法体完整;确认 dist/、unpackage/ 未被修改。


任务 8:编译验证、文档更新与提交

文件: docs/superpowers/plans/2026-10-23-basic-membership-spec-revision.md(本文件)、docs/2026-10-23-basic-membership-gap-analysis.md、E:/cfc/.workbuddy/memory/2026-10-23.md

步骤:

  • cd E:/cfc/cfc-backend && mvn clean compile -q 全量通过(Java 8 兼容:无 var/List.of 等新语法)
  • 更新 docs/2026-10-23-basic-membership-gap-analysis.md:将"差异清单"改写为"新口径基线"(本计划即实现依据),标注已修复项
  • 更新 .workbuddy/memory/2026-10-23.md:追加"二十六、9.9 会员权益口径修正"章节(口径表 + 迁移 382 + 文件清单 + 遗留项)
  • Git:仅添加本计划 15 个源码文件 + 文档,作者 zxyj-web <agent@zxyj-w.com>,分支 cfclub,push 前 git status 确认无 tools/xaf_agent_hub/config.json 等敏感/无关文件
  • 提交信息示例:fix(membership): 9.9体验会员权益口径修正(AI对话/饮食识别改日配额、去测评配额、开放指定商品会员价)

验收标准: 编译零 error;文档/日志已更新;提交内容干净(git show --stat 核对文件清单)。

核验要点: 核验智能体独立跑一次 mvn clean compile;核对 git show --stat 文件数=15 个源码 + 文档;确认无敏感文件入库。


派发顺序与依赖

任务1(配额内核)→ 任务2(入口门禁)→ 任务3(会员中心)→ 任务4(迁移+schema)
                                                        ↘ 任务5(接口/定时)↗
任务6(会员价,独立)─┐
任务7(前端,依赖1的 unlimited 语义)─┘→ 任务8(编译+文档+提交)
  • 任务 6 与 1–5 无代码依赖,可并行派发
  • 任务 7 依赖任务 1 的 unlimited 字段语义(后端先行)
  • 每个任务:执行智能体交付 → 核验智能体验收 → 通过后才放行下一任务
  • 全部完成后由任务 8 统一编译、更新文档、提交推送

风险与回滚

风险 缓解
日/月双周期唯一键在月初 1 号重合读到旧月记录 迁移 382 清理 AI_CHAT/FOOD_RECOGNIZE 旧记录(任务 4)
FAMILY 被误拦/误显示剩余次数 unlimited 标记三处前端判断 + consumeMemberQuota 放行(任务 1/7 核验重点)
定时任务重置周期内用量导致配额无限 refreshQuotas 只建不重置(任务 5 回归用例)
迁移 382 重复执行 全部 INSERT IGNORE/条件 UPDATE/DELETE,幂等
FREE 报告解读口径变化 rejectFree=false 维持既有 1 次/月,不静默放开也不硬拦
前端未重新编译导致线上不生效 dist/ 为构建产物,需用户侧 HBuilderX 重新编译(计划内已声明,执行智能体不手改 dist)