astrology-backend-integration

本技能介绍如何实现吠陀占星后端，将占星 API 与 AI/LLM 系统集成，用于预测和咨询。内容涵盖占星应用中的领域专属模式、数据结构和最佳实践。

何时使用本技能

在需要以下功能时使用本技能：

• 构建吠陀占星咨询平台
• 集成占星 API（AstrologyAPI.com、Prokerala 等）
• 生成并存储 kundli（出生星盘）
• 实现基于 dasha 的预测
• 检测 dosha（Manglik、Pitra 等）
• 提供宝石／rudraksha 建议
• 创建 AI 占星顾问
• 支持家庭／成员星盘管理
• 构建合盘／匹配系统

前置条件

使用本技能前，你应当：

• 已完成 ai-integrated-api-backend 技能（或了解外部 API 与 AI 集成）
• 对吠陀占星概念有基本了解
• 拥有占星 API 提供商的访问权限

占星领域基础知识

核心概念

Kundli（出生星盘）

• 个人的完整占星档案
• 需要：出生日期、时间、地点（经纬度）
• 时区：对准确性至关重要（印度默认 IST = 5.5）
• 组成部分：星盘、行星、dasha、dosha、补救措施

星盘（分盘）

• D1（Rashi Chart）：主要出生星盘，包含 12 宫
• D9（Navamsa）：婚姻与灵性星盘
• 其他分盘（D10、D60 等）用于特定生活领域

宫位（Bhava）

• 代表人生领域的 12 个宫位
• 重要对应关系：
  • 第 1 宫：自我、健康、性格
  • 第 2 宫：财富、家庭、言语
  • 第 4 宫：母亲、房产、幸福
  • 第 5 宫：子女、教育、创造力
  • 第 7 宫：婚姻、合作关系
  • 第 10 宫：事业、声誉、父亲
  • 第 11 宫：收益、朋友、志向
  • 第 12 宫：损失、灵性、异国

行星（Grahas）

• 吠陀占星中的 9 颗行星：
  • 太阳（Surya）：权威、自我、自尊
  • 月亮（Chandra）：思维、情绪、母亲
  • 火星（Mangal）：精力、勇气、冲突
  • 水星（Budha）：沟通、智力
  • 木星（Guru）：智慧、扩张、好运
  • 金星（Shukra）：爱情、关系、奢华
  • 土星（Shani）：纪律、业力、延迟
  • Rahu：欲望、痴迷、异国
  • Ketu：超脱、灵性、前世

星座守护星（黄道守护星）

• 每个黄道星座都由一颗行星守护：
  • 白羊座 → 火星
  • 金牛座 → 金星
  • 双子座 → 水星
  • 巨蟹座 → 月亮
  • 狮子座 → 太阳
  • 处女座 → 水星
  • 天秤座 → 金星
  • 天蝎座 → 火星
  • 射手座 → 木星
  • 摩羯座 → 土星
  • 水瓶座 → 土星
  • 双鱼座 → 木星

Dasha（行星周期）

• Vimshottari Dasha：120 年周期
• 结构：主运（Mahadasha）→ 次运（Antardasha）→ 小运（Pratyantar）
• 每颗行星各自掌管特定年数
• 对预测时间至关重要：“X 何时会发生？”

Dosha（凶相）

• Manglik Dosha：火星位于特定宫位（1、2、4、7、8、12）
  • 影响婚姻匹配
  • 以百分比衡量（0-100%）
  • 存在化解条件（例如，双方都是 Manglik）
• Pitra Dosha：祖先业债
  • 太阳／月亮受 Rahu／Ketu 影响
  • 补救措施：Puja、布施

补救措施

• 宝石：增强较弱的行星
  • 每颗行星对应一种宝石（太阳对应红宝石，月亮对应珍珠等）
  • 需在特定手指、日期佩戴，并使用特定金属
  • 指定重量（克拉）
• Rudraksha：用于灵性补救的念珠
  • 不同 mukhi（面）对应不同的行星
  • 佩戴以获得保护并恢复平衡
• Puja／Mantras：仪式补救措施

占星 API 集成模式

第 1 步：选择占星 API 提供商

常见选项：

• AstrologyAPI.com（https://json.astrologyapi.com/）
• Prokerala API
• GeoVedic API
• AstroSage API

常用功能：

• 生成出生星盘（D1、D9）
• 提供带 nakshatra 的行星位置
• Vimshottari Dasha
• Dosha 分析（Manglik、Pitra、Kaal Sarp 等）
• 宝石／Rudraksha 建议
• Panchang（每日历法）
• 合盘／匹配

