Document

?????? MBTI AI ?????????

整理日期：2026-05-18

???????????????????????????????????????????????

星座八字塔罗 MBTI AI 分析小程序需求方案

版本：v0.1
日期：2026-05-18
定位：个人使用 / 原型验证 / 自我探索娱乐工具

1. 项目背景

目标是做一个微信小程序，用于整合塔罗、星座、八字、MBTI 等信息，结合服务端 AI API 生成个性化分析结果，并支持用户持续追问和对话。

这个产品不建议定位成“算命”“预测未来”或“命运判断”工具。更稳妥的定位是：

一个结合塔罗牌义、星座、八字排盘、MBTI 倾向的自我观察与娱乐分析助手。

核心思路：

前端负责信息录入、抽牌、固定知识展示、结果展示和对话交互。
后端负责用户身份、资料存储、塔罗/星座/八字/MBTI 数据整合、Prompt 组装、AI API 调用和历史记录。
AI 负责解释和表达，不负责基础排盘、星座计算、抽牌随机逻辑等确定性任务。

2. 产品目标

2.1 MVP 目标

第一版先实现一个自己可用、流程完整的小程序：

用户可以录入出生信息、MBTI、关注问题。
用户可以随机抽取塔罗牌，支持单张和三张牌阵。
用户可以手动选择塔罗牌，用于复盘现实牌面或学习牌义。
前端可以展示每张塔罗牌的固定基础含义，不调用 AI。
用户可以发起 AI 综合分析。
后端把塔罗牌、星座、八字、MBTI、用户问题组合成 Prompt，调用 AI API。
前端展示 AI 返回的结构化分析结果。
用户可以围绕一次分析继续对话追问。
支持查看历史分析和历史对话。

2.2 非目标

第一版暂不做：

塔罗牌图片识别。
用户上传牌面图片。
付费、会员、次数售卖。
社交分享、裂变传播。
复杂星盘图绘制。
复杂 MBTI 完整测试系统。
多用户社区或公开内容流。
正式商业化发布和大规模运营。

3. 用户场景

3.1 综合自我分析

用户输入一个当前关心的问题，比如：

最近工作状态不太稳定，我适合主动换方向吗？

然后选择分析维度：

塔罗
星座
八字
MBTI

小程序抽牌或读取已抽牌结果，后端根据用户资料计算或整理相关信息，最终生成一份综合分析报告。

3.2 塔罗抽牌、自选牌与牌义学习

塔罗模块分为三种使用方式：

随机抽牌：用户选择牌阵，输入问题，点击抽牌。
手动选牌：用户自己选择某张牌和正逆位，用于录入现实中已经抽到的牌。
牌义学习：用户不输入问题，只浏览各张牌的基础信息。

随机抽牌或手动选牌后，系统展示：

抽到的牌
正位 / 逆位
基础关键词
基础牌义
AI 解读按钮

用户点击 AI 解读后，后端将牌义、牌阵位置、用户问题等组合给 AI。用户只查看牌义学习页时，不触发 AI 分析。

3.3 AI 持续对话

用户看完分析后，可以继续问：

这个结果是不是说明我应该换工作？
从 MBTI 角度怎么看我的问题？
塔罗和八字的结论有没有冲突？
给我一个更现实的行动建议。

后端需要保留当前分析上下文，并把必要摘要带入后续 AI 请求。

4. 功能范围

4.1 首页

首页提供主要入口和最近状态。

功能：

显示产品标题和一句简短定位。
显示“开始综合分析”“塔罗抽牌”“AI 对话”“我的资料”入口。
显示最近一次抽牌或最近一次分析摘要。
显示免责声明入口。

效果示意：

┌────────────────────────┐
│  自我探索助手           │
│  塔罗 · 星座 · 八字 · MBTI │
├────────────────────────┤
│  [开始综合分析]          │
│  [塔罗抽牌]              │
│  [继续对话]              │
├────────────────────────┤
│  今日牌面：尚未抽取      │
│  最近报告：2 条          │
└────────────────────────┘

底部 Tab：首页｜抽牌｜分析｜对话｜我的

4.2 我的资料

用于录入 AI 分析所需基础资料。

字段：

字段	是否必填	用途
昵称	否	个性化称呼
性别	否	分析时作为可选参考
出生日期	是	星座、八字计算
出生时间	八字需要	八字时柱、星盘上升等计算
出生地点	星盘建议填写	星盘、时区、地点参考
当前居住地	否	语境参考
MBTI 类型	否	人格倾向参考
关注方向	否	工作、感情、学业、人际、自我状态等

效果示意：

我的资料

┌────────────────────┐
│ 昵称      星河       │
│ 出生日期  1998-03-21 │
│ 出生时间  14:30      │
│ 出生地点  上海       │
│ MBTI      INFJ       │
│ 关注方向  工作/关系   │
└────────────────────┘

[保存资料]

4.3 塔罗模块

塔罗模块不是单一抽牌页，而是一个包含抽牌、自选牌、牌库查询的功能区。

第一版支持：

随机抽牌：单张牌、三张牌阵。
手动选牌：选择牌阵位置、具体牌、正位 / 逆位。
牌义查询：查看 78 张牌基础信息。
固定牌义展示：不调用 AI。
AI 解读：用户明确点击后才调用后端 AI。

牌阵建议：

牌阵	位置	用途
单张牌	当前建议	快速分析
三张牌 A	过去 / 现在 / 建议	状态梳理
三张牌 B	现状 / 阻碍 / 行动	问题分析

塔罗模块入口示意：

塔罗

[抽牌] [牌库]

抽牌模式：
[随机抽取] [手动选牌]

选择牌阵：
[单张] [过去-现在-建议] [现状-阻碍-行动]

你的问题：
最近工作适合主动变化吗？

┌────────────┐
│  愚者       │
│  正位       │
└────────────┘

基础牌义：
新的开始、探索、自由、未知、冒险。

[生成 AI 解读]

手动选牌流程：

塔罗 / 手动选牌

选择牌阵：
[单张] [三张]

