# 开发计划 v20260604

**制定日期：** 2026-06-04
**制定依据：** `docs/requirements-changelog.md` (v20260604.1 + v20260604.2) + `docs/test-coverage-report.md` + 当前代码审计
**当前代码状态：** ⚠️ 测试编译失败（7处） + EPIC 10 后端大部分就绪 + 关系分析需重构

---

## 状态摘要

| 维度 | 状态 |
|------|------|
| 后端编译 | ✅ 通过 |
| 测试编译 | ❌ 7处失败（ChatService/OrderService 签名变更导致）|
| 测试运行 | ⏳ 修复后需验证 |
| v20260604.1 (EPIC 10 超级会员) 完成度 | ~60%（后端支付/佣金/升级就绪，前端支付模板就绪，订阅入口待补充） |
| v20260604.2 (重命名+关系分析重设计) 完成度 | ~0%（代码未动）|

---

## PHASE 0：阻塞项修复（P0，1天）

### 0.1 修复测试编译失败

**问题：** 7处测试编译失败，原因：

| 文件 | 位置 | 失败原因 |
|------|------|---------|
| `ControllerIntegrationTest.java` | L295 | `ChatService.sendMessage` 签名变更 — 新增 `String` 参数（chartRecordId/sessionId） |
| `ControllerIntegrationTest.java` | L333 | `OrderService.createOrder` 签名变更 — 参数从 5→6 个（新增 isSeedPrice 等） |
| `ChatServiceTest.java` | L53, L76, L90, L108, L130 | 同 sendMessage 签名变更 |

**修复策略：** 为每个调用点补齐缺少的参数（`null` 占位或合理的默认值），确保编译通过后运行全量测试验证。

**涉及文件：**
- `num-server/src/test/java/.../controller/ControllerIntegrationTest.java`（2处）
- `num-server/src/test/java/.../service/ChatServiceTest.java`（5处）

**验收标准：** `mvn test` 编译通过，运行 `Tests run: N, Failures: 0`

### 0.2 验证已知 Bug 修复

| Bug | 状态 | 验证方式 |
|-----|------|---------|
| `upgradeVip` 不认 `"super_member"` productType | ✅ 已修复（0.1中添加别名） | 重启后端，annual→super_member 支付，检查 user.vipType = 'super_annual' |
| `chart-compare` 页面未注册 pages.json | ✅ 已修复（0.2中注册） | 导航到 relations/chart-compare → 正常打开 |
| `number-analysis` 页面未注册 pages.json | ✅ 已修复（0.2中注册） | 导航到 relations/number-analysis → 正常打开 |
| `POST /api/profile/info` 缺 `isSeedPriceUser` 字段 | ⏳ 待验证 | 检查 ProfileController.getInfo 返回值 |

---

## PHASE 1：EPIC 10 超级会员收尾（P1，1-2天）

### 1.1 超级会员订阅入口 × 3

参考 US-10.1，需要在 3 处嵌入订阅入口：

| 位置 | 状态 | 需要做的事 |
|------|------|----------|
| 关系页（未授权时） | ❌ 待实现 | `relations/index.vue` 顶部 Banner：`🔒 开通超级会员...` |
| 我的页面（免费用户/年费用户） | ✅ 已实现 | 免费用户双方案卡片 + 年费用户"升超级"按钮已存在 |
| AI 解读页（咨询结束后） | ❌ 待实现 | `chart/index.vue` 底部或右上角入口 |

**文件：**
- `client/pages/relations/index.vue`
- `client/pages/chart/index.vue`

### 1.2 超级会员升级→能量师补差价

**当前状态：** `UserService.upgradeVip()` 的 `super_annual → practitioner` 路径已存在。但需要验证：
- 佣金补差逻辑：`OrderService.handlePractitionerCommission()` 中的 `sumAnnualCommissionTo()` 已扩展到包含 `super_member` 订单的佣金
- 前端入口：超级会员卡片上的"升级能量师"按钮已存在（`profile/index.vue` L97）

**待验证项：** 升级定价前端是否正确调用了 `pricingApi.upgrade()` 并传 `productType: 'practitioner'`

### 1.3 超级会员佣金

**当前状态：** `OrderService.handleSuperMemberCommission()` 已实现，使用 `commission.super_member.direct_rate(3000)/upstream_rate(500)` 费率。

**待验证：** 推广超级会员的佣金结算是否正确，佣金明细是否显示"超级会员直接推荐佣金"等备注。

### 1.4 管理后台配置卡片

**当前状态：** 管理后台是否存在超级会员定价+佣金配置卡片？

