博物馆打卡

概述

去博物馆之前选好馆，由本 skill 生成一份 5 任务打卡清单 + 3 件镇馆之宝攻略；到现场后逐任务上传照片与文字；离馆后生成一张可分享的成就海报。不是游戏——没有任何排行榜 / 积分 / 抽卡，成就就是那张海报。

何时使用

• 用户说"去 XX 博物馆打个卡""帮我做个博物馆打卡攻略""带娃/和朋友去博物馆，给我安排打卡任务"。
• 用户想要一份有结构、结合自己兴趣的馆内打卡动线，而非泛泛的游览建议。
• 不适用于：要全馆藏品清单、要实时展讯、要游戏化养成玩法（本 skill 明确不含）。

输入

• museumName（字符串，必填）：博物馆全称或别名（故宫 / 国博 / 陕历博 / 上博 / 南博 / 豫博 / 湘博 / 辽博 / 川博 / 湖北省博物馆 / 兵马俑 / 三星堆…）。
• hobbies（字符串数组，可选）：用户爱好，用于定制任务引导。建议取值：历史故事 / 艺术品 / 建筑 / 某朝代 / 书法绘画 / 亲子共学 / 拍照出片 / 其他。

调用流程（付费编排 · 严格遵守，与 museum-treasures 同范式）

端点：POST https://museumcheck.cn/skillhub/museum-checkin（可用环境变量 CHECKIN_API_BASE 覆盖）。

1. 发起请求：带 JSON body {"museumName":"<名称>","hobbies":["历史故事","亲子共学"]} 调用上面端点。
2. 若返回 HTTP 402（PAYMENT_REQUIRED）：
   • 从响应头取 WeixinPay-Required（即 paymentCode）和 X-Out-Trade-No。
   • 通过平台微信支付能力（weixinpay_pay）以该 paymentCode 向用户发起 ¥0.01 授权，请用户用微信完成支付。
   • 支付成功后，用原请求体不变，加请求头 X-Out-Trade-No: <上面的值> 重新 POST 同一端点。
3. 若返回 HTTP 200：解析响应体 content（见下「输出结构」），按「5 任务规范」引导用户。
4. 若返回 HTTP 404：馆名未收录或别名未命中；若响应带 candidates 可提示用户近似馆名，否则请用户换用官方全称。

便捷联调：node scripts/query.js "故宫" '["亲子共学"]'（脚本需自行补一段，先 POST 取 402、走 weixinpay_pay、再带 --out-trade-no 重试；本 skill 不强制附脚本）。

付费前置检查与异常处理（Pay Skill 改造必含）

前置检查（发起 402 之前必做）

• 确认 weixinpay 插件已安装 / 可用：本 skill 的支付依赖平台微信支付能力（weixinpay_pay 支付卡片）。若消费者环境未安装或未启用 weixinpay 插件，402 触发后无法弹出支付卡片，链路会卡住。agent 应在发起请求前确认 weixinpay 能力可用；若不可用，先提示用户「请在 WorkBuddy 中安装 / 启用微信支付插件后再试」，不要继续走支付。
• 确认端点确实返回 402：仅当收到 HTTP 402 + WeixinPay-Required + X-Out-Trade-No 时才进入支付；若直接 200，说明当前无需付费，直接走「输出结构」。
• 金额核对：402 响应可携带金额字段，提示用户本次为 ¥0.01（测试价），一次买断全程，不会重复扣费。

异常处理

• 用户未支付 / 中途关闭：用户关闭支付卡片且未付款 → 不产生扣款，订单停在 PENDING。用户可随时用原请求体重新发起，端点生成新的 X-Out-Trade-No 再次进入支付。无卡死态。
• 重复携带订单号（幂等）：同一 X-Out-Trade-No 多次重试是安全的——仅当该订单真实支付成功后才返回 200，重复请求不会二次扣费。支付成功后若因网络抖动收到 5xx，请用同一订单号重试，而非新发起支付。
• 支付成功但后端 5xx：极少数情况下支付已成功但端点返回 5xx（服务异常）。此时订单已 FULFILLED，用户应用原 X-Out-Trade-No 重试领取结果，不应再付一次。若持续 5xx，联系技能提供方按平台流程退款。
• 退款：本 skill 为一次性的信息检索与整理服务（¥0.01/次），不提供「内容不满意」类退款；若因服务未交付（支付成功但始终无法返回 200）需退款，统一走 skillhub 平台工单 / 退款通道处理，由平台裁决。weixinpay 侧仅执行扣款与平台发起的退款，技能本身不直连退款 API。
• 404 / 馆未收录：见「调用流程」第 4 步，发生在付费之前，不进入支付；如已支付（理论不会发生）按平台退款。

输出结构（200 响应体）

• museum / province：匹配到的官方馆名与省份。
• tasks：数组，长度 = 2 + 镇馆之宝件数（通常为 5）：
  • 索引 1 = 门口打卡；索引 2–4 = 3 件镇馆之宝；索引末 = 情字打卡 + 合影。
  • 每个 task 含 title / photo{required,hint,composition} / text{required[],optional[]}；宝物任务额外含 treasure{name,dynasty,category,description,imageUrl,rights} 与 hobbyHint。
