# 陸府命理AI API 使用指南

> 版本: v6.0 | 更新: 2026-04-24
> 基準: 命理網(DestinyNet)南派/通用版安星法 | 57星100%驗證

## 基礎信息

- **API端點**: `http://mingli.lufu.cloud/api/`
- **服務器**: `http://43.160.243.60:80/api/` (nginx代理)
- **健康檢查**: `GET /api/health`
- **算法列表**: `GET /api/algorithms`

---

## API 列表

### 1. 命理計算 POST `/api/calculate`

對指定的出生資訊計算命理數據。

**請求格式**:
```json
{
    "algorithm": "bazi|ziwei|nayin|shensha|...",
    "birth_info": {
        "birth_date": "1978-04-12",
        "birth_time": "07:15",
        "gender": "male",
        "birth_place": "台灣台中"
    }
}
```

**算法列表**:

| ID | 名稱 | 說明 | 專業度 |
|:---|:---|:---|:---:|
| `bazi` | 八字命理 | 子平八字完整排盤 | 10/10 |
| `ziwei` | 紫微斗數 v3 | 57星匹配命理網 | ✅ 新版 |
| `nayin` | 納音五行 | 六十甲子納音分析 | 10/10 |
| `shensha` | 神煞體系 | 20+神煞 | 10/10 |
| `tiaohou` | 調候用神 | 窮通寶鑑調候 | 10/10 |
| `western` | 西洋占星 | 12星座+10行星 | 10/10 |
| `qizheng` | 七政四餘 | 7政4餘傳統星命 | 10/10 |
| `qimen` | 奇門遁甲 | 63格局+8門 | 10/10 |
| `liuyao` | 六爻占卜 | 64卦+6獸 | 10/10 |
| `meihua` | 梅花易數 | 8卦+萬物類象 | 10/10 |
| `liuren` | 大六壬 | 10課體+12天將 | 10/10 |
| ... | 共19種 | 全部專業度10/10 | |

**範例**:
```bash
curl -X POST http://mingli.lufu.cloud/api/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm":"ziwei",
    "birth_info":{
        "birth_date":"1978-04-12",
        "birth_time":"07:15",
        "gender":"male"
    }
}'
```

---

### 2. 八字報告 POST `/api/bazi_report`

生成包含HTML區塊的完整八字報告。

```bash
curl -X POST http://mingli.lufu.cloud/api/bazi_report \
  -H "Content-Type: application/json" \
  -d '{"birth_info":{"birth_date":"1978-04-12","birth_time":"07:15","gender":"male","birth_place":"台灣台中"}}'
```

返回8個HTML區塊：四柱、五行、神煞、大運、流年、格局、調候、綜合分析。

---

### 3. 紫微HTML命盤 POST `/ziwei/pan/html`

```bash
curl -X POST http://mingli.lufu.cloud/ziwei/pan/html \
  -H "Content-Type: application/json" \
  -d '{"birth_date":"1978-04-12","birth_time":"07:15","gender":"male","name":"林志忠"}'
```

返回完整4x3紫微命盤HTML。

---

### 4. 紫微JSON數據 POST `/ziwei/pan`

```bash
curl -X POST http://mingli.lufu.cloud/ziwei/pan \
  -H "Content-Type: application/json" \
  -d '{"birth_date":"1978-04-12","birth_time":"07:15","gender":"male"}'
```

返回JSON格式的命盤數據（含大限、神煞、四化）。

---

## 快取系統

- Redis 快取（端口6379）已啟用
- 快取TTL: 3600秒（1小時）
- 快取鍵: `lufu:{md5(algorithm+birth_info)}`
- 同參數第二次請求自動命中快取（~0.03ms）
- 響應中包含 `metadata.cache_hit` 標記

---

## 性能指標

| 指標 | 數值 |
|:---|:---:|
| 八字 QPS | 599 req/s |
| 紫微 v3 QPS | 627 req/s |
| 高併發(50) QPS | 617 req/s |
| 平均延遲 | ~16ms |
| 快取命中延遲 | <0.1ms |
| 可用算法 | 19種 |

---

## 前端頁面

- **紫微HTML命盤**: http://mingli.lufu.cloud/ziwei.html
- **八字網頁**: http://mingli.lufu.cloud/bazi.html
- **聖者報告**: http://mingli.lufu.cloud/sage-report/

---

## 服務架構

```
nginx :80
├── /           → /var/www/mingli/ (前端靜態頁面)
├── /api/       → proxy 127.0.0.1:3004 (19種算法 + Redis快取)
├── /ziwei/     → proxy 127.0.0.1:3005 (紫微HTML API)
├── /sage-report/ → /var/www/html/sage-report/
└── /sage-test/  → /var/www/html/sage-test/
```