Journey Cards

把"AI 带你去一个地方"这件事，接进你自己的前端。

这个仓库不是 npm 包，也不是组件库——它是一份数据契约加一份可以照抄的参考实现。你的存储能存下一段 JSON，你的前端就能把它渲染成一趟点得开的旅行；React、Vue、原生都行。

功能本身是这样的：AI 自己挑一个国家、选 6 处停留、每处配一张竖屏照片和一段第一人称的话，在聊天里落成一张卡片。点开是全屏的照片故事——照片铺满整屏，地名在顶部，那段话落在左下角，底部一个音乐播放器和 6 个圆点，左右滑就走到下一处。

跟"在聊天里发几张图"的区别是：这是一趟有顺序、有旁白、有配乐的行程，AI 是带路的那个人，不是图片搬运工。

为人机恋而做，但设计与后端无关：两张表、一组很小的 REST 接口、一个纯前端的渲染器，就够了。

里面有什么

• INTEGRATE.md —— 接进你自己的前端：最小数据契约（哪些字段必填、哪些缺了也能跑）、三块 UI 哪块必须哪块可以不要、从参考实现里只需要抄哪几个函数和哪几段 CSS（一张对照表）、样式怎么跟宿主隔离、React / Vue / 原生三段骨架，以及一节「不抄会踩坑」。大多数人从这份开始看。
• SPEC.md —— 完整设计：两张表的字段与建表语句、9 个 REST 接口的请求/响应/错误码、照片和音频怎么存、以及一份"照抄时最容易踩"的坑清单（position 两张表方向相反、iOS 上 .volume 赋值无效、跨域音频会静音不报错……）。面向自带前端的接入方。
• AI-GUIDE.md —— 给 AI 看的那一份：建一趟旅行的调用顺序、怎么在正文里落 `` 标签、以及一段可以直接贴进系统提示词的写作规范（照片选什么、那段话该怎么写、什么口吻不要写）。
• examples/journey-cards.html —— 一个自包含的参考 UI：聊天卡片 + 全屏故事浮层。浏览器直接打开就能看，自带 mock 数据。CSS 变量换肤，CONFIG 块改名字，每处真实 API 调用位置都标了注释。

五分钟先看到东西

open examples/journey-cards.html

双击也行。不需要后端、不联网、没有任何依赖——单文件，mock 数据写在里面。

打开后：

1. 看到聊天流里的那张卡片（一排竖条照片，横向滑动会有磁力吸附）；
2. 点任意一条 → 全屏故事浮层，照片铺满，地名在上，旁白在左下；
3. 底部圆点或左右滑动切换 6 处；
4. 底部播放器点一下开始放（示例里配的是一段本地生成的音，不外链）。

确认交互对味了，再往下接自己的后端。

改成你们的名字

examples/journey-cards.html 开头的 CONFIG 块，改这几行：

const CONFIG = {
  // 名字：卡片标题里"谁带你去"的那个人
  user:      "YOU",        // ← 你的名字
  assistant: "PARTNER",    // ← AI 的名字

  // 卡片上的四行字（{assistant} {title} {year} {count} 会被替换）
  cardKicker: "JOURNEYS",
  cardTitle:  "{assistant} 带你去了{title}",
  cardSub:    "{year} · {count} 处停留",
  // 卡片底下那行小字。写你们自己的话 —— 或者干脆让 AI 每趟自己写一句
  // （journey 数据里带 hint 就用数据里那句，这里只是没给时的兜底，见下）
  cardHint:   "",

  // 后端：留空 = 用文件里自带的 mock 数据
  apiBase: "",
  token:   "",
};

改完保存刷新，卡片抬头、副标题、底下那句话就全跟着变。 （真接进自己 app 时，名字从你自己存用户信息的地方取，不用写死在这里。）

底下那行小字建议走数据：每趟的六张照片气质都不一样，让 AI 跟着那趟的情绪现写一句，比一句写死的口号耐看得多。写死的那句翻到第三趟就废了。

配色改 :root 里的 --jc-* 变量。播放器主色不在 CSS 里——它跟着每趟旅行的 audio.hue 走（0–360，oklch(0.62 0.13 )），所以每趟旅行的播放器颜色可以不一样。

数据长什么样

一趟旅行 = 一个 journey + 若干 stop。GET /api/journeys 返回的就是下面这个形状（这里只列一趟、两处）：

{
  "journeys": [
    {
      "id": "j_m9xk2p3_a3f9c",
      "title": "新西兰",
      "titleEn": "New Zealand",
      "year": "2025",
      "hint": "南半球的秋天，从一片湖开始。",
      "cover": "/api/journeys/photo/jp_m9xk2p3_a3f9c",
      "position": -1,
      "createdAt": 1753672345678,