# 开发计划 v20260605

**制定日期：** 2026-06-05
**制定依据：** `docs/requirements-changelog.md` (v20260604.3~v20260604.5), `docs/test-coverage-report.md`, `docs/distribution-model-v2.md`, `docs/points-system.md`, `docs/quota-design.md`
**当前版本：** v20260604.5
**测试基线：** 183 tests, 0 failures, 5 skipped (pre-existing @Disabled)
**Admin 构建：** ✅ 成功 (21.77s)

---

## 一、项目状态总结

### 1.1 已编码（本地 master 领先 origin/master 10+ commits）

| 功能 | 版本 | 状态 | 说明 |
|------|------|------|------|
| 关系能量分析重设计 | v20260604.2 | ✅ 完成 | 后端6API+前端3页+Chatflow集成 |
| 提现管理 | v20260604.3 | ✅ 完成 | WithdrawService/Controller/Entity/前端页+测试 |
| 主题系统 | v20260604.3 | ✅ 完成 | ThemeToggle+theme.scss+store |
| 术语统一 | v20260604.3 | ✅ 完成 | 命盘→能量盘，文档+代码 |
| 关系人CRUD | v20260604.3 | ✅ 完成 | RelationController/Entity/Repository |
| 配额系统（新） | c5021ee | ✅ 完成 | QuotaService(174行)+UserConsultationQuota实体+Repository |
| 分销v2文档 | v20260604.5 | ✅ 完成 | 40%统一/间接10积分/删除补签/100分解1次 |
| SCSS 构建修复 | v20260605 | ✅ 完成 | uni.scss内联theme.scss + 11个页面移除冗余import + 4个darken()/CSS var兼容修复 |

### 1.2 未编码（待实现）

| 功能 | 版本 | 状态 | 优先级 |
|------|------|------|--------|
| 分销v2 代码实现 | v20260604.5 | ❌ 未编码 | P1 🔴 |
| 打卡积分体系 | v20260604.4 | ❌ 未编码（设计待确认） | P1 🔴 |
| QuotaService 集成 | c5021ee | ⚠️ 已编码未集成 | P1 🟡 |
| 推送代码到远程 | — | ⚠️ 已编码未推送 | P1 🟡 |

### 1.3 测试缺口

| 模块 | 代码行数 | 测试数 | 优先级 |
|------|---------|--------|--------|
| WxPayService | 189 | 0 | 高 🔴 |
| RelationAnalysisService | 新模块 | 0 | 中 🟡 |
| ExportService | - | 0 | 低 🟢 |
| @Disabled 测试 | - | 5个 | 低 🟢 |

### 1.4 本轮已修复（v20260605）

| # | 问题 | 修复内容 | 涉及文件数 |
|---|------|---------|-----------|
| 1 | `uni.scss` root stylesheet 相对 import 在页面内联时路径错误 | 内联 `theme.scss` 全部内容到 `uni.scss` | 1 |
| 2 | 11 个页面的 `<style>` 冗余 `@import "@/styles/theme.scss"`（`@` 别名不解析） | 全部移除（theme 已全局可用） | 11 |
| 3 | `darken(var(--color-brand), 4%)` — SCSS 颜色函数不能处理 CSS var | 改用 SCSS 字面变量 `$brand-color: #1E3A5F` | 4 (relations/analysis/common) |
| 4 | `darken($warm-white, 2%)` — 同上，`$warm-white: var(--color-bg)` | `$warm-white` 改用字面量 `#F8F6F1` | 1 |
| 5 | `QuotaService.existing.isEmpty()` Java 8 不兼容 | `!existing.isPresent()` | 1 |
| 6 | 微信开发者工具 `__subPageFrameEndTime__` / `__global` 运行时错误 | ⚠️ 环境问题（DevTools 2.01.2510290 + lib 3.15.2 内部错误），非代码问题，需用户侧确认 | — |

---

## 二、Sprint 1 — 基础设施 + 高优测试 (P0-P1)

### 目标
将本地代码推送到远程，堵住 WxPayService 无测试的风险缺口，将新配额系统接入核心链路。

### 2.1 推送代码到远程

**说明：** 本地 master 领先 origin/master 10+ 个 commit（含 withdraw/theme/quota/relation/SCSS修复等），需立即推送避免丢失。

**操作：** `git push origin master`

**前置条件：** 无

---

### 2.2 WxPayService 单元测试 (189行, 0覆盖)

**说明：** 支付核心服务无测试，一旦出错直接影响收入。需覆盖全部公共方法。

**需要 Mock 的外部依赖：**
- `WxPayProperties` — 微信支付配置（appId/mchKey/apiV3Key/privateKey/serialNo）
- `CloseableHttpClient` — HTTP 客户端
- `ConfigService` — sys_config 读取
- `OrderService` — 订单状态更新
- `UserService` — VIP 类型变更

