コンテンツ更新管理 — 開発者向け情報

本ページは コンテンツ更新管理（プラグインスラッグ content-maintenance-plugin・名前空間 ContentMaintenancePlugin・prefix plg_cmp_）を拡張・調査・移行するための技術情報です。記載はすべて v1.0.1 の実装に基づきます。

ブロック「コンテンツ更新管理セクション」

本プラグインが登録するブロックは 1 つだけです。ショートコードは 1 つも登録せず、カスタム投稿タイプ・カスタムタクソノミーも追加しません。

attributes は managedId 1 個だけ

担当者・承認者・次回確認日・更新頻度・重要度・通知・期限切れ処理といった管理設定は、ブロック属性に一切入りません。正本はカスタムテーブル plg_cmp_targets の行で、ブロックが持つのは行を引くための管理 ID だけです。したがって post_content をパースしても管理設定は取り出せませんし、逆に post_content を書き戻しても管理設定は変わりません。エディタのサイドバーの「管理設定を保存」は投稿の「更新」とは別の REST 書き込みです（次章）。

supports（4 キー）

色・タイポグラフィ・スペーシングの supports は宣言していません。保存側は useBlockProps.save() ＋ useInnerBlocksProps.save() の <div> 1 枚で、期限の状態を HTML に焼き込みません（表示のたびに判定するため）。

管理 ID の発番とネスト禁止

• 発番はクライアント（crypto.getRandomValues の 6 バイト）とサーバ（wp_insert_post_data での保険）の 2 か所にあります。クライアント側の発番条件は「① managedId が空」「② エディタ内の自分以外のブロックが同じ ID を持つ」「③ その ID を別の投稿が持っている（REST で確認）」の 3 つで、振り直すのは新しくマウントした側（貼った側）だけです。
• ③ は「この投稿の保存済み本文に同じ ID があるならコピーではない」と判断して通信しません。通常の編集・エディタの読み込みでは、この重複確認の REST を 1 回も呼びません（管理設定サイドバーを開いたときの取得と、保存後の通知取得は別経路です）。
• 発番は __unstableMarkNextChangeAsNotPersistent() の直後に行うため、取り消し履歴に独立した段を作りません。
• サーバ側の振り直しの結果本文が変わらなければ post_content に触りません（保存のたびに差分が出るのを避けるため）。逆に言うと、ブロック管理を使う投稿では管理 ID を振るために post_content が書き換わることがあります。
• 入れ子は 3 層で塞いでいます。エディタは allowedBlocks から自分自身だけを除外し、サーバは管理ブロックの内側にある管理ブロックへ ID を振らず、収集もしません（＝管理対象になりません）。
• 同期パターン（core/block）の内側にいると判定したときは、クライアントは管理 ID を一切触りません。同期パターンの実体である投稿タイプ wp_block は管理対象にできる投稿タイプの候補からも除外されています。

フロント側に出るもの・出ないもの

render_block の分岐条件は is_admin() だけです。したがってページ表示・フィード・抜粋の生成・公開 REST の content.rendered の 4 経路には差し替えが効き、ブロックエディタのキャンバスには効きません。事前に本文を書き換えていないので、期限が来た瞬間から効き、確認完了で即座に元へ戻ります。代替メッセージは esc_html() を通すプレーンテキストで、専用の CSS は出力しません（クラス名だけ付けてテーマに任せる設計）。リダイレクト対象のマップは 300 秒の transient にキャッシュし、確認完了・確認結果登録・期限切れ処理実行・save_post で破棄します。

ブロックの期限切れ処理は 4 種（none warn hide alt_message）で、フロント出力が変わるのは hide と alt_message の 2 つだけです。表示ラベルは画面によって異なり、ブロックのサイドバー（JS）は フロントで非表示、管理画面（PHP）は ブロックを非表示 です。

REST API

名前空間は content-maintenance-plugin/v1。register_rest_route() の呼び出しは 3 本で、メソッド×パスの組み合わせは 4 エンドポイントです。認証は WordPress コア標準の cookie 認証 ＋ nonce（wp_rest / X-WP-Nonce）で、独自のトークン発行はありません。4 エンドポイントすべてに permission_callback が設定されています（コアの rest_cookie_check_errors() が nonce を検証する前提で、プラグイン側では二重検証しません）。いずれも管理画面・ブロックエディタ向けで、フロント公開用の API ではありません。

