Spielogue

ゲームのデータベースに対する提案を作成する。 targetGameItemId を **省略すると新規ゲーム提案**、**指定するとその game_item の更新提案**。 draft は自然な構造化オブジェクトで、指定したフィールドだけが提案変更内容になる。 名前（nameJa / nameEn）が既存ゲームと正規化後に完全一致するとデフォルトで拒否される。 別物として登録したい場合は acknowledgeDuplicateOf に重複先の gameItemId を指定すること。 同じゲームの別パッケージ（同 definition の別 item）として登録したい場合は acknowledgeAsSameDefinitionOf に重複先の gameDefinitionId を指定する。 値に確信がない時は、まず dryRun: true で検証してポリシー警告（warnings）を確認してから本提案すること。 既存の誤った値を「未設定」に戻す時は null を明示する（省略では消せない）。例: 公式に上限が存在しないのに登録されている場合は playTimeMinutes: { max: null }。数値・日付系（playerCount / playTimeMinutes の min・max、recommendedAge、releasePriceJpy、packageDimensions の各辺、initialReleaseDate、japanReleaseDate）と文字列系（nameEn / slug / description / playTimeNote）が null を取る。 【省略フィールドの扱い】draft オブジェクトに **含めなかったフィールドは「変更しない」** として扱われる。確認できなかった値は無理に埋めず、省略してレビューに回すこと。空欄でレビューされるほうが、誤った値で承認されるより安全。 【値を消す】既に入っている値を「未設定」に戻したい時は **null を明示する**（省略では消せない）。null を受け付けるフィールドは各フィールドの説明に明記してある。 【全部外す】配列フィールド（mechanics / designers / cardSizes / seriesIds / links 等）は **null が「全て外す」**。例外は無いので、消したい時は常に null を送れば良い。なお空配列は多くのフィールドで拒否される — 絞り込みの結果たまたま空になった指定と、意図した全削除とを区別できないため。 各フィールドの入力ポリシーは以下の通り。Web のフォームと公開ドキュメント /docs/game-data-policy でも同じ内容を参照できる。 【ゲーム種別】(game_definitions.kind) 理由: ゲーム種別は、サービス内の各画面でその作品・パッケージをどう扱うかを決めます。拡張なのにベースゲームとして登録されると、本来「ベースと一緒に遊んだ」と記録すべき場面で単独の作品のように扱われたり、アクセサリやプロモがベース作品と並んでコレクションの主役を埋もれさせたりしてしまいます。登録段階で正しく分類しておくことで、こうした表示や集計の食い違いを防いでいます。 - ベースゲーム … これ単体で遊べる、基本となる作品。 - 独立拡張 … 単体でも遊べる作品。ベースゲームと混ぜても遊べる。 - 拡張 … 遊ぶにはベースゲームが必要な作品。 - バンドル … 複数の作品を詰め合わせただけで、それ自体に固有のプレイ体験がないパッケージ。ベースゲームの新版に拡張が同梱されている場合はベースゲームのまま、中身を「同梱物」として記録する。 - アクセサリ … スリーブやオーガナイザー等。親となる作品は持たない。特定のゲーム専用なら「対応ゲーム」を指定して紐づける。 - プロモ … プロモカードなど小規模な追加コンテンツ。 良い例: カタン 航海者版 → 拡張 メモ: 遊ぶにはカタン本体が必要なので、独立拡張ではなく拡張 良い例: ウイングスパン 東洋の翼 → 独立拡張 メモ: 単体でも遊べて、ウイングスパン本体と混ぜても遊べる 良い例: 単体で遊べるが、ベースと混ぜて遊ぶ想定がない姉妹作 → ベースゲーム メモ: 「独立拡張」はベースゲームと混ぜても遊べる作品だけ。混ぜられないなら独立したベースゲームとして登録する 良い例: カタン用の追加シナリオカード 1 枚 → プロモ メモ: イベント配布や特典などのおまけ規模はプロモ。単体の商品として流通する追加コンテンツは拡張が目安 【パッケージ名（日本語）】(game_items.name_ja) 理由: Spielogue では「同じ内容の別パッケージ」（例: 新装版・豪華版）は同じ作品として扱います。「カタン 日本語版」「カタン 英語版」のように言語ごとに別の名前で登録すると、本来同じ作品のプレイログやレビューが分散してしまい、人気・評価・統計といったサービスの基本機能が成立しなくなります。そのため、名前本体のみを入れることを基本ポリシーにしています。 - 公式の日本語表記（パッケージ／出版社サイト）を入れる。ひらがな・カタカナ・漢字のいずれかを必ず含める（英字だけの名前はここには入れない）。 - 「日本語版」「JP 版」など言語版の表記は付けない。名前本体だけを入れる。 - 「初版」「第1版」「旧版」「無印」「オリジナル版」のように、新版が出てから振り返って付くだけで実際のパッケージや出版社告知に書かれていない相対呼称は含めない。 - 「新装版」「2024年版」「20周年記念版」など、出版社が公式名として冠している表記はそのまま入れる。 - 正式な版名・版別の呼称が存在しないパッケージには、無理に別名を付けない。同じ名前のパッケージが複数あっても、発売年で区別して表示される。 - 副題は全角コロン「：」で区切る。 - 公式の日本語表記が存在しない場合（日本未発売など）は、原題のカタカナ転写を入れてよい。転写に確信が持てなければ、空欄のまま送る。 - 国産作品でも公式表記が英字のみの場合は、英字名に公式表記を、日本語名に一般に使われている読みのカタカナを入れる（例: 英字名「XENO」・日本語名「ゼノ」）。読みが定まらなければ日本語名は空欄のまま送る。 良い例: カタン 悪い例: カタン 日本語版 良い例: 宝石の煌めき 悪い例: 宝石の煌めき 初版 メモ: 「初版」は新版が出てから生まれる呼称。当時のパッケージにはその表記がない 良い例: カルカソンヌ 悪い例: カルカソンヌ 旧版 メモ: 「旧版」も後付け。新版側にだけ「2024年版」「新装版」など実在の表記を入れて区別する 良い例: ナンジャモンジャ・シロ 悪い例: ナンジャモンジャ メモ: シロ／ミドリ等は別作品なので、パッケージ名の段階で区別する 良い例: アークノヴァ メモ: 日本未発売だった時期のカタカナ転写の例 【パッケージ名（英字 / 原題）】(game_items.name_en) 理由: 原題と日本語の名前は別フィールドで持っています。これは「日本語の表記が思い出せないが英字なら覚えている」といった検索や、海外コミュニティ情報との突き合わせのためです。ここに勝手な英訳を入れると、他ユーザーが原題で検索したときにヒットしないか、二重登録の温床になってしまいます。 - 原題（または国際的に使われる表記）を入れる。勝手な英訳はしない。 - 原題が英語以外（ドイツ語など）の場合は、国際的に広く使われている表記（多くは英語版タイトル）を入れてよい。 - 副題は半角コロン + 半角スペース「: 」で区切る（例: Terraforming Mars: Prelude）。 - 「Japanese Edition」「JP Version」のような言語版サフィックスは付けない。 - 「1st Edition」「Original」のように、新版が出てから振り返って付くだけで実際のパッケージや公式名には書かれていない相対呼称は含めない。 - 「Anniversary Edition」「Revised Edition」「Classic Edition」など、出版社が公式名として冠している表記はそのまま入れる。 - 公式の英題がない場合（日本でしか発売されていない国産作品など）は、空欄のまま送る。 良い例: Wingspan 悪い例: Wingspan Japanese Edition メモ: 日本だけで発売されている国産作品は空欄でよい 【作品名（日本語）】(game_definitions.name_ja) 理由: Spielogue では「カタン」のように、パッケージを区別せず作品単位で語る場面が多くあります。作品名は、プレイログやレビューの集計、ゲーム詳細・プレイ実績画面の見出し、検索など、パッケージをまたいで作品を指すあらゆる場面で使われる名前です。各パッケージの正式な名前は「パッケージ名」に、それらをまとめる作品そのものの名前をここに入れます。 - 作品をまとめて指す名前を入れる。 - 表記ルールはパッケージ名（日本語）と同じ（日本語必須・言語サフィックスなし）。 - 普段はパッケージ名と同じでよい。新装版などパッケージごとに名前が違う時だけ、作品名を別途指定する。 良い例: カタン メモ: パッケージ「カタン」と「カタン 新装版」をまとめる作品名。普段はパッケージ名と同じでよい 【作品名（英字）】(game_definitions.name_en) 理由: 用途は「作品名（日本語）」と同じです。海外コミュニティ情報との突合や英字検索のために、英字でも持てるようにしています。 - ルールはパッケージ名（英字）と同じ。 【文脈内名称（日本語）】(game_items.contextual_name_ja) 理由: ゲームは、シリーズの一覧、ベースゲームと拡張のセット、同じ作品の版違いなど、関連するゲーム同士を並べて表示する場面が多くあります。このとき正式名「テラフォーミング・マーズ：プレリュード」をそのまま並べると、共通部分の「テラフォーミング・マーズ」が冗長で、肝心の「プレリュード」が読み取りにくくなります。並べる文脈で読みやすくするための短い名前がこのフィールドです。 - 拡張・シリーズ内・版違いなど、関連ゲームと並べて表示される場面で使う。 - 共通部分を繰り返さず、それだけで識別できる短い名前にする。 - 正式名が十分短いなど、並べても読みにくくならない場合は空欄でよい。空欄ならパッケージ名がそのまま表示される。 - 表記ルールはパッケージ名（日本語）と同じ（日本語必須・言語サフィックスなし）。 良い例: プレリュード 悪い例: テラフォーミング・マーズ：プレリュード メモ: 「テラフォーミング・マーズ」の拡張。並べて表示される場面では共通部分を繰り返さない 良い例: 新装版 メモ: 「カタン 新装版」を版違い同士で並べる場面では「新装版」だけで識別できる 【文脈内名称（英字）】(game_items.contextual_name_en) 理由: 用途は「文脈内名称（日本語）」と同じです。海外コミュニティ情報の突合や、英字表示モードでの可読性のために用意しています。 - ルールはパッケージ名（英字）と同じ。 【プレイ人数（最小）】(game_definitions.min_player_count) 理由: ユーザーは「今日は3人だから何が遊べる？」のように、人数を起点に作品を探します。ここにハウスルールでの可能人数を入れてしまうと、検索結果が当てにならなくなり、「公式には2人用のはずなのに 1 人として登録されている」といった食い違いが頻発します。出版社・ルールブックの値を一次ソースとして揃えることで、人数フィルタが信頼できる前提を作ります。 - 公式ルールブックに記載された人数の下限を入れる。 - 公式のソロモードがある作品は 1 を入れる。プレイモードにも「ソロ」を追加する。 - ソロモードが拡張などで後から追加された場合は、ベース作品の人数は変えず、その拡張側の人数に反映する。 - 拡張作品にも、その拡張自身のパッケージ／ルールブックに記載された人数を入れる（例: カタンの 5〜6 人用拡張なら最小 5・最大 6）。記載がなければ空欄のまま送る。 【プレイ人数（最大）】(game_definitions.max_player_count) 理由: 最小人数と同じく、人数フィルタや「大人数で遊べる作品」のおすすめが正しく動くために、出版社が公式にサポートしている上限を入れます。「頑張れば 8 人でも遊べる」のような感覚の値は入れません。 - 公式ルールブックに記載された人数の上限を入れる。 - 上限が公式に明記されていない場合は、無理に推定せず空欄のまま送る。 【プレイ時間（最短）】(game_definitions.min_play_time) 理由: プレイ時間は「短時間で遊べる作品を探す」に直結する重要な軸です。ティーチング（ルール説明）時間は経験者・初心者で何倍も変わるため、これを含めると作品自体の性質を表す指標になりません。純粋なプレイ時間を入れることで、ユーザーが時間軸で検索したときの期待を裏切らないようにしています。 - 公式パッケージ／ルールブックに記載の値を採用する。 - ティーチングやセットアップは含めない（純粋なプレイ時間だけを入れる）。 - 「30〜60 分」と幅がある場合は下限（30）を入れる。 - 「1 人あたり 30 分」のような人数比例の表記は、公式の人数範囲から計算した値を入れ、元の表記はフォームの「プレイ時間の補足」に書く。 【プレイ時間（最長）】(game_definitions.max_play_time) 理由: 最短時間と同じ理由で、時間検索が信頼できる前提を作るための値。慣れたグループの「いつもこれくらいで終わる」という実感ではなく、出版社が想定している上限を入れます。 - 公式パッケージ／ルールブックに記載の値を採用する。 - ティーチングやセットアップは含めない。 - 公式の表記が「30 分」のように単一の場合は、最短・最長の両方に同じ値を入れる。 【推奨年齢】(game_definitions.recommended_age) 理由: 推奨年齢は「子どもと遊べる作品を探す」「家族向けにハードルを揃える」といった用途に使われます。個人の感じ方（うちの子は 5 歳でこれが遊べた、など）で上書きされると参考値として機能しないため、出版社の表記を統一の基準として採用します。 - 公式パッケージ／ルールに記載された対象年齢の数値を入れる（「8+」「10歳〜」なら 8 や 10 の数値部分だけ）。 - 版や地域によって表記が異なる場合（例: 旧版は「12+」・新版は「8+」）は、公式サイトの最新の表記を採用する。 - 推奨年齢が公開されていない作品は、空欄のまま送る。 良い例: 8 悪い例: 8+ メモ: 数値だけを入れる。「8歳以上」のような表示はサービス側で付ける 【プレイモード】(game_definitions.play_modes) 理由: 「協力作品が好き」「ソロでも遊びたい」のような探し方は強いニーズがあります。出版社が公式に提示しているモードはサービスの推薦に使えますが、ファンが考えた派生ルールでのモードは再現性が保証されないため、これを混ぜるとフィルタの意味がブレます。 - 競争 … 全員が個別に勝利を目指す（標準的な対戦）。 - 協力 … 全員で共通の目標に挑む。 - チーム戦 … 2 チーム以上に分かれて対戦する。 - 1 対多 … 1 人が残り全員と対立する非対称型（例: 1 人の敵役・逃走役 vs 残り全員）。 - ソロ … 公式のソロモードがある場合のみ選ぶ。 - 公式ルール内のバリアント（公式に提示された別ルール）で遊べるモードは含めてよい。 - ファンが考えた派生ルールでのモードは含めない。 【メカニクス】(game_definitions.mechanics) 理由: メカニクスは「このメカニクスが好きな人にこの作品」というおすすめの軸です。1 つの作品に「あれもこれも」と全部選んでしまうと、フィルタとしてもおすすめとしても機能しなくなり、ユーザーが好きな作品を発見する仕組みが壊れます。実際にプレイ体験を左右している要素だけを選ぶことが大切です。 - プレイ体験を実際に左右しているものだけを選ぶ。「あれもこれも」と網羅しない（目安は多くても 5 個程度）。 - 迷ったら公式紹介文・出版社サイトの記述を一次ソースとして参照する。 - それでも判断がつかないものは選ばず、空欄のまま提案を送ってよい。 - 拡張で追加されるメカニクスは、その拡張の体験の中心になるときだけ、拡張側に追加する。 【共通の補足】 - クレジット名（designers / artists / publishers）も日本語表記を優先。既存 PERSON / ORGANIZATION entries は日本語表記で登録されており、英語のみで送ると別エンティティとして二重登録される。 - シリーズ名（seriesNames）も同様に日本語表記を優先。承認時に name_ja / name_en の完全一致で名寄せされるため、表記が揺れると重複シリーズができる。 - 一次ソース（出版社公式 / ボドゲーマ等）で確認できない値は省略し、レビューに回す。空欄でレビューされる方が、誤った値で承認されるより安全。