**需要测试的场景：**
- `createOrder()` — 正常创建微信订单、支付金额计算、签名验证
- `handleNotify()` — 成功回调、失败回调、重复通知幂等
- `refund()` — 退款成功/失败/余额不足
- 异常场景：签名错误、订单不存在、重复回调、微信接口超时

**涉及文件：**
- `num-server/src/test/java/com/etotem/num/service/WxPayServiceTest.java`（新建）

---

### 2.3 QuotaService 集成到核心链路

**说明：** QuotaService (c5021ee) 已完成，但 ChatService 仍调用旧的 `userService.checkDailyQuota()` 和 `userService.consumeQuota()`。需替换为新的 `quotaService.checkAndConsume()`。

**工作量评估：**
- `ChatService.sendChatMessage()` — 替换 quota 检查行（~2行改）
- 验证 UserService 中的旧 `checkDailyQuota()` / `consumeQuota()` 是否被其他调用者使用
- 如其他调用者已迁移或无其他调用，清理旧方法
- ChatServiceTest 需验证新配额路径

**涉及文件：**
- `num-server/.../service/ChatService.java`（替换 quota 调用）
- `num-server/.../service/ChatServiceTest.java`（更新测试）
- `num-server/.../service/UserService.java`（视情况清理旧方法）

---

## 三、Sprint 2 — 分销v2 重构 (P1)

### 3.1 CommissionService 重写

**依据：** `docs/distribution-model-v2.md`

**变更清单：**

| # | 变更 | 说明 | 涉及文件 |
|---|------|------|---------|
| 1 | 删除二级佣金结算 | `level=2` 的分支全部移除 | `CommissionService.java` |
| 2 | 统一一级佣金 40% | 从 `commission.level1.rate_unified` 读取，不再按角色区分 | `CommissionService.java` |
| 3 | 新增间接邀请积分 | 间接邀请人不拿佣金，奖励 10 积分/次 | `CommissionService.java` |
| 4 | 佣金 `level` 语义更新 | 0=团队分红, 1=一级佣金, 2=预留 | `Commission.java` |
| 5 | sys_config 种子数据 | 新增 `commission.level1.rate_unified`, `commission.indirect_invite.points` 等 | `ConfigService.java` |

### 3.2 OrderService.paySuccess() 改造

**依据：** `docs/distribution-model-v2.md` §八

| # | 变更 | 说明 |
|---|------|------|
| 1 | 删除 `handleSecondLevelCommission()` 调用 | 二级佣金逻辑移除 |
| 2 | 统一调用一级佣金结算（40%） | 所有付费产品走统一逻辑 |
| 3 | 间接邀请人积分发放 | 在创建订单时检查上级的上级 |

### 3.3 UserService.hasPermission() 扩展

**变更：** 推广权限从 `practitioner` 扩展为所有付费用户（C端/家庭/超级/能量师）

**涉及文件：** `UserService.java`

### 3.4 前端佣金面板适配

| # | 变更 | 说明 |
|---|------|------|
| 1 | 佣金记录标签更新 | `一级佣金`（蓝） / `团队分红`（金） |
| 2 | 推广码面板可见范围扩展 | 所有付费用户可见，不再限能量师 |
| 3 | 能量师团队展示 | "我的团队"板块（直接下级数/团队销售额/分红） |

**涉及文件：** `client/pages/commission/index.vue`, `client/pages/profile/index.vue`

---

## 四、Sprint 3 — 打卡积分体系 (P1)

**依据：** `docs/points-system.md` (v20260604.4) + `v20260604.5` 修正（取消补签，100分解1次）

### 4.1 数据库表（3张）

| 表名 | 说明 | 依据 |
|------|------|------|
| `points_points` | 积分主表（userId/year/balance/consecutiveDays/lastCheckinDate） | §7.1 |
| `points_records` | 积分流水表（userId/type/amount/balanceAfter/refId） | §7.2 |
| `points_rewards` | 兑换奖励表（name/cost/type/isActive） | §7.3 |

### 4.2 后端

| # | 变更 | 说明 |
|---|------|------|
| 1 | `PointsPoints` / `PointsRecord` / `PointsReward` 实体 | 对应 3 张表 |
| 2 | `PointsRepository` / `PointsRecordRepository` / `PointsRewardRepository` | JPA CRUD |
| 3 | `PointsService` | checkin/balance/records/redeem/expire |
| 4 | `PointsController` | 6 个 REST 端点 |
| 5 | sys_config 种子数据 | 签到/邀请/兑换参数 |
| 6 | 年度清零定时任务 | `@Scheduled` 11月1日提醒/12月31日清零 |
| 7 | CommissionService 间接积分调用 | 分销v2间接邀请时调用 pointsService |

