# CFD FastAPI Server

將 2D 翼型空氣動力分析包裝成一般 FastAPI HTTP API，讓前端、腳本或其他服務可以直接呼叫完整的「幾何 → 網格 → 求解 → 後處理 → 視覺化」流程。

```text
Client ──▶ FastAPI Server ──▶ aerosandbox / NeuralFoil / SU2
                              └─▶ Cp 分布 / 極曲線 / dashboard / artifact downloads
```

## 功能

| API | 功能 |
|---|---|
| `POST /api/geometry/airfoil` | 從 NACA 4/5 位數代碼生成翼型座標 (`.dat`) |
| `POST /api/meshes/2d` | 生成 2D 網格，支援 placeholder 與 SU2/Gmsh |
| `POST /api/solver/run` | 執行 NeuralFoil，或提交非同步 SU2 求解 |
| `GET /api/solver/results/{job_id}` | 查詢 job 狀態；完成後回傳 CL / CD / CM / Cpmin / 轉捩點 |
| `POST /api/workflow/airfoil` | 一次完成 geometry -> mesh -> solver；SU2 只提交背景求解 |
| `POST /api/visualizations` | 生成視覺化 artifact metadata |
| `GET /artifacts/{artifact_id}` | 在瀏覽器 inline 預覽視覺化圖檔 |
| `GET /artifacts/{artifact_id}/download` | 下載視覺化圖檔 |
| `/mcp/` | Streamable HTTP MCP endpoint，提供同一套 CFD workflow tools |

### 視覺化模式

| `plot_kind` | 內容 |
|---|---|
| `summary` | 翼型形狀 + 結果數字 |
| `cp` | 沿翼型表面真 Cp 分布 |
| `polar` | CL/CD vs alpha 雙軸極曲線 |
| `drag_polar` | CL vs CD 拖力極曲線 |
| `mesh` | 網格預覽圖 |
| `dashboard` | 綜合 dashboard 與網格預覽 |
| `mach` | 馬赫數分佈圖 (SU2) |
| `pressure` | 壓力分佈圖 (SU2) |

`POST /api/visualizations` 會回傳：

```json
{
  "status": "success",
  "summary": "...",
  "artifact": {
    "artifact_id": "vis_abc123",
    "filename": "dashboard_vis_abc123.jpg",
    "mimeType": "image/jpeg",
    "size_bytes": 170868
  }
}
```

圖檔不直接塞進 JSON body，而是落地成 artifact。用回傳的 `artifact_id` 組 `GET /artifacts/{artifact_id}` 在瀏覽器預覽，或組 `GET /artifacts/{artifact_id}/download` 下載。

HTTP API 只回傳資源 id，不回傳伺服器端檔案路徑。手動流程請依序傳遞 `geometry_id`、`mesh_id`、`job_id`、`artifact_id`。

SU2 求解是非同步工作。`POST /api/solver/run` 或 `POST /api/workflow/airfoil` 使用 `solver_backend="su2"` 時會回傳 `status: "submitted"` 與 `job_id`；之後用 `GET /api/solver/results/{job_id}` 輪詢，直到狀態變成 `converged` 或 `failed`。NeuralFoil surrogate 仍同步回傳結果。

## 快速開始

### 環境需求

- Python 3.11+
- `uv`

### 本機啟動

```bash
uv sync
uv run python -m cfd_server
```

啟動後可用：

- Swagger UI: `http://localhost:8765/docs`
- OpenAPI: `http://localhost:8765/openapi.json`
- Health check: `http://localhost:8765/healthz`
- MCP endpoint: `http://localhost:8765/mcp/`

### 執行測試

```bash
uv run --group dev pytest
```

### Docker

```bash
docker build -t cfd-server:su2-local .
docker run --rm -p 8765:8765 -v "$PWD/jobs:/app/jobs" cfd-server:su2-local
```

檢查 SU2 與 Gmsh：

```bash
docker run --rm cfd-server:su2-local SU2_CFD --help
docker run --rm cfd-server:su2-local gmsh --version
```

### Docker Compose

```bash
docker compose up --build cfd-server
```

## API 範例

### 建立翼型

```bash
curl -X POST http://localhost:8765/api/geometry/airfoil \
  -H "content-type: application/json" \
  -d '{
    "naca_code": "0012",
    "chord_length": 1.0,
    "n_points_per_side": 180,
    "normalize_geometry": true
  }'
```

### 一鍵工作流

```bash
curl -X POST http://localhost:8765/api/workflow/airfoil \
  -H "content-type: application/json" \
  -d '{
    "naca_code": "0012",
    "velocity": 30.0,
    "angle_of_attack": 5.0,
    "solver_backend": "neuralfoil"
  }'
```

SU2 一鍵工作流會先產生 SU2/Gmsh mesh，然後提交背景求解：

```bash
curl -X POST http://localhost:8765/api/workflow/airfoil \
  -H "content-type: application/json" \
  -d '{
    "naca_code": "0012",
    "velocity": 30.0,
    "angle_of_attack": 5.0,
    "mesh_format": "su2",
    "solver_backend": "su2",
    "max_iterations": 500
  }'
```

查詢背景求解：

```bash
curl http://localhost:8765/api/solver/results/06936164e5a7
```

### 視覺化

```bash
curl -X POST http://localhost:8765/api/visualizations \
  -H "content-type: application/json" \
  -d '{
    "job_id": "06936164e5a7",
    "plot_kind": "dashboard",
    "image_format": "jpeg"
  }'
```

## MCP

這個服務現在同時提供 Streamable HTTP MCP，直接重用現有 service layer，不需要另外維護第二套 CFD 邏輯。

MCP tools:

- `generate_airfoil_geometry`
- `generate_2d_mesh`
- `run_cfd_solver`
- `check_solver_results`
- `run_airfoil_workflow`
- `visualize_cfd_results`
- `get_visualization_artifact`

本機啟動 HTTP + MCP：

```bash
uv run python -m cfd_server
```

用 MCP Inspector 連線：

```bash
npx -y @modelcontextprotocol/inspector
```

連到：

```text
http://localhost:8765/mcp/
```

如果你要用 stdio 模式直接跑 MCP server：

```bash
uv run python -m cfd_server.app.interfaces.mcp.server
```

## 測試

- `tests/conftest.py`: 共用 FastAPI `TestClient` 與 workflow fixture
- `tests/test_http_workflow.py`: 幾何、網格、求解、結果查詢、路由註冊
- `tests/test_async_su2_solver.py`: SU2 非同步提交與狀態轉換
- `tests/test_visualization_artifacts.py`: artifact metadata 與落地檔案
- `tests/test_artifact_download.py`: artifact HTTP download endpoint
- `tests/test_su2_config.py`: SU2 config 單元測試

## 專案結構

```text
cfd-server/
├── cfd_server/
│   ├── __main__.py
│   ├── app/
│   │   ├── interfaces/
│   │   │   └── http/        # FastAPI app, routers, request schemas
│   │   └── services/        # workflow / visualization service layer
│   ├── server.py            # 相容 wrapper
│   ├── core/
│   ├── mesh/
│   ├── solvers/
│   ├── visualization/
│   └── models/
├── tests/
├── pyproject.toml
├── Dockerfile
└── README.md
```