パラメータ

post_id / object_key は args で必須宣言しているため、欠けたリクエストは WordPress コアが 400 で弾きます。

GET /block-target のレスポンス（6 キー）

settings の 22 キーは id / name / assigneeId / approverId / escalationUserId / nextReviewDate / intervalValue / intervalUnit / priority / reviewNote / referenceUrl / notifyBefore / notifyAfter / notifyOnDue / escalationDays / notifyChannels / notifyConnections / expirationAction / altMessage / workflowStatus / recordStatus / expired です。expired は保存列ではなくサーバ側の判定結果で、エディタは次回確認日から自前で計算せずこの値だけを見ます。

候補ユーザー（assignees / approvers / escalation）は 1 回 100 件まで取得してから権限で絞るため、候補は 100 件未満になりえます。現在の担当者が候補条件から外れた場合は {表示名}（権限なし） として選択肢に残します。

POST /block-target のレスポンスとエラー

エラーが 1 つでもあると 1 項目も保存されません（部分保存はしません）。保存時の検証は次のとおりです。

期限前・期限超過の日数リストは保存時に「正の整数だけ・重複除去・降順」へ整形されます。保存が成功すると、担当者・承認者・エスカレーション先・次回確認日が変わった項目ごとに専用の履歴が残り、どれも変わっていなければ「管理設定変更」の履歴が 1 件残ります。

その他 2 エンドポイントの応答

• GET /block-target/owned-elsewhere → { "ownedElsewhere": true|false } の 1 キーのみ。通信に失敗したときクライアントは false（＝別投稿のものではない）に倒します。
• GET /editor-notices → { "errors": [], "warnings": [], "success": [] }。投稿単位（Post\Meta_Box）とフィールド単位（Field\Meta_Box）の transient を両方 drain し、同じ文言は畳みます。ブロックエディタはメタボックスの保存 POST が返す HTML を捨てるため、保存後にこのルートへ取りに来て core/notices として表示する仕組みです。REST と画面描画のどちらか一方だけが消費します。

WP-CLI コマンドは提供していません。上記 4 本のほかに、同梱のバグ報告モジュールが別名前空間のルートを 1 本追加します（管理者専用。本プラグインの管理 API ではありません）。

カスタムテーブル（4 本）

物理テーブル名は $wpdb->prefix ＋ plg_cmp_ ＋ 論理名です。wp_plg_cmp_targets と決め打ちできません（サイトの DB プレフィックスに従います）。作成は dbDelta()、削除は DROP TABLE IF EXISTS（アンインストールの「すべて削除」のみ）。

日時カラムはすべて current_time( 'mysql' ) ＝ サイトタイムゾーンの壁時計で保存します（UTC ではありません）。履歴・通知ログ・管理対象の created_at / updated_at / deadline_state_at のいずれも同じで、履歴の刈り込み境界も「サイトタイムゾーンの今日 − N 日 00:00:00」という壁時計文字列で作られます。期限判定の基準日も wp_date( 'Y-m-d' ) です。外部から日時を突き合わせるときは gmdate() 系と混ぜないでください。

plg_cmp_targets の主要カラム

• 行の同一性は uniq_target(target_type, post_id, object_key) の複合ユニークです。二重登録しようとすると作成が 0 を返します。索引は他に post_id / sweep(record_status,next_review_date) / assignee / approver / list_filter(record_status,workflow_status,deadline_state) / type_priority。
• リポジトリは列一覧に無いキーを捨て、列挙カラム（target_type / priority / workflow_status / last_result / interval_unit / record_status / expiration_action / deadline_state）と notify_channels の値を検証して、外れていれば保存そのものを拒否します。

plg_cmp_history（14 列）

列は id / target_id / cycle / action / actor_type / actor_id / value_before / value_after / comment / channel / result / log_id / rule_id / created_at。索引は PRIMARY / target_created(target_id,created_at) / created_at / action の 4 本です。