第 1 张：当前位置
[选择牌]  愚者
[正位] [逆位]

第 2 张：阻碍
[选择牌]  宝剑八
[正位] [逆位]

[查看基础牌义] [用于 AI 分析]

4.4 牌义知识库

牌义知识库用于学习和查询，不依赖 AI。这个页面要让用户能“自己看牌”，而不是每次都进入分析。

内容：

78 张塔罗牌列表
大阿卡那 / 小阿卡那分类
花色筛选：权杖、圣杯、宝剑、星币
搜索：中文名、英文名、关键词
正位关键词
逆位关键词
感情、事业、自我成长等常见解释
牌面元素说明

牌库列表示意：

牌义知识库

[搜索牌名或关键词]

[全部] [大阿卡那] [权杖] [圣杯] [宝剑] [星币]

┌────────────┐
│ 愚者 The Fool       │
│ 新的开始 / 探索 / 自由 │
└────────────┘
┌────────────┐
│ 女祭司 The High Priestess │
│ 直觉 / 秘密 / 内在智慧     │
└────────────┘

牌详情示意：

愚者 The Fool
大阿卡那 0

[基础] [正位] [逆位] [关系] [工作]

基础信息：
代表新的开始、探索、自由、未知和冒险。

正位关键词：
新的开始、开放、尝试、信任直觉。

逆位关键词：
鲁莽、逃避、准备不足、方向不清。

[加入当前抽牌] [返回牌库]

说明：

固定牌义可以缓存在小程序端，提升打开速度。
后端也保留同一份结构化数据，用于 AI Prompt。
如果后续做版权安全，需要使用自建牌义文本或确认数据源 license。
牌库详情页不展示“命运结论”或个性化分析，只展示基础知识。

4.5 综合分析

综合分析是核心功能。

用户输入：

当前问题
选择分析维度
选择是否使用最近一次抽牌
可选补充信息

分析维度：

塔罗牌面
星座
八字
MBTI

结果结构：

简短总结
当前状态观察
塔罗牌面解读
星座 / 八字 / MBTI 参考
多维度交叉分析
现实建议
可以继续追问的问题

效果示意：

综合分析报告

问题：
最近工作适合主动变化吗？

分析依据：
- 塔罗：愚者 正位
- 星座：白羊座
- 八字：后端排盘摘要
- MBTI：INFJ

一、简短总结
你现在更适合先做小范围探索，而不是立刻做不可逆决定。

二、塔罗观察
愚者正位强调新的开始、试探和开放性……

三、综合建议
可以先用 2-4 周验证一个新方向……

4.6 AI 对话

对话页需要支持上下文。

功能：

新建对话
基于某次分析继续对话
展示用户消息和 AI 回复
支持清空当前会话
支持保存对话历史

上下文策略：

不建议每次把完整历史都传给 AI，成本高且容易超长。
后端保存会话摘要 context_summary。
每轮请求带最近若干条消息 + 会话摘要 + 用户资料摘要 + 当前分析快照。

效果示意：

AI 对话

AI：你可以继续追问刚才的分析。

我：这是不是说明我应该换工作？

AI：不建议直接把它理解成“必须换工作”。
更适合的理解是：你需要为变化做一次低成本验证……

4.7 历史记录

历史记录包括：

抽牌记录
分析报告
对话记录

列表字段：

标题
类型
创建时间
关联问题
使用的分析维度

5. 页面结构

建议小程序页面：

/pages/index/index              首页
/pages/profile/profile          我的资料
/pages/tarot/draw               塔罗抽牌
/pages/tarot/manual             手动选牌
/pages/tarot/library            塔罗牌库
/pages/tarot/card-detail        牌义详情
/pages/analysis/create          创建分析
/pages/analysis/result          分析结果
/pages/chat/chat                AI 对话
/pages/history/history          历史记录
/pages/history/detail           历史详情
/pages/knowledge/index          知识库
/pages/settings/settings        设置与免责声明

底部 Tab：

首页｜抽牌｜分析｜对话｜我的

塔罗 Tab 内部二级导航：

抽牌｜牌库

抽牌页内部模式切换：

随机抽取｜手动选牌

6. 前后端职责划分

6.1 前端职责

微信登录态获取。
后端登录 token 保存与请求头携带。
用户资料录入与展示。
塔罗牌抽取交互。
手动选牌和牌库浏览。
固定知识库展示。
分析结果展示。
对话输入与消息展示。
历史记录查看。
加载态、失败态、空状态处理。
常用静态数据缓存，例如塔罗牌库、牌阵规则、MBTI 类型说明。

6.2 后端职责

微信 openid 换取与用户识别。
登录态签发与校验。
用户资料存储。
塔罗牌数据管理。
抽牌结果生成或校验。
星座计算。
八字排盘或接入排盘库。
MBTI 信息整理。
Prompt 组装。
AI API 调用。
AI 输出格式修正。
历史记录存储。
限流、日志、安全过滤。

6.3 客户端数据存储原则

客户端只保存“展示和体验需要的数据”，服务端保存“权威数据”。不要把 AI API Key、完整 Prompt、服务端内部知识库来源、敏感日志放在客户端。

用户输入的出生日期、出生时间、出生地点、MBTI 等资料，以服务端数据库为准。客户端可以缓存一份 profile.cache 用于表单回显，但不能只存在客户端。八字、星座、星盘、MBTI 测评分数等计算结果也应由服务端生成并保存，避免换设备、清缓存或重新分析时结果不一致。

建议客户端存储：

数据	存储位置	是否权威	说明
`access_token`	`wx.setStorage`	否	后端签发，过期后重新登录
用户资料缓存	`wx.setStorage`	否	用于表单回显，服务端为准
塔罗牌库缓存	`wx.setStorage` 或本地 JSON 包	否	基础牌义可缓存，带版本号
牌阵规则缓存	`wx.setStorage` 或本地 JSON 包	否	用于抽牌页展示
最近一次抽牌	页面状态 + 本地缓存	否	用于快速继续分析
最近一次分析摘要	本地缓存	否	首页展示用
当前聊天草稿	页面状态 / 本地缓存	否	防止用户切页丢输入

