技术栈规格：AI 与基础设施
本文档概述了驱动一款高度个性化、对话式、具备视觉能力的 AI 塔罗应用所需的技术架构。
🧠 1. 智能层（LLM 与 NLP）
应用的核心是一个高度定制化、上下文感知的"神谕"引擎。
A. 主模型：大语言模型 (LLM)
- 模型选择： Claude 3.5 Sonnet 或 GPT-4o。
- 理由： 与小型模型相比，这些模型在推理能力、遵循复杂符号指令的能力以及"类人"的诗意/共情语调方面表现更优。
- 角色：
- 生成个性化的塔罗/占星解读。
- 对话式互动（"神谕"聊天）。
- 从日记数据中总结"情感弧线"。
- 提示工程策略：
- 系统提示词： 高度详细的"角色"定义（灵性闺蜜 / 灵魂向导）。
- 上下文注入： 每个提示词必须包含用户的本命盘数据（行星、宫位、相位）和当前行运。
B. 微调与 RAG（检索增强生成）
- RAG 实现： 我们将使用向量数据库（例如 Pinecone 或 Weaviate），而非对整个模型进行塔罗主题的微调。
- 知识库：
- 精心整理的高保真塔罗牌图像、象征意义和历史含义库。
- 占星行运及其心理学蕴意数据库。
- 工作流程： 当用户提问时，系统从向量数据库检索最相关的"象征上下文"，并注入到 LLM 提示词中。
👁️ 2. 视觉层（计算机视觉）
用于实现"灵视塔罗"（扫描实体卡牌）。
A. 模型架构
- 模型选择： YOLO (You Only Look Once) 或 Segment Anything Model (SAM)。
- 要求： 实时、低延迟地检测卡牌边界和符号。
- 逻辑流程：
- 检测： 在单个摄像头画面中识别多张卡牌的边界。
- 分类： 使用轻量的专用分类器（或基于 CLIP 的嵌入）根据视觉特征识别 78 张牌中的具体哪一张。
- 映射： 将检测到的卡牌位置映射到特定的"牌阵模板"（例如凯尔特十字）。
B. 实现方式
- 端侧 AI (Edge AI)： 为获得最佳速度和隐私保护，使用 CoreML (iOS) 和 TensorFlow Lite (Android) 直接在用户设备上运行检测模型。这降低了服务器成本和延迟。
🏗️ 3. 基础设施与后端
A. 后端架构
- 框架： NestJS (Node.js / TypeScript)。
- 为何选择 NestJS：
- 内置 WebSocket 网关 (
@WebSocketGateway)，用于在"神谕"聊天中逐 token 流式传输 LLM 响应 — 无需额外依赖。 - 一流的 GraphQL 模块 (
@nestjs/graphql)，支持代码优先的 Schema 生成，实现从 Prisma 模型 → 解析器 → Expo 客户端的端到端类型安全。 - 依赖注入 (DI) 使定义
OracleService接口并在不触及业务逻辑的情况下切换 LLM 提供商（Claude vs GPT-4o）变得轻而易举。 - 守卫 (Guards) 与拦截器 (Interceptors) 可在解析器/控制器层面干净地执行订阅等级策略（如免费用户 = 每天 1 次抽牌，高级用户 = 无限次）。
- Bull 队列集成 (
@nestjs/bull)，用于将 CPU 密集型任务（如分享图片/视频渲染）分流到后台工作进程。 - 模块化架构 — 功能以独立模块的形式干净扩展：
TarotModule、AstrologyModule、NotificationModule、BillingModule、VisionModule。
- 内置 WebSocket 网关 (
- API 设计： GraphQL（允许前端仅请求庞大的占星数据对象中所需的特定部分）。
- 实时引擎： WebSockets（通过 NestJS Gateway）实现无缝的流式"聊天"体验（神谕"正在输入"预言的效果）。
📝 备注：如果技术栈中已包含 Next.js。 如果 MysticX 最终推出基于 Next.js 构建的 Web 端应用，则无需再引入 NestJS 作为独立后端。Next.js 的 API Routes（路由处理器）和 Server Actions 可以在同一代码库中直接充当 API 层。这避免了部署和维护两个独立的服务进程，将整个技术栈保持在单一 monorepo 中，并简化了身份认证（SSR 页面与 API 端点之间共享 Cookie/Session）。仅在后端作为独立服务且不涉及 Next.js Web 应用的情况下，才使用 NestJS。
B. 数据层
- 主数据库： PostgreSQL（通过 Prisma）用于存储结构化的用户档案、本命盘和订阅状态。
- 向量数据库： Pinecone 用于存储和检索占星/塔罗象征嵌入。
- 缓存层： Redis 用于快速检索每日行运和活跃用户会话数据。
C. 集成层
- 占星 API： 与 Swiss Ephemeris（或 AstrologyAPI 等提供商）集成，计算实时行星位置。
- 健康 API： 与 Apple HealthKit 和 Google Fit 集成，用于基于仪式的能量预测。
🛠️ 4. 前端与移动端开发
框架决策：Expo (React Native) vs. Flutter
经过全面评估，我们推荐 Expo (React Native) 作为 MysticX 的移动端框架。以下是支撑该决策的完整对比。
对比表
| 评估维度 | Expo (React Native) | Flutter |
|---|---|---|
| 编程语言 | TypeScript/JavaScript | Dart |
| 渲染方式 | 原生 OEM 组件 + 通过 react-native-skia 使用 Skia | 自定义渲染引擎 (Impeller/Skia) — 自绘每个像素 |
| 动画性能 | 配合 react-native-reanimated + react-native-skia 表现优秀 | 卓越 — 内置 60/120fps 引擎，更少样板代码 |
| Rive 支持 | 良好（官方 SDK） | 最佳（最深度集成，支持状态机） |
| 云端构建 | EAS Build — 第一方服务，有免费额度，一条命令搞定 | Codemagic / Bitrise — 第三方服务，需付费 |
| 商店提交 | EAS Submit — 单条命令，托管式签名 | Codemagic + Fastlane — 更多配置和维护成本 |
| OTA 热更新 | EAS Update — 成熟可靠，无需经过应用商店审核即可推送 UI/文案/素材更新 | Shorebird — 较新，功能有限，第三方服务 |
| 商店元数据 | EAS Metadata — 在代码中管理多语言商店列表 | Fastlane deliver/supply — 需手动配置 |
| 开发者人才池 | 庞大（JS/TS 是全球最流行的编程语言） | 较小（Dart 在 Flutter 之外较为小众） |
| Web/桌面端复用 | 通过共享 TS 包与 Next.js Web 端共享代码 | Flutter Web 存在但在复杂 Web 应用场景下不够成熟 |
| 原生模块访问 | 通过 Expo Modules API + Config Plugins 实现完全原生访问（HealthKit、原生分享面板等） | 通过 Platform Channels 实现完全原生访问 |
| 跨平台一致性 | 可能存在少量平台特异性 UI 差异 | 像素级完美一致，所有设备表现相同 |
| 生态系统成熟度 | npm 生态极其庞大 | pub.dev 生态持续增长，但规模远小于 npm |
为何 Expo 更适合 MysticX
迭代速度对内容驱动型应用至关重要。 MysticX 需要不断发布新的每日意念、卡牌画作、文案和 AI 提示词调整。Expo 的 OTA 热更新让我们可以绕过应用商店审核，即时推送这些更改。Flutter 没有成熟的替代方案 — Shorebird 仍处于早期阶段。
统一的 TypeScript 技术栈。 后端（Node.js/TypeScript）、AI 提示词工程层和移动应用共享同一种语言。这消除了上下文切换开销，支持共享验证逻辑（例如本命盘 schema），并且大幅降低招聘难度。
EAS 是巨大的开发体验优势。 在 Flutter 中，你需要拼凑 Codemagic + Fastlane + Shorebird 才能近似 Expo 仅用
eas build、eas submit和eas update即可提供的功能。更少的活动部件 = 发布日出问题的概率更低。动画性能差距已大幅缩小。 借助运行在 UI 线程上的
react-native-reanimatedv3+ 和提供完整 Skia 画布的@shopify/react-native-skia，Expo 与 Flutter 在我们的使用场景（卡牌翻转、发光光环、粒子特效）下的动画性能差距已微乎其微。未来的 Web 扩展。 当 MysticX 最终推出 Web 端（数据仪表盘、营销着陆页）时，在移动应用和 Next.js Web 应用之间共享 TypeScript 代码轻而易举。Flutter Web 在生产级 Web 体验方面还不够成熟。
何种情况下 Flutter 会是更好的选择
- 如果 MysticX 是一个类游戏体验，需要持续的 3D 渲染、复杂的物理模拟，或要求在数千种 Android 设备型号间保证绝对的像素级一致性。
- 如果团队已经是 Dart/Flutter 技术栈，没有 JS/TS 经验。
最终选定技术栈
- 框架： Expo (React Native) + TypeScript。
- 动画引擎： react-native-reanimated + @shopify/react-native-skia 实现高性能 2D 图形，辅以 Rive 实现预构建的交互式矢量动画（卡牌翻转、星体运动）。
- 构建与发布： Expo Application Services (EAS) — 构建、提交、更新和元数据管理。
- 设计系统： 定制的"Mystic 设计系统"，具备统一排版、"毛玻璃 (Glassmorphic)"组件和"发光"特效。
📊 技术栈总览
| 组件 | 技术选型 |
|---|---|
| LLM 大语言模型 | Claude 3.5 Sonnet / GPT-4o |
| 向量数据库 | Pinecone / Weaviate |
| 计算机视觉 | CoreML / TensorFlow Lite |
| 后端 | NestJS (TypeScript) / GraphQL + WebSocket Gateway |
| 数据库 | PostgreSQL + Prisma |
| 缓存 | Redis |
| 移动端 | Expo (React Native) + TypeScript |
| 动画 | react-native-reanimated + react-native-skia + Rive |
| CI/CD 与 OTA | Expo Application Services (EAS) |
| 基础设施 | AWS / Google Cloud |