# 需求版本变更日志

> 每次需求变更在此追加新版本，版本号格式: `vYYYYMMDD.N`（如 v20260529.1）
> 已发布的版本不可修改，只可新增。

---

## v20260604.3

**发布日期：** 2026-06-04
**变更类型：** 新增功能
**状态：** ✅ 已确认

### 版本摘要

新增 **「提现」功能**（sys_manage 管理后台专属），覆盖提现规则配置、手续费设置、提现记录查询与导出、风控告警全流程。提现方式采用微信「企业付款到零钱」（夜间批量处理，23:30 定时作业），叠加劳务报酬个税预扣与节税策略。

### 变更清单

| # | 类型 | 变更 | 涉及位置 |
|---|------|------|---------|
| 1 | 🆕 新增 | `withdraw_records` 表（提现记录：金额/税务/通道/风控/审计字段） | US 新功能 |
| 2 | 🆕 新增 | `user_wallet` 表（余额快照：可提现/冻结/累计/周限/失败计数） | US 新功能 |
| 3 | 🆕 新增 | `withdraw_rule_config` 表（提现规则配置：管理员可动态调整限额/费率/税务参数） | sys_manage |
| 4 | 🆕 新增 | 提现申请 API（发起申请/查询进度/撤销） | 后端 API |
| 5 | 🆕 新增 | 提现记录管理 API（列表查询/单条详情/导出 CSV） | sys_manage 管理后台 |
| 6 | 🆕 新增 | 税务预览 API（输入金额 → 返回预计扣税+实际到账金额） | 前端 withdraw 页 |
| 7 | 🆕 新增 | 夜间批量处理定时任务（`@Scheduled` 23:30 执行，支持余额充足的微信直付与微信退费两种通道） | 后端 Service |
| 8 | 🆕 新增 | 风控告警机制（余额不足自动标记 `NEED_MANUAL`，超 3 天未处理进入 `FAILED` 并通知运维） | 后端 Service |
| 9 | 🆕 新增 | `sys_config` 税务参数（8 条：劳务报酬免征额/阶梯税率/速算扣除/年度汇算开关） | US-8.1 |
| 10 | 🆕 新增 | 节税策略：周限提 + 年度汇算退补 + ¥800 免征提示 + 代开发票引导（>¥30,000/年） | 前端/后端 |
| 11 | 🆕 新增 | 前端提现页（`client/pages/withdraw/index.vue`：余额展示 + 输入 + 税务预览卡片 + 快捷金额 + 提现记录入口） | 前端 |
| 12 | 🆕 新增 | 管理后台提现管理（概览卡片 + 记录列表 + 手动处理按钮 + 导出功能） | sys_manage |
| 13 | 🔧 更新 | `commissions` 表新增字段（`wallet_locked`/`withdraw_record_id`，关联提现记录） | 数据库 |
| 14 | 🔧 更新 | `profileApi` 新增 `withdrawSummary()`（累计提现/累计个税/本年度汇总） | API |
| 15 | 🔧 更新 | 个人中心新增「我的提现」入口（≡ 记录列表） | 前端 profile |

### 影响范围

- **数据库**：新增 2 张表（`withdraw_records`/`withdraw_rule_config`）+ 1 张快照表（`user_wallet`）+ `commissions` 表 2 个字段
- **API**：新增 6 个提现相关端点 + 1 个税务预览端点
- **定时任务**：新增夜间批量提现处理（23:30 cron）+ 安全监控（每分钟 pending 巡检）
- **前端**：新增 withdraw 页面 + profile 入口；管理后台新增提现模块
- **税务**：劳务报酬所得预扣代缴（¥800 免征、20%/30%/40% 累进），平台承担微信手续费 0.6%，退费通道走微信「退款」API（不扣税，需退款余额充足）
- **节税**：周限提策略 + 年度汇算 + 小额合并提示 + 代开发票引导

### 约束与风险