不建议客户端存储：

AI API Key。
第三方服务密钥。
服务端完整 Prompt 模板。
完整 AI 请求上下文。
长期保存的敏感出生资料作为唯一数据源。

推荐本地缓存 key：

auth.accessToken
auth.expiresAt
profile.cache
tarot.cards.v1
tarot.spreads.v1
tarot.lastDraw
analysis.lastSummary
chat.draft.<sessionId>
app.knowledgeVersion

客户端启动时的数据同步：

打开小程序
-> 读取本地 token
-> 如果 token 存在且未过期，请求 /api/user/profile
-> 并行检查知识库版本 /api/app/bootstrap
-> 如果版本变化，刷新塔罗牌库和牌阵规则缓存
-> 首页展示最近抽牌和最近报告摘要

6.4 客户端状态分层

建议前端把状态分成三层：

层级	内容	生命周期
页面状态	当前输入、loading、选中的牌、当前 tab	当前页面
全局状态	登录状态、用户资料摘要、知识库版本	小程序运行期间
本地缓存	token、牌库、最近抽牌、草稿	跨会话

用户资料、抽牌、分析、对话最终都以后端返回结果为准。客户端可以先做乐观展示，但需要在接口失败时回滚或提示重试。

6.5 个人资料与计算结果存储模型

个人资料分两层保存：

类型	表	内容	说明
用户原始输入	`user_profiles`	出生日期、出生时间、出生地点、时区、MBTI、关注方向	用户填写什么就保存什么
服务端计算结果	`computed_profiles`	星座、八字排盘、星盘、MBTI 测评分数	根据 `user_profiles` 计算得到

推荐流程：

用户填写出生日期/时间/地点/MBTI
-> 小程序 POST /api/user/profile/save
-> 服务端保存到 user_profiles
-> 服务端触发或延迟执行计算
-> 计算结果写入 computed_profiles
-> 小程序缓存 profile.cache 用于表单回显

数据归属：

出生日期、出生时间、出生地点、时区：保存到 user_profiles。
用户手动填写的 MBTI：保存到 user_profiles.mbti_type。
太阳星座、星盘摘要：保存到 computed_profiles.zodiac_json / computed_profiles.natal_chart_json。
八字排盘结果：保存到 computed_profiles.bazi_json。
MBTI 测评四维度分数：保存到 computed_profiles.mbti_scores_json。
AI 分析时使用的资料快照：保存到 analysis_reports.input_snapshot_json。

为什么报告要保存资料快照：

用户后续可能修改出生信息或 MBTI。
历史报告需要知道当时使用的是哪一版资料。
方便排查“为什么这次分析和上次不同”。

资料删除策略：

用户删除资料时，优先清空或软删除 user_profiles 和 computed_profiles。
历史报告如果保留，应明确是否继续保留 input_snapshot_json。
更稳妥的个人版做法是：用户删除资料时，同步删除或匿名化相关分析报告和聊天记录。

7. 系统架构

flowchart TD
  A["微信小程序前端"] --> B["后端 API 服务"]
  B --> C["用户资料数据库"]
  B --> D["结构化知识库"]
  B --> E["八字/星盘/MBTI 计算模块"]
  B --> F["知识检索模块"]
  B --> G["Prompt 模板管理"]
  D --> F
  E --> H["分析上下文组装器"]
  F --> H
  G --> H
  H --> I["AI API 服务"]
  I --> J["AI 原始输出"]
  J --> K["输出清洗与结构化"]
  K --> B
  B --> A

推荐技术选型：

层级	推荐
小程序前端	原生微信小程序或 Taro / uni-app
后端	Node.js NestJS / Express，或 Python FastAPI
数据库	SQLite / PostgreSQL / MySQL
缓存	第一版可不接，后续用 Redis
部署	云服务器 + HTTPS 域名
AI 调用	后端环境变量保存 API Key

个人原型建议：

如果你熟悉 JavaScript：前端原生小程序 + Node.js 后端。
如果你更想快速写 AI 和排盘逻辑：前端原生小程序 + Python FastAPI 后端。

7.1 知识库与计算层方案

参考本地资料《命理与人格分析数据资源整理》，本项目不应把所有资料直接塞进 Prompt。更稳的方式是把“固定知识”“确定性计算”“AI 表达”拆开。

知识层分为四类：

类型	用途	第一版处理
结构化知识库	塔罗牌义、牌阵规则、星座关键词、MBTI 类型说明	JSON / SQLite / 数据库表
确定性计算模块	星座、八字排盘、星盘、MBTI 测评分数	程序计算，AI 不直接计算
RAG 检索库	从较长解释文本、规则资料、风格样例中检索相关片段	第二阶段接入，第一版预留表结构
Prompt 模板库	控制不同分析模式的输入结构和输出格式	后端维护版本号

第一版建议优先做结构化知识库，不急着做向量库。原因是 MVP 的主要输入非常明确：抽到哪张牌、是什么牌阵、用户是什么星座/八字/MBTI。大部分检索可以通过 card_id、spread_id、mbti_type、zodiac_sign 这类字段精确命中。

RAG 更适合第二阶段用于：

更长的塔罗牌义解释。
八字规则解释框架。
星盘相位解释。
MBTI 类型与行为模式说明。
多领域分析案例和表达风格参考。

数据使用优先级：

程序计算结果优先，特别是八字、星盘、MBTI 测评分数。
结构化知识库优先，尤其是塔罗牌义、牌阵位置、星座关键词。
RAG 检索片段作为补充解释，不作为唯一依据。
AI 只负责综合表达、解释和对话，不负责凭空生成基础事实。

推荐资源映射：

