では **🔌 API設計（ID:312）** のHTMLを出力します：
“`html
みーきゅんクラウド — API設計
🔌 API 設計書
顧客ポータル・管理機能・VPN Engine・Nextcloud連携を結ぶ FastAPI ベースの API サーバ。画面と DB・WireGuard・将来の Nextcloud 連携を束ねる中核レイヤ。
FastAPI
uvicorn
port 9000
port 9081
MariaDB
WireGuard
uvicorn
port 9000
port 9081
MariaDB
WireGuard
顧客ポータル
:9000
/root/mikyun-cloud/
VPN Engine
:9081
/opt/mikyun-portal/
顧客UI
/client
client_ui.py
管理UI
/ui
ui_admin.py
1 — API全体構造
顧客（iPhone / WG接続中）
↓ https://portal.wan-secure.net/client
↓
FastAPI :9000 /root/mikyun-cloud/app/main.py
├─ /client/* 顧客ポータルUI client_ui.py
├─ /ui/* 管理者UI ui_admin.py
└─ HTTP内部通信
↓
FastAPI :9081 /opt/mikyun-portal/mikyun_vpn_engine.py
├─ MariaDB: mikyun_cloud
├─ WireGuard 設定生成・peer管理
└─ QR / conf ファイル生成
2 — 実装ファイル
| ファイル | 役割 | ポート |
|---|---|---|
| /root/mikyun-cloud/app/main.py | メインアプリ・Basic認証ミドルウェア | 9000 |
| /root/mikyun-cloud/app/client/client_ui.py | 顧客向けポータルUI（/client） | 9000 |
| /root/mikyun-cloud/app/ui_admin.py | 管理者向けUI（/ui） | 9000 |
| /opt/mikyun-portal/mikyun_vpn_engine.py | VPN Engine・IP採番・WG設定生成 | 9081 |
| /opt/mikyun/bin/wg_issue_device.py | conf・QR生成スクリプト（採番なし） | — |
3 — 顧客向けAPI
| Method | Path | 用途 |
|---|---|---|
| GET | /client | ログイン画面（親端末IP自動認識） |
| POST | /client/login | パスフレーズ認証・契約画面へ |
| GET | /client/devices/{contract_id} | 端末一覧・契約情報表示 |
| POST | /client/add/{contract_id} | 子端末追加 |
| POST | /client/pause/{device_id} | 端末一時停止 |
| POST | /client/resume/{device_id} | 停止解除 |
| POST | /client/promote/{device_id} | 子端末を親端末へ昇格 |
| POST | /client/delete/{device_id} | 子端末削除 |
| GET | /client/qr/{contract_id}/{device_id} | QR表示 |
| GET | /client/conf/{device_id} | conf ダウンロード |
4 — 管理者API（/ui）
| Method | Path | 用途 |
|---|---|---|
| GET | /ui/contracts | 契約一覧 |
| GET | /ui/contracts/new | 新規契約作成フォーム |
| POST | /ui/contracts/new | 契約作成 + 親端末初回発行 |
| GET | /ui/contracts/{contract_id} | 契約詳細 |
| POST | /ui/contracts/{contract_id}/add-child | 子端末追加 |
| POST | /ui/contracts/{contract_id}/promote-parent | 親端末昇格 |
| POST | /ui/devices/{device_id}/pause | 端末停止 |
| POST | /ui/devices/{device_id}/resume | 端末復帰 |
| GET | /ui/devices/{device_id}/qr | QR取得（認証不要・public_router） |
| GET | /ui/devices/{device_id}/conf | conf取得 |
| GET | /ui/contracts/{contract_id}/parent-qr | 親端末QR取得 |
| GET | /ui/health | 運用ヘルス確認 |
5 — 内部VPN Engine API（:9081）
mikyun_vpn_engine.py が担当。顧客ポータルから HTTP で呼び出す。
| Method | Path | 用途 |
|---|---|---|
| GET | /health | 生存確認 |
| POST | /contracts/create | 契約作成 + 親端末発行・WG peer追加・QR生成 |
| GET | /contracts/list | 契約一覧取得 |
| GET | /contracts/{contract_id} | 契約詳細取得 |
| GET | /contracts/{contract_id}/devices | 端末一覧取得 |
| POST | /devices/add-child | 子端末追加・空きIP採番・WG peer追加 |
| POST | /devices/pause | 端末停止（iptables DROP + status=paused） |
| POST | /devices/resume | 停止解除（iptables DROP削除 + status=active） |
| POST | /devices/promote-parent | 子端末を親端末へ昇格 |
| POST | /devices/delete | 端末削除・peer除去・論理削除 |
IP採番ロジック（2026-03-22 変更済み）
# customer_devices の使用中IP（revoked/expired以外）を全件取得
# 10.251.0.0/24 の空き最小番号を割り当て
# 予約IP: 10.251.0.1（VPS/GW）、10.251.0.254（DNS）
# DB の wg_ip UNIQUE制約で二重防御
SHARED_SUBNET = "10.251.0.0/24"
RESERVED_IPS = {"10.251.0.1", "10.251.0.254"}
割当範囲 = 10.251.0.2 〜 10.251.0.253（最大252台）
6 — 将来のNextcloud連携API
| Method | Path | 用途 |
|---|---|---|
| POST | /internal/nextcloud/users | 契約作成時にNCユーザー作成・ID・PW・容量割当 |
| PATCH | /internal/nextcloud/users/{contract_id}/quota | 容量同期 |
| GET | /internal/nextcloud/users/{contract_id}/usage | 使用量取得 |
| POST | /internal/nextcloud/users/{contract_id}/disable | 停止・凍結 |
7 — APIとDBの対応
| テーブル | 関わる主API |
|---|---|
| contracts | /contracts/create・list・detail、quota変更、停止、解約 |
| customer_devices | 端末一覧・追加・停止・復帰・昇格・失効・QR再発行 |
| admin_logs | 全管理操作・発行処理の監査ログ記録 |
8 — 実装優先順位
1契約一覧 / 契約詳細 / 端末一覧 ✅ 完了
2子端末追加 ✅ 完了
3pause / resume ✅ 完了
4QR再取得 ✅ 完了
5親端末昇格 / revoke ✅ 完了
6Nextcloud連携（ID・PW・容量自動生成・使用量表示）🔲 未実装
“`