MF-1 仕様

位置付け

機材ID: MF-1
名称: 演出用PCデータ（旧 CMS 機能内包）
担当: タングラム（Uniba）
物理構成: 独立サーバではなく、MD-2（顔登録の演出用PC）内のデータストアとして組み込まれる。MF-1 は論理 CMS の呼称。
役割: visitor_id をキーに、顔パラメータ（ひつじの顔画像分析エンジンが割り出したパラメータ。本仕様では metadata として保存）を保管し、各ゾーン（Z-2 ホスピタリティ／Z-3 イマーシブ／Z-4 アクセラレーション／Z-5 クリエーション）の演出用PCが再利用できるようにする。
想定モデル: レセプション顔登録の完了直後に 演出プログラムが 1 回 PUT（metadata 保存） → 後続の各ゾーン演出PCが GET で再利用 （2026-05-27 MTG）。
位置づけの根拠: 顔情報のやり取りの基本方針「visitor_id と顔パラメータを紐づけたデータはユニバで保存する」「顔パラメータの取得・保存の API の口を用意する」を実装する機材が MF-1。

実装との整合（2026-06-05）: 本仕様の API 面はモック実装 nec-bss-mock #104 に合わせて更新済み。ベースパスは /api/datastore、保存は PUT、顔パラメータの保存キーは metadata（旧称 features）。実装の対応エンドポイント（DS-1〜7）は docs/face-registration/API.md のデータストア API 節を参照。グループ内訪問者一覧のみ、ネスト形 /api/datastore/groups/{group_id}/visitors（本仕様）に実装側を合わせる予定。

シーケンス概観

MF-1 を中心とした「顔パラメータの書き込み」と「他演出ゾーンからの参照」を 1 枚で図示する。

API 一覧

visitor_id／group_id をキーとする 5 つのエンドポイントを提供する。

API ID	エンドポイント	概要	主な呼び出し元
MF1-API-1	`GET /api/datastore/visitors/{visitor_id}/face`	顔画像（jpeg）取得	各ゾーンの演出用PC
MF1-API-2	`PUT /api/datastore/visitors/{visitor_id}/metadata`	顔パラメータ（metadata）の保存	ホスピタリティのひつじ演出 PC（MD-5）
MF1-API-3	`GET /api/datastore/visitors/{visitor_id}`	レコード取得（metadata・顔画像 URL・更新時刻）	各ゾーンの演出用PC
MF1-API-4	`GET /api/datastore/groups`	グループ一覧取得（既定は当日、`?date=YYYYMMDD` 指定可）	各ゾーンの演出用PC（オペレーター操作の起点）
MF1-API-5	`GET /api/datastore/groups/{group_id}/visitors`	グループ内の訪問者一覧取得	各ゾーンの演出用PC

用語: 顔パラメータの保存・取得キーは metadata（旧称 features）。実態は顔情報のやり取りで定義される 顔パラメータ（ひつじの顔画像分析エンジンが割り出したパラメータ。NES 顔特徴量とは別物）。命名は実装（#104）に合わせ metadata で確定（旧論点 6 は解消）。

MF1-API-5 のパス: モック実装 #104 はグループ全件取得を GET /api/datastore/groups/{group_id} で提供するが、本仕様の /groups/{group_id}/visitors（visitors サフィックス付き） に合わせて実装側を修正する方針。

プロトコル: HTTP/REST。ベースパスは /api/datastore（演出用PC = MD-2 と同一ホスト・同一ポート）
保存メソッド: PUT（同一 visitor_id への再保存は upsert で上書き）
metadata はスキーマレス: 保存した JSON をそのまま保持・返却（MF-1 は中身を解釈しない）
共通レスポンスヘッダ: 認証は同一 LAN 想定で当初は無認証（CORS 等は実装に準拠）
追加の操作（顔画像キャッシュ PUT …/face、metadata クリア DELETE …/metadata）はモック実装の DS-5／DS-7 を参照

エラーレスポンス

エラー時のレスポンス本体は共通フォーマット。