- **微信商户余额约束**：企业付款依赖微信「可 Master 余额」，非企业银行账户。余额不足时批量任务自动跳过，次日重试；运维需每日监控并充值
- **提现频率限制**：每人每周 1 次（`withdraw.max_per_week`），后台可调整
- **退款余额独立性**：首笔退费走「退款余额」，与 Master 余额分离，退款余额为 0 时退费降级为标准微信直付，首笔退费资格作废
- **人工介入规则**：单笔 >¥500 需审核；日失败 >3 次冻结 24h；超过 3 天未处理告警运维

### 迁移说明

新增功能，无需数据迁移。现有佣金记录 (`commission`/`commission_history`) 需在首次提现时批量初始化 `user_wallet` 余额快照（`available_balance = SUM(settled_amount)`）。

---

## v20260604.2

**发布日期：** 2026-06-04
**变更类型：** 重构 + 新增
**状态：** ✅ 已确认

### 版本摘要

全量重构 Phase 1 需求文档：①术语统一"命盘→能量盘"；②查重逻辑改为 `(userId, name, birthday)`；③"我的能量盘"按姓名+生日匹配自动展示；④关系类型从 6 类扩为 9 类（亲子拆为父母/子女/祖父母/孙子女），并改为后台动态配置；⑤关系能量分析从双盘对比彻底重设为**多人选择+提问+AI对话+分析记录**模式；⑥"我的"页面新增按角色展示的统计卡片。

### 变更清单

| # | 类型 | 变更 | 涉及位置 |
|---|------|------|---------|
| 1 | 🔄 全局替换 | 所有"命盘"→"能量盘"（含 3 处"数字能量能量盘"→"数字能量盘"） | README.md, style-guide.md, system-spec.md, phase1-product-plan.md, phase1-user-stories.md |
| 2 | 🔧 更新 | US-1.1 查重从 `(userId, birthday)` 改为 `(userId, name, birthday)`，确认弹窗文案同步 | US-1.1 |
| 3 | 🆕 新增 | US-5.2 "我的能量盘"入口（自动匹配用户注册姓名+生日） | US-5.2 |
| 4 | 🆕 新增 | US-5.2 统计卡片区（按角色展示咨询/推广/收入等统计数据） | US-5.2 |
| 5 | 🔧 更新 | US-10.6 关系类型表：亲子→父母/子女/祖父母/孙子女（6类→9类） | US-10.6 |
| 6 | 🔧 更新 | US-10.6 关系类型改为从 `sys_config relation.types` 动态加载 | US-10.6, US-8.1 |
| 7 | 🔄 重写 | US-10.6 核心流程重设计：静态双盘对比 → 多人选择+提问+AI对话+分析记录 | US-10.6 |
| 8 | 🆕 新增 | `relation_analysis_records` 表（分析会话，含成员快照） | US-10.6 |
| 9 | 🆕 新增 | 6 个分析相关 API：start/list/detail/delete/chatSend/chatHistory | US-10.6 |
| 10 | 🆕 新增 | `relations` 表移除 `compatibility_score`/`ai_analysis_cache`/`last_analyzed_at` 字段 | US-10.6 |
| 11 | 🔧 更新 | US-8.1 sys_config 种子数据新增 `relation.types` JSON 配置项 | US-8.1 |
| 12 | 🔧 更新 | US-8.1 管理后台新增关系类型配置卡片（动态表格增删改） | US-8.1 |
| 13 | 🔧 更新 | 附录A：ChartRecord 联合唯一索引 `uk_user_name_birthday` | 附录A |
| 14 | 🔧 更新 | style-guide §6.5 个人中心布局图：新增区域三统计卡片 | style-guide.md |
| 15 | 🔄 重写 | style-guide §8.5 关系页布局（8.5.2 首页/8.5.3 分析选择/8.5.4 分析对话） | style-guide.md |

### 影响范围

