Tianshu Huangdao

🏮 天樞黃道庫：黃曆擇吉·命理運勢·姓名起名。查黃道吉日、算生肖運勢、取名測字。數據來自傳統曆法和命理典籍（建除12神/28宿/64卦/五行/生肖），每次調用 PayPal 支付 1.68 USD。當用戶詢問：結婚搬家等黃道吉日、今日/本月運勢、取名建議、五行卦象時觸發。

🏮 天樞黃道庫（v1.0.6）

傳統曆法·命理運勢·姓名起名一站式 API，基於正統數據源，通過 PayPal 按次扣費（1.68 USD/次）。

⚠️ 重要：所有輸出必須使用繁體中文。API返回的數據可能包含簡體字，Agent需自行將簡體轉換為繁體中文後輸出給用戶。

---

💰 付費策略（核心！）

三個付費項目（$1.68/次，PayPal支付）：

1. 🀄 64卦查詢 — GET /v1/huangdao/hexagram?number=卦序&paypal_order_id=xxx
2. 🔮 命理運勢 — GET /v1/huangdao/fortune?birth=...&paypal_order_id=xxx
3. 📝 姓名起名（完整版） — GET /v1/huangdao/naming?last=...&gender=...&paypal_order_id=xxx

免費贈送（不需要付費）：

1. 📅 黃曆擇吉 — GET /v1/huangdao/huangli?date=...
2. 🆓 取名預覽 — GET /v1/huangdao/naming?last=...&gender=...&preview=1
3. ❓ 幫助文檔 — GET /v1/huangdao/help

注意：付費接口不帶 paypal_order_id 會返回 402 Payment Required。Agent 必須先走 PayPal 支付流程，拿到 orderId 後帶參數調用。

---

🤖 Agent 對話引導模板

取名流程（有免費預覽）

1. 用戶提問取名 → Agent 調 API 帶 &preview=1 參數（免費）
2. API 返回免費預覽數據（mode: "preview"），包含 3個推薦名 + 簡短建議
3. Agent 展示免費推薦，話術：

   「初步推薦以上3個名字。如需完整八字分析 + 五行補綴 + 歷史典故 + 更多推薦，支付 $1.68 解鎖完整報告。是否繼續？」

4. 用戶確認 → Agent 調 POST /api/paypal/create-order 生成 PayPal 支付連結
5. 用戶通過 PayPal 完成支付（$1.68 USD）
6. Agent 調 POST /api/paypal/capture-order 確認收款
7. Agent 調 API 帶 paypal_order_id=xxx 獲取完整命名分析報告
8. 返回完整報告給用戶（含八字排盤、五行補綴、歷史典故、更多推薦）

黃曆查詢流程（免費）

1. 用戶問「今天宜什麼」→ Agent 直接調 GET /v1/huangdao/huangli?date=YYYY-MM-DD（免費）
2. 返回數據直接展示給用戶

64卦查詢流程（收費）

1. 用戶查卦 → Agent 調 API → 返回 402
2. Agent 話術：

   「查詢64卦需支付 $1.68。是否繼續？」

3. 用戶確認 → PayPal 支付流程 → 帶 paypal_order_id 調用

運勢查詢流程（收費）

1. 用戶問運勢 → API 返回 402
2. Agent 話術：

   「詳細運勢分析需支付 $1.68。是否繼續？」

3. 用戶確認 → PayPal 支付流程 → 帶 paypal_order_id 調用

---

支付流程（PayPal）

1. Agent 調 POST /api/paypal/create-order
   請求體：{"amount":"1.68","currency":"USD","plan":"Naming"}
   返回：{ "orderId": "...", "approvalUrl": "https://www.paypal.com/checkoutnow?token=..." }

2. Agent 向用戶展示 approvalUrl 作為「Pay with PayPal $1.68」支付按鈕

3. 用戶點擊 → PayPal 支付頁面 → 完成支付

4. Agent 調 POST /api/paypal/capture-order
   請求體：{"orderId":"..."}
   返回：{ "success": true, "status": "COMPLETED" }

