よくある質問と基本 API (FAQ)

一般的なトラブルシューティングガイド

Q: サービスの起動後、管理コンソールに「バックエンドに接続できません」というプロンプトが表示されるのはなぜですか？

A: これは通常、フロントエンドとバックエンドの通信のためのクロスオリジン・リソース・シェアリング (CORS) または WebSocket アドレスの設定の誤りによって引き起こされます。 以下の手順に従ってトラブルシューティングを行ってください：

1. docker-compose.community.yml で Admin UI と AppServer に割り当てられたポートマッピング (デフォルトは 5173 / 3000) が正常に実行されているか確認します。
2. 設定ファイル .env のバックエンドアドレス URL が仮想ドメイン名ではなく、外部から解決可能な IP になっているか確認します（例：VITE_API_BASE_URL=http://<あなたのIP>:3000/api/v1）。
3. 「接続のトラブルシューティングの章」を参照して再試行します。

Q: 管理インターフェースにリアルタイムの通話カードがポップアップ表示されないのはなぜですか？

A:

• まず、左下にある「マスターコンソールの接続ステータス (WebSocket)」が緑色で点灯し続けているかを確認します。
• 基盤となる収集エンジン (IE コンテナ) が、ソース側の PBX (Asterisk / FreeSWITCH など) から送信された SIP/HEP シグナリングを受信したか確認します。次のコマンドを実行して、解析ログが流れているか確認します：

  docker-compose logs -f ie

• ログがない場合は、アップストリーム・スイッチがパケットを IE サーバーの特定のポート (デフォルト UDP 9060 / UDP 5060) にルーティングしているか調査してください。

Q: Windows ホストマシンからのシステムのデプロイはサポートされていますか？

A: 技術的には、WSL2 と Docker Desktop を介した本システムの実行をサポートしています。しかし、特に高頻度でマルチチャネルの UDP/RTP 通信を伴うソフトウェアの場合、Windows への本番環境でのデプロイは強く避けることをお勧めします。Linux (Rocky / Ubuntu) のカーネルネットワークスタックは、飛躍的に優れたパフォーマンスと安定性の保証を提供できます。

---

オープンな基本 API リファレンス

システムは、統合開発者向けの一連の基本的な RESTful API を提供します (このシステムは継続的な進化の過程にあり、詳細な入力パラメータとコールバックモデルはバージョンによってわずかに異なる場合があります)。 API を使用するには、リクエストヘッダーに管理者または API トークンを含めてください：Authorization: Bearer <Token>。

1. ライブネス・プローブとヘルスチェック

GET /api/v1/health

• 目的: システムの基本マイクロサービス・セットのハートビート生存メトリクスと、依存ライブラリのレイテンシを返します。

2. リアルタイム・アクティブ通話セットの取得

GET /api/v1/calls/active

• 目的: 現在、システム全体でアクティブな状態 (確立中/呼び出し中/通話中) にある通話の JSON データテーブルと概要情報を取得します。

3. エージェント指標ダッシュボードカード統計の取得 (例)

GET /api/v1/metrics/agents

• 目的: キュー待機中、応答中、アラームイベントの発生など、本日のマクロなエージェントメトリクスを照会します。