MysticX Docs

简体中文

English

简体中文

English

Appearance

MysticX 移动端应用开发计划 ​

概要 ​

本文档详细阐述了 MysticX 原生移动应用的开发计划，目标平台为 iOS 和 Android。该应用将把完整的 AI 塔罗解读体验带到移动端，包含原生交互、推送通知、离线能力和平台特定的支付流程。

目标平台：iOS 15.1+ 和 Android 7+（API 24+） 框架：React Native + Expo（SDK 55+） 时间线：见下方阶段分解。

目录 ​

技术栈 ​

推荐技术栈 ​

类别技术选型理由
框架React Native + Expo（SDK 55）共享代码库、OTA 更新、成熟生态。团队已使用 React 和 TypeScript。
语言TypeScript与 Web 应用同一语言 — 共享类型和验证 Schema。
导航Expo Router（基于文件）与 Next.js App Router 相似的范式，内置深链接。
状态管理Zustand与 Web 应用同一库 — 可共享 Store 逻辑。
表单React Hook Form + Zod与 Web 相同，可共享验证 Schema。
样式NativeWind v4React Native 的 Tailwind CSS — 与 Web 栈一致的开发体验。
动画React Native Reanimated硬件加速原生动画（翻牌、牌阵展开）。
手势处理React Native Gesture Handler原生手势识别，用于牌面交互。
AI 流式传输Server-Sent Events（SSE）via fetch与 Web 相同的流式协议。
认证Better Auth（REST API 调用）复用现有认证端点，基于 Token 的会话。
应用内购买RevenueCat（react-native-purchases）抽象 Apple/Google IAP 复杂性。兼容 Expo。
外部支付Stripe React Native SDK用于积分包购买（IAP 要求以外的场景）。
推送通知Expo NotificationsiOS（APNs）和 Android（FCM）统一推送。
图片处理Expo Image高效图片加载和缓存。
安全存储expo-secure-storeKeychain（iOS）/ EncryptedSharedPrefs（Android）用于 Token 存储。
触觉反馈expo-haptics翻牌和揭示时的触觉反馈。
日期/时间Luxon与 Web 应用相同。
分析Mixpanel React Native与 Web 相同的分析平台。
OTA 更新EAS Update无需应用商店审核即可推送 JS Bundle 更新。
构建/发布EAS Build + EAS SubmitiOS 和 Android 云构建，自动提交。

为什么选择 Expo 而非裸 React Native？ ​

  1. EAS Build — 基于云的构建，无需 macOS CI 来构建 iOS 应用
  2. OTA 更新 — 无需等待应用商店审核周期即可推送 Bug 修复和功能调整
  3. Expo Router — 基于文件的路由与 Next.js App Router 一致，降低学习成本
  4. Config Plugins — 无需 eject 即可配置原生模块
  5. Expo SDK — 相机、通知、触觉反馈、安全存储等预配置模块
  6. Development Builds — 支持原生模块的快速迭代

为什么不选 Flutter 或 Swift/Kotlin 原生？ ​

  • Flutter：需要用 Dart 重写所有逻辑。无法与现有 TypeScript 代码共享代码。
  • 原生（SwiftUI/Jetpack Compose）：需要维护两个独立代码库。初期速度更快但长期维护成本翻倍。团队专长在 TypeScript/React。
  • React Native + Expo：最大化代码共享（类型、验证、工具函数），单一代码库，团队熟悉度高，Expo 的托管工作流降低了首个移动应用的 DevOps 负担。

架构 ​

系统概览 ​

┌─────────────────────────────────┐
│       移动应用（Expo）            │
│  ┌───────────┐  ┌────────────┐ │
│  │   页面    │  │   Stores   │ │
│  │ (Router)  │  │  (Zustand) │ │
│  └─────┬─────┘  └─────┬──────┘ │
│        │               │        │
│  ┌─────┴───────────────┴──────┐ │
│  │       API 客户端层          │ │
│  │  (fetch + SSE + auth)      │ │
│  └─────────────┬──────────────┘ │
│                │                │
│  ┌─────────────┴──────────────┐ │
│  │  RevenueCat │ Stripe SDK   │ │
│  │  (IAP)      │（积分购买）    │ │
│  └─────────────┬──────────────┘ │
└────────────────┼────────────────┘
                 │
                 ▼
