西南财经大学—美食护照 Skill
> 新生入学第一周，在西财柳林校区吃过的地方都值得被记住。
> 不是查店工具，是吃出来的成就系统——把「在西财吃了什么」变成一枚枚可以收集的徽章。
一、它到底干嘛的
大众点评能告诉你附近有什么店，但它不知道你吃过哪些。
而对一个刚到西财的新生来说，真正的问题往往不是"没得吃"：
- 开学一个月了，还有哪些窗口根本没去过
- 同学说"那家好吃"，我到底吃过没有
- 毕业之前，想把学校周边的店吃一遍，但记不住进度
这份护照把「吃了什么」这件原本会忘掉的小事，变成看得见、集得齐、晒得出的收集游戏。
一句话区别：别的 App 给你一长串店名让你自己筛，它给你一枚枚亲手点亮的徽章。
二、创意点在哪
这不是一份打卡清单，而是把游戏化机制搬进了校园生活：
| 游戏机制 | 在本技能里的落地 |
|---|---|
| 收集 | 30 家精选榜，吃过一家点亮一枚真实商家头像 |
| 进度可视化 | 4 个片区分区进度条 + 总进度环 |
| 成就系统 | 10 枚勋章，含时段成就（夜猫子/早起鸟）、连击成就（连续 3 天） |
| 称号阶梯 | 7 级称号，从「美食小白」一路升到「西财食神」 |
| 每日任务 | 「今日挑战」每天推一家没吃过、且现在开着的店 |
| 社交炫耀 | 竖版分享卡，专为小红书/朋友圈设计，进度和称号直接上图 |
关键的是，这些机制全部建立在真实数据之上：营业时段来自校内食堂供餐时间与高德 POI，所以「今日挑战」不会推一家已经关门的店。游戏化的壳 + 硬数据的骨，这是它和普通打卡清单的根本区别。
三、最快用法：直接说话就行
不用记任何命令，像发朋友圈一样说：
| 你想 | 直接这么说 |
|---|---|
| 记一笔吃过 | 「打卡 重庆面庄」 |
| 看进度 | 「我的打卡进度」「我集齐了几家」 |
| 今天吃啥 | 「今日挑战」「不知道今天吃什么」 |
| 看成就 | 「我解锁了哪些成就」 |
| 出图分享 | 「生成我的美食护照」「做个分享卡」 |
模糊匹配也认：说「重庆面」能命中「重庆面庄」，已打卡的自动去重，不会重复计数。
四、模块速查
python scripts/passport.py --checkin "重庆面庄" # 打卡（模糊匹配、自动去重）
python scripts/passport.py --quest # 今日挑战：现在开着 + 没打卡的店
python scripts/passport.py --progress # 终端进度条 + 称号 + 待打卡
python scripts/passport.py --achievements # 成就墙详情
python scripts/passport.py --list # 30 家名单与状态（🕐=现在营业）
python scripts/passport.py --passport 护照.html # 生成护照 HTML
python scripts/passport.py --share 分享卡.html # 生成竖版分享卡
--now HH:MM 指定时刻，用于演示或提前规划（如 --now 22:30）。
五、四个核心玩法
1. 打卡（--checkin）
说「打卡 重庆面庄」即可，支持模糊匹配，自动去重。
打卡时刻会被记录——这是「夜猫子」（22:00 后）、「早起鸟」（09:00 前）这类时段成就的判定依据。
2. 今日挑战（--quest）
从你没打卡过 + 现在正在营业的店里挑一家。
这一步是硬过滤，不是随机推荐：校内店继承食堂供餐时段（07:00-09:00 / 11:00-13:00 / 17:00-19:00），校外店用高德 POI 营业时间。所以晚上 19:30 不会推荐只开到 19:00 的食堂窗口。
同一天内推荐结果固定（按日期做稳定选取），不会反复刷新出不同答案。
3. 成就与称号（--achievements / --progress）
称号（按精选榜命中数）：
美食小白(0-4) → 探店学徒(5-9) → 探店达人(10-14) → 美食探长(15-19) → 美食宗师(20-24) → 资深食神(25-29) → 西财食神(30)
10 枚成就勋章：
| 勋章 | 解锁条件 |
|---|---|
| 🎬 开张大吉 | 完成第 1 次打卡 |
| 🧊 破冰之旅 | 打卡满 5 家 |
| 🚶 渐入佳境 | 打卡满 10 家 |
| ⛰️ 半壁江山 | 打卡满 15 家 |
| 🏫 校内通 | 校内 10 家全部打卡 |
| 🚩 片区征服者 | 任一校外片区全部打卡 |
| 🦉 夜猫子 | 22:00 之后完成一次打卡 |
| 🐦 早起鸟 | 09:00 之前完成一次打卡 |
| 🔥 集章狂魔 | 连续 3 天都有打卡 |
| 👑 西财食神 | 30 家全部集齐 |
4. 导出与分享（--passport / --share）
python scripts/passport.py --passport # 完整护照：集章墙 + 进度环 + 成就墙 + 打卡清单
python scripts/passport.py --share # 竖版分享卡：进度 + 称号 + 最近打卡 + 下一站
两者都是单文件自包含 HTML（头像 base64 内嵌），双击即开、离线可用、发群发朋友圈不会破图。
六、30 家精选榜怎么选的
筛选口径（与主作品一致，可复现）：
- 校外 20 家：高德评分 ≥4.5 为硬门槛（好评/味道好的代理指标），同分按人均升序（越实惠越靠前）
- 校内 10 家：源数据无评分与价格，保留学生常去的经典窗口，置信度标 A-
- 一粟堂窗口已剔除：一粟堂 2026-09 起装修改造、暂停供餐，其窗口（含小锅炒鸡）不进榜，改由民族特色食堂（清真食堂）替补——避免让用户去打卡一家吃不上的店
片区分布：校内 10 / 旭辉 Cmall 5 / 新尚天地 5 / 东门柳浪湾 10
数据字段：名称、片区、位置、营业时间、评分、人均、品类、置信度。其中 29 家有营业时间（校内店继承食堂供餐时段，校外店取自高德 POI）。
数据由 scripts/build_targets.py --from ../swufe-food 从主作品知识库生成，可复现。
七、能做 / 不能做
能做：
- 记录与统计你在西财吃过哪些精选店
- 按当前时间过滤，只在营业时段推荐待打卡店
- 生成带真实商家头像的护照与分享卡（单文件、离线可看）
- 追踪称号与成就解锁进度
不能做（如实说明）：
- 不覆盖光华校区，仅柳林校区
- 不查实时排队，营业时间来自静态数据，节假日与临时调整以现场为准
- 不会自动识别你吃了什么——打卡是手动的，需要你主动说一句「打卡 某某店」
- 校外 20 家无口味评价：高德 POI 只有评分与人均，没有文字点评，所以护照只做集章不做打分
八、与主作品的分工
| 美食推荐 Skill | 美食护照 Skill（本作品） | |
|---|---|---|
| 解决什么 | 「现在去哪吃」 | 「我吃过哪些、还差哪些」 |
| 交互 | 查询 → 给结论 | 打卡 → 收集 → 分享 |
| 驱动 | 场景/预算/门区 | 成就/称号/集章 |
| 产出 | 推荐卡、攻略 HTML | 护照、分享卡 |
两者数据同源、口径一致，可独立使用，也可配合：先用推荐 Skill 决定吃啥，吃完用护照 Skill 打卡。
九、合规声明
- 数据来源：高德地图 POI 公开数据 + 校内食堂公开供餐信息，不含任何私聊、通讯录、位置轨迹等非公开数据
- 无个人身份信息：打卡记录仅存店名、片区、时间，均为用户本人产生，不含也不上传任何个人信息
- 离线运行：纯本地 JSON，运行不联网、不调用外部 API、不上传数据
- 头像版权：商家头像来自高德地图 POI，版权归原作者所有，仅作展示；如需商用请自行替换
十、可复现 Demo
python scripts/passport.py --passport demo/demo-passport.html
python scripts/passport.py --share demo/demo-share.html
demo/ 下已生成两个产物（护照含 5/30 演示打卡、4 枚成就解锁效果）；真实使用时 data/checkins.json 为空，从 0/30 开始。