json

{
  "error": "human-readable message",
  "code": "ERROR_CODE"
}

HTTP ステータス	`code` 例	意味
400	`INVALID_REQUEST`	リクエスト不正（JSON パース失敗、必須項目欠落等）
404	`NOT_FOUND`	該当 `visitor_id` が存在しない
500	`INTERNAL_ERROR`	サーバ内部エラー

備考:

code は SCREAMING_SNAKE_CASE。
バイナリ応答（MF1-API-1 の jpeg）でもエラー時は本フォーマット（application/json）に切り替えて返す。

MF1-API-1: 顔画像取得

GET /api/datastore/visitors/{visitor_id}/face

項目	内容
用途	各ゾーンの演出用PCが、入場検知時に対象訪問者の顔画像を取得する
パスパラメータ	`visitor_id`（string）
レスポンス（200）	`Content-Type: image/jpeg`、本体は jpeg バイナリ
レスポンス（404）	該当 `visitor_id` の画像が存在しない（エラーレスポンス参照）

備考:

画像形式は jpeg（zeroMQ 経由で受け取る GW 配信が jpeg のため、API もこれに揃える / 2026-05-27 確定）。
画像のサイズはカメラから切り出した顔領域。人により変動（2026-05-27 MTG）。
他ゾーンからの顔画像取得口は MF1-API-1 に一本化（NETWORK.md の「ME-2／ME-1 へ接続するのは MD-2 のみ」方針と整合）。共有マネージャ API-3 は MD-2 内部の取得経路として利用、他ゾーン演出 PC は直接叩かない。
画像の破棄タイミングは ME-2（共有マネージャ）の動作に合わせる（2026-06-04 MTG）。

MF1-API-2: 顔パラメータ（metadata）の保存

PUT /api/datastore/visitors/{visitor_id}/metadata
Content-Type: application/json

項目	内容
用途	ホスピタリティのひつじ演出 PC（MD-5）が、`visitor_id` ごとに算出した顔パラメータを保存する。顔登録完了直後（顔画像・visitor_id を MD-2 から push 受信した直後）に 1 回 `PUT` する
パスパラメータ	`visitor_id`（string）
リクエスト本体	任意の JSON（スキーマレス）— 演出プログラムが必要とするフィールドを自由に格納
レスポンス（200）	保存後のレコード（MF1-API-3 と同形）を返す
レスポンス（4xx）	バリデーション失敗等（エラーレスポンス参照）

リクエスト例（あくまで形式の参考。フィールド構造はひつじさん側で確定）:

json

{
  "name": "山田 太郎",
  "identity": {
    "color_palette": ["#a1c4fd", "#c2e9fb"],
    "particle_pattern": "wave_a",
    "seed": 12345
  },
  "metadata": {
    "computed_at": "2026-06-03T10:15:30+09:00"
  }
}

備考:

スキーマレスで受け、そのまま返す方針（2026-05-27 確定）。鍵はあくまで visitor_id 単位。
上記フィールド構造はひつじさん側で確定する想定。MF-1 は中身を解釈しない。
同一 visitor_id への複数回 PUT は 上書き（upsert）。顔画像キャッシュは保持される（metadata のみ更新）。
同意のみ完了者（同意 OK・顔登録 NG）は visitor_id を持たないため、本 API は呼ばれない。
保存主体は ホスピタリティのひつじ演出 PC（MD-5） で確定（2026-06-04 MTG）。モック実装 #104 では、検証用にレセプション顔登録完了（GW-EVT-6）時のサーバ側自動保存でも同等の metadata を投入する（API.md プロセス C 参照）。

MF1-API-3: 顔パラメータの取得

GET /api/datastore/visitors/{visitor_id}

項目	内容
用途	各ゾーンの演出用PCが、MF1-API-2 で保存された値を取得して再利用する（パーソナライズ演出のパラメータ参照等）。顔パラメータは `metadata` フィールドに入る
パスパラメータ	`visitor_id`（string）
レスポンス（200）	`Content-Type: application/json`。`metadata`（MF1-API-2 で保存した JSON）・`face_image_url`・`updated_at` を含むレコード
レスポンス（404）	該当 `visitor_id` のレコードが存在しない（未保存・同意のみ完了者等。エラーレスポンス参照）