database_game_propose

Spielogue のゲームデータベースを部分一致 + 類似度で検索します。プレイログやコレクション登録時に対象 game_item_id を確定するために使用します。各結果は gameItemId（パッケージ単位）と、その item が属する作品の gameDefinitionId を返します。2 件が同一作品かは gameDefinitionId の一致で判別できます。

database_game_search

game_item_id を指定して詳細情報（人数・時間・説明・デザイナー等）を取得します。レスポンスには、その item が属する作品の gameDefinitionId も含まれます。パッケージ名（nameJa / nameEn）とは別に、作品名（definitionNameJa / definitionNameEn）も返します。両者がずれている（作品名にパッケージ固有の版表記が混ざっている等）時はdatabase_game_propose の definitionNameJa / definitionNameEn で作品名だけを直せます。

database_game_get

既存の game_play に play_partners を participants として紐づけます。is_winner / fun_level (1-5) / memo を任意で記録できます。

playlog_participant_attach

1 件の game_play を削除します。誤爆防止のため、confirm.expectedName にはそのプレイのゲーム名を渡します。plays[] は名前を持たないので、playlog_session_get の plays[].gameItemId を database_game_get で引いた nameJa / nameEn を使います。gameItemId が null（カスタムタイトル）の play は、collection_game_list の items[].id を plays[].userGameId で突き合わせ、その行の customGameTitle を使います。サーバが現在の対象と照合し、不一致なら CONFIRM_TARGET_MISMATCH で拒否します。ユーザーに対象を提示して同意を得てから呼んでください。

