yeqv111 / mccarbon

# 麦麦碳账本 · mccarbon
> 你大概从没算过，自己在麦当劳吃掉了一年多少公斤二氧化碳。
> **麦麦碳账本**把它算出来，还告诉你换成什么能少一点。
---
## 一句话介绍
省钱不是主题，热量不是主题，点餐更不是主题——**麦麦碳账本**要讲的是「你的麦当劳一年，排了多少碳，以及怎么少排一点」。
它用麦当劳官方 MCP 拉取你的历史订单，按**三层碳核算模型**（餐品 / 包装 / 配送）估算出个人餐饮碳足迹，产出一份单文件 HTML「碳账本」：总碳足迹、碳等级 A–E、三层结构、月度曲线、碳重集中类别、最碳重一单、直观换算（几棵树 / 开车多少公里），以及一个**减排模拟器**。
**为什么选这个方向？** 全站参赛作品里，没有任何一份做环保 / 碳足迹维度（基于对官方仓库全部 529 份参赛作品的竞品分析，详见 workbuddy.md）。它天然契合麦当劳自身的「Plan for Change / 2050 净零」叙事，同时是一个真正的**个人工具**——不是玩梗，是能用的东西。
## 核心能力
- **三层碳核算**：把碳足迹拆成 餐品层（约 90%）/ 包装层 / 配送层，每一层都有独立的排放因子与来源。
- **可辩护的方法学**：能查到公开实测数据的餐品直接采用实测值（带 `measured` 标注），其余按碳类别中值外推；所有因子都在 `factors.py` 里，可逐条核对（见下文「方法学」）。
- **数据真实**：通过麦当劳 MCP 的 `order-list`、`query-order`、`list-nutrition-foods`、`query-my-account` 拉取历史订单与账户信息。
- **套餐自动展开**：真实订单里的「随心配」「买薯送薯」等套餐会被展开成单品，碳核算才准确。
- **减排模拟器**：红肉换白肉、外送改自提、小食减量、甜品减半、拆掉套餐组合——每一条都算出「能减多少 kg」和「占总量的百分比」。
- **离线可跑**：内置 2026 年全年示例数据（`--mock`），零 Token 也能一键看效果。
- **单文件碳账本**：生成的 `carbon-book.html` **不依赖任何外部 CDN / 图表库**，双击打开就是一张可截图的「碳账本长图」。
- **隐私保护**：会员卡号**默认打码**展示，避免截图分享时泄露账号。
- **零第三方依赖**：只用 Python 标准库（`urllib`、`datetime`、`html`、`json`）。
## 快速开始
> 📖 **第一次使用？** 直接看 **USAGE.md**。
 [code] 
嫌 `PYTHONPATH=src` 麻烦的话，装一次就能用短命令：
 [code] 
环境要求：**Python 3.9+**（已在 3.9.6 与 3.13.12 实测通过），**零第三方依赖**。
## 方法学（M）
碳足迹题材最怕被质疑「数字是编的」，所以这里把口径写在明处。三层模型：
### 第一层 · 餐品层（约占总量 90%）
| 来源 | 关键数据 |
|---|---|
| Vegan Society「Plate Up For The Planet」 | 英国麦当劳餐品实测：Double Big Mac 4.46 / Quarter Pounder 2.99 / Big Mac 2.35 / 20 块麦乐鸡 2.13 / Filet-O-Fish 0.82 / McPlant 0.29 / McFlurry 0.17 / 大薯条 0.15（kg CO2e / 份）|
| ADEME Agribalyse 数据库 | 快餐汉堡品类 LCA 值 18.6 kg CO2e/kg 成品，其中**农业环节占 92.5%** |
| 欧盟牛肉 LCA | 23.5 kg CO2e/kg——是豆类 / 土豆的 20 倍以上，这就是「换蛋白质」最有效的原因 |
中文菜单的绝大多数餐品没有公开实测值，因此按**碳类别中值**外推（牛肉 2.40 / 鸡肉 1.00 / 鱼 0.80 / 植物基 0.30 / 小食 0.35 … kg CO2e 每份）。这比把英国单品数据硬套到中文菜单上更稳，也更好解释。
### 第二层 · 包装层
依据《中国产品全生命周期温室气体排放系数库》：
- PP 餐盒（650mL / 23g）≈ **186.18 g CO2e / 个**
- 一次性餐具（一套）≈ **54 g CO2e**
- 塑料袋（6g）≈ **19 g CO2e**
按渠道分摊：外送（餐盒 + 餐具 + 袋）远重于到店 / 自提。
### 第三层 · 配送层
参考国内外卖研究：每单平均 111.80 g CO2e，其中**包装占 86%**，配送段本身仅约 **15.6 g**（电动两轮为主）。
→ 所以「到店自提」几乎能抹掉配送层，是减排里性价比最高的动作之一。
### 换算常数
一棵成熟树每年约吸收 21 kg CO2；汽油乘用车约 170 g CO2 / 公里。
> ⚠️ **免责声明**：本账本为**估算值**，非麦当劳官方披露数据，仅用于横向对比与减排方向判断。不同地区、供应链、包装规格都会导致实际值偏差。
## 真实数据接入
真实历史订单来自 `order-list`，营养数据来自 `list-nutrition-foods`，积分账户来自 `query-my-account`。**必须先有 Token**。
1. 申请麦当劳 MCP Token（参考 M-China/mcd-mcp-server）。
2. 配置 Token（二选一）：
 [code] 
3. **先验证 Token**（推荐第一步）：
 [code] 
能打印出**会员卡号 / 积分**，说明 Token 有效；若报 `401` 则 Token 无效或已过期。
4. 拉取真实订单并生成碳账本：
 [code] 
## 命令说明
 [code] 
| 子命令 | 作用 | 常用选项 |
|---|---|---|
| `report`（默认）| 生成碳账本 | `--html ` `--json ` `--start/--end` `--name` `--city` `--token` `--detail` |
| `demo` | 用离线示例数据一键演示 | 同 `report` |
| `export` | 只导出归一化订单 JSON | `--json ` |
| `account` | 只读取并打印真实会员账号信息（验证 Token 用） | `--token` |
数据源优先级：`--mock` 强制离线；`--live` / `--token` / `MCD_MCP_TOKEN` 强制走真实；都不写则检测到 Token 就走真实，否则回退 mock。
## 项目结构
 [code] 
## 技术亮点
- **三层核算可解释**：每一层的贡献都能拆开、能核对，不是一个大黑箱。
- **因子表是数据，不是代码**：新增餐品只要往 `DISH_FACTORS` 加一行；新增类别只要往