模块	可参考资源	在本项目中的用法
塔罗	Blacik/tarot-card-meanings-78	转成 78 张牌 JSON / 数据表，作为牌义与 Prompt 输入
综合命理语料	divination-combined	清洗后做风格参考或 RAG 候选，不直接作为权威知识
八字	bazi 开源排盘库、bazi-mingli 规则资料	排盘走算法库，规则资料拆成解释模板
星盘	Kerykeion	用出生时间地点生成结构化星盘数据
精确星历	Swiss Ephemeris / pyswisseph	后续需要更高精度时再接入，并确认许可证
MBTI	OpenJung / OEJTS	做开放式测评题和四维度分数
MBTI 评估	MBTIBench	作为偏差和评估方式参考

7.2 服务端模块设计

服务端建议采用分层结构，不要把 AI 调用、数据库、业务逻辑都写在接口处理函数里。

推荐结构：

controllers / routes
  只处理 HTTP 入参、鉴权、返回格式

services
  处理业务流程，例如抽牌、生成分析、继续对话

repositories
  处理数据库读写

domain modules
  tarot、profile、analysis、chat、knowledge、compute

adapters
  微信登录、AI API、排盘库、向量库等外部依赖

服务端核心模块：

模块	职责
`AuthModule`	微信登录、openid 换取、token 签发、鉴权
`UserModule`	用户资料保存、资料读取、资料删除
`TarotModule`	牌库、牌阵、随机抽牌、手动选牌校验
`KnowledgeModule`	结构化知识查询、知识库版本、RAG 检索预留
`ComputeModule`	星座、八字、星盘、MBTI 分数计算
`AnalysisModule`	分析输入组装、Prompt 模板选择、AI 调用、报告保存
`ChatModule`	会话创建、消息保存、上下文摘要、连续追问
`HistoryModule`	抽牌、分析、对话历史聚合查询
`SafetyModule`	输入长度限制、内容边界、限流、敏感输出过滤
`AiProviderAdapter`	封装具体 AI API，避免业务层直接依赖供应商 SDK

服务端目录示意：

server/
  src/
    app.ts
    config/
      env.ts
    modules/
      auth/
      users/
      tarot/
      knowledge/
      compute/
      analysis/
      chat/
      history/
      safety/
    adapters/
      wechat/
      ai-provider/
      bazi-provider/
      astrology-provider/
    db/
      schema/
      migrations/
      repositories/

7.3 关键服务端流程

微信登录：

客户端 wx.login 获取 code
-> POST /api/auth/wechat-login
-> 后端用 code 换 openid
-> 查找或创建 users
-> 签发 accessToken
-> 客户端保存 token

随机抽牌：

客户端选择牌阵和问题
-> POST /api/tarot/draw
-> 后端校验牌阵
-> 后端随机抽牌和正逆位
-> 保存 tarot_draws
-> 返回 drawId 和牌面基础信息

手动选牌：

客户端选择牌阵、牌、正逆位
-> POST /api/tarot/manual
-> 后端校验牌是否存在、牌阵位置是否匹配
-> 保存 tarot_draws，source=manual
-> 返回 drawId 和牌面基础信息

综合分析：

客户端提交 question、analysisTypes、drawId
-> 后端读取用户资料、抽牌、知识片段
-> 后端计算星座/八字/星盘/MBTI
-> 后端选择 Prompt 模板
-> 后端调用 AI API
-> 后端清洗输出并保存 analysis_reports
-> 返回结构化报告

对话追问：

客户端提交 sessionId、analysisId、message
-> 后端读取会话摘要、最近消息、分析快照
-> 后端组装 followup_chat Prompt
-> 调用 AI API
-> 保存用户消息和 AI 回复
-> 必要时更新 context_summary
-> 返回 AI 回复

7.4 服务端数据归属

数据	权威归属	客户端是否可缓存	说明
用户 openid	服务端	否	不直接暴露 openid 给前端业务使用
用户资料	服务端	是	客户端仅缓存表单回显
塔罗牌库	服务端 / 静态资源	是	带版本号同步
牌阵规则	服务端 / 静态资源	是	带版本号同步
抽牌记录	服务端	是	最近一次可缓存
AI 分析报告	服务端	可缓存摘要	完整报告以后端为准
聊天消息	服务端	可缓存当前页	历史以后端为准
Prompt 模板	服务端	否	不下发给客户端
AI 调用日志	服务端	否	只用于排查和成本统计

8. AI 数据流

客户端与服务端的总体关系：

flowchart LR
  A["页面层"] --> B["客户端状态管理"]
  B --> C["本地缓存 wxStorage"]
  B --> D["统一请求封装"]
  D --> E["服务端 API"]
  E --> F["业务服务"]
  F --> G["数据库"]
  F --> H["知识库/计算模块"]
  F --> I["AI API"]

交互原则：

页面不直接调用 AI，不直接访问第三方服务。
页面只调用自己的后端 API。
后端返回结构化数据，前端按固定组件展示。
客户端缓存只提升体验，不能作为最终数据来源。
任何会产生费用或隐私风险的操作都走后端校验。

综合分析流程：

sequenceDiagram
  participant U as 用户
  participant M as 小程序
  participant S as 后端
  participant DB as 数据库
  participant KB as 知识库
  participant CALC as 计算模块
  participant AI as AI API

  U->>M: 输入问题并选择分析维度
  M->>S: POST /api/analysis/generate
  S->>DB: 读取用户资料和最近抽牌
  S->>CALC: 计算星座/八字/星盘/MBTI分数
  CALC-->>S: 返回结构化计算结果
  S->>KB: 按牌面/牌阵/类型检索知识片段
  KB-->>S: 返回结构化知识和参考片段
  S->>S: 组装分析上下文和Prompt
  S->>AI: 调用AI API
  AI-->>S: 返回分析文本
  S->>S: 清洗并结构化输出
  S->>DB: 保存分析报告
  S-->>M: 返回报告
  M-->>U: 展示分析结果

9. Prompt 组装方案

后端不要直接把用户输入原样转给 AI。建议用模板组合。

输入来源：

