API 参考

所有 API 路由位于 /api/ 下。认证端点由 Better Auth 管理；应用端点位于 /api/v1/ 下。

认证

方法	端点	说明
*	/api/auth/[...all]	Better Auth 全局捕获（登录、注册、OAuth、会话等）

解读

方法	端点	说明
POST	/api/v1/readings	创建新的塔罗解读（入队 BullMQ 任务）
GET	/api/v1/readings/can-play	检查用户是否可以开始解读（积分/限额检查）

对话

方法	端点	说明
POST	/api/v1/chats/[chatId]	在解读对话中发送后续消息

积分

方法	端点	说明
POST	/api/v1/credits/purchase	购买积分包（创建 Stripe 结账会话）

牌阵和问题

方法	端点	说明
GET	/api/v1/spreads	列出所有可用的塔罗牌阵
GET	/api/v1/questions/sample	获取某分类的示例问题
GET	/api/v1/spread-questions/sample	获取某牌阵的示例问题

塔罗读者

方法	端点	说明
GET	/api/v1/tarot-readers	列出所有可用的塔罗读者

每日一牌

方法	端点	说明
GET	/api/v1/card-of-day	获取今日的每日一牌记录
POST	/api/v1/card-of-day	完成每日一牌（发放积分）

牌面皮肤

方法	端点	说明
GET	/api/v1/card-skins	列出所有牌面皮肤及拥有状态

指引（洞察）

方法	端点	说明
POST	/api/v1/guidance/weekly	生成每周指引（入队异步任务）
POST	/api/v1/guidance/soul-journey	生成/刷新灵魂旅程（入队异步任务）

AI 记忆

方法	端点	说明
GET	/api/v1/memory	获取用户的 AI 记忆事实

通知

方法	端点	说明
GET	/api/v1/notifications	列出通知（分页，可按分类筛选）
POST	/api/v1/notifications/[id]/read	标记通知为已读
POST	/api/v1/notifications/read-all	标记所有通知为已读
GET	/api/v1/notifications/unread-count	获取未读通知数量

邀请

方法	端点	说明
GET	/api/v1/invitations/summary	获取用户的邀请统计和邀请码
GET	/api/v1/invitations/invitees	列出被邀请的用户及其状态

会员

方法	端点	说明
GET	/api/v1/membership/billing	获取订阅和账单信息

反馈

方法	端点	说明
POST	/api/v1/feedback	提交用户反馈（附可选截图）

分析

方法	端点	说明
POST	/api/v1/analytics/events	追踪分析事件
POST	/api/track-pageview	记录页面浏览（访客 Cookie）

用户资料

方法	端点	说明
POST	/api/me/avatar	上传用户头像

管理

方法	端点	说明
POST	/api/admin/upload	上传文件（图片、资源）
POST	/api/admin/translate	AI 驱动的内容翻译

内部接口（Telegram 机器人）

受 INTERNAL_API_KEY 请求头保护，不供外部使用。

方法	端点	说明
POST	/api/v1/internal/readings/create	从 Telegram 机器人创建解读

下载

方法	端点	说明
GET	/api/download	下载解读分享图片