步骤 2：API 端点映射

必要端点（AstrologyAPI.com 示例）：

Base URL: https://json.astrologyapi.com/

1. POST /v1/horo_chart/{chart_id}
   - Get D1 (chart_id=D1), D9 (chart_id=D9), etc.
   - Returns: List of 12 houses with sign and planets

2. POST /v1/planets
   - Get detailed planetary positions
   - Returns: Planet positions, retrograde status, nakshatra, longitude

3. POST /v1/astro_details
   - Get basic astrological details
   - Returns: Ascendant, rasi, nakshatra, etc.

4. POST /v1/current_vdasha
   - Get current dasha period
   - Returns: Major, minor, sub-minor planet and dates

5. POST /v1/current_vdasha_all
   - Get complete dasha timeline
   - Returns: All major/minor/sub-minor periods from birth to 120 years

6. POST /v1/manglik
   - Check Manglik dosha
   - Returns: Manglik status, percentage, explanation

7. POST /v1/pitra_dosha_report
   - Check Pitra dosha
   - Returns: Present/absent, explanation

8. POST /v1/basic_gem_suggestion
   - Get gemstone recommendation
   - Returns: Gemstone, metal, finger, day, deity, mantra, carat weight

9. POST /v1/rudraksha_suggestion
   - Get Rudraksha recommendation
   - Returns: Mukhi number, ruling planet, benefits

10. POST /v1/puja_suggestion
    - Get puja recommendations
    - Returns: Puja type, purpose, timing

步骤 3：基础载荷结构

标准出生信息载荷：

{
  "day": 15,           // Day of birth (1-31)
  "month": 6,          // Month (1-12)
  "year": 1990,        // Year (YYYY)
  "hour": 14,          // Hour in 24-hour format (0-23)
  "min": 30,           // Minute (0-59)
  "lat": 28.7041,      // Latitude (decimal)
  "lon": 77.1025,      // Longitude (decimal)
  "tzone": 5.5         // Timezone offset (5.5 for IST)
}

关键注意事项：

• 时区：必须准确。印度默认时区 IST = 5.5
• 时间格式：使用 24 小时制，不要使用 12 小时制 AM/PM
• 坐标：使用 Google Maps Geocoding API 或类似工具获取准确的纬度和经度
• 日期验证：确保日期有效（例如，不存在 2 月 30 日）

步骤 4：API 管理器实现

职责：

• 使用 API 进行身份验证（通常采用 HTTP Basic Auth 或 API Key）
• 根据用户出生信息构建载荷
• 调用多个端点（星盘、dasha、dosha、补救措施）
• 处理 API 速率限制和错误
• 返回结构化响应

关键模式：

API Manager Methods:
- get_horo_chart(birth_details, chart_id) → D1/D9 chart
- get_planets(birth_details) → Planet positions
- get_dasha(birth_details) → Current dasha
- get_dasha_all(birth_details) → Complete timeline
- get_manglik(birth_details) → Dosha status
- get_gem_suggestion(birth_details) → Remedies

并行获取：

• 大多数端点彼此独立
• 使用异步任务（如 Celery）并行获取
• 将总耗时从 9×3s = 27s 缩短至约 3s

数据存储模式

数据库架构设计

集合 1：用户出生信息（user_metadata）

{
  "user_id": 12345,
  "dob_full_name": "John Doe",
  "dob_gender": "male",
  "dob_day": 15,
  "dob_month": 6,
  "dob_year": 1990,
  "dob_hour": 14,
  "dob_minute": 30,
  "dob_lat": 28.7041,
  "dob_long": 77.1025,
  "dob_city": "New Delhi",
  "dob_state": "Delhi",
  "created_on": "2024-01-15T10:00:00Z",
  "updated_on": "2024-01-15T10:00:00Z"
}

集合 2：原始占星数据（user_astro_metadata）

{
  "user_id": 12345,
  "astro_details": { /* API response */ },
  "horo_d1_chart_data": { /* D1 chart response */ },
  "horo_d9_chart_data": { /* D9 chart response */ },
  "planet_chart_data": { /* Planets response */ },
  "current_vdasha": { /* Current dasha */ },
  "current_vdasha_all": { /* Complete dasha */ },
  "manglik": { /* Manglik dosha */ },
  "pitra_dosha_report": { /* Pitra dosha */ },
  "basic_gem_suggestion": { /* Gemstone */ },
  "rudraksha_suggestion": { /* Rudraksha */ },
  "created_on": "2024-01-15T10:05:00Z",
  "updated_on": "2024-01-15T10:05:00Z"
}

