docs: 利用者から見た機能の一覧を docs/features に追加 (#7225)

[ttokoro20240902]

概要(Overview・Refs Issue)

Closes #7225

利用者（購入者・店舗運営者・開発者）から見た機能の一覧を本体に置き、機能を追加・変更する PR で更新する仕組みを入れます。結合試験項目書（EC-CUBE/eccube-specification#125）の観点表は、ここで振る機能 ID を参照します。

#6961 にスタックした PR です（base = docs/spec-static-site）。仕様書ポータル（ルートの README.html）と docs-check CI を前提にしています。

• docs/features/features.yaml — 正本。4.4 時点の機能 110 件（フロント 28 / 管理画面 54 / 開発者・運用者 28）
• docs/features/features.html — features.yaml から生成する一覧（ビルド不要でブラウザで開ける）。ポータルから導線を追加。README.md は GitHub で表示される索引として残す
• eccube:docs:export と docs-check（docs: 仕様書の集約 export コマンドと鮮度チェック CI を追加 (#6906) #6961）の対象に docs/ 配下の HTML 文書を追加（下記）
• .github/bin/feature-list.php — 検証と生成。--check は docs-check CI で実行
• PR テンプレートに「機能を追加・変更した場合は機能一覧を更新したか」を追加（docs: 仕様書の集約 export コマンドと鮮度チェック CI を追加 (#6906) #6961 で追加した README の項目の隣）
• AGENTS.md に更新ルールを追記

方針(Policy)

Issue の「進め方 1」の決定事項です。

• 置き場所・形式: 機械的に差分を取って照合できるよう YAML を正本にし、人が読む HTML は生成物としてコミットする。file:// で開く HTML からは別ファイルを fetch() できないため、HTML 側で YAML を読む方式は取らない
• 機能 ID: 接頭辞-グループ 2 桁-連番 2 桁（例: AD-20-01）。仕様書の章番号とは独立
  • 接頭辞: FR フロント（購入者） / AD 管理画面（店舗運営者） / DV 開発者・運用者（CLI・API・拡張）
  • グループは features.yaml 先頭の groups に定義し、10 刻みで振る（既存のグループの間に AD-25 のように足せる）
  • 採番したら変えない。廃止しても行は消さず removed を付けて欠番にする
• 粒度: 管理画面はメニュー単位、フロントは主要な導線、開発者向けは CLI / API / 拡張ポイントの単位から始める
• 本体 PR・導入バージョン: 4.4 で追加・変更した機能だけ埋め、既存の機能は空欄（Issue の進め方 2）。prs はリリースのバージョンごとに書く（prs: {4.4.0: [6858]}）。不具合修正だけの PR は載せない。本体 PR はリリースごとに試験観点と照合するための列なので features.yaml にだけ持ち、features.html には表示しない（行が伸び続けるため）

実装に関する補足(Appendix)

• docs: 仕様書の集約 export コマンドと鮮度チェック CI を追加 (#6906) #6961 の仕組みへの変更: 一覧の生成物を README.html にすると、同じディレクトリの README.md（索引）と同じものに見えるため features.html とした。名前が README.html でなくても集約出力と鮮度チェックから外れないよう、DocsExportService と check-readme-docs.php の対象に docs/ 配下の *.html を加えた（README.html 以外の HTML は docs/ 配下だけ。現在 docs/ にある HTML は features.html だけで、既存の文書が新たに対象になることはない）
• prs には、その行の機能の仕様を変えることが主な目的の PR だけを載せる。別の機能を追加した PR の波及（CSV の列が増える等）は追加元の行にだけ書く
• 検証内容: 機能 ID の形式・重複・グループの定義、必須列、未知の列（打ち間違い対策）、バージョン表記、dirs のパスの実在、README.html が features.yaml の生成物と一致するか
• feature-list.php は symfony/yaml を使うため、docs-check ジョブに ./.github/actions/composer を追加した
• docs-check は README / docs/features を変えたときだけ走る。src/ のディレクトリ名変更で dirs が切れても、次に機能一覧を触るまで検出されない（全 PR で composer install を走らせるコストとの兼ね合い）

テスト（Test)

• php .github/bin/feature-list.php --check: 合格（ホスト PHP 8.3 / コンテナ PHP 8.2）
• 壊した YAML（ID 形式違い・未定義グループ・連番 00・重複・未知の列・存在しないパス・バージョン表記違い）と、YAML だけ変えて HTML を作り直さない状態で、それぞれ失敗することを確認
• php .github/bin/check-readme-docs.php: 合格（ポータルからのリンク・section 属性・相対リンク）。features.html のポータルからのリンクを消す／section 属性を消すと失敗することを確認
• DocsExportServiceTest: docs/ 配下の HTML だけが追加で出力されるテストを追加（7 tests 合格）
• bin/console eccube:docs:export --filter=customer: README.html 28 件＋docs/features/features.html の 29 件を出力
• php-cs-fixer: 差分なし

相談（Discussion）

• PR と機能の対応は、4.4 宛にマージされた PR のタイトルと本文から判断して割り当てています。仕様書側の観点表との突き合わせで、漏れ・誤りを指摘してください（4.3 からの同期分の不具合修正は載せていません）
• 機能の粒度（1 行の大きさ）が観点表との対応に合っているか

マイナーバージョン互換性保持のための制限事項チェックリスト

• 既存機能の仕様変更はありません
• フックポイントの呼び出しタイミングの変更はありません
• フックポイントのパラメータの削除・データ型の変更はありません
• twigファイルに渡しているパラメータの削除・データ型の変更はありません
• Serviceクラスの公開関数の、引数の削除・データ型の変更はありません
• 入出力ファイル(CSVなど)のフォーマット変更はありません

レビュワー確認項目

• 動作確認
• コードレビュー
• E2E/Unit テスト確認(テストの追加・変更が必要かどうか)
• コード変更に対応する README.html/README.md（コード近接の仕様書・索引）の更新漏れがないか
• 機能を追加・変更した場合、docs/features/features.yaml（機能の一覧）を更新し docs/features/README.html を作り直したか
• 互換性が保持されているか
• セキュリティ上の問題がないか
  • 権限を超えた操作が可能にならないか
  • 不要なファイルアップロードがないか
  • 外部へ公開されるファイルや機能の追加ではないか
  • テンプレートでのエスケープ漏れがないか

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 625becb6-036c-402e-a271-fea466c83f87

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}