- **数据库**：`chart_records` 索引变更 + `relations` 表字段精简 + 新增 `relation_analysis_records` 表
- **API**：新增分析会话类 6 个接口；`/api/relation/detail`/`/api/relation/reanalyze` 废弃
- **sys_config**：新增 1 项（relation.types JSON），共 21 项
- **Dify**：关系分析从 Workflow（结构化输出）改为 Chatflow（自然语言对话）
- **前端**：个人中心新增统计卡片 + 关系页全流程重写（选择页+对话页+记录页）
- **后端**：ChartRecord 查重逻辑改 3 字段、新增分析会话管理相关 Service

---

## v20260604.1

**发布日期：** 2026-06-04
**变更类型：** 新角色 + 新页签
**状态：** ✅ 已确认

### 版本摘要

新增**超级会员**角色（¥1,314/年，固定价），位于C端年费与能量师之间。超级会员享有全部AI权益 + 关系能量分析页签 + 分销权限。同时新增 **🔗 关系** 小程序中间页签（首页·关系·分析·我的），包含夫妻/亲子/同事/朋友/上下级关系能量盘对比分析 + 八星号码能量分析功能。

### 变更清单

| # | 类型 | 变更 | 涉及位置 |
|---|------|------|---------|
| 1 | 🆕 新增 | **EPIC 10**：超级会员订阅与关系能量分析（US-10.1~10.7） | phase1-user-stories.md |
| 2 | 🆕 新增 | US-10.1 超级会员订阅入口（3处：关系页/我的/AI解读页） | EPIC 10 |
| 3 | 🆕 新增 | US-10.2 超级会员支付与开通（微信支付，vipType='super_annual'） | EPIC 10 |
| 4 | 🆕 新增 | US-10.3 升级路径（C端→超级会员补差价，超级→能量师补差价+佣金补差） | EPIC 10 |
| 5 | 🆕 新增 | US-10.4 超级会员佣金结算（30%+5%比例分成，推广超级会员） | EPIC 10 |
| 6 | 🆕 新增 | US-10.5 关系页签入口与付费引导（tabBar 改造，4页签） | EPIC 10 |
| 7 | 🆕 新增 | US-10.6 添加关系人与双能量盘对比分析（6类关系，Dify Workflow） | EPIC 10 |
| 8 | 🆕 新增 | US-10.7 八星号码能量分析（手机号/车牌号，8星映射+Dify解读） | EPIC 10 |
| 9 | 🔄 更新 | productType 枚举：新增 'super_member' | US-6.6 |
| 10 | 🔄 更新 | vipType 枚举：新增 'super_annual' | US-6.6 |
| 11 | 🔄 更新 | paySuccess() 分支：新增 super_member → US-10.4 | US-6.6 |
| 12 | 🔄 更新 | sys_config 种子数据：新增3项（pricing.super_member + commission.super_member.*） | US-8.1.5 |
| 13 | 🔄 更新 | 管理后台页面：新增超级会员定价+超级会员佣金配置卡片 | US-8.1.4 |
| 14 | 🔄 更新 | 排期建议：新增 Week 10+（EPIC 10） | 排期建议 |
| 15 | 🔄 更新 | 附录C 角色权限表：3类→4类（含超级会员列） | 附录C |
| 16 | 🔄 更新 | TabBar 配置：能量盘页签移除→新增关系页签 | style-guide.md §8.2 |
| 17 | 🆕 新增 | 关系页签布局规范（非会员引导/关系首页/双能量盘/号码分析） | style-guide.md §8.5 |
| 18 | 🔄 更新 | 定价方案表 README：增加超级会员行列 | README.md |

### 影响范围

- **定价体系**：4层角色，超级会员固定¥1,314，无种子价
- **佣金体系**：超级会员推广超级会员 = 30%+5%，推广C端/能量师复用现有配置
- **TabBar**：从 首页·能量盘·分析·我的 改为 首页·关系·分析·我的（能量盘页移除tab入口）
- **sys_config**：从17项增加到20项
- **数据库**：新增 relations 表 + number_analyses 表
- **Dify**：新增2个Workflow（关系能量分析 + 号码能量分析）
- **角色**：从3类扩展为4类（普通/C端/超级/能量师）