来源	内容
用户问题	当前想分析的问题
用户资料	出生日期、时间、地点、MBTI、关注方向
塔罗结果	牌名、正逆位、牌阵位置、固定牌义
星座结果	太阳星座，后续可扩展月亮/上升
八字结果	年柱、月柱、日柱、时柱、五行摘要等
MBTI 结果	用户自填类型，后续可扩展四维度测评分数
知识库检索	精确命中的牌义、牌阵规则、类型说明、规则片段
历史上下文	最近分析摘要或会话摘要
安全边界	娱乐、自我反思、不做绝对预测

Prompt 模板示意：

你是一个自我探索分析助手。
请基于塔罗、星座、八字、MBTI 信息进行娱乐性、自我反思式分析。
你必须优先使用后端提供的结构化计算结果和知识库片段，不要自行编造八字、星盘、牌义或 MBTI 基础定义。

边界要求：
1. 不要做绝对预测。
2. 不要宣称结果必然发生。
3. 不要替用户做重大现实决定。
4. 不提供医疗、法律、投资等专业结论。
5. 输出要具体、温和、可执行。

用户问题：
{{question}}

用户资料：
{{profile_summary}}

塔罗信息：
{{tarot_cards}}

星座信息：
{{zodiac_summary}}

八字排盘摘要：
{{bazi_summary}}

MBTI 信息：
{{mbti_summary}}

知识库检索结果：
{{retrieved_knowledge}}

历史上下文：
{{context_summary}}

请按以下结构输出：
1. 简短总结
2. 当前状态观察
3. 塔罗解读
4. 星座/八字/MBTI 交叉分析
5. 现实建议
6. 可以继续追问的问题

10. 接口设计草案

10.0 通用接口约定

接口基础约定：

Base URL: https://api.example.com
Content-Type: application/json
Authorization: Bearer <accessToken>

统一响应格式：

{
  "success": true,
  "data": {},
  "error": null,
  "requestId": "req_20260518_001"
}

错误响应格式：

{
  "success": false,
  "data": null,
  "error": {
    "code": "AUTH_EXPIRED",
    "message": "登录已过期，请重新登录"
  },
  "requestId": "req_20260518_002"
}

常见错误码：

错误码	含义	客户端处理
`AUTH_REQUIRED`	未登录	调用登录流程
`AUTH_EXPIRED`	token 过期	重新 `wx.login`
`VALIDATION_ERROR`	入参错误	标记表单错误
`RATE_LIMITED`	请求太频繁	提示稍后再试
`AI_PROVIDER_ERROR`	AI 服务失败	显示重试按钮
`CONTENT_REJECTED`	输入或输出不符合边界	提示调整问题
`NOT_FOUND`	资源不存在	返回列表页或提示刷新

分页格式：

{
  "items": [],
  "page": 1,
  "pageSize": 20,
  "hasMore": true
}

10.1 登录与启动配置

POST /api/auth/wechat-login
POST /api/auth/logout
GET  /api/app/bootstrap

登录请求：

{
  "code": "wx_login_code"
}

登录响应：

{
  "accessToken": "server_signed_token",
  "expiresAt": "2026-05-19T00:00:00+08:00",
  "user": {
    "id": "user_001",
    "hasProfile": true
  }
}

GET /api/app/bootstrap 用于客户端启动时获取版本和基础配置。

响应：

{
  "knowledgeVersion": "2026-05-18.1",
  "tarotCardsVersion": "tarot_v1",
  "tarotSpreadsVersion": "spread_v1",
  "featureFlags": {
    "manualTarot": true,
    "baziEnabled": true,
    "natalChartEnabled": false,
    "mbtiTestEnabled": false
  },
  "limits": {
    "maxQuestionLength": 500,
    "maxChatMessageLength": 500
  }
}

10.2 用户资料

POST /api/user/profile/save
GET  /api/user/profile
DELETE /api/user/profile

保存资料请求：

{
  "nickname": "星河",
  "gender": "unknown",
  "birthDate": "1998-03-21",
  "birthTime": "14:30",
  "birthPlace": "上海",
  "timezone": "Asia/Shanghai",
  "mbtiType": "INFJ",
  "focusAreas": ["career", "relationship"]
}

保存资料响应：

{
  "profile": {
    "id": "profile_001",
    "nickname": "星河",
    "birthDate": "1998-03-21",
    "birthTime": "14:30",
    "birthPlace": "上海",
    "timezone": "Asia/Shanghai",
    "mbtiType": "INFJ",
    "focusAreas": ["career", "relationship"]
  },
  "computedProfile": {
    "id": "computed_001",
    "zodiac": {
      "sunSign": "Aries"
    },
    "bazi": {
      "yearPillar": "...",
      "monthPillar": "...",
      "dayPillar": "...",
      "hourPillar": "..."
    },
    "mbti": {
      "type": "INFJ",
      "scores": null
    }
  }
}

说明：

客户端保存资料时只提交用户原始输入。
客户端不提交自己计算的八字、星座或星盘作为权威结果。
服务端保存原始资料后，立即计算或在生成分析前懒计算 computed_profiles。
客户端可把响应里的 profile 缓存到 profile.cache，用于表单回显。

10.3 塔罗

GET  /api/tarot/cards
GET  /api/tarot/cards/:id
POST /api/tarot/draw
POST /api/tarot/manual
GET  /api/tarot/draws

抽牌请求：

{
  "spread": "single",
  "question": "最近工作适合主动变化吗？",
  "allowReversed": true
}

抽牌响应：

{
  "drawId": "draw_001",
  "spread": "single",
  "cards": [
    {
      "cardId": "major_00",
      "nameCn": "愚者",
      "nameEn": "The Fool",
      "orientation": "upright",
      "position": "当前建议",
      "keywords": ["新的开始", "探索", "自由", "未知"]
    }
  ]
}

手动选牌请求：

{
  "spread": "single",
  "question": "我想复盘刚才自己抽到的牌",
  "cards": [
    {
      "cardId": "major_00",
      "orientation": "upright",
      "position": "当前建议"
    }
  ]
}

手动选牌响应与随机抽牌响应一致，也生成 drawId。区别是 source 标记为 manual，便于历史记录区分。