**需检查：** `admin/src/views/settings/index.vue` — 确认是否已有超级会员定价（`pricing.super_member`）和超级会员佣金（`commission.super_member.*`）的配置卡片。

---

## PHASE 2：全代码库"命盘→能量盘"重命名（P1，1天）

### 2.1 范围

v20260604.2 要求将所有"命盘"改为"能量盘"（含 3 处"数字能量能量盘"→"数字能量盘"）。文档部分（README, style-guide, system-spec 等）已在需求变更中更新，**但代码内仍包含大量"命盘"字样**。

### 2.2 搜索范围

| 层 | 搜索关键词 | 文件量 | 优先级 |
|---|-----------|-------|-------|
| 后端 Java | "命盘" 在注释/异常消息/字段描述 | ~15-20处 | 高（用户可见） |
| 前端 Vue | "命盘" 在模板文本/变量名/注释 | ~30-40处 | 高（用户可见） |
| 前端 utils | calculator.js 注释 | ~5处 | 低（仅参考） |
| 测试文件 | "命盘" 在测试描述 | ~10处 | 低（内部） |

### 2.3 注意

- **变量名、数据库字段名、API 路径** — 不改（避免破坏性变更）
- **用户可见文案** — 全改（Toast提示、页面标题、功能描述）
- **注释/文档字符串** — 全改（保持一致性）
- **3处特例**："数字能量能量盘"→"数字能量盘"

---

## PHASE 3：关系能量分析重设计（P1-P2，3-4天）

### 3.1 背景

v20260604.2 彻底重设了关系能量分析流程：

```
旧: 添加关系人 → 双命盘对比（静态）→ AI 合盘解读（Workflow）
新: 添加关系人 → 选择多人 → 提问 → AI 对话（Chatflow）→ 分析记录留存
```

### 3.2 数据库变更

| 表 | 变更 | 说明 |
|---|------|------|
| `relations` | 移除 `compatibility_score`, `ai_analysis_cache`, `last_analyzed_at` | 旧字段废弃 |
| `relation_analysis_records` | **新增** | 分析会话，含成员快照（JSON） |

`relation_analysis_records` 表结构（参考 US-10.6）：

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long PK | |
| userId | Long | 创建者 |
| title | String | 分析主题（自动生成 or 用户填写） |
| member_snapshot | Text (JSON) | 参与成员快照（用户本人+选取的关系人，含姓名/生日/性别/关系类型）|
| chat_session_id | String | Dify Chatflow 会话 ID |
| status | String | active / archived |
| create_time | LocalDateTime | |
| update_time | LocalDateTime | |

### 3.3 后端 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `POST /api/relation/analysis/start` | 新建分析会话 | 选关系人→创建会话→返回 session_id |
| `POST /api/relation/analysis/list` | 历史记录 | |
| `POST /api/relation/analysis/detail` | 单条详情 | |
| `POST /api/relation/analysis/delete` | 删除记录 | |
| `POST /api/relation/analysis/chatSend` | 发送消息 | 调用 Dify Chatflow |
| `POST /api/relation/analysis/chatHistory` | 聊天历史 | |

**注意：** 旧 API（`/api/relation/compare`, `relation/compare/interpret`）可保留或标记废弃。

### 3.4 Dify 变更

| 变更 | 说明 |
|------|------|
| Workflow → Chatflow | 关系分析从结构化输出改为自然语言对话 |
| 新增 Chatflow | inputs: 成员快照(JSON) + 用户问题; 输出: AI 回答 |
| sys_config 新增 | `dify.chatflow.relation_app_id`（Chatflow ID） |

### 3.5 前端页面

| 页面 | 说明 | 状态 |
|------|------|------|
| `relations/index.vue` | 关系首页：关系人列表 + 分析记录列表 + 新建分析入口 | ❌ 需重写 |
| `relations/analysis-chat.vue`（新建）| 分析对话页：成员列表 + 对话区 + 输入框 | 🆕 新建 |
| `relations/number-analysis.vue` | 八星号码分析（不受影响，保持原有设计） | ✅ 已存在 |

### 3.6 现有资产复用

| 资产 | 用途 |
|------|------|
| `TriangleChart.vue` | 对话中可嵌入展示每个成员的三角图（作为参考信息） |
| `ChatService` / Dify Chatflow 集成 | 复用现有 AI 对话框架 |
| `CalculatorService` | 成员能量盘数据由后端计算，前端直接渲染 |
| `Relation` entity / repository | 关系人 CRUD 仍可用 |

---

## PHASE 4：测试质量改进（P2，2天）

### 4.1 WxPayService 单元测试（P0 推荐）

