Strona główna Odkrywaj Pomoc
Zarejestruj się Zaloguj się
liaoxg
/
num
1
0
Forkuj 0
Pliki Problemy 0 Oczekujące zmiany 0 Wiki
Gałąź: master
Gałęzie Tagi
num
/
docs
/
development-plan-v20260605.md

development-plan-v20260605.md 12 KB
Bezpośredni odnośnik Historia Czysty

开发计划 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