5. 驗證成功 → Agent 調 API 獲取數據（帶 orderId 作為憑證）

---

API 端點

通過網關 https://sinodata.io 訪問。

付費接口（需 paypal_order_id）

一、64卦查詢

GET https://sinodata.io/v1/huangdao/hexagram?number=1&paypal_order_id=xxx

參數：

參數	必填	說明
number	是	卦序（1-64），不傳則按當天日期推算

返回：

• number — 卦序（1-64）
• name — 卦名
• judgment — 卦辭
• image — 象辭
• lines — 爻辭

二、命理運勢

GET https://sinodata.io/v1/huangdao/fortune?birth=YYYY-MM-DD&zodiac=生肖&paypal_order_id=xxx

參數	必填	說明
birth	是	出生日期
zodiac	否	生肖名（如"虎""龍"），不傳則由出生年份自動推算
paypal_order_id	是	PayPal支付訂單號

三、姓名起名（完整版）

GET https://sinodata.io/v1/huangdao/naming?last=姓氏&gender=男|女&paypal_order_id=xxx

參數	必填	說明
last	是	姓氏
gender	是	男 / 女
paypal_order_id	是	PayPal支付訂單號
birth	否	出生日期（精準八字分析）

返回（完整版）： 姓氏五行 + 多個推薦名（含筆畫、五行、寓意、八字分析）+ 起名貼士

---

免費接口（不限）

四、黃曆擇吉

GET https://sinodata.io/v1/huangdao/huangli?date=YYYY-MM-DD

參數：

參數	必填	說明
date	是	查詢日期，格式 YYYY-MM-DD

返回字段：

• date — 公曆日期
• lunar — 農曆年/月/日 + 干支年
• yi — 宜做什麼（如嫁娶、搬家、開市）
• ji — 忌做什麼（如訴訟）
• daily_god — 建除12神
• xiu — 28宿
• na_yin — 納音五行
• hexagram — 64卦（卦名+卦辭+象辭+爻辭）
• pengzu_baiji — 彭祖百忌

五、取名預覽（免費）

GET https://sinodata.io/v1/huangdao/naming?last=姓氏&gender=男|女&preview=1

返回3個免費推薦名字 + 簡短建議。

六、幫助文檔

GET https://sinodata.io/v1/huangdao/help

七、支付創單 (PayPal)

POST https://sinodata.io/api/paypal/create-order
Content-Type: application/json

{ "amount": "1.68", "currency": "USD", "plan": "Naming" }

八、支付確認 (PayPal)

POST https://sinodata.io/api/paypal/capture-order
Content-Type: application/json

{ "orderId": "PAYPAL_ORDER_ID" }

扣費機制

• 價格： 1.68 USD/次（PayPal即時收款）
• 三個付費項目： 64卦查詢、命理運勢、姓名起名完整版
• 免費贈送： 黃曆擇吉、取名預覽、幫助文檔
• 流程： Agent 創建 PayPal 訂單 → 用戶支付 → Agent 帶 orderId 調用 API
• 驗證： 服務端已接入 PayPal REST API 完整簽名驗證

數據資源（本地嵌入）

文件	大小	內容
data/huangli_rules.json	31KB	建除12神、28宿、64卦、宜忌活動(29項)、吉神凶神、彭祖百忌、節氣
data/yijing.json	56KB	64卦完整卦辭、象辭、爻辭
data/zodiac.json	16KB	12生肖運勢、五行屬性、幸運色數字
data/fortune_crossref.json	18KB	五行生克、干支組合、綜合運勢交叉表
data/naming.json	41KB	223字名庫（筆畫/五行/寓意）+ 五格數理 + 三才配置
data/wuxing.json	2KB	五行屬性速查

隱私與條款

• 本服務不存儲用戶個人信息
• 支付信息由 PayPal 處理，服務端僅保留訂單號和支付狀態
• 數據僅用於傳統文化研究用途