{
  "drawId": "draw_002",
  "source": "manual",
  "spread": "single",
  "cards": [
    {
      "cardId": "major_00",
      "nameCn": "愚者",
      "nameEn": "The Fool",
      "orientation": "upright",
      "position": "当前建议",
      "keywords": ["新的开始", "探索", "自由", "未知"]
    }
  ]
}

10.4 综合分析

POST /api/analysis/generate
GET  /api/analysis/list
GET  /api/analysis/detail/:id

请求：

{
  "question": "最近工作适合主动变化吗？",
  "analysisTypes": ["tarot", "zodiac", "bazi", "mbti"],
  "drawId": "draw_001",
  "extraContext": "最近对当前岗位有些疲惫，但还没有明确的新方向。"
}

说明：

分析请求只传 drawId、问题和分析维度。
出生日期、八字、星座、MBTI 等资料由服务端根据当前登录用户读取。
服务端会把本次分析使用的 user_profiles 和 computed_profiles 写入 input_snapshot_json。
如果用户资料不完整，服务端返回可用维度和缺失字段，客户端提示用户补充。

响应：

{
  "analysisId": "analysis_001",
  "title": "关于工作变化的综合分析",
  "summary": "你现在更适合先做小范围探索，而不是立刻做不可逆决定。",
  "sections": [
    {
      "title": "简短总结",
      "content": "当前状态更偏向试探新方向，而不是立即做大幅改变。"
    },
    {
      "title": "塔罗解读",
      "content": "愚者正位代表新的开始、探索和不确定性。"
    }
  ],
  "suggestedQuestions": [
    "我应该怎么判断变化的时机？",
    "这张牌和我的 MBTI 有什么关系？"
  ]
}

10.5 对话

POST /api/chat/session/create
POST /api/chat/message
GET  /api/chat/sessions
GET  /api/chat/session/:id

发送消息：

{
  "sessionId": "chat_001",
  "analysisId": "analysis_001",
  "message": "这是不是说明我应该换工作？"
}

响应：

{
  "messageId": "msg_002",
  "role": "assistant",
  "content": "不建议直接理解成必须换工作。更合理的行动是先做低成本验证。",
  "contextSummaryUpdated": true
}

10.6 知识库与计算接口

这些接口主要供前端知识展示和后端内部调用。

GET  /api/knowledge/tarot/cards
GET  /api/knowledge/tarot/cards/:id
GET  /api/knowledge/mbti/types/:type
POST /api/compute/profile

POST /api/compute/profile 可以在用户保存资料后触发，也可以在生成分析前懒计算。

请求：

{
  "profileId": "profile_001",
  "computeTypes": ["zodiac", "bazi", "natal_chart", "mbti"]
}

响应：

{
  "computedProfileId": "computed_001",
  "zodiac": {
    "sunSign": "Aries"
  },
  "bazi": {
    "yearPillar": "...",
    "monthPillar": "...",
    "dayPillar": "...",
    "hourPillar": "...",
    "fiveElements": {}
  },
  "natalChart": null,
  "mbti": {
    "type": "INFJ",
    "scores": null
  }
}

10.7 客户端请求封装

小程序端建议封装统一 request 方法，所有页面都通过它访问后端。

职责：

自动拼接 baseUrl。
自动带上 Authorization。
统一处理 AUTH_EXPIRED。
统一处理 loading 和错误提示。
只把 data 返回给页面。

伪代码：

async function apiRequest({ url, method = 'GET', data }) {
  const token = wx.getStorageSync('auth.accessToken')

  const res = await wx.request({
    url: `${BASE_URL}${url}`,
    method,
    data,
    header: {
      'Content-Type': 'application/json',
      Authorization: token ? `Bearer ${token}` : ''
    }
  })

  if (!res.data.success) {
    if (res.data.error?.code === 'AUTH_EXPIRED') {
      await relogin()
    }
    throw res.data.error
  }

  return res.data.data
}

页面调用示例：

const draw = await apiRequest({
  url: '/api/tarot/draw',
  method: 'POST',
  data: {
    spread: 'single',
    question,
    allowReversed: true
  }
})

11. 数据库设计草案

users
- id
- openid
- created_at
- updated_at

login_sessions
- id
- user_id
- token_hash
- expires_at
- revoked_at
- created_at

user_profiles
- id
- user_id
- nickname
- gender
- birth_date
- birth_time
- birth_place
- timezone
- mbti_type
- focus_areas_json
- privacy_consent_at
- deleted_at
- created_at
- updated_at

tarot_cards
- id
- name_cn
- name_en
- arcana
- suit
- number
- associations_json
- upright_keywords_json
- reversed_keywords_json
- upright_meaning
- reversed_meaning
- love_meaning
- career_meaning
- yes_no_meaning
- self_growth_meaning
- created_at
- updated_at

tarot_spreads
- id
- name
- description
- positions_json
- prompt_rule
- enabled
- created_at
- updated_at

knowledge_sources
- id
- name
- type
- source_url
- local_path
- license
- quality_status
- notes
- created_at
- updated_at

knowledge_items
- id
- source_id
- domain
- ref_type
- ref_id
- title
- content
- tags_json
- embedding_id
- enabled
- created_at
- updated_at

computed_profiles
- id
- user_id
- profile_id
- zodiac_json
- bazi_json
- natal_chart_json
- mbti_scores_json
- source_profile_hash
- compute_version
- computed_at

prompt_templates
- id
- scene
- version
- system_prompt
- user_prompt_template
- output_schema_json
- enabled
- created_at
- updated_at

tarot_draws
- id
- user_id
- source
- spread
- question
- cards_json
- created_at

analysis_reports
- id
- user_id
- title
- question
- analysis_types_json
- input_snapshot_json
- result_json
- result_markdown
- prompt_template_id
- computed_profile_id
- created_at

chat_sessions
- id
- user_id
- analysis_id
- title
- context_summary
- created_at
- updated_at

chat_messages
- id
- session_id
- role
- content
- token_usage_json
- created_at

