صفحهٔ اصلی گشت‌و‌گذار راهنما
ثبت نام ورود
liaoxg
/
cfc
1
1
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
درخت: 09e58d7e49
شاخه‌ها تگ‌ها
cfc
/
docs
/
superpowers
/
plans
/
2026-06-04-phase1-and-phase2-diff-analysis.md

2026-06-04-phase1-and-phase2-diff-analysis.md 12 KB
تاريخچه خام

溪福俱乐部 Phase 1+2 — 现状差异分析

日期: 2026-06-04 目的: 在开始 Phase 1+2 实施前，明确现有代码与设计文档的差异，并提供决策依据

1. 现状总览

阶段 设计文档 实际状态 差异
Phase 0 (骨架) 角色模型 + TabBar + 服务商入驻 ✅ 已实现 (本次提交 8 个 commits) 无
Phase 1 (商品系统) 3 实体 + 3 Controller + 5 小程序页 + 3 Web 页 ❌ 未实现 实体不存在
Phase 2 (会员+积分) 2 实体 + 1 实体扩展 + 2 Controller + 3 小程序页 + 1 Web 页 🟡 部分实现 (代码层) 与设计不一致 + DB 表未建

2. Phase 1 现状分析

2.1 设计要求 (care-family-club-design.md §3.2-3.6)

项目 内容
新实体 Product, ProductOrder, SysConfig
新Controller ProductController, ProductOrderController, ProductVendorController, SysConfigController
新API端点 商品CRUD/审核/上下架/订单/支付/系统配置
新小程序页 5 页 (商品详情, 订单列表, 订单详情, 服务商中心, 商城页迭代)
新Web页 3 页 (商品管理, 订单管理, 系统配置)

2.2 实际状态

  • 0 个 Product 相关文件 (entity/mapper/service/controller 均不存在)
  • 0 个 SysConfig 相关文件
  • 商城页 pages/shop/index.vue 仅为占位 (Phase 0 实现)
  • 发现页 pages/discover/index.vue 仅为占位 (Phase 0 实现)

结论: Phase 1 完全未开始，需要从零实现。

3. Phase 2 现状分析

3.1 设计要求 (care-family-club-design.md §3.4-3.5, §5-6)

项目 内容
新实体 FamilyMembership, MemberSelection
实体扩展 PointsLog 新增 type=member_deduct
新Controller MembershipController, MemberSelectionController
新API端点 会员信息/购买/续费/等值商品选择/积分抵扣
新小程序页 3 页 (会员中心, 购买/续费, 等值商品选择)
新Web页 1 页 (会员管理)
会员等级 3 等级: free / standard / premium
会员年费 standard = 1314元/年, premium = SysConfig 配置
核心业务 1314 等值商品选择 + 积分抵扣会员费

3.2 实际状态

3.2.1 已存在的文件

文件 内容 状态
entity/FamilyMembership.java familyId, levelCode, startDate, endDate, paymentMethod, paymentStatus, orderNo, transactionId, amount, autoRenew, createdAt, updatedAt ✅ 存在
entity/MembershipLevel.java levelCode, levelName, levelDesc, priceMonthly, priceYearly, features(JSON), maxChildren, maxTasksPerDay, aiReviewEnabled, prioritySupport, teacherConsultation ✅ 存在
entity/PaymentOrder.java orderNo, familyId, levelCode, paymentType, amount, status, payMethod, transactionId, paidAt ✅ 存在
controller/MembershipController.java 6 端点: /levels, /my, /current, /orders, /notify, /can-use ✅ 存在
service/MembershipService.java 6 方法 (含占位实现) ✅ 存在
service/api/MembershipServiceInterface.java 接口定义 ✅ 存在
service/DatabaseSyncService.java 注册了 membership_levels/family_memberships 表 ✅ 存在

3.2.2 关键问题