---

## v20260601.1

**发布日期：** 2026-06-01
**变更类型：** 流程重构
**状态：** ✅ 已确认

### 版本摘要

重构咨询发起流程：用户扫推广码后进入咨询填写页**无需登录**，点击"开始咨询"时触发登录，登录后才建立推广关系。首次注册用户弹出资料完善浮层（预填姓名/生日），支持保存或跳过。

### 变更清单

| # | 类型 | 变更 | 涉及位置 |
|---|------|------|---------|
| 1 | 🔄 重写 | US-6.2 流程：咨询页无需登录 → 发起时触发登录 → 登录后绑定关系 → 不登录不建立 | US-6.2 |
| 2 | 🔧 更新 | US-1.1：onAnalyze 增加登录守卫（未登录→跳转登录页） | US-1.1 |
| 3 | 🆕 新增 | login/index.vue：接收 index 传入的 birthday/name/questions 参数 | login/index.vue |
| 4 | 🆕 新增 | login/index.vue：首次用户弹出资料完善浮层（昵称/性别/生日），含 保存/跳过 按钮 | login/index.vue |
| 5 | 🔧 更新 | index/index.vue：onAnalyze 未登录时携带参数 navigateTo 到登录页 | index/index.vue |
| 6 | 🔧 更新 | `pending_referrer` 仅在登录成功后提交并清除，不登录永不使用 | US-6.2 |

### 影响范围

- 前端：index/index.vue（登录守卫）、login/index.vue（接收参数+浮层）
- 需求文档：US-6.2（完整重写流程部分）、US-1.1（第6条重写）
- 后端不受影响（登录接口不变）

---

## v20260531.4（已归档）

**发布日期：** 2026-05-31
**变更类型：** 修正
**状态：** ✅ 已确认

### 版本摘要

按需求调整：学业方向分析不再作为独立菜单入口，改为**能量盘解读内容的组成部分**，嵌入在通用解读中展示。

### 变更清单

| # | 类型 | 变更 | 涉及位置 |
|---|------|------|---------|
| 1 | 🔧 更新 | US-9.1 入口：删除"我的页面→学业方向"菜单项，改为解读内容区内部激活 | US-9.1 |
| 2 | 🔧 更新 | style-guide 6.5 布局图：删除 📖 学业方向菜单行 | style-guide.md |
| 3 | 🔧 更新 | profile/index.vue：删除学业方向菜单项 + goAcademicOrientation 函数 | 前端代码 |

---

## v20260531.3（已归档）

**发布日期：** 2026-05-31
**变更类型：** 设计重构
**状态：** ✅ 已确认

### 版本摘要

重新规划"我的"页面（个人中心），从纯列表菜单改为四大区域布局（用户卡片→会员状态→功能菜单→退出登录），按用户角色（普通/C端/能量师）智能展示不同内容。

### 变更清单

| # | 类型 | 变更 | 涉及位置 |
|---|------|------|---------|
| 1 | 🆕 设计 | 四大区域布局：用户卡片（墨蓝渐变背景+角色标签+社交摘要） | style-guide.md 6.5 |
| 2 | 🆕 设计 | 会员状态卡片按角色分支展示（免费upsell/年费橙色/能量师紫色/已过期灰色） | US-4.3 |
| 3 | 🔧 更新 | 功能菜单改为三组卡片式：我的服务 + 推广工具 + 更多 | US-5.2 |
| 4 | 🆕 新增 | 学业方向入口（📖）置于我的服务组，标注NEW | EPIC 9 |
| 5 | 🆕 新增 | 推广码独立卡片（金色背景，大号monospace字体） | US-6.5 |
| 6 | 🔧 更新 | 编辑资料入口改到头像旁 ✏ 图标 | US-5.3 |
| 7 | 🆕 新增 | 种子价会员在状态卡片下方显示专属标记"🌱 种子价专属会员" | US-4.3 |
| 8 | 🆕 新增 | 前端代码：页面重构（`client/pages/profile/index.vue`） | 前端代码 |