api_request_logs
- id
- user_id
- request_id
- method
- path
- status_code
- error_code
- latency_ms
- created_at

ai_call_logs
- id
- user_id
- scene
- provider
- model
- prompt_tokens
- completion_tokens
- cost_estimate
- status
- error_message
- created_at

12. 固定知识、RAG 与计算模块

这一层是产品质量的关键。AI 不能直接替代资料库和计算逻辑，尤其是八字、星盘、MBTI 测评这类结构化结果。

12.1 塔罗知识库

第一版需要一份结构化 78 张牌数据，建议参考本地资料中提到的 Blacik/tarot-card-meanings-78，但使用前需要确认许可证。也可以先手工整理一版自用中文牌义。

建议字段：

中文名
英文名
分类：大阿卡那 / 小阿卡那
花色：权杖 / 圣杯 / 宝剑 / 星币
编号
正位关键词
逆位关键词
正位解释
逆位解释
感情解释
工作解释
自我成长解释
yes/no 倾向
元素、行星、星座等关联信息

处理原则：

保留结构化字段，不要把所有牌义混成一个长文本。
抽牌时通过 card_id 精确读取牌义。
解读时要区分“牌本身含义”和“牌阵位置含义”。
三张牌阵需要额外维护每个位置的解释规则。

示例结构：

{
  "cardId": "major_00",
  "nameCn": "愚者",
  "nameEn": "The Fool",
  "arcana": "major",
  "uprightKeywords": ["新的开始", "自由", "探索"],
  "reversedKeywords": ["鲁莽", "逃避", "准备不足"],
  "associations": {
    "element": "air",
    "planet": "uranus"
  }
}

12.2 牌阵规则库

牌阵不只是抽几张牌，还要定义每个位置的语义。

建议第一版支持：

牌阵	位置	Prompt 规则
单张牌	当前建议	聚焦当前状态和下一步行动
过去-现在-建议	过去 / 现在 / 建议	不做宿命判断，只解释状态变化
现状-阻碍-行动	现状 / 阻碍 / 行动	输出具体、低风险、可执行建议

后端组 Prompt 时，应该把牌阵规则和牌义分开：

{
  "spread": {
    "name": "现状-阻碍-行动",
    "positions": ["现状", "阻碍", "行动"]
  },
  "cards": [
    {
      "position": "阻碍",
      "card": "宝剑八",
      "orientation": "upright",
      "meaning": "限制感、困住、视角受限"
    }
  ]
}

12.3 星座与星盘

MVP 可先做太阳星座：

根据出生日期计算太阳星座。
提供基础性格关键词。
给 AI 的输入应是结构化摘要，而不是“每日运势”文本。

第二阶段可接入星盘：

推荐优先考虑 Kerykeion 生成本命盘数据。
输入需要出生日期、出生时间、出生地点、时区。
输出给 AI 的结构化字段建议包括太阳、月亮、上升、行星落座、宫位、主要相位。

如果后续需要更精确星历，可评估 Swiss Ephemeris / pyswisseph，但商业使用前要单独确认许可证。

星盘输入示例：

{
  "birth": {
    "datetime": "1995-08-21 14:30:00",
    "timezone": "Asia/Shanghai",
    "location": "Shanghai, China"
  },
  "natalChart": {
    "sun": {"sign": "Leo", "house": 9},
    "moon": {"sign": "Pisces", "house": 4},
    "ascendant": {"sign": "Sagittarius"},
    "aspects": []
  }
}

12.4 八字排盘与规则库

八字必须走确定性排盘，不建议让 AI 直接根据出生时间推算。

第一版至少输出：

年柱
月柱
日柱
时柱
日主
五行数量摘要
十神基础摘要，可选

第二阶段再扩展：

日主强弱
用神参考
大运
流年
节气切换
真太阳时处理

后端可参考本地资料中提到的 bazi 开源项目集合，选择一个稳定排盘库；bazi-mingli 更适合作为分析流程和解释框架参考，不建议直接替代排盘算法。

八字输入给 AI 的结构建议：

{
  "birth": {
    "datetime": "1995-08-21 14:30:00",
    "timezone": "Asia/Shanghai",
    "location": "Shanghai, China"
  },
  "chart": {
    "yearPillar": "...",
    "monthPillar": "...",
    "dayPillar": "...",
    "hourPillar": "..."
  },
  "derived": {
    "dayMaster": "...",
    "tenGods": [],
    "fiveElements": {},
    "dayMasterStrength": "unknown"
  }
}

12.5 MBTI 与人格分析

MVP 支持用户手动填写 MBTI 类型。

第二阶段建议做开放式测评，而不是直接使用官方 MBTI 版权体系：

可参考 OpenJung / OEJTS 的开放式 Jung / MBTI-like 测评框架。
保存四个维度分数，而不仅是 INTJ 这类类型标签。
用户文本样本只能作为弱参考，不要只靠几句话推断人格。

后端给 AI 的 MBTI 输入建议：

{
  "questionnaire": {
    "source": "manual_or_openjung",
    "scores": {
      "E_I": 0,
      "S_N": 0,
      "T_F": 0,
      "J_P": 0
    },
    "type": "INFJ"
  },
  "analysisGoal": "self-reflection"
}

注意：

MBTI 更适合表达偏好倾向，不适合做确定人格结论。
Kaggle MBTI 一类文本数据有自报标签和社区话题偏差，最多作为实验或评估参考。
MBTIBench 更适合作为评估偏差和标注质量的参考。

12.6 RAG 检索策略

第一版可以不接向量数据库，但需要预留结构。

建议分阶段：

阶段	策略	说明
MVP	精确字段检索	按牌、牌阵、星座、MBTI 类型直接查结构化数据
阶段 2	关键词检索	从规则库中按领域和标签查片段
阶段 3	向量检索	对长文本知识、案例、解释风格做语义检索

知识片段入库前需要做：

确认来源和许可证。
去重。
抽样检查质量。
标注领域：tarot、bazi、astrology、mbti。
标注用途：meaning、spread_rule、calculation_rule、style_sample。

