Appearance
API-003 新台情報 REST
概要
新台情報取得（ADM-023）と新台情報 機種マスタ紐付け（ADM-024）の操作を、管理画面を開かずに行うための REST。新台情報担当ロール（new_machine_editor）のユーザーがアプリケーションパスワードで呼ぶ。処理は両画面と同じ Service / Repository を使う。
API-003-1 POST /fetch
取得元サイト（DMM ぱちタウン）から新台情報を取得して upsert し、最終実行結果を保存する（ADM-023 の最終実行結果に表示される）。
入力（リクエスト）
| param | 必須 | 型・制約 | 説明 |
|---|---|---|---|
mode | いいえ | latest / last_month / past_month | 取得モード。省略時は latest。last_month / past_month は常にクールダウンを無視するため manage_options を持つユーザーのみ |
year | 条件 | 2000〜2100 | past_month のとき必須 |
month | 条件 | 1〜12 | past_month のとき必須 |
force | いいえ | bool（true / "1" 等） | クールダウンを無視する。manage_options を持つユーザーのときだけ有効で、それ以外は無視する |
出力（レスポンス）
| field | 型 | 説明 |
|---|---|---|
success | bool | true |
message | string | ADM-023 と同じ完了文言（一部サイトで問題があれば部分完了文言） |
result.inserted | int | 新規件数 |
result.updated | int | 更新件数 |
result.fetched | int | パース件数 |
result.skipped_sites | string[] | クールダウン等でスキップしたサイト |
result.failed_sites | string[] | 取得に失敗したサイト |
result.unregistered_sites | string[] | Scraper 未登録のサイト |
result.force_applied | bool | 強制取得が実際に適用されたか |
log | string[] | 実行ログ |
HTTP ステータス: 200
失敗・エラー条件
| 条件 | HTTP | message |
|---|---|---|
mode 不正・年月不正 | 400 | NewMachineFetchCopy::FETCH_MODE_INVALID |
manage_options を持たないユーザーが last_month / past_month を指定 | 403 | NewMachineFetchCopy::FETCH_MODE_ADMIN_ONLY |
| 取得処理で例外 | 500 | NewMachineFetchCopy::FETCH_FAILED（log 付き） |
API-003-2 GET /items
入力（リクエスト）
| param | 必須 | 型・制約 | 説明 |
|---|---|---|---|
filter | いいえ | unlinked / all | unlinked（省略時）は機種マスタ未紐付けの行（非表示も含む）、all は全行 |
include_masters | いいえ | bool | true のとき紐付け候補の機種マスタ一覧を masters に含める |
出力（レスポンス）
| field | 型 | 説明 |
|---|---|---|
success | bool | true |
filter | string | 適用した filter |
items | array | { id, machine_name, machine_type, maker, release_date, spec_type, kishu_id, is_hidden, source_site, source_url }[]。導入日の新しい順、同日は機種名順 |
masters | array | include_masters 指定時のみ。{ id: int, name: string, inactive: bool }[] |
HTTP ステータス: 200。filter が不正なときは 400（NewMachineRestCopy::FILTER_INVALID）。
API-003-3 POST /links
ADM-024 の一括保存と同じく、行ごとに紐付けを保存する。一部の行が失敗しても成功した行は保存される。
入力（リクエスト）
JSON ボディ。
| param | 必須 | 型・制約 | 説明 |
|---|---|---|---|
items | はい | array（1〜200 件） | 保存する行 |
items[].new_machine_id | はい | 正の整数 | 新台情報 ID |
items[].mode | はい | existing / new | existing は既存マスタを kishu_id で指定。new は new_name の機種マスタを解決（同名が未登録なら新規登録）して紐付ける |
items[].kishu_id | 条件 | 正の整数 | existing のとき必須 |
items[].new_name | 条件 | string | new のとき必須。sanitize_text_field でタグ等を除去してから使う |
出力（レスポンス）
| field | 型 | 説明 |
|---|---|---|
success | bool | true |
has_errors | bool | 失敗した行があるか |
counts | object | { updated: int, unchanged: int, error: int } |
rows | array | 入力と同じ順の { new_machine_id, machine_name, status, message, kishu_id, kishu_name, kishu_inactive }[]。status は updated / unchanged / error |
HTTP ステータス: 200
失敗・エラー条件
| 条件 | HTTP | message |
|---|---|---|
items が無い・空 | 400 | NewMachineRestCopy::ITEMS_REQUIRED |
items が 200 件を超える | 400 | NewMachineRestCopy::ITEMS_TOO_MANY |
new_machine_id / mode が不正な行がある | 400 | NewMachineRestCopy::ITEMS_INVALID（1 行も保存しない） |
| 行単位の失敗（マスタ未指定・非アクティブ等） | 200 | 該当行の status: error と message |
API-003-4 POST /visibility
入力（リクエスト）
| param | 必須 | 型・制約 | 説明 |
|---|---|---|---|
id | はい | 正の整数 | 新台情報 ID |
is_hidden | はい | bool | true で非表示 |
出力（レスポンス）
| field | 型 | 説明 |
|---|---|---|
success | bool | true |
id | int | 新台情報 ID |
is_hidden | bool | 更新後の値 |
message | string | ADM-024 と同じ表示切替の文言 |
HTTP ステータス: 200
失敗・エラー条件
| 条件 | HTTP | message |
|---|---|---|
id 不正 | 400 | Messages::REST_INVALID_ID_MESSAGE |
is_hidden 不正 | 400 | NewMachineRestCopy::IS_HIDDEN_REQUIRED |
| 対象が無い | 404 | NewMachineKishuLinkAdminCopy::INVALID_RECORD |
| 更新失敗 | 500 | NewMachineKishuLinkAdminCopy::VISIBILITY_UPDATE_FAILED |
権限・nonce・レート制限
全エンドポイント共通。NewMachineRestHandler + WordPressNewMachineEditorPermissionChecker（判定は BotRestPolicyPermissionChecker）。Handler がルートごとに action を付け、Checker は action に応じてレート制限を変える。Capability はどの action も manage_new_machine_info。action が無い・不明なときは 403。
action | ルート | Capability | レート制限（ユーザー単位） | カウンタ不可時 |
|---|---|---|---|---|
read | API-003-2 | manage_new_machine_info | 1 分 120 回 | 通す |
fetch | API-003-1 | manage_new_machine_info | 1 時間 20 回 | 拒否（429） |
write | API-003-3・4 | manage_new_machine_info | 1 分 20 回（合算） | 拒否（429） |
| 項目 | 内容 |
|---|---|
| 匿名アクセス | 403（WordPress REST 標準の応答） |
| nonce | 検証しない（アプリケーションパスワード前提）。Cookie 認証で呼ぶ場合の REST nonce は WordPress コア側の挙動に従う |
| レート制限 | BotRestRateLimiter（transient、固定ウィンドウ）。バケットは new-machine:read / new-machine:fetch / new-machine:write。超えたら 429 |
| ログ | ログイン済みユーザーの 403 と、429 のときだけ error_log に 1 行（NewMachineRestCopy::LOG_DENIED_FORMAT） |
| Local バイパス | API-001 の WordPressPermissionChecker と同じ条件（レート制限もかけない） |
fetch の last_month / past_month と force は、上の判定を通ったうえで Controller が manage_options（WordPressPermissionChecker）を確かめる。レート制限は権限判定の段階で数えるため、Controller が 400（mode 不正等）・403（FETCH_MODE_ADMIN_ONLY）で返した呼び出しも fetch の回数に含まれる。
監査ログ
API-003-1・3・4 は BotRestAuditLogger で error_log に 1 行 JSON（接頭辞 [bot-rest-audit]）を書く。リクエストボディ・機種名・取得ログの本文は書かない。入力検証で 400 になったリクエストは記録しない。
| ルート | 記録する項目 |
|---|---|
new-machine/v1/fetch | user_id・mode・year・month・force（実際に適用したか）・outcome（success / partial / failed / admin_only）・inserted・updated・fetched |
new-machine/v1/links | user_id・items_count・outcome（success / partial）・updated・unchanged・error |
new-machine/v1/visibility | user_id・id・is_hidden・outcome（updated / unchanged / not_found / failed） |
取得処理の例外は、例外クラス名とコードだけを error_log に書く（NewMachineRestCopy::LOG_FETCH_ERROR_FORMAT）。レスポンスは固定文言（NewMachineFetchCopy::FETCH_FAILED）。