为何使用两个集合？

• 出生信息很少更改（不可变）
• 占星数据可以刷新（dasha 会随时间变化）
• 分离后可独立更新

家庭成员支持

集合 3：家庭成员出生信息（user_member_metadata）

{
  "_id": "member_unique_id",
  "user_id": 12345,
  "relation": "spouse",
  "dob_full_name": "Jane Doe",
  "dob_gender": "female",
  "age": 32,
  "dob_day": 20,
  "dob_month": 8,
  "dob_year": 1992,
  // ... same birth detail fields
}

集合 4：家庭成员占星数据（user_member_astro_metadata）

{
  "user_id": 12345,
  "member_id": "member_unique_id",
  // ... same astro data fields as user_astro_metadata
}

关系类型：

• "self"（主用户）
• "spouse"、"mother"、"father"
• "son"、"daughter"、"child"
• "brother"、"sister"
• 可按需自定义关系

Kundli 转换模式

问题描述

挑战：API 响应嵌套层级深、内容冗长，且键名不一致。需要将其转换为清晰、适合 AI 使用的结构。

API 响应示例问题：

• 大小写混用的键："Sign"、"sign"、"SIGN"
• 内容冗长："此人因火星位于第 7 宫而有 28.5% 的 Manglik……"
• 嵌套层级过深：宫位 → 星座 → 行星 → 详情
• 字符串格式："Mars(Retrograde)"，而非结构化数据

解决方案：多步转换流水线

步骤 1：规范化键

• 将所有键转换为小写
• 递归处理嵌套对象
• 统一数组结构

步骤 2：转换星盘

• 将宫位列表转换为字典（宫位编号 → 详情）
• 提取每个宫位的星座
• 将星座映射到其主星（Aries → Mars）
• 提取每个宫位中的行星

步骤 3：丰富行星信息

• 解析行星字符串："Mars(Retrograde)" → {name: "Mars", isRetrograde: true}
• 添加宿、黄经和位置
• 标记吉凶状态

步骤 4：构建 Dasha 时间线

• 将日期字符串解析为 ISO 格式
• 筛选合理的时间范围（例如，从 2010 年至 current_year + 25）
• 按主 → 次 → 次次层级组织结构

步骤 5：提取 Dosha 值

• 将冗长报告精简为关键值
• Manglik：仅提取百分比
• Pitra：仅提取存在/不存在

步骤 6：整理补救措施

• 宝石：提取名称、金属、手指、日期、克拉数
• Rudraksha：提取面数、行星和益处

输出：完整的 Kundli 结构

Relation with user: self

Birth Details:
  name: John Doe
  gender: male
  date_of_birth: 15 Jun 1990
  time_of_birth: 02:30 PM
  place_of_birth: New Delhi, Delhi

D1 Chart:
  House 1:
    sign: Aries
    sign_lord: Mars
    planets:
      - name: Sun
        isRetrograde: false
        nakshatra: Ashwini
        longitude: 65.23
      - name: Mercury
        isRetrograde: true
        nakshatra: Bharani
        longitude: 72.45
  House 2:
    sign: Taurus
    sign_lord: Venus
    planets: []
  # ... Houses 3-12

D9 Chart:
  # Same structure as D1

Dasha Timeline:
  - major_planet: Venus
    start_date: 2015-05-01
    end_date: 2035-05-01
    minor_periods:
      - planet: Venus
        start_date: 2015-05-01
        end_date: 2018-09-01
      - planet: Sun
        start_date: 2018-09-01
        end_date: 2019-09-01
      # ... more minor periods

Current Dasha:
  major: Venus
  minor: Moon
  sub_minor: Mars

Doshas:
  manglik_percentage: 28.5
  pitra_dosha_present: false

Remedies:
  gemstone:
    name: Diamond
    metal: Silver
    finger: Middle
    day: Friday
    carat: 2-3
  rudraksha:
    mukhi: 6
    ruling_planet: Venus
    benefits: "Harmony, love, relationships"

AI 提示词集成模式

上下文组装

注入的组件：

1. 完整 Kundli（上述 YAML 格式）
2. 查询专属的宫位映射
3. 考虑性别的解读规则
4. 用于判断时间的当前 dasha
5. 语言偏好（Hindi/English）