### 影响范围

- 前端页面：`client/pages/profile/index.vue`（重构）
- 需求文档：US-4.3（重写验收标准1-9）、US-5.2（入口描述）、US-5.3（编辑入口）、US-6.5（入口描述）、US-9.1（新增学业方向入口）
- 样式指南：style-guide.md 6.5（完整布局图）
- 种子价会员：状态卡片下方新增金色 badge
- 种子价会员：需后端字段 `isSeedPriceUser`

---

## v20260531.2（已归档）

**发布日期：** 2026-05-31
**变更类型：** 修正
**状态：** ✅ 已确认

### 版本摘要

修正**种子会员定义**：从"按付费人数顺序（前300人）"改为"三重条件判定"——①通过创始人码注册 ②在有效期内 ③名额未满。新增种子价有效期配置项。

### 变更清单

| # | 类型 | 变更 | 涉及位置 |
|---|------|------|---------|
| 1 | 🔄 重写 | US-4.2 种子价判断逻辑：三重条件（创始人码+有效期+名额） | US-4.2 |
| 2 | 🆕 新增 | `pricing.practitioner.seed_period_end` 配置项（种子价有效期截止时间） | US-8.1 |
| 3 | 🔧 更新 | `POST /api/pricing/current` 新增 `seedReason` + `seedPeriodEnd` 字段 | US-8.1 |
| 4 | 🔧 更新 | 管理后台定价卡片新增有效期日期选择器+三重条件注释 | US-8.1 |
| 5 | 🔧 更新 | US-4.1 付费页展示种子价提示文案按 `seedReason` 分支 | US-4.1 |
| 6 | 🔧 更新 | US-4.4 升级说明：种子价仅限创始人码首次购买 | US-4.4 |
| 7 | 🔧 更新 | 附录C角色表+场景3+决策表：种子价定义修正 | 附录C |
| 8 | 🔧 更新 | README定价表：种子价描述修正 | README.md |

### 影响范围

- 核心变更：US-4.2 种子价判定逻辑（从人数顺序 → 注册渠道+有效期+名额）
- 新增配置：`pricing.practitioner.seed_period_end`（valueType=`datetime`）
- API变更：`/api/pricing/current` 新增 `seedReason`、`seedPeriodEnd` 字段
- 前端变更：管理后台新增 `el-date-picker`；支付页种子价提示文案按原因分支
- 自然注册用户（无推荐人）不享受种子价

---

## 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: `pending` → `settled` 断链，需重写~~ ✅ **已修复，创建时直接设为 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~至今 |

---

## v20260604.4

**发布日期：** 2026-06-04
**变更类型：** 新增功能
**状态：** 🚧 设计待确认

### 版本摘要

新增**打卡赚积分**功能模块。用户每日签到打卡可获得积分，积分用于兑换服务权益（能量盘次数、推广次数、优惠券等）。积分体系独立于佣金和现金提现，纯内部激励代币。

### 变更清单

| # | 类型 | 变更 | 涉及位置 |
|---|------|------|---------|
| 1 | 🆕 新增 | 签到打卡基础逻辑（每日一次、连续签到、补签消耗） | 后端 Service + 前端页面 |
| 2 | 🆕 新增 | 积分规则引擎（签到分数 + 连续奖励 + 特殊日子双倍） | 后端 Service |
| 3 | 🆕 新增 | 积分消耗场景（兑换能量盘次数/聊天次数/优惠券/抽奖资格） | 商城兑换页 |
| 4 | 🆕 新增 | 积分流水记录（进账/消耗，支持查询） | 数据库 + API |
| 5 | 🆕 新增 | 打卡日历 UI（连续天数展示 + 补签入口 + 奖励预览） | 前端 Component |
| 6 | 🆕 新增 | 补签机制（消耗积分补昨日，VIP 每日免费补签 1 次） | 后端 Service |
| 7 | 🔧 更新 | 每日自动重置计数器需兼容现有 quota 体系（不相互干扰） | UserService |