┌─────────────────────────────────┐
│    现有 MysticX 后端             │
│  (Next.js API + Workers + DB)  │
└─────────────────────────────────┘

核心设计原则 ​

  1. API 优先 — 移动应用是纯客户端。所有业务逻辑都在现有 Next.js API 中。无需新建后端。
  2. 共享类型 — 将共享的 TypeScript 类型抽取到 packages/shared 工作区包中，供 Web 和移动端共同使用。
  3. 基于 Token 的认证 — 移动端使用 Bearer Token 认证（Better Auth 的会话 Token 存储在 Secure Store 中）。
  4. 离线感知 — 解读历史和每日一牌本地缓存。离线时优雅降级。
  5. 原生体验 — 平台特定的导航模式、触觉反馈和手势。不是 WebView 套壳。

Monorepo 结构 ​

mysticx/
├── apps/
│   ├── web/              # 现有 Next.js 应用（移入）
│   └── mobile/           # 新 Expo 应用
│       ├── app/          # Expo Router 页面
│       ├── components/   # 移动端专属组件
│       ├── hooks/        # 移动端专属 Hooks
│       ├── stores/       # Zustand Stores（可从 shared 导入）
│       ├── lib/          # API 客户端、认证、工具函数
│       ├── assets/       # 牌面图片、图标、字体
│       └── app.json      # Expo 配置
├── packages/
│   └── shared/           # 共享类型、验证 Schema、常量
├── prisma/               # 数据库 Schema（仅 Web）
├── scripts/              # Workers、机器人（仅 Web）
└── package.json          # pnpm 工作区根目录

如果 Monorepo 迁移初期影响太大，移动应用也可以放在独立仓库中，通过发布的 npm 包或 git submodule 引用共享类型。长期可维护性推荐 Monorepo 方案。

API 客户端层 ​

一个轻量的 API 客户端模块，包装 fetch 并提供：

  • 基础 URL 配置（dev/staging/prod）
  • 自动从 Secure Store 注入 Bearer Token
  • 401 响应时自动刷新 Token
  • SSE 流式传输支持，用于解读内容传递
  • 通过共享 Zod Schema 实现请求/响应类型安全
  • 带指数退避的重试逻辑
  • 网络连接状态感知
typescript
// 简化示例结构
type ApiClient = {
  get<T>(path: string): Promise<T>;
  post<T>(path: string, body: unknown): Promise<T>;
  stream(path: string, onToken: (token: string) => void): Promise<void>;
};

功能范围 ​

MVP（v1.0）— 核心解读体验 ​

功能说明优先级
认证邮箱/密码 + Google OAuth 登录P0
首页牌阵选择网格、快捷操作、每日一牌提示P0
塔罗解读完整解读流程：问题 → 牌阵 → 抽牌 → AI 流式传输P0
牌面动画使用 Reanimated 的翻牌、牌阵布局和揭示动画P0
后续对话解读后与 AI 的追问对话P0
每日一牌每日抽牌，含洞察和积分领取P0
解读历史可滚动浏览的历史记录，支持搜索和筛选P0
积分余额显示和管理积分P0
订阅购买通过 IAP 或 Stripe 订阅 Gold/DiamondP0
积分包购买一次性积分购买P0
推送通知解读完成、每周指引就绪、订阅事件P0
设置语言、主题、通知偏好P0
新手引导首次启动的功能介绍引导P1

v1.1 — 用户互动功能 ​

功能说明优先级
AI 记忆查看查看你的 AI 记忆事实P1
每周指引查看和生成每周指引P1
灵魂旅程查看和刷新灵魂旅程P1
分享解读生成图片进行社交分享P1
Widget（iOS）每日一牌主屏幕小组件P1
Widget（Android）每日一牌主屏幕小组件P1
触觉反馈牌面交互时的触觉反馈P1

v1.2 — 增长功能 ​

功能说明优先级
好友邀请可分享链接的邀请推荐系统P2
应用内通知通知中心下拉菜单P2
牌面皮肤商城浏览和购买牌面皮肤P2
读者选择浏览和解锁 AI 读者P2
博客阅读浏览博客文章P2
离线模式缓存最近的解读以供离线查看P2
生物识别认证Face ID/Touch ID/指纹锁P2

有意排除在移动端之外的功能 ​