系统提示词结构：

You are an expert Vedic astrologer with deep knowledge of:
- Planetary positions and aspects
- House significations
- Dasha timing predictions
- Dosha analysis and remedies

User's Complete Birth Chart:
<kundli>
[YAML kundli structure here]
</kundli>

Query Analysis Rules:
- Marriage questions → Focus on House 7, Venus, Jupiter
- Career questions → Focus on House 10, Saturn, Sun
- Finance questions → Focus on House 2, 11, Jupiter
- Health questions → Focus on House 1, 6, planets in these houses
- Children questions → Focus on House 5, Jupiter
- Property questions → Focus on House 4, Mars

Gender-Specific Rules:
- For females: Jupiter = husband, Venus = marriage
- For males: Venus = wife, Mars = passion

Timing Predictions:
- Use current dasha: [Major/Minor/Sub-minor]
- Consider transits for immediate events
- Dasha changes indicate life phase shifts

Response Format:
- Provide predictions based on chart analysis
- Cite specific planetary positions
- Mention relevant dasha periods
- Suggest remedies if doshas present
- Answer in [Hindi/English] as per user preference

查询专属上下文

婚姻查询示例：

Query: "When will I get married?"

Additional Context:
- House 7 analysis: [Sign, Lord, Planets]
- Venus position: [House, Sign, Strength]
- Jupiter position: [House, Sign, Strength]
- Current dasha: [Will marriage planet dasha start soon?]
- Manglik dosha: [If yes, mention in prediction]

Prediction Approach:
1. Check House 7 lord strength
2. Check Venus/Jupiter periods in dasha
3. Look for favorable transits
4. Consider dosha impacts

职业查询示例：

Query: "What career is best for me?"

Additional Context:
- House 10 analysis: [Sign, Lord, Planets]
- Sun position: [Authority, leadership]
- Saturn position: [Discipline, perseverance]
- Mercury position: [Communication, intellect]
- Strongest planet in chart: [Natural talent]

Prediction Approach:
1. Identify dominant planets
2. Map to career domains (Sun→govt, Mercury→business, etc.)
3. Check House 10 lord placement
4. Consider current dasha planet's signification

高级功能

兼容性／配对（Kundli Milan）

Ashtakoot 体系（8 项配对）：

1. Varna（1 分）：精神契合度
2. Vashya（2 分）：相互吸引力
3. Tara（3 分）：出生星宿契合度
4. Yoni（4 分）：身体契合度
5. Graha Maitri（5 分）：心理契合度
6. Gana（6 分）：性情
7. Bhakoot（7 分）：爱与感情
8. Nadi（8 分）：健康与子嗣

总分：最高 36 分

• 18-24：一般匹配
• 25-32：良好匹配
• 33-36：极佳匹配

实现方式：

• 需要双方的 kundli
• 调用配对 API 端点
• 显示各项得分
• 如果双方都是 Manglik，则突出显示 Manglik 取消情况

Panchang（日历）

组成部分：

• Tithi（太阴日）
• Vara（星期）
• Nakshatra（月宿）
• Yoga（日月组合）
• Karana（半个 Tithi）

使用场景：

• Muhurat 选择（吉时）
• 节日日期
• 每日运势背景

行运预测

当前行星位置：

• 获取当前日期的行星位置
• 与出生星盘进行比较
• 识别相位（合相、对冲、三分相、四分相）
• 预测短期事件

实现清单

阶段 1：API 设置

• 选择占星 API 提供商
• 设置身份验证凭证
• 测试所有必需的端点
• 将 API 响应映射到内部模型
• 为 API 故障实现错误处理

阶段 2：数据模型

• 创建出生详情架构（user_metadata）
• 创建占星数据架构（user_astro_metadata）
• 为家庭支持创建成员架构
• 添加索引（user_id、member_id）
• 制定数据保留政策

阶段 3：Kundli 构建器

• 实现键规范化
• 转换星盘（D1、D9）
• 补充行星详情
• 构建 dasha 时间线
• 提取 dosha 值
• 格式化补救措施
• 使用示例 API 响应进行测试

阶段 4：AI 集成

• 设计包含 kundli 上下文的系统提示词
• 将查询类型映射到重点宫位
• 添加性别感知规则
• 在时间预测中纳入 dasha
• 支持印地语／英语回复
• 测试预测准确性

阶段 5：功能

