requirements-changelog.md 12 KB
需求版本变更日志
每次需求变更在此追加新版本，版本号格式:
vYYYYMMDD.N（如 v20260529.1） 已发布的版本不可修改，只可新增。
v20260531.1（当前版本）
发布日期： 2026-05-31
变更类型： 新增
状态： ✅ 已确认
版本摘要
新增 EPIC 9：学业方向分析与人工方案，覆盖"家长为孩子选学业方向"完整场景。引入 平台佣金留存模型（区别于年费的固定金额/比例模型），预留 lilishop 商城接口层。
变更清单
| # | 类型 | 变更 | 涉及位置 |
|---|---|---|---|
| 1 | 🆕 新增 | US-9.1 学业方向AI深度解读（Dify专用Workflow） | EPIC 9 |
| 2 | 🆕 新增 | US-9.2 申请能量师出方案（plan_requests表+自动派单） | EPIC 9 |
| 3 | 🆕 新增 | US-9.3 能量师介入AI会话（chat_interventions表+senderType） | EPIC 9 |
| 4 | 🆕 新增 | US-9.4 方案价格协商（plan_request_logs表+协商卡片） | EPIC 9 |
| 5 | 🆕 新增 | US-9.5 方案付费与交付（平台佣金计算+plan_deliveries表） | EPIC 9 |
| 6 | 🆕 新增 | US-9.6 人工方案分销佣金（平台留存口径） | EPIC 9 |
| 7 | 🆕 新增 | CommerceService 接口层 + StubCommerceService 桩实现 | EPIC 9 |
| 8 | 🔧 更新 | US-6.6 productType 新增 practitioner_plan 枚举 + 支付分支 |
US-6.6 |
| 9 | 🔧 更新 | US-8.1 系统配置新增7个参数（平台佣金率/分销比例/方案限价等） | US-8.1 |
| 10 | 🔧 更新 | US-8.1 前端管理页面新增"人工方案配置"卡片 | US-8.1 |
| 11 | 🔧 更新 | 附录B.8 新增学业方向 Workflow 映射 | 附录B |
| 12 | 🔧 更新 | 附录C 权限表新增学业/方案/介入/付费 4项权限行 | 附录C |
| 13 | 🔧 更新 | 排期扩充至9+周（原8周→Week 5学业Workflow→Week 9+方案） | 排期建议 |
影响范围
- 主要涉及文件：
docs/phase1-user-stories.md（新增 EPIC 9 + 更新 US-6.6/8.1/附录B/附录C/排期） - 关联文件：
docs/requirements-changelog.md（本版本记录） - 数据库新增6张表：
plan_requests,plan_request_logs,plan_deliveries,chat_interventions,practitioner_ratings,commerce_goods - 开发新增：
CommerceService接口 +StubCommerceService桩实现 - 代码新增：
DifyService.interpretAcademicOrientation(), 聊天消息senderType枚举
v20260529.2（已归档）
发布日期： 2026-05-29
变更类型： 修订完善
状态： ✅ 已确认
版本摘要
全量通读 Phase 1 需求文档，修复 20 项问题（5项逻辑硬伤 + 6项不清晰 + 5项使用体验 + 4项细节优化）。
变更清单
| # | 类型 | 变更 | 涉及位置 |
|---|---|---|---|
| 1 | 🐛 逻辑修复 | US-5.2 验收标准从 US-5.3 段落内移回正确位置 | US-5.2 / US-5.3 |
| 2 | 🐛 逻辑修复 | US-6.2 pending_referrer 覆盖逻辑自相矛盾 → 明确"每次覆盖，以最后一次为准" | US-6.2 |
| 3 | 🐛 逻辑修复 | API 路径统一为 POST /api/consultation/start（原 US-1.1 写 consultation，附录A 写 chart） |
US-1.1 / 附录A / README |
| 4 | 🐛 逻辑修复 | US-8.1 B端管理卡片缺 C端推荐佣金（l1_cend）输入项，种子数据缺对应行 | US-8.1（UI/组件/种子SQL/测试用例） |
| 5 | 🐛 逻辑修复 | 排期表缺少 US-5.1/US-1.x/US-3.x 等核心流程，仅排了分销 → 扩充至 8 周完整排期 | 排期建议 |
| 6 | 💡 清晰化 | US-1.1 姓名字段明确为"被咨询者姓名"；已登录用户自动填入注册生日 | US-1.1 |
| 7 | 💡 清晰化 | US-1.1 重复生日返回旧记录时增加 toast 提示"已找到您之前的咨询记录" | US-1.1 |
| 8 | 💡 清晰化 | US-3.2 明确"1次主性格概要"与 US-3.4 "3轮AI问答"为独立配额、互不消耗 | US-3.2 |
| 9 | 💡 清晰化 | US-3.1 Dify 加载时间从 5秒 → 10秒，超 8秒显示提示语 | US-3.1 |
| 10 | 💡 清晰化 | US-6.4 重复编号 5 修复（注意项改为独立引用块，不占用编号） | US-6.4 |
| 11 | 💡 清晰化 | US-3.3 明确"重新生成"入口位置（解读页右上角菜单）和确认框 | US-3.3 |
| 12 | 🎨 体验优化 | US-6.5 "可提现"改为"累计收益"，标注"提现即将开放" | US-6.5 |
| 13 | 🎨 体验优化 | US-2.1 明确次数限制仅针对"分享到微信/朋友圈"，保存到相册不限 | US-2.1 |
| 14 | 🎨 体验优化 | US-7.1 批注模式优先推荐非侵入式的方案A（底部面板，不阻塞其他操作） | US-7.1 |
| 15 | 🎨 体验优化 | US-8.1 "恢复默认值"明确为"恢复初始值"，增加 tooltip 和确认框 | US-8.1 |
| 16 | 🎨 体验优化 | US-4.4 升级详情卡片增加权益对比表，帮助用户感知升级价值 | US-4.4 |
| 17 | 🔧 细节优化 | US-6.6 删除 paySuccess() 伪代码（与 US-6.3 重复），改为交叉引用 | US-6.6 |
| 18 | 🔧 细节优化 | 附录A Step 5 明确 calculator.js 降级兜底的边界（离线计算，不提供AI解读） | 附录A |
| 19 | 🔧 细节优化 | US-6.3 增加"首次直接购买能量师"示例（非升级场景对比） | US-6.3 |
| 20 | 🔧 细节优化 | 排期中 US-8.2 提前至 Week 7（与分销并行，不依赖 Week 4 才做） | 排期建议 |
影响范围
- 主要涉及文件：
docs/phase1-user-stories.md（US-1.1/2.1/3.1/3.2/3.3/4.4/5.2/5.3/6.2/6.3/6.4/6.5/6.6/7.1/8.1 + 排期 + 附录A） - 关联文件：
README.md（API 路径修正） - 开发影响：US-8.1 管理后台 B端佣金卡片需增加第三个输入项，种子数据多插入一行
v20260529.1（已归档）
发布日期： 2026-05-29
变更类型： 初始版本
状态： ✅ 已确认
版本摘要
数字能量学智能体 Phase 1 完整需求规格，涵盖命盘生成、AI 解读、付费订阅、分销佣金、管理后台、前端样式指南及命盘算法命名约定。
包含文档
| 文档 | 说明 |
|---|---|
docs/phase1-user-stories.md |
25个用户故事，含验收标准、优先级、排期、依赖图 |
docs/style-guide.md |
前端样式指南（品牌色/字体/组件/动效/微信专项） |
docs/distribution-model.md |
分销模式设计方案 |
docs/system-spec.md |
系统需求规格说明书 |
docs/phase1-product-plan.md |
Phase 1 产品规划 |
docs/1.0产品对齐方案.md |
定价模型B的完整方案 |
docs/requirements-changelog.md |
本文件，版本变更日志 |
已确认的关键决策
| 决策 | 内容 |
|---|---|
| 定价模型 | 模型B：能量师种子价 ¥1,314 / 标准价 ¥1,986，均后台可配 |
| C端年费 | ¥131，入 Phase 1，含分销 |
| 种子价规则 | 按付费时间判定，前 300 人享受 |
| B端佣金 | 固定金额 ¥500（一级）/ ¥100（二级） |
| C端佣金 | 比例 40%（直接）/ 5%（上级） |
| 提现管理 | 推迟至 Phase 2 |
| C端订阅入口 | 命盘解读页底部 |
| 命盘计算 | 从 calculator.js 前端迁移到后端 CalculatorService.java |
| 咨询会话 | 按 (userId, birthday) 联合唯一索引，同用户+同生日始终返回同一条记录 |
| 新生日弹窗 | "此生日将开启全新的命盘咨询，确认吗？" |
| 每日互动限制 | 非付费用户 3 轮/天，全局计数器，绑定当前命盘 |
| 咨询字数限制 | "想了解的问题"输入框限 100 字 |
| 命盘位置命名 | A-H（输入层）+ I-X（7内部+15外部）= 30个位置 |
| 外部公式 | P=reduce(I+M), Q=reduce(J+M), R=reduce(P+Q); S=reduce(K+N), T=reduce(L+N), U=reduce(S+T); V=reduce(M+O), W=reduce(N+O), X=reduce(V+W) |
| 外部年龄映射 | 左=21-40岁, 顶=41-60岁, 右=61+岁 |
已知问题 / 待办
当前代码外侧三组计算为内部数字的"重复展示"，需改为上述独立计算公式✅ 已检查，代码已使用独立公式佣金状态流转 BUG:✅ 已修复，创建时直接设为 settledpending→settled断链，需重写推广码由注册时生成改为付费后生成✅ 已检查，paySuccess() 中已调用 generateReferralCodeForUser()- 云函数目录已删除，仅 Java 后端有效
文档版本记录
| 日期 | 变更 | 涉及文件 |
|---|---|---|
| 2026-05-29 | 初始版本 v1 | 全部文档 |
| 2026-05-29 | US-1.1 重写为咨询发起流程，新增100字限制、userId+birthday查重、确认弹窗 | phase1-user-stories.md |
| 2026-05-29 | US-1.2 三角布局从旧命名(F,G,H,I)更新为新命名(I,J,K,L) | phase1-user-stories.md |
| 2026-05-29 | 新增 US-1.3 完整位置命名与计算规则对照表（A-X） | phase1-user-stories.md |
| 2026-05-29 | 新增 US-3.4 AI交互问答免费/付费控制 | phase1-user-stories.md |
| 2026-05-29 | US-5.2 改为历史咨询记录，按 userId+birthday 归组 | phase1-user-stories.md |
| 2026-05-29 | 新增 附录A：新计算规则代码文件变更清单（后端/前端/数据库/执行顺序） | phase1-user-stories.md |
| 2026-05-29 | US-5.1 重写为微信登录+注册信息完善流程，新增9个用户资料字段 | phase1-user-stories.md |
| 2026-05-29 | 新增 US-5.3 个人资料编辑（为陌生社交预留字段） | phase1-user-stories.md |
| 2026-05-29 | US-1.4 展开（4→14条，含面板交互/Tab切换/手势关闭） | phase1-user-stories.md |
| 2026-05-29 | US-2.1 展开（5→16条，含分享方式/次数限制/风控） | phase1-user-stories.md |
| 2026-05-29 | US-2.2 展开（5→16条，含PDF排版/后端生成/缓存） | phase1-user-stories.md |
| 2026-05-29 | US-7.1 展开（5→18条，含批注编辑/位置关联/数据库设计） | phase1-user-stories.md |
| 2026-05-29 | US-7.2 展开（4→14条，含标签筛选/颜色管理/多对多关联表） | phase1-user-stories.md |
| 2026-05-29 | 新增 附录B：Dify AI 架构设计（Workflow/Chatflow/知识库/Java集成/API规格） | phase1-user-stories.md |
| 2026-05-29 | US-3.1/3.4 更新验收标准，增加 Dify 工作流集成要求 | phase1-user-stories.md |
| 2026-05-29 | 附录A 新增 DifyService.java 和 ChatService.java 改造条目 | phase1-user-stories.md |
| 2026-05-29 | US-2.2 PDF导出限制修改：已付费用户不限次数（原上限10次/天） | phase1-user-stories.md |
| 2026-05-29 | 新增 附录C：三类用户角色权限对照表（普通/C端/能量师） | phase1-user-stories.md |
| 2026-05-29 | US-4.4 新增：年费升级能量师的定价规则（按剩余天数折价） | phase1-user-stories.md |
| 2026-05-29 | US-6.3 重写：增加推荐人身份判断（能量师全额定/C端半额）、升级补差逻辑（减已付年费佣金） | phase1-user-stories.md |
| 2026-05-29 | US-6.4 增加注明年费佣金可能在升级时被抵扣 | phase1-user-stories.md |
| 2026-05-29 | US-6.6 paySuccess() 分支逻辑更新 |
phase1-user-stories.md |
未来版本模板
## vYYYYMMDD.N（下版本）
**发布日期：** YYYY-MM-DD
**变更类型：** 新增 / 修改 / 废弃
**状态：** 草稿 / 已确认
### 变更清单
| 变更项 | 变更前 | 变更后 | 理由 |
|--------|--------|--------|------|
| xxx | xxx | xxx | xxx |
### 影响范围
- 变更涉及的用户故事：US-x.x
- 变更涉及的后端文件：xxx
- 变更涉及的前端文件：xxx
### 迁移说明
需要执行的迁移步骤：
1. ...
2. ...
锚定摘要（会话跟踪）
每次会话结束时更新，记录 session 的进展/变更/决策。每次只追加，不修改旧内容。
| 日期 | 内容 |
|---|---|
| 2026-05-30 | 本轮修复 (v20260530.1)： 基于 US-6.2~US-6.6/v20260529.2 需求变更文档，完成 16 项问题修复的代码落地。核心变更：(1) UserService — 推广码 6 位+过滤 O0I1 生成、自邀请检测、无效码静默降级；(2) Order/Commission/User 实体扩充字段（productType/isUpgrade/remark/vipType/计数器）；(3) ConfigService 内存缓存 + @PostConstruct 自动种子数据 + PricingController 定价查询端点（含种子名额余量）；(4) OrderService.paySuccess() 重写 — productType 分支判断（回执户/能量师）、推荐人全额/半额身份判断、升级补差逻辑、幂等性保护；(5) AdminController 配置更新支持批量模式；(6) 前端 Subscribe 页改用定价 API + 种子名额展示；(7) Commission 页权限拦截 + remark 来源展示 + 下拉刷新；(8) Index 页 date picker 限定 1900~至今 |