问题 严重度 详情
DB 表未建 🔴 严重 family_memberships, membership_levels, payment_orders 在 DatabaseInitializer.java 无 DDL; 在 schema.sql 也无 DDL。代码无法运行。
会员等级 4 vs 3 🟠 中 现有 FREE/BASIC/PROFESSIONAL/ENTERPRISE (4 等级) 与设计 free/standard/premium (3 等级) 不一致。
计价模式不同 🟠 中 现有: 月费 + 年费 (monthly + yearly)
设计: 仅年费 (1314元/年)
字段不同 🟡 低 现有: features(JSON), maxChildren, maxTasksPerDay, aiReviewEnabled, prioritySupport, teacherConsultation
设计: 仅 startDate/endDate/autoRenew/paymentMethod/pointsDeducted/pointsAmount/status
1314 等值商品选择 🔴 缺失 MemberSelection 实体不存在, MemberSelectionController 不存在
积分抵扣会员费 🔴 缺失 PointsLog.type=member_deduct 扩展未实现, deductForMembership 方法未实现
createOrder 残缺 🔴 严重 orderMapper.insert 被注释掉, 订单无法写入
processPaymentCallback 残缺 🔴 严重 返回 true 但未执行任何实际操作
familyId 占位 🟠 中 多处硬编码 Long familyId = 1L, 未从 JWT 提取
Free 等级处理 🟡 低 现有代码有 FREE 等级; 设计 free 是"未付费的默认状态", 不需要独立的 MembershipLevel 记录
SysConfig 不存在 🔴 缺失 points_exchange_rate, points_deduct_cap, member_fee_standard, member_fee_premium, member_eligible_budget, renewal_discount_rate, member_discount_standard, member_discount_premium 等配置均无实现

3.2.3 无人引用的 API

  • 无 frontend 消费者: grep 整个 cfc-frontend (排除 node_modules) 找不到 membership 相关引用
  • 无 web admin 消费者: grep 整个 cfc-web (排除 node_modules) 找不到 membership 相关引用
  • 无内部 Service 调用: 现有代码无其他 Service 调用 MembershipService

结论: 现有 Phase 2 代码是孤岛 — 没有任何消费者。修改它不会影响其他业务。

4. 决策选项分析

4.1 选项 A: 沿用现有 4 等级 (FREE/BASIC/PROFESSIONAL/ENTERPRISE)

维度 评估
改动量 🟢 较小 — 复用现有实体/Controller/Service 框架
设计一致性 🟠 偏离 — 与设计文档 3 等级不一致
业务契合 🟠 4 等级更细, 适合阶梯定价, 但与"1314元年费"哲学不符
向后兼容 🟢 DB 数据兼容 (现有数据保留)
代码修改 补全 createOrder 实际逻辑, 补全 processPaymentCallback, 修正 familyId 提取, 补 DB DDL, 添加 MemberSelection, 添加积分抵扣
风险 🟢 低 (无消费者, 修改安全)

4.2 选项 B: 重写为设计 3 等级 (free/standard/premium)

维度 评估
改动量 🟠 中等 — 需要修改 entity 字段, 重写 MembershipService 业务逻辑, 调整 levelCode 值
设计一致性 🟢 完全对齐设计文档
业务契合 🟢 "体验-标准-高级"3 等级匹配 1314 会员费定位
向后兼容 🟠 DB 需要数据迁移 (FREE/BASIC/PROFESSIONAL/ENTERPRISE → free/standard/premium)
代码修改 删除 features/maxChildren 等冗余字段, 重写 MembershipService, 重建 DB DDL + 种子数据, 写 MemberSelection 完整实现
风险 🟡 中 (无消费者, 但需要数据迁移脚本)

4.3 选项 C: 部分对齐 (混合方案)

保留现有 4 等级 (FREE/BASIC/PROFESSIONAL/ENTERPRISE)，但不重写，仅在 Phase 2 计划中：

  • 把 BASIC 视为 standard (1314元/年)
  • 把 PROFESSIONAL 视为 premium (SysConfig 配置)
  • FREE 视为设计中的"未付费免费体验" (无 FamilyMembership 记录，自动 isActive=false)
  • 删除 ENTERPRISE 等级 (暂无需求)
维度 评估
改动量 🟢 最小
设计一致性 🟠 仍偏离 — 4 等级但只用 3 个
业务契合 🟠 OK — 业务效果与设计等价
风险 🟢 最低

5. 推荐

推荐 选项 A: 沿用现有 4 等级

理由:

  1. 零消费者 — 现有 MembershipController 无任何 API 调用方, 重构无破坏性影响
  2. 代码已存在 — 6 端点 + 6 Service 方法 + 3 实体结构已落地, 复用价值高
  3. 改动聚焦 — 重点补全: (1) DB DDL (2) createOrder/processPaymentCallback 实际逻辑 (3) familyId 提取 (4) MemberSelection 新增 (5) 积分抵扣
  4. 设计偏离可控 — 4 等级可视为"更细粒度", 不影响业务目标; 设计文档可后续修订
  5. 降低风险 — 不引入数据迁移脚本, 不破坏现有代码