• action は 17 種の許可リストで、そこに無い値は書き込み時点で捨てられます（target_created / settings_changed / assignee_changed / approver_changed / escalation_changed / next_date_changed / status_changed / review_started / review_registered / approval_requested / approved / rejected / notification_sent / notification_failed / expiration_executed / expiration_released / notification_retry）。
• actor_type は user / system の 2 値。明示しなかった場合は actor_id → get_current_user_id() の順に解決し、それも 0 なら system になります。定期処理からの書き込みは自動的にシステム扱いです。
• 配列・オブジェクトの値は wp_json_encode() して保存します。
• リポジトリに update / delete メソッドがありません。クラス全体で INSERT と SELECT と DELETE 1 本だけで、その DELETE を呼ぶのは保持期間の刈り込み 1 か所です。管理画面から履歴を編集・削除する UI もありません。

plg_cmp_notification_log（16 列）と plg_cmp_rules（11 列）

• 通知ログの列は id / kind / target_id / cycle / event / timing / channel / recipient / role / dedup_key / status / attempts / last_error / reason / created_at / updated_at。dedup_key に UNIQUE 制約があり、これが二重送信の防止装置です（次章）。索引は PRIMARY / uniq_dedup / target_cycle / kind_status / created_at。
• 運用ルールの列は id / name / post_type / target_type / priority / enabled / term_conditions / object_keys / defaults / created_at / updated_at。絞り込みに使う値だけを列に出し、条件と初期管理設定は LONGTEXT の JSON 3 列で持ちます。索引は PRIMARY / match_lookup(enabled,post_type,priority) / type_priority。

スキーマ版と追従

オプション・post meta・user meta

設定画面が書き込むオプション（16 個）

期限切れ処理の既定値は 4 系統（投稿・ブロック・ACF・カスタムフィールド）すべて none ＝ 何もしない、期限当日通知の全体既定は OFF、履歴保持期間は 0 ＝ 無期限、アンインストールは keep ＝ すべてのデータを保持です。つまり有効化しただけでは、公開中の投稿のステータスが変わることも、履歴が消えることも、削除でデータが消えることもありません。移行スクリプトで既定値を上書きするときは、この安全側の初期状態を意図的に外していることになります。

設定 UI を持たないオプション・transient

transient（options 上は _transient_plg_cmp_*）は plg_cmp_redirect_map（リダイレクト対象マップ・300 秒）/ plg_cmp_notice_{user}_{post}（メタボックスの保存結果・60 秒）/ plg_cmp_field_notice_*（フィールドの検証結果）/ plg_cmp_license_notice（60 秒）/ plg_cmp_update_data_{md5}・plg_cmp_releases_data（更新情報・12 時間）です。ライセンス API の向き先は wp-config.php の define( 'PLG_API_URL', … ) で上書きできます。

post meta / user meta

user meta の入力欄はユーザープロフィール画面の見出し コンテンツ更新管理の通知 にあります（設定画面ではありません）。編集に必要なのは edit_user だけで、独自 capability は要りません。post meta はこの 1 キーのみで、管理設定を post meta に持たせている箇所はありません（正本はすべてカスタムテーブル）。

独自 capability（5 種）とロール既定

付与は初回インストール時の一度きりです。フラグオプション plg_cmp_caps_granted が立っていれば、プラグイン更新でも再有効化でも maybe_grant() は即 return します。運用側でロールから外した capability（例: 投稿者から plg_cmp_edit_targets を剥がす）を、更新のたびに黙って復元しない設計です。裏返すと、新しい capability を後から配りたいときは自分で add_cap() する必要があります。付与は role への add_cap のみで、個別ユーザーへ付与する UI はありません（権限管理プラグイン等の標準機構で行う想定）。