功能原因
管理后台仅桌面端。移动端展示太复杂。
反馈提交改用应用内评价提示。
联盟营销面板低频功能，仅 Web 端。
Devbox 测试开发工具，移动端构建不需要。

支付集成策略 ​

这是移动应用最复杂的部分，因为涉及 Apple 和 Google 的 IAP 政策。

IAP 政策问题 ​

Apple App Store 政策 和 Google Play Store 政策 要求在应用内消费的数字商品必须使用各自的应用内购买系统（Apple Pay / Google Play Billing）。这意味着：

  • 订阅（Gold/Diamond） — 在移动应用内购买时必须通过 Apple IAP / Google Play Billing
  • 积分包 — 属于应用内消费的数字商品，在移动应用内购买时也必须通过 IAP
  • Apple 抽成 15-30%（通过小型企业计划年收入 < $1M 的开发者为 15%，否则 30%）
  • Google 抽成 15-30%（前 $1M 为 15%，之后 30%）

推荐方案：混合模式（RevenueCat + Stripe） ​

RevenueCat 用于 IAP（移动端订阅 + 积分包） ​

推荐使用 RevenueCat 作为 IAP 的抽象层，因为：

  1. 单一 SDK 同时支持 Apple 和 Google 商店
  2. 服务端收据验证 — 杜绝客户端收据伪造
  3. Webhook 集成 — 实时同步订阅状态到我们的后端
  4. 跨平台权益 — 用户在 iOS 上订阅后，其 Gold/Diamond 状态在 Web 和 Android 上同样有效
  5. 分析面板 — MRR、流失率、试用转化指标
  6. 兼容 Expo — react-native-purchases 支持 Expo Config Plugins

Stripe 用于 Web 购买（现有） ​

在 Web 端创建的现有 Stripe 订阅继续有效。移动应用通过 API 检查用户的订阅状态，不论购买来源。

实现架构 ​

┌──────────────────────────────────────────────────┐
│                   移动应用                         │
│                                                   │
│   ┌─────────────┐        ┌─────────────────────┐ │
│   │ RevenueCat  │        │   Stripe SDK        │ │
│   │ SDK         │        │  （Web 购买          │ │
│   │ (IAP)       │        │    备选方案）         │ │
│   └──────┬──────┘        └──────────┬──────────┘ │
└──────────┼──────────────────────────┼────────────┘
           │                          │
           ▼                          ▼
┌──────────────────┐     ┌──────────────────────┐
│   RevenueCat     │     │  Stripe Webhooks     │
│   后端           │     │ （现有）               │
│  （收据           │     │                      │
│   验证）          │     │                      │
└────────┬─────────┘     └──────────┬───────────┘
         │                          │
         ▼                          ▼
┌──────────────────────────────────────────────────┐
│              MysticX 后端 API                     │
│                                                   │
│   RevenueCat Webhook 处理器    Stripe Webhooks    │
│   POST /api/v1/webhooks/rc    （现有）             │
│                                                   │
│   ┌──────────────────────────────────────┐        │
│   │  统一订阅服务                          │        │
│   │  - 检查 RevenueCat 权益              │        │
│   │  - 检查 Stripe 订阅                  │        │
│   │  - 合并为统一等级状态                  │        │
│   └──────────────────────────────────────┘        │
└──────────────────────────────────────────────────┘

价格一致性策略 ​

移动端价格与 Web 端完全一致。我们全额承担 Apple/Google 15-30% 的佣金费用，为用户提供简单公平的定价体验。

产品Web 价格移动端价格平台费（15%）平台费（30%）
Gold 月付$19.99$19.99-$3.00-$6.00
Gold 年付$167.92$167.92-$25.19-$50.38
Diamond 月付$69.99$69.99-$10.50-$21.00
Diamond 年付$587.92$587.92-$88.19-$176.38
2K 积分$9.99$9.99-$1.50-$3.00
5K 积分$19.99$19.99-$3.00-$6.00
12K 积分$39.99$39.99-$6.00-$12.00
30K 积分$79.99$79.99-$12.00-$24.00

策略：申请 Apple 小型企业计划（收入 < $1M 享受 15% 佣金）及 Google 对应计划，以最小化利润影响。在 15% 的费率下，降低的利润作为用户获取成本是可接受的。如果收入超过 $1M 进入 30% 费率档位，届时重新评估此决策。

跨平台订阅同步 ​