### 设计要点（待用户确认）

- **连续打卡奖励阶梯**：连续 3/7/15/30 天额外积分 bonus
- **补签消耗**：建议 50 积分/次（可配置），VIP 每日免费 1 次
- **积分过期**：建议次年 1 月 1 日清零上一年度积分
- **积分用途**：兑换能量盘咨询次数、兑换 AI 聊天次数、抵扣会员费（可选）
- **防作弊**：同一设备/IP 每日限打卡 1 次；VIP 无此限制

### 关联影响

- 需新增 `user_points` 表和 `points_log` 表
- 前端「我的」页增加打卡入口 + 积分余额展示
- 不影响现有佣金提现体系（积分 ≠ 现金）
- 与「家庭套餐」权益可叠加（家庭套餐用户打卡积分翻倍）

---

## v20260604.5

**发布日期：** 2026-06-05  
**变更类型：** 参数调整 + 规则澄清  
**状态：** ✅ 已确认

### 版本摘要

基于用户决策，对 `docs/distribution-model-v2.md` 和 `docs/points-system.md` 两项设计文档进行规则修正：分销佣金统一为直接邀请 40%、间接邀请不结算佣金仅奖励 10 积分；积分体系取消补签；积分兑换以 100 分=1次单人能量盘分析为基准，可扩展其他商品。所有规则参数均可通过后台配置动态调整。

### 变更清单

| # | 类型 | 变更 | 涉及位置 |
|---|------|------|---------|
| 1 | 🔧 修改 | 直接邀请佣金比例统一为 **40%**（原为 C端15%/家庭18%/能量师20%） | `distribution-model-v2.md` §4.1 |
| 2 | 🆕 新增 | 间接邀请（二级）奖励 **10 积分/次**，不结算佣金 | `distribution-model-v2.md` §4.2 |
| 3 | 🆕 新增 | 能量师团队分红可与积分挂钩，作为团队贡献值计算依据 | `distribution-model-v2.md` §4.3 |
| 4 | 🔧 修改 | 系统运营官（tarunner）默认日限模式，按需放开上限；超级会员暂缓 | `distribution-model-v2.md` §2 |
| 5 | ❌ 删除 | 打卡积分「补签机制」（原每月3次/每次5分） | `points-system.md` §6 |
| 6 | 🔧 修改 | 积分兑换单人能量盘分析固定为 **100 积分** = 1次配额，可扩展其他商品 | `points-system.md` §4 |
| 7 | 🔧 修改 | `sys_config` 从多角色佣金比例合并为 `commission.level1.rate_unified=4000`；新增 `points.redeem.analysis_cost=100` | `distribution-model-v2.md` §6.3 |
| 8 | 🆕 新增 | 积分消耗还可兑换 `points_rewards` 表中定义的其他商品/服务 | `points-system.md` §4 |

### 约束与澄清

- **免费配额不变**：3人×3次/天硬约束，积分兑换独立通道，不叠加
- **佣金与积分解耦**：佣金（钱）与积分（权益）两套体系并行，不互相抵扣
- **所有规则后台可配**：兑换项成本、签到奖励、间接积分数量均写入 sys_config，无需发版即可调整

### migrate 影响范围

- `commissions` 表 `level` 字段语义不变：0=团队分红 1=一级佣金 2=预留
- 统一佣金 40% 上线后，历史低比例佣金记录保持原值，新增订单按 40% 结算
- `commissions` 表中已有的 `indirect_invite` 字段复用（新增 indirect_points 字段或另行记录）

---