• contribution：照片贡献（UGC）说明与端点。
• poster：成就海报生成说明。
• disclaimer：版权免责声明，必须原样展示或转述。

5 任务规范（按索引引导用户采集什么）

Task 1 · 门口打卡（到达仪式）

• 照片（必）：馆名石 / 正门 / 招牌；建议人 + 门同框，或纯门牌特写。若用户爱好「建筑」则强调馆舍本身；爱好「拍照出片」则给构图/光线建议。
• 文字（必）：① 到达时间 + 天气一句话；② 进门第一感受（1 句）。
• 文字（选）：同行人昵称（用于海报署名）。

Task 2–4 · 镇馆之宝 ×3（复用 museum-treasures 的 3 件）

• 展示给用户：每件 treasure 的 名称 / 年代 / 类别 / 官方照片 imageUrl / 简介 description + 版权标注（rightsType / license / 署名）。
• 照片（必）：用户与这件宝物的同框照，或宝物特写占画面 2/3。
• 文字（必）：① 最打动你的一点（1 句，结合用户爱好，用 hobbyHint 引导）；② 给宝物一个情绪标签（震撼 / 温柔 / 神秘 / 治愈…）。
• 文字（选，仅第 1 件宝物）：标记「今日最爱的一件」。
• 合规：贡献照片时只收用户自拍，不转发官方图 / 他人图。

Task 5 · 情字打卡 + 合影（收官）

• 照片（必）：与同行人的合影（门口 / 庭院 / 某宝物前均可）。
• 文字（必）：①「情」字——此行最难忘的瞬间 / 一句话写给同行的人（亲 / 友 / 爱皆可，1–3 句）；② 今日一句总结（如"带娃看遍千年，值"）。
• 这两句即海报的「金句区」；合影是第 5 张拼图。

结合用户爱好的定制逻辑（已后端预生成，直接使用 hobbyHint）

后端 buildCheckinPlan 依据 hobbies 预填了每个任务的 hint：

• 建筑 → 门口/宝物强调馆舍与构图；拍照出片 → 强调光线/构图/避反光；
• 书法绘画 → 宝物引导看笔法章法题跋；历史故事 → 引导看背后史实；
• 亲子共学 → 宝物让孩子先说、情字记「童言童语」；情侣/朋友 → 情字写一句话给同行的人。
• 引导文案直接读 task.photo.hint 与 task.hobbyHint 即可，无需前端再判断。

照片贡献（UGC 收图飞轮）

每次用户上传一张照片后，询问：「要把这张贡献给博物馆照片库、帮更多人做攻略吗？」

• 用户同意 → 先 POST https://museumcheck.cn/image/upload（multipart，字段名 file）拿到 museumcheck.cn/images/... URL；再 POST https://museumcheck.cn/api/museum-photo-contribution，body：{museumId, kind:"entrance"|"treasure", photoUrl, treasureName?, contributor?}。
  • museumId 用后端匹配到的 province_馆名 形态（与 museum_treasures 一致）；kind 门口=entrance、宝物=treasure。
  • 后端仅允许同源 https 图、60s/30 次限频、字段校验——超时/限频就提示稍后重试。
• 这是「收集更多博物馆照片」的飞轮，未来反哺「博物馆信息」付费 skill 素材库。

成就海报（Phase C）

5 任务齐了 → 用 5 张图 + 各任务金句 + 馆名 + 日期 + 同行人 生成海报：

• 优先：复用 museumcheck.cn 现有成就海报生成器（HTML→图片），角标「镇馆之宝 ×3 打卡达成」。把收集到的 5 图 URL 与金句交给该生成器。
• 兜底：若当前不在 museumcheck.cn 环境，用 HTML/Canvas 就地合成一张 5 宫格海报（顶部馆名+日期、中部 5 宫格、底部金句区、角标徽章）并直接展示给用户。
• 落库：可写入 achievement_posters（公开成就墙）。

版权与合规（重要）

• 收取的是信息检索与整理服务费，不是图片售卖；图片版权与授权归原权利人。
• 每件宝物都标注 rightsType 与许可信息，用户须自行对后续使用（转载、商用、再创作）的合规性负责。
• 文物本体多为公有领域(PD)；所链图片按 CC0 / CC BY / CC BY-SA 等署名。贡献照片时仅收用户自拍。

限制

• 收录范围同 museum-treasures（Top 头部馆，每馆 3 件镇馆之宝），未收录馆返回 404。
• 价格为测试价 ¥0.01/次；一次买断全程（生成任务 + 出海报），Phase B/C 同会话内不再二次收费。
• 「结合爱好」仅改变引导文案，不改变任务结构（始终 门口 + 3 宝物 + 情字合影）。
• 不含任何游戏化机制（无排行榜 / 积分 / 抽卡），与腾讯系小游戏化玩法明确区分。