用户通过 IAP 订阅时：

  1. RevenueCat 验证收据并发送 Webhook 到我们的后端
  2. 后端更新用户等级（FREE → GOLD 或 DIAMOND）
  3. 按订阅计划发放积分
  4. 用户等级在 Web 和移动端同步体现

用户通过 Stripe（Web 端）订阅时：

  1. Stripe Webhook 触发（现有流程）
  2. 后端更新用户等级
  3. 移动应用在下次 API 调用或推送通知时获取新等级

跨平台权益检查优先级：

  1. 首先检查 RevenueCat 权益（移动端购买）
  2. 检查 Stripe 订阅状态（Web 端购买）
  3. 如果两端都有，取最高等级（边缘情况：用户在两个平台都订阅了）

Apple IAP 特殊考量 ​

  • StoreKit 2 — RevenueCat 在 iOS 15+ 上使用 StoreKit 2，提供更好的 API
  • 恢复购买 — App Store 合规要求在设置中提供恢复购买按钮
  • 订阅管理 — 深链接到 iOS 订阅设置
  • 免费试用 — 可通过 Apple IAP 系统提供试用期
  • 宽限期 — 在 App Store Connect 中启用，用于续订失败
  • 价格同意 — 处理 Apple 的价格上调同意流程

Google Play Billing 特殊考量 ​

  • Google Play Billing Library v6+ — RevenueCat 已处理
  • 确认购买 — 必须在 3 天内确认，否则自动退款
  • 用户取消调查 — Google 自动显示
  • 账户冻结 — 处理支付失败时的暂停状态

收入确认 ​

收入流向（移动端 IAP）：
  用户支付 $19.99（Gold 月付 via IAP）
  → Apple/Google 抽成 $3.00-$6.00（15-30%）
  → MysticX 收到 $13.99-$16.99
  → RevenueCat 免费至 $2.5K MTR，之后收取追踪收入的 1%

收入流向（Web Stripe）：
  用户支付 $19.99（Gold 月付 via Stripe）
  → Stripe 收取 $0.88（2.9% + $0.30）
  → MysticX 收到 $19.11

UI/UX 设计 ​

设计原则 ​

  1. 神秘而不花哨 — 深色主题、微妙渐变、流畅动画。与 Web 端的高端质感保持一致。
  2. 触控优先 — 大触控目标（最小 44pt）、滑动手势、触觉反馈
  3. 渐进披露 — 不要信息过载。展示必要内容，按需揭示深度。
  4. 遵循平台惯例 — iOS 的系统返回手势，Android 的 Material 导航。尊重各操作系统。
  5. 精简至核心 — 移动端空间有限。每个像素都需物有所值。

导航结构 ​

标签栏（底部）：
├── 首页           # 牌阵网格、每日一牌、快捷操作
├── 解读           # 历史记录、搜索、筛选
├── 每日一牌       # 每日一牌功能（居中，突出）
├── 洞察           # 每周指引、灵魂旅程、AI 记忆
└── 个人资料       # 设置、订阅、积分、邀请

页面清单 ​

首页标签 ​

  • 首页 — 每日问候主视觉卡片、牌阵选择网格（2 或 3 列）、"开始解读"按钮、最近解读预览
  • 牌阵详情 — 牌阵描述、牌位视觉展示、示例问题、"开始"按钮
  • 解读流程 — 输入问题 → 抽牌动画 → AI 流式响应 → 结构化解读视图
  • 后续对话 — 对话视图，含消息气泡、输入指示器、快捷回复建议

解读标签 ​

  • 解读历史 — 按时间排列的列表，支持搜索、牌阵类型筛选、日期分组
  • 解读详情 — 完整解读，含可展开部分（总结、牌面、建议）
  • 分享预览 — 生成分享卡片，支持社交平台选择

每日一牌标签（居中） ​

  • 每日一牌 — 全屏牌面揭示动画、每日洞察、积分领取、共鸣追踪
  • 每日一牌历史 — 过往抽牌日历视图

洞察标签 ​

  • 洞察概览 — 每周指引、灵魂旅程、AI 记忆卡片
  • 每周指引 — 格式化的指引内容，含生成/刷新按钮
  • 灵魂旅程 — 个人进化叙事，含主题标签
  • AI 记忆 — 5 条记忆事实列表及解释