レスポンス例（200。metadata に MF1-API-2 で保存した JSON がそのまま入る）:

json

{
  "visitor_id": "v_001",
  "face_image_url": "http://md-2.local:3000/api/datastore/visitors/v_001/face",
  "metadata": {
    "name": "山田 太郎",
    "identity": {
      "color_palette": ["#a1c4fd", "#c2e9fb"],
      "particle_pattern": "wave_a",
      "seed": 12345
    },
    "computed_at": "2026-06-03T10:15:30+09:00"
  },
  "updated_at": "2026-06-03T10:15:30.000Z"
}

備考:

metadata はスキーマレス JSON。フィールド構造は MF1-API-2 で保存した内容に依存する。
face_image_url は顔画像キャッシュがあれば取得 URL（MF1-API-1 の実体）、なければ null。
「使い回す」想定（2026-05-27 MTG）。各ゾーン演出は同じ visitor_id で同じ値を参照することで体験の一貫性を担保。

MF1-API-4: グループ一覧取得

GET /api/datastore/groups            # 既定は当日（JST）
GET /api/datastore/groups?date=YYYYMMDD   # 日付指定

項目	内容
用途	訪問予定のグループ一覧を取得する。各ゾーン演出 PC のオペレーター操作（タブレットで `group_id` を選択）の起点
クエリ	`date`（任意、`YYYYMMDD`）。省略時は当日（JST）
レスポンス（200）	`Content-Type: application/json`、対象日 `date` とグループ配列。該当無しは `groups: []`

レスポンス例（形式の参考）:

json

{
  "date": "20260604",
  "groups": [
    { "group_id": "g_2026_06_04_abc", "group_name": "株式会社ABCDEFG", "visit_date": "20260604", "language": "ja", "visitor_count": 5, "record_count": 3 },
    { "group_id": "g_2026_06_04_xyz", "group_name": "株式会社XYZ", "visit_date": "20260604", "language": "ja", "visitor_count": 3, "record_count": 0 }
  ]
}

備考:

2026-06-04 MTG で「グループの情報は必要」「パラメータなしに group のリストを返却する」と確定。既定当日＋?date= 指定は実装（#104）に準拠。
record_count は当該グループのうち MF-1 にレコード（metadata or 顔画像）が存在する数。
データ源は MD-2 が保持する訪問グループ情報（ME-2 API-1 で取得済みのもの）。

MF1-API-5: グループ内訪問者一覧取得

GET /api/datastore/groups/{group_id}/visitors

モック実装 #104 はグループ全件取得を GET /api/datastore/groups/{group_id} で提供しているが、 本仕様の /groups/{group_id}/visitors（visitors サフィックス付き）に実装側を合わせる方針。

項目	内容
用途	指定グループ内の訪問者一覧を、MF-1 のレコード（metadata・顔画像 URL）を併記して全件取得する。各ゾーン演出 PC が group_id 起点で対象訪問者を辿り、特徴量をまとめて再利用する
パスパラメータ	`group_id`（string）
レスポンス（200）	`Content-Type: application/json`、訪問者配列。MF-1 未保存の訪問者も含め、その分は `metadata`／`face_image_url` を `null` で返す
レスポンス（404）	該当 `group_id` が存在しない（エラーレスポンス参照）

レスポンス例（形式の参考）:

json

{
  "group_id": "g_2026_06_04_abc",
  "group_name": "株式会社ABCDEFG",
  "visit_date": "20260604",
  "language": "ja",
  "visitors": [
    {
      "visitor_id": "v_001",
      "visitor_name": "山田 太郎",
      "face_status": "complete",
      "face_image_url": "http://md-2.local:3000/api/datastore/visitors/v_001/face",
      "metadata": { "name": "山田 太郎", "identity": { "seed": 12345 } },
      "updated_at": "2026-06-03T10:15:30.000Z"
    },
    {
      "visitor_id": "v_002",
      "visitor_name": "鈴木 花子",
      "face_status": "still",
      "face_image_url": null,
      "metadata": null,
      "updated_at": null
    }
  ]
}