关键补全任务 (Phase 2 计划):

  1. DatabaseInitializer 增加 3 张表 DDL + 种子数据 (FREE/BASIC/PROFESSIONAL/ENTERPRISE 各 1 条)
  2. MembershipService.createOrder 实际写库 (注入 OrderMapper)
  3. MembershipService.processPaymentCallback 实际开通/续费会员
  4. MembershipController 所有 familyId 改用 @RequestHeader("X-User-Id") + User 查询
  5. MemberSelection 实体 + Mapper + Service + Controller
  6. PointsLog.type 扩展 (member_deduct 枚举值)
  7. PointsService.deductForMembership 新方法
  8. SysConfig 实体 (Phase 1 计划实现, Phase 2 复用)
  9. 前端: 会员中心/购买/等值商品选择 3 页
  10. Web: 会员管理 1 页

6. 实施顺序

Phase 0 (✅ 已完成) 角色模型 + TabBar + 服务商入驻
       ↓
Phase 1 (🆕 需新建)  商品系统
   - Product / ProductOrder / SysConfig
   - 服务商发布商品 + 管理员审核
   - 商城页可浏览可购买
       ↓
Phase 2 (🟡 部分实现) 会员+积分
   - 补 DB DDL + 补 Membership 业务逻辑
   - 新增 MemberSelection (1314等值商品选择)
   - 新增积分抵扣会员费
   - 前端 3 页 + Web 1 页

严格依赖: Phase 2 依赖 Phase 1 的 Product (等值商品选择需要 Product 列表)

7. 需用户确认事项

  1. 会员等级: 选项 A (沿用 4 等级) / 选项 B (重写 3 等级) / 选项 C (混合)
  2. Phase 1 计划范围: 完整实现 Product/Order/SysConfig + 5 小程序页 + 3 Web 页
  3. Phase 2 计划范围: 补 Membership 业务 + MemberSelection + 积分抵扣 + 3 小程序页 + 1 Web 页
  4. 支付方式: 纯余额/积分支付 (无真实微信支付)
  5. 种子数据: 5 个示例商品 (覆盖 5 种 productType)

8. 文件清单预估

Phase 1 计划文档需覆盖

后端新建 (~10 个文件):

  • entity/Product.java, entity/ProductOrder.java, entity/SysConfig.java
  • mapper/ProductMapper.java, mapper/ProductOrderMapper.java, mapper/SysConfigMapper.java
  • service/ProductService.java, service/ProductOrderService.java, service/SysConfigService.java
  • dto/ProductDTO.java, dto/ProductOrderDTO.java, dto/SysConfigDTO.java
  • controller/product/ProductController.java, controller/product/ProductOrderController.java, controller/product/ProductVendorController.java, controller/config/SysConfigController.java

后端修改 (~2 个文件):

  • config/DatabaseInitializer.java (新增 3 张表 DDL + 种子)
  • entity/User.java (无变更, 但需在 DatabaseInitializer 增加商品 seeder)

前端新建 (~5 个文件):

  • pages/discover/product-detail.vue (商品详情，可复用商城/发现)
  • pages/shop/order-list.vue (订单列表)
  • pages/shop/order-detail.vue (订单详情)
  • pages/vendor/products.vue (服务商商品管理)
  • pages/vendor/orders.vue (服务商订单管理)

前端修改 (~3 个文件):

  • pages/shop/index.vue (从占位 → 商品列表)
  • pages/discover/index.vue (从占位 → 活动+课程列表)
  • pages/vendor/center.vue (添加商品管理/订单管理入口)
  • utils/api.js (新增 product APIs)

Web 新建 (~3 个文件):

  • src/views/admin/ProductManage.vue (商品管理)
  • src/views/admin/OrderManage.vue (订单管理)
  • src/views/admin/SysConfig.vue (系统配置)

Web 修改 (~3 个文件):

  • src/api/product.js (新建)
  • src/router/index.js (新增路由)
  • src/views/Layout.vue (新增菜单)

Phase 2 计划文档需覆盖 (待 Phase 1 完成后再细化)

(略 — 取决于用户选项 A/B/C 决策)