个人资料标签 ​

  • 个人资料 — 头像、姓名、邮箱、等级徽章、积分余额
  • 订阅 — 当前计划详情、升级/管理按钮、账单历史
  • 积分 — 余额、交易历史、购买积分包
  • 邀请 — 邀请码、分享按钮、已邀请用户列表
  • 设置 — 语言、主题（浅色/深色/跟随系统）、通知、应用信息
  • 商城 — 牌面皮肤浏览、读者解锁展示

牌面交互设计 ​

牌面交互是应用的核心卖点，必须给人魔幻般的感觉：

  1. 牌组 — 3D 透视的扇形打开牌面（背面朝上）
  2. 选牌 — 拖动或点击选择；选中的牌浮起并伴有触觉脉冲
  3. 翻牌 — 使用 Reanimated 共享值的 3D 翻转动画（60fps）
  4. 牌阵布局 — 牌面动画移动到牌阵位置（凯尔特十字、菱形等）
  5. 牌面放大 — 点击牌面在底部弹出中查看完整详情

流式解读展示 ​

  • AI 响应以流的形式进入滚动视图，支持 Markdown 渲染
  • 章节标题（总结、第 1 张牌、第 2 张牌、建议）渐进显示
  • 每批新 Token 的微妙淡入动画
  • 自动滚动跟随最新内容
  • 流式传输完成时的"完成"触觉反馈

深色模式 ​

应用应默认深色模式（与神秘主题一致），但支持浅色模式和系统偏好。颜色 Token 应与 Web 应用的 CSS 自定义属性保持一致。

排版 ​

  • 主字体：系统字体（iOS 为 SF Pro，Android 为 Roboto）
  • 装饰字体：用于牌名和解读标题的衬线字体（如 Playfair Display 或类似字体）
  • 正文字体：系统无衬线字体以保证可读性

离线体验 ​

  • 最近查看的解读缓存在 AsyncStorage 中
  • 今日的每日一牌结果本地缓存
  • 牌阵和问题分类在首次加载时缓存
  • 离线状态：顶部横幅提示，网络依赖功能操作禁用
  • 连接恢复时自动重试

阶段分解 ​

第 0 阶段：基础搭建（第 1-2 周） ​

  • 使用 TypeScript 和 EAS 创建 Expo 项目
  • 配置 Expo Router 的标签导航
  • 设置 NativeWind v4，匹配 Web 主题的设计 Token
  • 实现带认证 Token 管理的 API 客户端层
  • 设置 Secure Store 用于 Token 持久化
  • 配置 Mixpanel React Native
  • 设置 EAS Build 配置文件（development、preview、production）
  • 创建共享类型包（或确定类型共享方案）

第 1 阶段：认证（第 2-3 周） ​

  • 登录页面（邮箱/密码）
  • 注册页面及邮箱验证
  • Google OAuth 登录（Expo AuthSession）
  • 会话管理及自动 Token 刷新
  • Expo Router 中的路由保护处理
  • 密码重置流程

第 2 阶段：核心解读体验（第 3-6 周） ​

  • 带牌阵选择网格的首页
  • 牌阵详情页面
  • 带字数计数器的问题输入
  • 抽牌动画（核心亮点）
  • AI 解读流式传输页面
  • 带 Markdown 的结构化解读展示
  • 后续对话界面
  • 带筛选的解读历史列表
  • 解读详情视图
  • 积分余额展示和扣除 UI

第 3 阶段：每日一牌（第 6-7 周） ​

  • 带揭示动画的每日一牌页面
  • 洞察展示（情绪天气、行动、问题）
  • 积分领取流程
  • 共鸣追踪
  • 每日一牌历史

第 4 阶段：支付（第 7-9 周） ​

  • RevenueCat 设置和产品配置
  • Apple App Store 产品创建（订阅 + 消耗品）
  • Google Play Store 产品创建（订阅 + 消耗品）
  • 订阅购买流程（IAP）
  • 积分包购买流程（IAP）
  • 通过 Webhook 实现跨平台订阅同步
  • 订阅管理页面
  • 恢复购买流程
  • 后端 RevenueCat 事件 Webhook 处理器
  • 双平台价格测试和验证

第 5 阶段：推送通知（第 9-10 周） ​

  • Expo Notifications 设置（APNs + FCM）
  • 后端推送 Token 注册
  • 通知类型：解读完成、指引就绪、每日提醒、订阅事件
  • 通知偏好设置页面
  • 从通知深链接到特定页面
  • 角标数量管理

