Repository navigation

wp-plugin-spec - 画面、API、データ (統合ひな型)

各プラグインリポジトリ直下の docs/ フォルダー等にコピーして利用することを想定する。
コピー後、1行目を # <plugin-slug> - 画面、API、データ に変更すること。
ファイル名の一例: docs/SPEC_UI_API_DATA.md
小〜中規模プラグイン向けに、「画面仕様、API 仕様、データ仕様」を1ファイルにまとめておき、大きくなったら分割版を使う。

分割版 (同一 docs/ 内):

SPEC_UI_AND_FLOWS.md — 管理画面、フロント UI と画面遷移
SPEC_API_AND_INTEGRATION.md — REST API および外部サービス連携
SPEC_DATA_DICTIONARY.md — データ、設定値、ストレージ定義

React / REST / Settings は、アダプタです。判断は、純関数です。永続化と wp_remote_* は、アダプタに閉じます。詳細な設計方針は、docs/SPECS.md の「2. 設計方針」、置き場所は、SPEC_ARCHITECTURE.md です。

1. 画面仕様 (UI) とフロー

設定ページは add_options_page または add_menu_page を使う (PHP アダプタ)。
読み書きは register_setting / get_option / update_option をアダプタで行う。
sanitize_callback、Nonce、capability は必須。
バリデーションと判断は純関数に出す。コンポーネントに混ぜない。
余白・テキストサイズは rem を基本とする。詳細は SPECS.md のスタイル規約。

1.1. 管理画面の一覧

画面 ID:
タイトル:
URL / メニュー階層:
React エントリーポイント:
権限 (capability):

1.2. 各画面の項目定義

画面 ID	フィールド名	ラベル	型	必須	バリデーション	保存先

1.3. ユーザーフロー

フロー名:
- 手順1:
- 手順2:

1.4. Gutenberg ブロック (該当する場合)

ブロック名	主な属性	フロント表示	正規化の純関数

block.json を正とする。登録は PHP アダプタ。翻訳は @wordpress/i18n。

2. REST API と外部連携

パスは /plugin-slug/v1/... を基本とする。
REST クラスはアダプタ。判断は includes/domain/ に。
permission_callback と Nonce は必須。
エラー系は HTTP ステータスとエラーコードを書く。WP_Error を握りつぶさない。

2.1. エンドポイント一覧

名前	パス	メソッド	概要	ドメイン関数

2.2. 各エンドポイント詳細

パス:
認証・認可:
リクエスト / レスポンス (正常系・エラー系):
永続化 (option / meta / テーブル / 外部 HTTP):

2.3. 外部 API (該当する場合)

サービス名	用途	認証	アダプタ	ドメイン関数

呼び出しは wp_remote_*。キーはアダプタから注入する。

3. データ辞書

永続化はアダプタ。ドメインはイミュータブルな値だけを受け取る。リポジトリインターフェースは量産しない。

3.1. Options API

option_name	説明	型	デフォルト値	アダプタ	ドメインの値の形

3.2. Post Meta / Term Meta

meta_key	対象	説明	型	デフォルト値	アダプタ

3.3. 独自テーブル (必要な場合)

テーブル名:
カラム / インデックス:
作成・更新するアダプタ:

4. AI 伴走開発での使い方メモ

本ファイルを1本渡して、画面 ID またはエンドポイント単位で実装を依頼する。
前提に「REST / 設定画面はアダプタ、判断は純関数、巨大サービスは使わない」を含める。
本ファイルが長くなったら、分割版3ファイルに移し、本ファイルは目次だけ残す。