# HTTP API

本頁列出 API Server 的端點、請求格式與資料表結構。

## 端點

API Server 監聽 `:8080`，成功時回傳 `ok` 字串或 `{"data": [...]}`；JSON 綁定失敗回 `400`，資料庫錯誤回 `500`，內容皆為錯誤訊息字串。

| 方法 | 路徑 | Body | 說明 |
|---|---|---|---|
| `GET` | `/api/health` | — | 健康檢查，回傳 `ok` |
| `GET` | `/api/pod/list` | — | 列出 `dismiss = 0` 的部署 |
| `POST` | `/api/pod/upsert` | `Pod` | 依 `uid` 新增或更新部署，並重設 `dismiss = 0` |
| `POST` | `/api/pod/update/:uid` | `Pod`（只取 `status`、`dismiss`） | 更新指定部署 |
| `POST` | `/api/pod/record/insert` | `Record`（取 `uid`、`content`、`hostname`、`ip`） | 依 `uid` 寫入一筆操作紀錄 |

未註冊的路徑由 `NoRoute` 處理，請求會一直掛著不回應。

## 範例

```bash
curl -X POST localhost:8080/api/pod/upsert \
  -d '{"uid":"t1","pod_id":"p","pod_name":"n","local_dir":"/a","remote_dir":"/b","status":"starting","replicas":1}'

curl localhost:8080/api/pod/list
```

## Pod 欄位

| 欄位 | 型別 | 說明 |
|---|---|---|
| `uid` | `string` | `md5("<MAC>@<本地絕對路徑>")` 或 `-u` 指定值 |
| `pod_id` | `string` | Podman Pod ID；查不到時為遠端目錄名 |
| `pod_name` | `string` | Podman Pod 名稱；查不到時為遠端目錄名 |
| `local_dir` | `string` | 本地專案絕對路徑 |
| `remote_dir` | `string` | `/home/podrun/<目錄名>_<雜湊前 8 碼>` |
| `file` | `string` | `-f` 指定的 compose 檔 |
| `target` | `string` | `--type` 的值；**[未完成]** k3s 僅作紀錄 |
| `status` | `string` | CLI 寫入 `starting` |
| `hostname` | `string` | 執行 CLI 的主機名稱 |
| `ip` | `string` | 執行 CLI 的主機第一個非 loopback IPv4 |
| `replicas` | `int` | 固定為 `1` |
| `created_at`／`updated_at` | `time` | 由資料庫寫入 |
| `dismiss` | `int` | `0` 有效、`1` 已移除 |

`pod_id` 寫入資料表的 `pod_uid` 欄位。

## 資料表

| 資料表 | 用途 | 欄位 |
|---|---|---|
| `pods` | 每個部署一列，`uid` 與 `pod_uid` 唯一 | `uid`、`pod_uid`、`pod_name`、`local_dir`、`remote_dir`、`file`、`target`、`status`、`hostname`、`ip`、`replicas`、`created_at`、`updated_at`、`dismiss` |
| `records` | 操作紀錄，`pod_id` 參照 `pods.id`（刪除時連動） | `pod_id`、`content`、`hostname`、`ip` |
| `domains` | **[未完成]** 預留給 `domain` 指令 | `pod_id`、`container_name`、`domain`、`created_at`、`updated_at`、`dismiss` |