第 6 阶段：打磨和平台适配（第 10-12 周） ​

  • 新手引导流程（3-4 个页面）
  • 所有牌面交互的触觉反馈
  • 横屏锁定（仅竖屏）
  • 应用图标和启动页
  • 设置页面（语言、主题、通知）
  • 错误边界和崩溃报告
  • 性能优化（列表虚拟化、图片缓存）
  • 无障碍审计（VoiceOver、TalkBack）
  • 平板布局适配（iPad、Android 平板）

第 7 阶段：测试和提交（第 12-14 周） ​

  • 真机端到端测试
  • TestFlight（iOS）和 Google Play 内部测试（Android）上的 IAP 测试
  • App Store 截图生成
  • App Store 元数据（描述、关键词）支持所有语言
  • Apple App Store 提交
  • Google Play Store 提交
  • 审核准备（演示账号、审核说明）

第 8 阶段：上线后功能（第 15 周+） ​

  • iOS Widget（每日一牌）
  • 每周指引和灵魂旅程页面
  • AI 记忆视图
  • 好友邀请系统
  • 牌面皮肤商城
  • 分享解读功能
  • 生物识别认证
  • 离线模式改进

挑战与应对 ​

1. Apple App Store 审核 ​

挑战：Apple 对使用 IAP 的数字内容类应用审核严格。他们可能会更加仔细地审查"占卜"类应用。

应对措施：

  • 将应用定位为"AI 驱动的自我反思和正念工具"而非"占卜"
  • 确保所有数字商品购买都通过 IAP
  • 包含明确的免责声明，说明解读仅供娱乐/反思参考
  • 为审核团队准备一个有充足积分的演示账号
  • 研究 App Store 审核指南第 5.3 节（游戏、赌博和彩票）— 塔罗不属于赌博，但需准备好应对提问

2. 支付复杂性 ​

挑战：管理两套支付系统（RevenueCat IAP + Stripe Web）并统一订阅状态。

应对措施：

  • RevenueCat 的 Webhook 集成使这一点可管理
  • 在后端创建统一订阅服务，同时检查两个来源
  • 使用 RevenueCat 的客户属性关联 MysticX 用户 ID
  • 在设置中突出显示"恢复购买"，方便用户切换设备
  • 充分测试跨平台场景（Web 上订阅 → 移动端验证，反之亦然）

3. 移动端 SSE 流式传输 ​

挑战：Server-Sent Events 在移动端的支持程度不一。后台执行限制可能终止长连接。

应对措施：

  • 使用带 ReadableStream 的 fetch 进行 SSE 解析（在 React Native 新架构中可用）
  • 实现流中断时的重连逻辑
  • 添加备用轮询机制，每 2 秒检查解读状态
  • 解读期间保持应用前台运行（阻止屏幕休眠）
  • 如果应用在生成期间进入后台，显示"解读进行中"推送通知

4. 牌面动画性能 ​

挑战：复杂的 3D 翻牌和牌阵布局动画需要在低端 Android 设备上达到 60fps。

应对措施：

  • 使用 React Native Reanimated（在 UI 线程运行，非 JS 线程）
  • 使用 expo-image 进行优化的牌面图片加载和磁盘缓存
  • 在牌阵选择时预加载牌面图片
  • 在低端设备上降低动画复杂度（通过设备信息检测）
  • 开发期间使用 Flipper 和 Android Studio Profiler 进行性能分析

5. 离线和网络弹性 ​

挑战：移动端用户经常在 WiFi、蜂窝网络和离线状态之间切换。

应对措施：

  • 使用 @react-native-community/netinfo 监测网络连接
  • 对非关键操作实现乐观 UI
  • 将失败请求加入队列，连接恢复时重试
  • 本地缓存解读历史、每日一牌和牌阵数据
  • 显示清晰的离线指示器，但不阻塞整个应用

6. 12 种语言的国际化 ​

挑战：移动端专属字符串的翻译工作量大。

应对措施：

  • 尽可能复用现有翻译字典（共享类型/常量）
  • 使用 Web 应用中适配 React Native 的 useTrans 模式
  • 先支持英文 + 中文（最大用户群），其他语言逐步添加
  • 使用 AI 翻译作为初稿，然后人工审核