playlog_play_delete

個別の game_play の人数・所要時間・ゲスト数を更新します。

playlog_play_update

YouTube / Vimeo の動画 URL を指定ゲームに紐付けて登録します。URL から provider と external_id を解析し、oEmbed でタイトル・公開日・尺を補完します。同一ゲーム × 同一動画の重複は ALREADY_EXISTS で reject します。誤爆防止のため、confirm.expectedName には対象ゲームの名前（database_game_search / database_game_get が返す nameJa / nameEn）を渡します。サーバが gameItemId の現在のゲームと照合し、不一致なら CONFIRM_TARGET_MISMATCH で拒否します。ユーザーに対象ゲームと URL を提示して同意を得てから呼んでください。

database_video_submit

指定ゲーム（game_item_id）に紐付く YouTube / Vimeo 動画を like 数の多い順に一覧します。各動画には provider・external_id・URL・タグ・尺・投稿者 ID が含まれます。

database_video_list

user_game をコレクションから削除します。誤爆防止のため、confirm.expectedName には削除する行のゲーム名（collection_game_list の items[].customGameTitle、またはその行の gameItemId を database_game_get で引いた nameJa / nameEn）を渡します。サーバが現在の対象と照合し、不一致なら CONFIRM_TARGET_MISMATCH で拒否します。ユーザーに対象を提示して同意を得てから呼んでください。

collection_game_remove

コレクションに 1 行追加します。ID 種別は 3 つで紛らわしいので注意: (1) gameItemId = データベースの具体的なパッケージ（例: カタン日本語版 2024）、(2) gameDefinitionId = データベースの作品単位（例: カタン全般、パッケージを問わず同じ）、(3) customGameTitle = データベース未登録のフリーテキスト。いずれか 1 つを指定。パッケージを確定したい場合は gameItemId を渡し、ぼやかしたい場合は gameDefinitionId、データベースにないなら customGameTitle を使う。status は OWNED / WANT / PREORDERED / PREVIOUSLY_OWNED から選択。

collection_game_add