**优先级理由：** 支付是资金核心，且为当前完全未覆盖模块（189行，🔴风险）。

**测试内容：**
- `createUnifiedOrder`：参数组装、签名验证、Mock RestTemplate 响应
- 异常路径：微信返回错误、网络超时
- Mock 模式验证

### 4.2 calculator.js 一致性验证

**方案：** 取 N≥50 组生日，分别在前端（Node 环境运行 calculator.js）和后端（CalculatorService）计算，对比 24 位置结果。

### 4.3 修复 @Disabled 测试

| 位置 | 问题 |
|------|------|
| `CommissionServiceTest.testCommissionStatusFlow_pendingToSettled` | 状态流转断链 |
| `CommissionServiceTest.testCommissionStatusFlow_settledToAvailable` | 自动流转未实现 |
| `CalculatorServiceTest.testExternalPosition_Formulas_Documented` | 外部位置公式待验证 |
| `CalculatorServiceTest.testExternalPosition_30PositionNaming` | 30位置命名待验证 |

### 4.4 前端测试框架搭建（基建）

搭建 vitest + @vue/test-utils，先覆盖核心模块：
1. `stores/user.js` — Pinia store 测试
2. `TriangleChart.vue` — 组件渲染测试

---

## PHASE 5：文档与收尾（P3，1天）

### 5.1 更新测试报告

```yaml
生成日期: 2026-06-04
后端单元测试: N 运行, 0 失败
Playwright E2E: 3/3 通过
测试编译: ✅ 通过
新增测试: WxPayService, calculator.js 一致性
```

### 5.2 更新需求变更日志

需追加 v20260604.3 版本（如果本次开发引入新的需求变更）。

---

## 执行顺序与依赖图

```
PHASE 0 (1天)
 ┌─────────────────────────────┐
 │ 0.1 修复测试编译             │ ← 无依赖
 │ 0.2 验证已知 Bug             │ ← 重启后端后验证
 └──────────┬──────────────────┘
            │
            ▼
PHASE 1 (1-2天)      PHASE 2 (1天)
 ┌──────────────┐   ┌────────────────┐
 │ 1.1 订阅入口   │   │ 命盘→能量盘重命名│ ← 无依赖，可并行
 │ 1.2 升级验证   │   └────────────────┘
 │ 1.3 佣金验证   │
 │ 1.4 管理后台   │
 └──────┬───────┘
        │
        ▼
PHASE 3 (3-4天)     ← 依赖 PHASE 2（命名一致性）
 ┌─────────────────────────────┐
 │ 3.2 DB: relation_analysis   │
 │ 3.3 后端 API (6个)          │
 │ 3.4 Dify Chatflow 迁移      │
 │ 3.5 前端页面重写/新建        │
 └─────────────────────────────┘

PHASE 4 (2天)        ← 可与 PHASE 1-3 并行
 ┌─────────────────────────────┐
 │ 4.1 WxPayService 测试       │
 │ 4.2 calculator.js 一致性    │
 │ 4.3 修复 @Disabled 测试     │
 │ 4.4 前端测试框架             │
 └─────────────────────────────┘

PHASE 5 (1天)
 ┌─────────────────────────────┐
 │ 5.1 更新测试报告             │
 │ 5.2 更新变更日志             │
 └─────────────────────────────┘
```

## 预估总工期

| Phase | 估算 | 并行 |
|-------|------|------|
| PHASE 0 | 1天 | — |
| PHASE 1 | 1-2天 | 与 Phase 2 并行 |
| PHASE 2 | 1天 | 与 Phase 1 并行 |
| PHASE 3 | 3-4天 | — |
| PHASE 4 | 2天 | 与 Phase 1-3 并行 |
| PHASE 5 | 1天 | 最后收尾 |
| **合计** | **5-8天** | 含并行（1人全栈） |

## 验收检查清单

- [ ] `mvn test` 编译通过，183+ 测试运行通过
- [ ] 超级会员可购买 ¥1,314/年并开通，vipType='super_annual'
- [ ] C端年费→超级会员补差价升级（前后端完整链路）
- [ ] 超级会员→能量师补差价升级含佣金补差
- [ ] 3处超级会员订阅入口全部就绪
- [ ] 所有用户可见"命盘"→"能量盘"（3处特例处理）
- [ ] 关系分析：选择多人→提问→AI对话→分析记录完整链路
- [ ] 关系分析记录可查看历史
- [ ] WxPayService 单元测试通过
- [ ] calculator.js 与后端计算结果一致（50+组生日验证）
- [ ] 前端单元测试框架搭建完成
- [ ] 测试报告更新并反映最新状态