• 寄稿者（contributor）・購読者（subscriber）には既定で何も付きません。capability を 1 つも持たないユーザーには、サブメニューが 1 件も登録されず、投稿編集画面のメタボックスも登録されず、管理画面の CSS/JS も読み込まれず、URL を直接叩けば 403、/block-target の読み書き 2 本は REST でも拒否されます（残る /block-target/owned-elsewhere と /editor-notices は前述のとおり対象投稿の edit_post だけで通ります）。
• 最上位メニュー（ダッシュボード）とライセンス画面だけは独自 capability ではなく manage_options を要求します。plg_cmp_manage_settings を編集者に付けてもこの 2 画面は開きません。
• 担当者・承認者に指定できるのは「対応する capability を持ち、かつその管理対象が紐づく投稿の edit_post を持つ」ユーザーです。したがって投稿者ロールは自分が書いた投稿しか担当できず、edit_pages を持たないため固定ページは自分が作成者でも担当できません。
• エスカレーション先だけは capability を問いません（候補一覧からは購読者ロールのみ除外）。
• 一覧に何行見えるかを決めるのは独自 capability だけではありません。plg_cmp_manage_targets または WordPress 標準の edit_others_posts のどちらかを持っていれば全件が見えます（既定では管理者と編集者）。どちらも持たないユーザーに並ぶのは、自分が担当者・承認者・エスカレーション先のいずれかである行と、自分が作成者の投稿の行（その投稿タイプを編集できる場合に限る）だけです。担当を持つ行は開けなくても一覧には残します——本人に見えていないと、一覧の警告から直しようがないためです。
• ワークフローの可否判定が見るのは「操作名 ・ record_status ・ 現在の運用ステータス ・ capability」の 4 つだけで、担当者への指名は条件に入りません（代行できます）。無効化された管理対象では全操作が拒否されます。
• 剥奪（revoke()）は既定付与の対象外だったロールも含めて全ロールを走査し、5 種を remove_cap します。呼び出し元はアンインストールの「すべて削除」だけです。

定期処理（WP-Cron）

本編が wp_schedule_event() で登録する繰り返しイベントは 2 本です（1 メソッドの 2 箇所）。これに加えて同梱のライセンスモジュールが日次のライセンス確認を 1 本登録するので、WP Crontrol などで見えるこのプラグイン由来の繰り返しイベントは 3 本になります。運用ルールの一括適用は繰り返しではなく、実行中だけ単発イベントを予約します。

• 登録は有効化フックに加えてadmin_init のたびに再試行します（wp_next_scheduled() で守られているため冪等）。日次イベントを後から追加した際に既存サイトへ追随させるための措置で、「有効化時にしか登録されない」わけではありません。
• 無効化時は 2 本とも wp_clear_scheduled_hook() で解除します。データは消えません。
• DISABLE_WP_CRON でコアの cron を止めているサイトでは、サーバーの cron から wp cron event run --due-now を実行してください。通知と期限切れ処理は毎時の定期処理で走ります。

スイープ 1 回の処理順

1. ロック取得。取れなければ即 return（skipped = true）。
2. 基準日（サイトタイムゾーンの今日）と期限接近閾値（既定 7 日）を決める。
3. カーソル（前回の続き）を plg_cmp_sweep_cursor から読み、管理対象を 200 件取得（record_status = 'active' かつ next_review_date IS NOT NULL・next_review_date ASC, id ASC 順）。
4. 各件の期限状態キャッシュを最新化（値が変わったときだけ DB を書く）。
5. 完了 3 ステータス かつ 期限状態が approaching / due_today / overdue の行について新サイクルを開始（cycle +1・workflow_status を pending へ）。
6. 各件について do_action( 'plg_cmp_sweep_target', $target, $today ) を発火。priority 10 で投稿 / ブロック / フィールドの期限切れ処理が、priority 20 で通知の送信判定がぶら下がる。
7. カーソルを進める（取得件数が上限に満たなければ末尾なのでオプションを削除＝次回は先頭から）。
8. 履歴の刈り込み（保持期間が 1 日以上のときだけ・1 回あたり最大 200 件・古い順）。
9. finally でロック解放。

これとは別に、plg_cmp_hourly_sweep そのものへ priority 20 で通知の自動再送がぶら下がります。こちらは管理対象 1 件ずつではなくスイープ 1 回につき 1 度動き、試行回数が上限（通算 3 回）未満の失敗ログを最大 50 件再送します。Sweeper::run() の戻り値は { processed, cycles_started, skipped, pruned } の 4 キーです（docblock は 3 キーと書いていますが実装は 4 キー）。