備考:

2026-06-04 MTG で「group_id キーで visitor の一覧を返す」と確定。
face_status（共有マネージャー仕様の登録状態 still／inprocess／provisional／complete／error）で「顔登録完了済み／同意のみ完了」を区別でき、各ゾーンが該当者だけを対象に演出を組み立てやすい。
個別訪問者の顔パラメータ・顔画像が必要な場合は、得られた visitor_id を使って MF1-API-1 / MF1-API-3 を呼び出す（本 API のレスポンスに同梱済みのため通常は不要）。

データ保持・破棄ポリシー

2026-05-27 MTG での合意:

当日中に破棄 が原則。
ただし再訪に備え、顔画像は破棄するが演出関連データの一部は永続化する。
バックアップは 3 台（MD-2〜MD-4）に同期・コピーで充分。
故障時は数営業日で復旧できれば良い温度感。
MD-2〜MD-4 のうち 1 台がアクティブ、他 2 台はコールドスタンバイ。可用性担保は 3 台全てでは不要、トラブル時はネットワーク設定切り替えで代替。
画像の破棄タイミングは ME-2（共有マネージャ）の動作に合わせる（2026-06-04 MTG）。MF-1 単独で破棄方針を持たず、ME-2 と同期して破棄する。

未確定: 「演出関連データの一部」の具体的な範囲（氏名のみか／会社情報・嗜好データを含むか）は要詳細化。

設計上の論点

未確定の主要な論点をまとめる。順次チーム内で詰めて反映する。

論点 1〜4 は 2026-06-04 までに解消済み（UPDATES.md 参照）。下記は引き続き検討対象。

論点 5: NES 顔特徴量を MF-1 に保管するか

本仕様の MF1-API-2 が「顔パラメータの保管」に寄ったことで、NES が算出する顔特徴量ベクトル を MF-1 に保管するかは別の論点として浮上した。なお顔情報のやり取りは「visitor_id と顔パラメータを紐づけたデータをユニバで保存」とするが、NES 顔特徴量については言及がない。

候補:

案	内容	メモ
P. 保管しない	MF-1 は顔パラメータ専用	既存 ARCHITECTURE の「演出用PCデータ＝NES 顔特徴量保管」の記述と齟齬 → 既存ドキュメント側を更新する必要
Q. 別エンドポイントで保管	`PUT /api/datastore/visitors/{visitor_id}/nes_metadata` 等を追加	用途が明確に分離できる
R. 同一エンドポイント（顔パラメータと一緒に）	演出プログラムが NES 特徴量も `metadata` JSON に含めて PUT	結合度高、ひつじさんが NES 値を扱う前提

→ 要確認。元々の MF-1 想定（NES 顔特徴量保管）から大きく外れているので、整合を取る必要あり。

論点 6: エンドポイント名称 `features` の妥当性（解消）

解消（2026-06-05）: 保存・取得キーは metadata に確定（モック実装 #104 に合わせる）。パスの features は廃止。metadata はスキーマレスな汎用名で、NES 顔特徴量との誤読リスクも回避できる。中身が顔情報のやり取りの 顔パラメータ である点は本仕様冒頭の「用語」注記で明示する。

論点 7: リアルタイム配信モデル（push 型 / MQTT WebSocket）

2026-06-04 MTG での新規論点: ホスピタリティでは顔登録完了直後に即座にビジュアルを出す要件があるため、プル型（GET 待ち）だけでは不足で push 型のリアルタイム配信が必要。

合意の方向性:

経路 1: 顔登録完了 → MD-5（ひつじ演出 PC）への push