7. 图片资源和包大小 ​

挑战：牌面图片（78 张牌 × 多种皮肤）可能导致包大小急剧膨胀。

应对措施：

  • 不将牌面图片打包进应用。从 CDN（Cloudflare R2）加载，并使用激进缓存策略
  • 使用 expo-image 配合 placeholder 和 cachePolicy: 'disk'
  • 实现渐进加载：立即显示牌背，按需加载牌面图片
  • 服务端压缩图片（使用 Sharp 转为 WebP 格式）
  • 默认牌面皮肤图片在首次启动时缓存（约 5 MB）

8. 应用大小 ​

挑战：未优化的 Expo 应用可能很大（基线 50 MB+）。

应对措施：

  • 启用 Hermes JS 引擎（Expo 55 默认启用）
  • 使用 ProGuard（Android）和 bitcode 裁剪（iOS）
  • Tree-shake 未使用的 Expo 模块
  • 目标总应用大小 < 80 MB

测试策略 ​

单元测试 ​

  • 共享验证 Schema（Zod）
  • API 客户端层
  • 积分计算逻辑
  • 状态管理 Store
bash
npx jest

组件测试 ​

  • React Native Testing Library 用于组件渲染测试
  • 关键页面的快照测试
  • 抽牌和表单流程的交互测试

端到端测试 ​

  • Detox（或 Maestro）用于端到端测试
  • 关键路径：登录 → 解读 → 追问 → 历史记录
  • IAP 流程在真机上测试

支付测试 ​

  • RevenueCat Sandbox（Apple）和 Testing API（Google）
  • Stripe 测试模式用于 Web 支付备选方案
  • 跨平台订阅场景：
    • 在 iOS 上订阅 → 在 Android 上验证
    • 在 Web 上订阅 → 在移动端验证
    • 在一个平台取消 → 验证状态更新

Beta 测试 ​

  • TestFlight（iOS）— 最多 10,000 名外部测试者
  • Google Play 内部测试 → 封闭测试 → 公开测试
  • 提交前内部团队测试 2 周
  • 分阶段发布：10% → 50% → 100%

设备矩阵 ​

最低测试覆盖：

iOSAndroid
iPhone SE（第 3 代）Pixel 7a
iPhone 14Samsung Galaxy A54
iPhone 16 Pro MaxSamsung Galaxy S24
iPad Air（第 5 代）Google Pixel Tablet

应用商店提交 ​

Apple App Store ​

要求：

  • Apple 开发者计划（$99/年）
  • App Store Connect 账号
  • 所有必需设备尺寸的截图（iPhone 6.7"、6.5"、5.5"；iPad 12.9"）
  • App 隐私营养标签
  • App 追踪透明度（ATT）提示（如使用广告分析）
  • 年龄分级：4+（塔罗作为娱乐在大多数国家不受年龄限制）

元数据（准备所有 12 种语言版本）：

  • 应用名称："MysticX - AI Tarot Reader"
  • 副标题："Personalized Tarot Readings"
  • 描述：聚焦 AI 驱动的自我反思、正念和个人成长
  • 关键词：tarot, ai, reading, horoscope, daily, card, spiritual, mindfulness, self-care
  • 分类：生活方式（主分类）、娱乐（副分类）

审核说明：

  • 提供有充足积分的演示账号
  • 说明该应用提供 AI 生成的个人反思洞察
  • 注明所有数字商品购买使用 IAP
  • 附上隐私政策和服务条款的链接

Google Play Store ​

要求：

  • Google Play 开发者账号（$25 一次性费用）
  • Play Console 访问权限
  • 手机和平板截图
  • 数据安全部分

应用商品详情质量：

  • 功能图片（1024x500）
  • 简短描述（最多 80 字符）
  • 完整描述
  • 内容分级问卷
  • 目标受众声明

上线后计划 ​

监控 ​

  • Sentry 或 Expo Error Reporting 用于崩溃追踪
  • RevenueCat Dashboard 用于 IAP 指标（MRR、流失率、试用转化）
  • Mixpanel 用于用户互动指标（DAU、留存率、解读完成率）
  • App Store Connect Analytics 和 Google Play Console 用于安装/卸载指标

OTA 更新 ​

Expo EAS Update 允许推送 JS Bundle 更新无需完整的应用商店审核。可用于：

  • Bug 修复
  • 文案/文字更改
  • 新牌阵数据
  • 功能开关调整