抽出範囲を「期限が近いものだけ」に絞っていないのは、管理対象ごとに通知タイミングが違うためです（閾値で切ると閾値より前の段階の通知が構造的に評価されなくなる）。代わりに次回確認日の昇順で全件をカーソルで巡回します。

冪等性は 3 層で担保する

ロックは transient ではなく options テーブルのユニーク制約です（要件ドキュメントとコード内コメントの一部に「transient ロック」と書かれていますが、実装は transient API を 1 行も使っていません）。wp-cron.php は非認証で誰でも叩ける公開エンドポイントで、ほぼ同時に複数リクエストが来るため「読んでから書く」方式では両方が取得できてしまう、というのが理由です。TTL は 300 秒。取り残しの掃除は「読み取った値と一致するときだけ消す」条件付き DELETE で、解放も自分が取ったトークンと一致するときだけ行います。合い札は time() . ':' . wp_generate_password( 12, false, false )。運用ルールの一括適用が別キーで同じ Lock を使います。

補足として、新しい確認サイクルに入ると cycle が変わるのでキーも変わり、通知も期限切れ処理も再び走ります。「何もしない」設定や遷移先 URL が空のリダイレクトも expired_done_cycle は消費します（消費しないと毎時同じ判定を繰り返すため）が、履歴は残しません。停止中（投稿タイプを管理対象から外した / ACF 連携が止まっている）は expired_done_cycle を進めませんが、通知側は停止中でも重複防止キーを消費します（「送らなかった」記録を 1 件残す）。これにより、停止を解除しても止まっていた期間の通知が後からまとめて飛ぶことがありません。

キャッチアップと期限状態の再計算

• スイープは実行のたびに「いま処理すべきで、まだ処理済み記録のない対象」を抽出するので、実行時刻に依存しません。WP-Cron が遅れても次の実行で補完されます。期限切れ処理は期限状態が overdue でありさえすれば何日遅れていても実行されます。
• 期限前通知は経過した段階を遡って送りません。いま有効な最新段階だけを送ります。
• deadline_state 列は検索用キャッシュにすぎません。一覧の行・詳細画面のバッジ・メタボックスは読み出しのたびに現在日で算出し直し、一覧の絞り込み・並び替え・ダッシュボードの件数は SQL で次回確認日から導出します。判定規則の正本は Deadline::state() ひとつで、SQL 版はその写しです。
• 履歴の刈り込みは毎時スイープの最後に走ります（日次ではありません）。1 回あたり最大 200 件・古い順で、残りは次のスイープに任せます。保持期間の既定は 0 ＝ 無期限なので、そのままでは 1 件も消えません。

管理側の送信経路（admin-ajax.php は使わない）

wp_ajax_ フックの登録は 1 か所もありません。管理画面の操作はすべて通常の POST → 処理 → wp_safe_redirect() で、画面はリロードされます。「画面を離れずに保存」「Ajax で一覧を更新」といった挙動はありません。JavaScript は管理画面用の 2 ファイル（assets/js/plg_cmp_admin.js / assets/js/plg_cmp_editor_notices.js）とブロックエディタ用のビルド成果物だけで、フロントには 1 本も出ません。

フック

プラグイン自身が発火するアクションは do_action() 9 か所 / 7 種、拡張用のフィルタは apply_filters() 6 か所 / 6 種です（いずれも includes/ 配下・同梱モジュール分を除く。Plugin::PREFIX は plg_cmp_）。JavaScript 側（@wordpress/hooks）のフックはありません。

アクション（do_action・7 種）

これらはプラグイン内部でも実際に使われています。たとえばリダイレクト対象のキャッシュ破棄は plg_cmp_target_completed / plg_cmp_target_review_registered / plg_cmp_expiration_executed の 3 本を購読しています。外部から確認完了に連動させたい処理（社内チャットへの追加通知、CDN パージなど）は plg_cmp_target_completed にぶら下げるのが素直です。

フィルタ（apply_filters・6 種）

いずれも件数の上限を調整するためのもので、管理画面の設定 UI はありません。表示内容や通知本文を差し替えるフィルタは提供していません。

