Develop

.agent/PLANS.md

@@ -56,7 +56,9 @@ ExecPlan の仕様書。複雑なタスクはこの仕様に従い `.agent/plans
 - 実装精度と再現性を維持したまま簡潔に書き、同一趣旨の重複記述を避ける
 - 長大なコード全文の貼り付けは原則避け、対象箇所・変更意図・確認コマンドを優先する
 - 次のマイルストーンへ自律的に進む（「次は？」と確認しない）
-- 完了した ExecPlan は削除せずナレッジとして残す
+- 完了した ExecPlan は `.agent/plans/archive/` へ移動する
+- アーカイブ時はファイル名先頭の日付を完了日（`YYYY-MM-DD`）へ更新する
+- ロードマップに `ExecPlan:` を記載している場合は、移動後のパスへ更新する
 
 ## 成功基準
 

.agent/plans/2026-02-14-api-router-foundation.md

@@ -0,0 +1,105 @@
+# ExecPlan: API Router基盤の先行構築（Phase 0）
+
+## Purpose / Big Picture
+
+REST API実装の前提として、`api.php` に集約されるルーター基盤を先行実装し、後続の認証・read・write実装を安全に分離して進められる状態を作る。これにより、機能追加時の分岐肥大化を防ぎ、API全体の拡張性と保守性を確保する。
+中長期的には、フロント・管理画面・APIを単一フロントコントローラへ統合するための足場として扱う。
+
+## Progress
+
+- [ ] (2026-02-14) ルート定義フォーマットを確定する
+- [ ] (2026-02-14) ルート登録レジストリを実装する
+- [ ] (2026-02-14) `method + path` ディスパッチャを実装する
+- [ ] (2026-02-14) namespace省略解決（`/api/v1/...` -> `/api/evo/v1/...`）を実装する
+- [ ] (2026-02-14) 404/405/OPTIONSの標準応答を実装する
+
+## Surprises & Discoveries
+
+- 既存CMSにはルーティングの明示レイヤーがなく、実装箇所の分散が起きやすい。
+
+## Decision Log
+
+- 2026-02-14 / AI / Routerは独立Phaseで先行し、後続Phaseの共通土台とする。
+- 2026-02-14 / AI / `GET /api/v1/...` は本体API省略形として解決する。
+- 2026-02-14 / AI / WordPressは構造設計の参考にするが、互換目的の制約は導入しない。
+- 2026-02-14 / AI / 本RouterはAPI専用に閉じず、将来の「管理画面URL変更機能」で再利用できる設計にする。
+- 2026-02-14 / AI / 当面は `api.php` 先行導入で段階移行し、最終的に単一エンドポイント運用へ寄せる。
+
+## Outcomes & Retrospective
+
+実装後に記載
+
+## Context and Orientation
+
+用語:
+
+- ルートレジストリ: ルート定義（namespace/version/path/methods/callback）を保持する仕組み。
+- ディスパッチャ: 受信リクエストを一致ルートへ振り分ける処理。
+
+対象ファイル:
+
+- `api.php`
+- `manager/includes/rest-api.inc.php`
+- `manager/includes/rest-routes.php`
+
+## Plan of Work
+
+まずルート定義・登録・解決の責務を固定し、認証やビジネスロジックとは分離する。Router層は純粋に経路解決と標準HTTP応答に集中し、認証・レート制限は後続Phaseでミドルウェアとして接続する。これにより段階実装時のリスクを抑える。
+あわせて予約パス（`/api/`, `/manager/`）の優先順位ルールを定義し、将来の管理画面URL変更時に同じ解決ルールを使えるようにする。
+移行期は既存エンドポイントとの互換を維持し、運用が安定した段階で単一フロントコントローラへ統合する。
+
+## Concrete Steps
+
+1. ルート定義APIを作る。  
+   編集対象ファイル: `manager/includes/rest-api.inc.php`  
+   実行コマンド: `php -l manager/includes/rest-api.inc.php`  
+   期待される観測結果: `register_rest_route()` 相当が利用できる。
+2. ディスパッチャを作る。  
+   編集対象ファイル: `manager/includes/rest-api.inc.php`  
+   実行コマンド: `rg -n "dispatch|405|404|OPTIONS" manager/includes/rest-api.inc.php`  
+   期待される観測結果: ルート未一致404、メソッド不一致405、OPTIONS応答が実装される。
+3. `api.php` をフロントコントローラ化する。  
+   編集対象ファイル: `api.php`  
+   実行コマンド: `php -l api.php`  
+   期待される観測結果: ルーティング処理が単一入口に集約される。
+4. 省略namespace解決を追加する。  
+   編集対象ファイル: `manager/includes/rest-api.inc.php`  
+   実行コマンド: `rg -n "/api/v1|/api/evo/v1|namespace" manager/includes/rest-api.inc.php`  
+   期待される観測結果: `/api/v1/...` が `/api/evo/v1/...` と同等に解決される。
+5. 予約パス優先順位ルールを定義する。  
+   編集対象ファイル: `manager/includes/rest-api.inc.php`（必要に応じて設定読み込み）  
+   実行コマンド: `rg -n "api_prefix|manager_prefix|reserved|priority" manager/includes/rest-api.inc.php`  
+   期待される観測結果: `api_prefix` と将来の `manager_prefix` を前提にした衝突回避ルールが確認できる。
+
+## Validation and Acceptance
+
+1. `php -l api.php manager/includes/rest-api.inc.php manager/includes/rest-routes.php` が成功すること。
+2. `GET /api/v1/` で本体APIディスカバリが返ること。
+3. `GET /api/evo/v1/` が `GET /api/v1/` と同等応答になること。
+4. 存在しないルートで404が返ること。
+5. 許可外メソッドで405が返ること。
+6. 予約パスがコンテンツURLより優先解決されること。
+
+## Idempotence and Recovery
+
+Router層の追加に限定し、認証や業務ロジックを混ぜない。問題発生時は`api.php`と`rest-api.inc.php`差分のみで切り戻し可能にする。
+
+## Artifacts and Notes
+
+- `.agent/plans/2026-02-14-rest-api-foundation-security.md`
+- `.agent/plans/2026-02-14-headless-read-api.md`
+- `.agent/plans/2026-02-14-manager-write-api.md`
+
+## Interfaces and Dependencies
+
+想定エンドポイント（Router検証用）:
+
+- `GET /api/v1/`
+- `GET /api/evo/v1/`
+- `GET /api.php?route=/evo/v1/`
+
+後続依存:
+
+- 認証・制限: `.agent/plans/2026-02-14-rest-api-foundation-security.md`
+- read API: `.agent/plans/2026-02-14-headless-read-api.md`
+- write API: `.agent/plans/2026-02-14-manager-write-api.md`

.agent/plans/2026-02-14-headless-read-api.md

@@ -0,0 +1,123 @@
+# ExecPlan: Headless公開Read API（Phase 2）
+
+## Purpose / Big Picture
+
+フロントエンドがCMSテンプレートを介さず利用できる公開Read APIを提供し、Evolution CMSをヘッドレスCMSとして運用可能にする。公開範囲を明示し、非公開データ漏えいを防ぎながら配信性能を確保する。
+
+## Progress
+
+- [ ] (2026-02-14) 公開対象フィールドと非公開フィールドを定義する
+- [ ] (2026-02-14) resources一覧/詳細APIを実装する
+- [ ] (2026-02-14) TVsとmedia metadata取得APIを実装する
+- [ ] (2026-02-14) ページング/フィルタ/ソート/フィールド選択を実装する
+- [ ] (2026-02-14) 非公開リソース遮断と境界値検証を完了する
+
+## Surprises & Discoveries
+
+- 既存リソース取得は管理画面用途と混在しているため、公開向け出力フィールドの絞り込みルールを先に決める必要がある。
+
+## Decision Log
+
+- 2026-02-14 / AI / `content` を含む完全本文返却は `fields` 指定がある場合のみ許可し、デフォルトは軽量メタ情報中心にする。代替案の常時全文返却は帯域負荷が高いため不採用。
+- 2026-02-14 / AI / 公開APIは匿名アクセス可だが、Phase 1のレート制限を必須適用する。代替案の無制限公開は不採用。
+- 2026-02-14 / AI / 非公開・権限制約ドキュメントは匿名APIから除外し、存在有無を過度に示さない応答方針を採用する。
+- 2026-02-14 / AI / WordPress互換の運用感を優先し、デフォルト `per_page=10`、上限 `100`、合計件数ヘッダを返す。
+- 2026-02-14 / AI / WordPressは公開GET運用の参考にするが、旧来仕様の互換は目的化せず、モダンなHTTP/認証設計を優先する。
+- 2026-02-14 / AI / 本Phaseの本体read APIは汎用取得に限定し、Ditto相当の高度フィルタや独自パラメータ互換は拡張API（スニペット/プラグイン）で提供する。
+
+## Outcomes & Retrospective
+
+実装後に記載
+
+## Context and Orientation
+
+用語:
+
+- read-only API: データ参照のみ可能で、更新系メソッドを受け付けないAPI。
+- fields選択: クライアントが必要な項目のみ指定する仕組み。
+
+対象ファイル:
+
+- `manager/includes/rest/controllers/resources-controller.php`
+- `manager/includes/rest/controllers/media-controller.php`
+- `manager/includes/rest-routes.php`
+- `manager/includes/rest-api.inc.php`（共通整形ロジック）
+
+前提依存（着手前に完了が必要）:
+
+- `.agent/plans/2026-02-14-api-router-foundation.md`
+- `.agent/plans/2026-02-14-manager-url-routing-migration.md`
+- `.agent/plans/2026-02-14-rest-api-foundation-security.md`
+
+## Plan of Work
+
+公開APIの返却仕様を固定し、最初に`resources`の一覧/詳細を実装する。次にTVとmedia metadataを追加し、共通のページングとフィルタ処理を適用する。全クエリはDBアクセス直前でエスケープし、返却前に公開許可判定を行う。管理向け内部情報（内部パス、権限状態、未公開フラグ詳細）はレスポンスに含めない。
+URLは `/api/v1/...` を第一選択にし、rewrite不能環境向けに `/api.php?route=/evo/v1/...` を同等フォールバックとして提供する。
+本体側は最小パラメータ（page/per_page/fields/sort/order/parents/depth）を維持し、Ditto互換の複雑条件は拡張名前空間（例: `/api/ditto/v1/...`）へ委譲する。
+
+## Concrete Steps
+
+1. 返却スキーマを定義する。  
+   編集対象ファイル: `.agent/plans/2026-02-14-headless-read-api.md`  
+   実行コマンド: `rg -n "Interfaces and Dependencies|Validation and Acceptance" .agent/plans/2026-02-14-headless-read-api.md`  
+   期待される観測結果: 必須フィールド、任意フィールド、除外フィールドが明文化される。
+2. resourcesコントローラを実装する。  
+   編集対象ファイル: `manager/includes/rest/controllers/resources-controller.php`  
+   実行コマンド: `php -l manager/includes/rest/controllers/resources-controller.php`  
+   期待される観測結果: `GET /evo/v1/resources`, `GET /evo/v1/resources/<id>` が動作する。
+3. mediaコントローラを実装する。  
+   編集対象ファイル: `manager/includes/rest/controllers/media-controller.php`  
+   実行コマンド: `php -l manager/includes/rest/controllers/media-controller.php`  
+   期待される観測結果: `GET /evo/v1/media` が動作し、許可範囲のメタ情報のみ返す。
+4. ルート登録を追加する。  
+   編集対象ファイル: `manager/includes/rest-routes.php`  
+   実行コマンド: `php -l manager/includes/rest-routes.php`  
+   期待される観測結果: read-onlyルートが `GET` のみで登録される。
+5. 境界値と情報漏えい防止を仕上げる。  
+   編集対象ファイル: `manager/includes/rest/controllers/resources-controller.php`, `manager/includes/rest-api.inc.php`  
+   実行コマンド: `rg -n "per_page|fields|404|403|sanitize" manager/includes/rest/controllers/resources-controller.php manager/includes/rest-api.inc.php`  
+   期待される観測結果: 上限下限、不正パラメータ、非公開アクセスの扱いが実装される。
+
+## Validation and Acceptance
+
+1. `php -l manager/includes/rest/controllers/resources-controller.php manager/includes/rest/controllers/media-controller.php manager/includes/rest-routes.php` が成功すること。
+2. 匿名で `GET /api/v1/resources?page=1&per_page=20`（またはフォールバックURL）が成功すること。
+3. 匿名で非公開リソースIDへアクセスした際に内容が返らないこと。
+4. `fields` 指定時に要求項目のみ返ること。
+5. `per_page=0`、負数、過大値で下限/上限丸めが動作すること。
+6. 連続アクセス時にPhase 1のレート制限が適用されること。
+7. レスポンスヘッダに `X-EVO-Total` と `X-EVO-TotalPages` が含まれること。
+8. `POST/PUT/PATCH/DELETE` を送ると405を返すこと。
+
+## Idempotence and Recovery
+
+コントローラ追加中心で既存管理機能への影響を分離する。APIルートはread-onlyに限定し、問題発生時はルート登録を外すだけで影響を局所化できる。
+
+## Artifacts and Notes
+
+- `assets/docs/template-system.md`
+- `assets/docs/cache-mechanism.md`
+- `.agent/plans/2026-02-14-rest-api-foundation-security.md`
+
+## Interfaces and Dependencies
+
+想定エンドポイント:
+
+- `GET /api.php?route=/evo/v1/resources&page=<n>&per_page=<n>&fields=<csv>&q=<keyword>`
+- `GET /api.php?route=/evo/v1/resources/<id>?fields=<csv>`
+- `GET /api.php?route=/evo/v1/media&path=<dir>&page=<n>&per_page=<n>`
+- `GET /api/v1/resources?page=<n>&per_page=<n>&fields=<csv>&q=<keyword>`
+- `GET /api/v1/resources/<id>?fields=<csv>`
+- `GET /api/v1/media?path=<dir>&page=<n>&per_page=<n>`
+
+依存:
+
+- Phase 1の認証/制限/レスポンス共通層
+- Bearer opaque token認証（非公開readや将来拡張時）
+- `db()->select()` と `db()->escape()`
+- `evo()->logEvent()`（異常系）
+
+既定ページング:
+
+- `per_page` のデフォルトは `10`
+- `per_page` の上限は `100`

.agent/plans/2026-02-14-manager-public-endpoint-retirement.md

@@ -0,0 +1,100 @@
+# ExecPlan: `manager` 公開エンドポイント廃止と段階的ディレクトリ整理（Phase 0.8）
+
+## Purpose / Big Picture
+
+`manager/` を公開URLとして廃止し、Router経由の単一入口運用へ移行する。物理ディレクトリ削除は即時に行わず、互換期間を経て段階的に整理することで運用リスクを下げる。
+
+## Progress
+
+- [ ] (2026-02-14) `manager` 公開URL廃止ポリシー（互換期間・リダイレクト方針）を確定する
+- [ ] (2026-02-14) Web到達経路をRouter経由へ集約する
+- [ ] (2026-02-14) 旧 `manager/` URLの互換導線を実装する
+- [ ] (2026-02-14) 物理ディレクトリ整理の移行計画（段階削除）を策定する
+- [ ] (2026-02-14) 監視・ロールバック手順を整備する
+
+## Surprises & Discoveries
+
+- URL統合と物理構成変更は同時実施すると失敗時の切り戻し範囲が広がるため、段階分離が必須。
+
+## Decision Log
+
+- 2026-02-14 / AI / まず「公開URLとしての `manager` 廃止」を先行し、物理ディレクトリ整理は後段で実施する。
+- 2026-02-14 / AI / 互換期間中は旧URLへのアクセスを制御付きで許容し、監視ログをもとに最終停止時期を判断する。
+- 2026-02-14 / AI / 単一フロントコントローラ方針を優先し、直接ディレクトリアクセスを前提にしない設計へ移行する。
+
+## Outcomes & Retrospective
+
+実装後に記載
+
+## Context and Orientation
+
+用語:
+
+- 公開URL廃止: URLとしてアクセス可能な入口を停止し、内部実装は維持する段階。
+- 互換期間: 旧URLを限定的に残し、移行を段階化する期間。
+
+対象ファイル:
+
+- `index.php`
+- `manager/index.php`
+- Webサーバー設定（Apache/Nginx ルールは運用手順として記録）
+- `.agent/roadmap.md`
+
+前提依存:
+
+- `.agent/plans/2026-02-14-api-router-foundation.md`
+- `.agent/plans/2026-02-14-manager-url-routing-migration.md`
+
+## Plan of Work
+
+まずRouter側で管理導線を確定し、旧 `manager/` の直接到達を縮退させる。次に互換リダイレクトと監視ログを導入し、アクセス実績を観測する。利用が収束した時点で物理ディレクトリの段階整理に進む。常に復旧可能性を優先し、URL停止とファイル削除を同時に行わない。
+
+## Concrete Steps
+
+1. 廃止ポリシーを定義する。  
+   編集対象ファイル: `.agent/plans/2026-02-14-manager-public-endpoint-retirement.md`  
+   実行コマンド: `rg -n "互換期間|ロールバック|Validation and Acceptance" .agent/plans/2026-02-14-manager-public-endpoint-retirement.md`  
+   期待される観測結果: 停止条件と復旧条件が明文化される。
+2. 旧URLの到達制御を実装する。  
+   編集対象ファイル: `index.php`, `manager/index.php`  
+   実行コマンド: `php -l index.php manager/index.php`  
+   期待される観測結果: 旧 `manager/` が定義した移行挙動（redirect/deny）になる。
+3. 監視ログを実装する。  
+   編集対象ファイル: `manager/index.php`（必要時）  
+   実行コマンド: `rg -n "logEvent|manager|redirect|deprecated" manager/index.php`  
+   期待される観測結果: 旧URLアクセスが観測可能になる。
+4. 物理整理のチェックリストを作る。  
+   編集対象ファイル: `.agent/roadmap.md`  
+   実行コマンド: `rg -n "manager|単一フロントコントローラ|Phase 0.8" .agent/roadmap.md`  
+   期待される観測結果: 段階削除の条件が追記される。
+
+## Validation and Acceptance
+
+1. `php -l index.php manager/index.php` が成功すること。
+2. 新管理URLでログイン・主要遷移が成功すること。
+3. 旧 `manager/` URLアクセスが定義どおりに処理されること。
+4. 旧URLアクセスが監視ログに記録されること。
+5. ロールバック手順で旧導線へ復帰できること。
+
+## Idempotence and Recovery
+
+「URL制御」「監視」「物理整理計画」を分離して反映する。障害時はURL制御のみを戻せるようにし、物理削除は最終段階まで実行しない。
+
+## Artifacts and Notes
+
+- `.agent/roadmap.md`
+- `.agent/plans/2026-02-14-api-router-foundation.md`
+- `.agent/plans/2026-02-14-manager-url-routing-migration.md`
+
+## Interfaces and Dependencies
+
+依存:
+
+- Router優先解決ルール
+- `manager_prefix` 設定化
+
+後続依存:
+
+- `.agent/plans/2026-02-14-rest-api-foundation-security.md`
+- `.agent/plans/2026-02-14-headless-read-api.md`
+- `.agent/plans/2026-02-14-manager-write-api.md`