chengQVQ / mcd-saver-planner

# 麦麦极致省钱规划师（MCD Saver Planner）
> 基于麦当劳 MCP 的**全渠道点餐优惠决策引擎**——用一句话，算出全网最省的点餐方案。
---
## 📖 一句话介绍
你在 WorkBuddy / 任意 MCP 客户端里说「**深圳宝安，巨无霸套餐，到店，怎么最省**」，
它会自动遍历全渠道、全量优惠券组合，输出 Top3 最低到手价方案，一句话确认即可下单。
---
## 🎯 项目背景与核心价值
### 用户在麦当劳点餐时面临的真实痛点
打开麦当劳 App 想点一份巨无霸，你会遇到：
- **菜单几十项**，套餐与单品混杂，「巨无霸三件套 41 元」和「巨无霸 26.5 元 + 薯条」哪个更划算？
- **优惠券分散在三个体系**：门店券、麦麦省券（需先领取）、积分券，App 里往往只显示「部分可用」
- **不知道能不能叠加**：门店券和麦麦省券同时用会怎样？买张随单购卡到底亏不亏？
- **三渠道价格不明**：到店自取、得来速车道取餐、麦乐送到家，哪个更划算？
结果就是：用户要么随手点一笔（浪费权益），要么在多个页面反复比对（决策成本高）。
### 本项目的解法
把上述决策过程封装成一个**优惠决策引擎**：自然语言输入 → 意图与参数解析 → 全渠道全量券组合遍历 → 服务端真实价格验证 → Top3 方案输出 → 一键下单。
**关键设计取舍：不本地估算优惠金额，而是把 `calculate-price` 作为唯一事实来源。**
即使官方叠加规则变化，引擎依然给出正确结果，只是多几次调用——用少量调用换取 100% 的准确性。
---
## ✨ 功能亮点
| # | 能力 | 说明 |
| --- | --- | --- |
| 1 | 🧠 **自然语言意图解析** | 识别 6 类意图（指定餐品/预算推荐/活动查询/订单复购/积分兑换/通用），自动抽取餐品、预算、渠道、人数、位置，缺参主动追问 |
| 2 | 🧮 **全量券组合遍历** | 跨类型券叠加规则引擎，遵守「同类型互斥、跨类型可叠加、活动券独立」规则，输出全局最优解 |
| 3 | 📊 **三渠道并行比价** | 到店自取 / 得来速 / 麦乐送并行计算，按 价格 60% + 时间 25% + 距离 15% 加权评分 |
| 4 | 🛒 **智能凑单建议** | 未达满减门槛时推荐最低价凑单品，并用**收益校验**确认凑单真的更便宜才推荐 |
| 5 | ⭐ **积分价值比算法** | 按「券面值 ÷ 所需积分」排序而非所需积分升序，优先消耗临期积分 |
| 6 | 📅 **活动预判决策** | 解析活动文案估算折扣力度，对比当前最优价给出「现在买 / 等活动买」建议 |
| 7 | 🔁 **订单复购** | 读取历史订单，按今天的优惠重新计算最省方案 |
| 8 | ⚡ **一键领券下单** | 自动领券 → 价格二次校验 → 创建订单 → 返回支付链接 |
| 9 | 🛡️ **稳定性保障** | 并行调用、TTL 缓存、指数退避、优雅降级、状态机约束，单轮调用 ≤ 15 次 |
---
## 🚀 快速开始
### 方式一：离线演示（无需 MCP Token，零配置）
项目内置了从麦当劳 MCP Server **真实响应采样**的 Mock 数据，可直接跑通全链路：
 [code] 
输出示例：
 [code] 
### 方式二：运行自动化测试
 [code] 
输出：**109 项断言全部通过**，覆盖意图识别、金额单位、券叠加规则、价格引擎、多渠道比价、凑单、活动预判、积分兑换、下单执行、异常处理、状态机与端到端链路。
### 方式三：配置自检（随时可查 Token 状态）
 [code] 
确认 Token 是否已生效，未配置时会给出逐步指引。
### 方式四：接入真实 MCP（交互模式）
**第 1 步：申请 MCP Token**
访问 麦当劳 MCP 控制台 → 右上角【控制台】→【激活】→ 复制 Token。
**第 2 步：配置 Token（零依赖，无需 `npm install`）**
 [code] 
然后用编辑器打开 `.env`，把占位符替换成你的真实 Token：
 [code] 
> `.env` 已在 `.gitignore` 中被忽略，可安全存放本地 Token，不会被提交到仓库。
**也可以临时用环境变量**（优先级高于 `.env`，仅当前窗口有效）：
 [code] 
**第 3 步：验证配置**
 [code] 
 [code] 
**第 4 步：启动**
 [code] 
 [code] 
### 方式五：单次执行
 [code] 
### 方式六：作为 WorkBuddy Skill 使用
在 WorkBuddy 中配置 MCP 连接器后，添加本仓库的 Skill 即可获得对话式体验。
---
## 💬 调用示例
### 🎯 想直接看效果？跑示例集
 [code] 
内置 Mock 数据，**无需 Token**，9 个可运行示例覆盖全部场景。输出节选：
 [code] 
---
## 📞 三种调用方式
### 方式 A：命令行（最简单）
 [code] 
**支持的交互指令：**
| 你说 | 效果 |
| --- | --- |
| 任意描述需求 | 出方案 |
| `下单方案1` | 创建订单，返回支付链接 |
| `换一家店` | 重新比价 |
| `再便宜点` | 查看凑单建议 |
| `exit` / `退出` | 退出 |
### 方式 B：作为代码库调用
 [code] 
### 方式 C：编程式多轮对话
 [code] 
**返回值结构：**
| `result.type` | 含义 | 关键字段 |
| --- | --- | --- |
| `plans` | 出方案了 | `plans[]`、`matchedItems`、`comboAdvice`、`pointsAdvice` |
| `clarification` | 信息不足，需追问 | `message`、`missingFields` |
| `campaign` | 活动建议 | `advice.suggestion`、`advice.futureActivities` |
| `points` | 积分建议 | `advice.bestCoupon`、`advice.pointValueRatio` |
| `error` | 执行异常 | `message` |
### 完整代码示例
见 `examples/usage.js`，覆盖 9 个场景，全部可直接运行。
---
## 📋 对话场景示例
以下为**离线 Mock 数据**下的实际输出，真实结果以线上门店菜单与实时优惠为准。
### 场景 1：指定餐品求最优
 [code] 
### 场景 2：按预算推荐
 [code] 
> 注：以上为**离线 Mock 数据**下的演示输出，真实结果以线上门店菜单与实时优惠为准。
### 场景 3：活动预判
 [code] 
### 场景 4：积分最优兑换
 [co