uniba（MD-2）が push 元、MD-5 が受信
ペイロード: 顔画像 + visitor_id。「誰の顔登録が終わったら id と画像を送る」モデル
MD-5 で顔パラメータを算出（< 1 秒）→ MF1-API-2（PUT …/metadata）で MF-1 に保存

経路 2: 顔パラメータ確定 → 他ゾーン演出 PC への push

MF-1（または MD-2）から各ゾーン演出 PC（MD-6 アクセラ／MD-7 イマーシブ／MD-8 クリエーション）へ push
ペイロード: visitor_id + 顔パラメータ（+ 顔画像が必要なら）

共通プロトコル:

MQTT WebSocket（タブレットで既に使用、各ゾーン演出 PC も同様に揃える）
uniba から MQTT WebSocket クライアントライブラリと受信例を共有
「揃えてもらって大丈夫」「このライブラリ使って受け取れるよ」を共有予定

その他関連メモ:

ホスピタリティ前のメタデータ生成タイミング（撮れた人から順番 / 全員揃ってから）は 現場判断、両パターン対応できる作りが望ましい
鏡の演出での扱いは未決（そのまま）

→ 要設計: 既存の HTTP REST 5 エンドポイント（MF1-API-1〜5）と並行して、MQTT WebSocket の topic 設計・ペイロード仕様 を起こす。push が一次系統、HTTP は「後から取りに来る／再取得」用の補助系統という整理が自然。

既存プロセスID	対応 API	備考
PC-3 他演出配信	MF1-API-3 `GET /api/datastore/visitors/{visitor_id}`（プル型）＋ push 型配信（論点 7）	push が一次系統、HTTP は再取得用の補助系統
他演出ゾーンでの顔画像参照	MF1-API-1 `GET /api/datastore/visitors/{visitor_id}/face`	他ゾーンからの取得口は MF1-API-1 に一本化（共有マネージャ API-3 は MD-2 内部の取得経路として利用）

残課題

[ ] 論点 5: NES 顔特徴量を MF-1 に保管するか
[x] ~~論点 6: エンドポイント名称~~ → metadata で確定（2026-06-05）
[ ] 論点 7: MQTT WebSocket の topic 設計・ペイロード仕様
[ ] MF1-API-5 のパスを /groups/{group_id}/visitors へ実装側で修正（現状 #104 は /groups/{group_id}）
[ ] ベース URL（ホスト名・ポート）の確定。パス基底は /api/datastore で確定
[ ] 認証方式（無認証 or 簡易トークン）の決定
[ ] 永続化される「演出関連データ（metadata）」の具体スキーマ
[ ] レート制限／インターバル要件の API 仕様への落とし込み
[ ] ファイルサーバ要否（2026-05-27 残課題）との関係整理

MF-1 仕様 ​

位置付け ​

シーケンス概観 ​

API 一覧 ​

エラーレスポンス ​

MF1-API-1: 顔画像取得 ​

MF1-API-2: 顔パラメータ（metadata）の保存 ​

MF1-API-3: 顔パラメータの取得 ​

MF1-API-4: グループ一覧取得 ​

MF1-API-5: グループ内訪問者一覧取得 ​

データ保持・破棄ポリシー ​

設計上の論点 ​

論点 5: NES 顔特徴量を MF-1 に保管するか ​

論点 6: エンドポイント名称 features の妥当性（解消） ​

論点 7: リアルタイム配信モデル（push 型 / MQTT WebSocket） ​

関連プロセスとの対応 ​

残課題 ​

MF-1 仕様

位置付け

シーケンス概観

API 一覧

エラーレスポンス

MF1-API-1: 顔画像取得

MF1-API-2: 顔パラメータ（metadata）の保存

MF1-API-3: 顔パラメータの取得

MF1-API-4: グループ一覧取得

MF1-API-5: グループ内訪問者一覧取得

データ保持・破棄ポリシー

設計上の論点

論点 5: NES 顔特徴量を MF-1 に保管するか

論点 6: エンドポイント名称 `features` の妥当性（解消）

論点 7: リアルタイム配信モデル（push 型 / MQTT WebSocket）

関連プロセスとの対応

残課題