# 溪福俱乐部 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)  <br>设计: 仅年费 (1314元/年) |
| **字段不同** | 🟡 低 | 现有: features(JSON), maxChildren, maxTasksPerDay, aiReviewEnabled, prioritySupport, teacherConsultation  <br>设计: 仅 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 决策)