原生变更（新模块、SDK 版本升级）仍需完整构建和商店提交。

迭代计划 ​

  • 每周：监控崩溃率，通过 OTA 修复关键 Bug
  • 双周：分析数据回顾，优化功能待办
  • 每月：应用商店更新，添加新功能
  • 每季度：包含重大新功能的大版本更新

关键指标追踪 ​

指标目标
次日留存> 40%
7 日留存> 20%
30 日留存> 10%
解读完成率> 80%
日均活跃解读数> 每活跃用户 2 次
免费→付费转化率> 5%
试用→订阅转化率> 30%
应用商店评分> 4.5 星
无崩溃率> 99.5%

竞品分析笔记 ​

App Store 塔罗应用（关键观察） ​

  1. Labyrinthos — 简洁极简 UI，注重教育。免费加高级功能 IAP。4.8 星。
  2. Golden Thread Tarot — 与 Labyrinthos 同一开发者。精美牌面插图，日记功能。4.7 星。
  3. Galaxy Tarot — Android 优先，传统外观。广告支持加高级版。4.5 星。
  4. Mystic Mondays — 现代艺术风格，健康品牌定位。订阅模式。4.6 星。
  5. The Pattern — 非塔罗，但类似"个性化洞察"概念。推送通知做得很成功。4.6 星。

用户期望（基于 App Store 评论） ​

  • 精美的牌面和动画 — 视觉体验即产品本身
  • 快速、准确的解读 — 用户缺乏耐心；流式传输在这方面很有帮助
  • 每日互动钩子 — 每日一牌是留存驱动力（大多数竞品都有此功能）
  • 日记/历史 — 用户希望追踪他们的解读记录
  • 不要激进的付费墙 — 让用户先体验价值再要求付费
  • 离线基础功能 — 无网络时也能查看过去的解读
  • 隐私 — 用户分享非常私人的问题。对数据处理要透明。

MysticX 差异化优势 ​

  • AI 驱动的个性化 — 大多数竞品使用静态牌义。MysticX 的 Gemini 集成提供真正独特的、有上下文的解读
  • AI 记忆 — 没有竞品能从过去的解读中学习
  • 互动追问 — 大多数应用是单向的。MysticX 允许与读者对话
  • 多 AI 读者角色 — 独特的个性，而非千篇一律的解读
  • 13 种牌阵 — 大多数竞品只提供 3-5 种
  • 跨平台 — Web、移动端和 Telegram 的无缝体验

预算估算 ​

项目费用频率
Apple 开发者计划$99年付
Google Play 开发者$25一次性
RevenueCat免费（< $2.5K MTR），之后 1%月付
EAS Build（Expo）免费层（30 次构建/月），$99/月进阶月付
Sentry（崩溃报告）免费层（5K 事件），$26/月团队版月付
设计（应用图标、启动页、截图）$500-$2,000一次性
应用商店优化（ASO）$0（自行操作）或 $500-$2,000（代理）一次性

待讨论问题 ​

  1. Monorepo 还是独立仓库？ — 推荐 Monorepo，但需要将现有 Web 应用迁移到 apps/web/。独立仓库起步更简单，但代码共享更困难。

  2. RevenueCat 还是 expo-iap？ — RevenueCat 增加了服务依赖但极大简化了 IAP。expo-iap 更底层。推荐：RevenueCat，适合首个移动应用。

  3. 移动端价格是否应高于 Web？ — 已确定：保持移动端与 Web 价格一致。我们全额承担平台费用，将其视为用户获取成本。申请 Apple/Google 小型企业计划以降低至 15%。

  4. 首发市场？ — 是否在第一天就全球发布，还是先从特定市场开始？推荐：全球发布（我们已支持 12 种语言）。

  5. IAP 免费试用？ — Apple/Google 支持订阅免费试用期。是否在移动端提供免费试用？推荐：是，Gold 提供 7 天试用，Diamond 提供 3 天试用。

  6. 应用名称？ — "MysticX" 简短好记。App Store 名称应该是 "MysticX" 还是 "MysticX - AI Tarot Reader" 以提高可发现性？推荐："MysticX - AI Tarot Reader" 用于 ASO 优化，图标下简称 "MysticX"。

Internal documentation for MysticX team

© 2026 Starai Labs