AI 请求中，检索片段应以“参考资料”的形式出现，并要求 AI 不要超出资料做事实判断。

12.7 Prompt 模板版本管理

建议后端维护多套 Prompt 模板：

场景	模板
塔罗单独解读	`tarot_single_reading_v1`
多牌阵解读	`tarot_spread_reading_v1`
综合分析	`integrated_analysis_v1`
对话追问	`followup_chat_v1`
MBTI 分析	`mbti_reflection_v1`

每次生成报告时保存：

使用的模板名。
模板版本。
输入快照。
检索到的知识片段 ID。
AI 输出结果。

这样后续如果 Prompt 改版，可以追踪旧报告是按哪套逻辑生成的。

13. 安全、隐私与限制

13.1 API Key

AI API Key 只能放后端环境变量。
小程序前端不能出现任何 AI API Key。

13.2 限流

个人使用也建议做基础限流：

每个 openid 每日 AI 分析次数限制。
每个 openid 每分钟请求次数限制。
单次用户输入长度限制。

13.3 隐私

会收集出生日期、出生时间、出生地点等敏感倾向信息，需要在隐私说明中明确：

收集哪些信息。
用于什么目的。
是否保存。
如何删除。
是否发送给第三方 AI 服务。

13.4 内容边界

AI 回复应避免：

绝对预测。
恐吓式表达。
医疗诊断。
法律建议。
投资建议。
诱导付费。
宣称灵验或保证结果。

建议固定免责声明：

本工具仅用于娱乐、自我观察与灵感记录，不作为现实决策依据。
涉及健康、法律、财务、职业等重要事项，请咨询专业人士并结合现实情况判断。

14. 视觉与交互风格

建议视觉方向：

深色背景。
金色、月白、浅紫作为点缀。
卡片式内容承载。
分析报告要分段清晰，避免整屏大段文字。
对话页保持简洁，优先可读性。

页面风格示意：

背景：#101018 / #151322
主色：#D7B56D 金色
辅助：#B9A7FF 浅紫
文字：#F5F1E8 / #A9A4B8
卡片：#1D1A2B
边框：rgba(215, 181, 109, 0.25)

交互状态：

抽牌时：洗牌动画或翻牌动画。
AI 分析时：显示“正在整理牌面与资料”。
AI 失败时：允许重试。
资料不完整时：提示缺少哪些信息，但允许只用部分维度分析。

15. 开发阶段规划

阶段 1：MVP 可用版

目标：完整跑通个人使用流程。

功能：

小程序基础框架。
微信登录。
用户资料录入。
塔罗牌库。
牌阵规则库。
太阳星座计算。
八字基础排盘。
单张 / 三张抽牌。
手动选牌。
牌义详情页。
综合分析接口。
AI 对话接口。
历史记录。
基础免责声明。

阶段 2：体验增强

功能：

每日抽牌。
报告收藏。
MBTI 简易测试。
更多牌阵。
更好的对话上下文摘要。
分析报告导出为长图。

阶段 3：知识库增强

功能：

更完整塔罗知识库。
八字规则库。
星盘计算。
知识来源和许可证管理。
知识片段质量标注。
RAG 检索增强。
Prompt 模板版本管理。

阶段 4：发布评估

如果要正式上架，需要补充：

小程序类目评估。
域名备案和 HTTPS。
隐私协议。
用户协议。
AI 生成内容标识。
内容安全审核。
第三方 AI 服务合规材料。

16. 推荐 MVP 任务拆分

按开发顺序：

确认技术栈：原生小程序 + 后端框架。
建立后端基础服务、数据库和配置管理。
做微信登录、token 鉴权和客户端统一请求封装。
做 /api/app/bootstrap，下发知识库版本、功能开关和限制配置。
做用户资料接口和客户端资料缓存。
准备 78 张塔罗牌结构化数据。
准备牌阵规则数据。
做客户端牌库缓存、列表、筛选、搜索和牌义详情页。
接入太阳星座计算和八字基础排盘。
做随机抽牌接口和抽牌页面。
做手动选牌接口和手动选牌页面。
做综合分析 Prompt 模板。
接入 AI API。
做分析结果页面。
做对话接口、上下文摘要和对话页面。
做历史记录聚合接口和页面。
增加限流、错误处理、请求日志、AI 调用日志和免责声明。
内部体验版测试。

17. 关键风险

风险	影响	建议
小程序审核风险	正式发布可能受限	个人版先体验，不强调预测和算命
AI API Key 泄露	成本和安全问题	必须后端转发
AI 胡编八字/星盘	分析基础错误	后端程序计算，AI 只解释
知识源许可证不清	后续发布或商业化受限	每个数据源记录 license，商用前单独确认
命理语料质量参差	分析内容混乱或误导	入库前抽样、去重、标注质量，不把综合语料当权威
用户隐私	出生信息较敏感	明确隐私说明，支持删除
AI 输出不可控	可能出现绝对化建议	Prompt 加边界，后端做基础过滤
成本失控	对话频繁调用 AI	限流、摘要、缓存、次数控制

18. 当前推荐结论

第一版建议采用：

原生微信小程序前端
+ Python FastAPI 或 Node.js 后端
+ 数据库存用户资料、抽牌、分析、对话
+ 后端维护塔罗牌义和排盘/计算结果
+ 后端组合 Prompt 调用 AI
+ 前端展示固定知识和 AI 结果

第一版产品重点不是“算得多全”，而是先把核心闭环做顺：

录入资料 -> 抽牌 -> 提问 -> 后端组合信息 -> AI 返回分析 -> 继续对话 -> 保存历史

只要这条链路稳定，后续再扩展星盘、完整八字规则库、MBTI 测试、更多牌阵和知识库。

19. 本地参考资料

本版优化参考了以下本地资料：

命理与人格分析数据资源整理.md：数据集、算法库、RAG 知识库、MBTI 评估和最小可行资源组合。
tarot-miniprogram-notes.md：塔罗小程序定位、体验版范围、后端转发、安全建议和上架风险。