いずれも戻り値は max( 1, (int) … ) でクランプされます（plg_cmp_bulk_apply_query_args は配列）。同梱モジュール由来の plugin_bug_report_is_license_active / plugin_bug_report_should_display / plugin_bug_report_allow_with_heavy_plugin はバグ報告ウィジェットのフックで、更新管理機能とは無関係です。

アンインストール時の挙動

削除範囲はオプション plg_cmp_uninstall_mode（設定画面の アンインストール時のデータ削除 > 削除範囲）で決まります。uninstall.php はオートローダより前にこのオプションをリテラルで読み、「そもそも何かを消すのか」を先に判定します。既定は keep（未設定時も同じ）で、未知の値も keep に倒します。

• all のときだけ uninstall.php が自前でオートローダを読み込みます（インスタンスを作るだけで init() は呼ばず、フックは張りません）。
• cron イベントは uninstall.php では解除していません。WordPress は削除前に必ず無効化を通るため、そこで解除済みだからです。
• 無効化（deactivate）では何も消えません。行うのはライセンス cron の解除、plg_cmp_hourly_sweep / plg_cmp_daily_sweep の解除、進行中の一括適用の予約解除（wp_unschedule_hook( 'plg_cmp_rule_bulk_apply' )。ジョブ本体のオプションは残すので再有効化すれば画面から再開・中止できる）、flush_rewrite_rules() の 4 つだけです。
• 有効化時に行うのは、plg_cmp_installed_version の記録（既存値は上書きしない）、テーブル作成、capability の初回付与、cron 登録、flush_rewrite_rules() の 5 つです。サンプルのルールや管理対象といった同梱データの投入はありません（シーダに相当するコードが存在しません）。

配布 zip に含まれないもの / 翻訳

配布 zip は .distignore で絞り込んでいます。含まれない主なものは次のとおりです。

composer.json が配布 zip に入らないため、そこに書かれた "php": ">=8.3" は開発環境の指定であって利用者の動作要件ではありません。利用者要件はプラグインヘッダの WordPress 6.6 以上 / PHP 8.1 以上です。ブロックのビルド成果物が react-jsx-runtime に依存するため、WordPress 6.5 以前では動きません。

含まれる主なものは plugin-base.php / uninstall.php / readme.txt / includes/（自前クラス 63 ファイル ＋ 同梱モジュール 2 つ）/ assets/css/plg_cmp_admin.css・assets/js/plg_cmp_admin.js・assets/js/plg_cmp_editor_notices.js / block/build/content-maintenance-section/（block.json / index.js / index.css / index-rtl.css / index.asset.php）です。ブロックはビルド済みで同梱されるので、利用者側で npm install && npm run build を走らせる必要はありません。

翻訳ファイルは 0 件

• text domain は content-maintenance-plugin で、plugins_loaded で load_plugin_textdomain() を呼んでいます。しかし自プラグイン用の .mo / .po / .pot はリポジトリ全体で 0 件です。languages/ には .gitkeep しか無く、その .gitkeep 自体が配布 zip から除外されるため、配布物の languages/ は実質空です。
• 結果として UI にはソース内の日本語リテラルがそのまま表示されます。国際化の下地（text domain）はありますが、英語 UI は提供していません。
• wp_set_script_translations() は呼んでいません。JavaScript 側の文言も日本語リテラルです。
• 最上位メニューのラベル（menu_title）は意図的に __() に通していません（画面の見出し page_title のほうは翻訳しています）。翻訳すると screen ID が変わり、バグ報告ウィジェットの表示許可画面と一致しなくなるためです。
• 例外として、同梱モジュール由来の includes/plugin-client/languages/ にある .pot / .po は zip に含まれますが、そちらは別の text domain を使っており、その text domain を読み込むコードは本プラグインにありません。

※ 本ページの内容は v1.0.1 時点の実装に基づきます。マルチサイトでは検証していません（ネットワーク対応コードは実装されておらず、テーブルは有効化したサイトの $wpdb->prefix でのみ作成されます）。ACF フィールド単位の管理には Advanced Custom Fields が必要ですが、ACF が無くても投稿単位・ブロック単位・カスタムフィールド単位の管理は動作します。