### 4.3 前端

| # | 页面/组件 | 说明 |
|---|-----------|------|
| 1 | 个人中心积分卡片 | 余额+连续天数+签到按钮 |
| 2 | 签到日历 UI | 连续天数展示+奖励预览 |
| 3 | 积分商城页面 | 奖励列表+兑换按钮 |
| 4 | 积分流水页面 | 进账/消耗记录 |
| 5 | 年底清零横幅 | 11月起展示 |

**涉及文件：** `client/pages/points/*.vue` (新建 3-4 页), `client/pages/profile/index.vue` (新增积分卡片)

---

## 五、Sprint 4 — 测试覆盖 + 低优任务 (P2-P3)

### 5.1 RelationAnalysisService 单元测试

**说明：** 新模块 6 个方法，0 测试覆盖。

**可测试方法：**
- `startAnalysis()` — 创建会话+首条消息
- `sendChatMessage()` — 发送消息+调用Dify
- `getChatHistory()` — 获取历史
- `listRecords()` / `getRecordDetail()` — 查询
- `deleteRecord()` — 删除

**涉及文件：** `num-server/src/test/java/com/etotem/num/service/RelationAnalysisServiceTest.java`（新建）

### 5.2 修复 5 个 @Disabled 测试

| 测试类 | 跳过数 | 原因 |
|--------|--------|------|
| CalculatorServiceTest | 2 | 外部位置公式/命名验证需领域知识确认 |
| CommissionServiceTest | 3 | 状态流转测试需修复数据准备（等分销v2重构后一并处理更合理） |

### 5.3 EPIC 9 前端收尾

| # | 任务 | 说明 |
|---|------|------|
| 1 | 学业方向 AI 前端入口 | "我的服务→学业方向"激活 |
| 2 | 人工方案工作台完整流程 | proposal/counter/accept 协商UI |
| 3 | 方案付费与交付展示 | 已实现后端，前端未完整串联 |

### 5.4 ExportService 单元测试（低优）

---

## 六、依赖关系图

```
Sprint 1 (P0-P1)
├── 2.1 Push to remote (无依赖)
├── 2.2 WxPayService tests (无依赖)
└── 2.3 Quota integration (依赖 QuotaService 已完成)

Sprint 2 (P1)
├── 3.1 CommissionService 重写 (无依赖)
├── 3.2 OrderService 改造 (依赖 3.1)
├── 3.3 UserService 扩展 (无依赖)
├── 3.4 前端适配 (依赖 3.1-3.3)
└── 3.4 间接积分调用 (依赖 Sprint 3 积分系统基础 → 可延迟)

Sprint 3 (P1)
├── 4.1 数据库表 (无依赖)
├── 4.2 后端Service+Controller (依赖 4.1)
└── 4.3 前端页面 (依赖 4.2)

Sprint 4 (P2-P3)
├── 5.1 RelationAnalysisService tests (无依赖)
├── 5.2 @Disabled tests (无依赖)
├── 5.3 EPIC 9 前端 (依赖已有后端代码)
└── 5.4 ExportService tests (无依赖)
```

---

## 七、可选/待确认

| 项目 | 说明 | 触发条件 |
|------|------|---------|
| 超级会员完整上线 | US-10.1~US-10.6 前端的超级会员引导付费流程 | 产品确认 |
| 八星号码分析前端优化 | `number-analysis.vue` 现有功能增强 | 产品确认 |
| 家庭套餐 | 全套 US-11 实现 | 产品决策 |
| 主题系统动态配置 | 管理员后台可切换主题色 | 待确认需求 |
| 微信开发者工具运行时错误 | `__subPageFrameEndTime__`/`__global` 错误 | 用户侧确认环境配置 |

---

## 八、风险与建议

### 8.1 微信开发者工具兼容性
TypeError: Cannot read property '__subPageFrameEndTime__' of null 和 __global 的两个错误均来自微信 `WAServiceMainContext.js` / `WASubContext.js` 运行时。可能原因：
- DevTools 版本 2.01.2510290 与基础库 3.15.2 组合的内部 bug
- 旧版 `unpackage/` 构建缓存未清理
- 建议：清除 `client/unpackage/` 目录后重新构建；如仍出现，尝试切换 DevTools 稳定版

### 8.2 建议执行顺序
1. **立即**：`git push origin master`（防丢失）
2. **并行**：WxPayService 测试 + QuotaService 集成（无依赖冲突）
3. **串行**：分销v2（Sprint 2）→ 积分体系（Sprint 3）
4. **空闲填充**：Sprint 4 低优测试

---

*最后更新：2026-06-05 by Sisyphus*