• 用户引导（收集出生详情）
• 地点自动补全（Google Maps API）
• 生成并显示 Kundli
• 家庭成员管理
• 兼容性配对
• Dosha 检测与补救措施
• 集成 Panchang
• 每日运势

阶段 6：优化

• 缓存 kundli 数据（10-60 分钟 TTL）
• 并行 API 调用（异步任务）
• 压缩大型 kundli 上下文
• 监控 API 使用情况和成本
• 实现速率限制

阶段 7：质量保证

• 验证时区准确性
• 测试边缘情况（午夜出生、DST）
• 验证 dasha 计算
• 检查 dosha 逻辑
• 与占星师进行用户验收测试
• 多语言测试

最佳实践

准确性优先

1. 时区至关重要：始终使用准确的时区偏移量
2. 坐标很重要：通过地理编码获取精确的经纬度
3. 时间格式：使用 24 小时制，并验证 AM/PM 转换
4. 日期验证：检查日期是否有效以及是否为闰年

数据管理

1. 将出生数据与占星数据分开：出生详情不可变，占星数据可刷新
2. 合理缓存：Kundli 不常变化，可缓存数小时
3. 为 Kundli 格式添加版本：添加版本字段，以便将来更改架构
4. 审计跟踪：记录所有 kundli 生成操作以便调试

AI 提示词工程

1. 结构化上下文：使用 YAML/XML 标签划分清晰的部分
2. 查询分类：预处理查询以确定关注领域
3. 引用来源：指示 AI 在回答中引用行星位置
4. 备用处理：处理星盘无法支持查询的情况

用户体验

1. 渐进式加载：在详细分析加载期间，先显示基本星盘
2. 解释说明：用简单易懂的语言解释占星术语
3. 补救方法：始终提供可执行的补救方法
4. 征得同意：保护敏感出生数据的隐私

常见误区

1. 时区错误：会导致星盘完全不同
2. 12 小时制 AM/PM 混淆：下午 2:30 ≠ 14:30，会造成 12 小时误差
3. 忽略逆行：行星逆行会改变解读结果
4. 大运静态不变：大运会随时间变化，应定期刷新
5. 预测过于简单：AI 需要详细背景信息，而不只是太阳星座
6. 缺少性别背景：金星／木星的解读因性别而异
7. 忽略 Dosha：Manglik dosha 对婚姻预测至关重要

框架适配

Django

• 使用 MongoDB 存储文档
• 使用 Celery 发起异步 API 调用
• 使用 Django 缓存缓存 kundli
• 使用 REST API 连接前端

FastAPI

• 使用 Motor（异步 MongoDB 驱动）
• 使用后台任务或 Celery
• 使用 Redis 缓存
• 使用 WebSocket 实现实时预测

Node.js (Express)

• 使用 Mongoose 操作 MongoDB
• 使用 Bull 管理作业队列
• 使用 Redis 缓存
• 使用 Socket.io 实现实时功能

Spring Boot

• 使用 Spring Data MongoDB
• 使用 Spring Async 或 RabbitMQ
• 使用 Spring Cache
• 使用 WebFlux 实现响应式功能

相关资源

• 吠陀占星文本：Brihat Parashara Hora Shastra、Jaimini Sutras
• API 提供商：AstrologyAPI.com、Prokerala、GeoVedic
• 库：Swiss Ephemeris（行星计算）
• 术语：https://en.wikipedia.org/wiki/Hindu_astrology

总结

构建占星后端需要：

1. 领域知识：了解宫位、行星、大运和 Dosha
2. 准确数据：时区和坐标至关重要
3. 结构化转换：将冗长的 API 数据转换为整洁的 kundli
4. 丰富的 AI 上下文：向大模型提供完整的出生星盘
5. 查询智能：将用户问题映射到相关星盘部分
6. 补救方法：始终提供可执行的指导

此技能提供模式和领域知识，助你构建集成 AI 的生产级吠陀占星系统。结合 ai-integrated-api-backend 技能，获取完整的实现指导。

重要的占星数据点：

• astro_details — 基本出生星盘详情
• horo_d1_chart_data — 主出生星盘（Rashi 星盘）
• horo_d9_chart_data — Navamsa 分盘
• planet_chart_data — 详细行星位置
• current_vdasha — 当前 Vimshottari 大运时期
• current_vdasha_all — 完整大运时间线
• manglik — Manglik dosha 分析
• pitra_dosha_report — Pitra dosha 分析
• basic_gem_suggestion — 宝石建议
• rudraksha_suggestion — Rudraksha 念珠建议