docs: コード近接の人間向け仕様ドキュメント(README.html/README.md)を導入 (#6906)

.gitignore

@@ -8,6 +8,8 @@ node_modules
 !/var/.htaccess
 /app/Plugin/*
 !/app/Plugin/.gitkeep
+!/app/Plugin/README.html
+!/app/Plugin/README.md
 /app/PluginData/*
 !/app/PluginData/.gitkeep
 /app/keystore/*

AGENTS.md

@@ -20,6 +20,8 @@ AI エージェント向けの情報は、この `AGENTS.md` を**正典（ハ
 | `GEMINI.md` | 薄いポインタ。Gemini CLI は Skill 非対応のため索引経由で `SKILL.md` へ誘導 | Gemini CLI |
 | `llms.txt` | 外部 LLM・クローラ向けの英語サマリ（llmstxt.org 準拠。公開 URL 前提） | LLM クローラ・外部 LLM |
 | `.claude/skills/<name>/SKILL.md` | レイヤ別の詳細規約（末端）。`.codex/skills`・`.agents/skills` は symlink 共有 | Skill 対応ツール（詳細は「Skill の配置と各ツールの読み込み」節） |
+| `<機能ディレクトリ>/README.html` | コード近接の**人間向けの仕様書**（挙動・なぜ・図表）。`data-section`/`data-customer` で章立て（顧客提出フィルタ用） | 人間（開発者・新規参加者・顧客） |
+| `<機能ディレクトリ>/README.md` | コード近接の**短い索引**。GitHub のディレクトリビューで自動表示され、`README.html`（人間向け仕様）と `SKILL.md`（AI 向け規約）への道標を兼ねる | GitHub 閲覧者・AI エージェント |
 
 ### 定義ファイルを増やすときの原則
 
@@ -29,6 +31,27 @@ AI エージェント向けの情報は、この `AGENTS.md` を**正典（ハ
 - 新しい定義ファイルを足すときは、上のインデックス表にも 1 行追加し、所在を本節で一元管理する。
 - 設計思想・アーキテクチャの詳細文書（`DESIGN.md` / `ARCHITECTURE.md`）は現状未整備。整備する場合も本ファイルはハブに留め、詳細はそれらへリンクして本節の表に追記する。
 
+### コード近接ドキュメント（README.html / README.md）
+
+主要な機能ディレクトリ（`src/Eccube/` の各レイヤ根や高複雑サブシステム、一部 `app/`）には、コードと同じ場所へ 2 ファイルを置く。
+**読者別に 3 層へ分離し、同じ事柄を二度書かず相互にリンクする**（Issue #6906）。
+
+| 成果物 | 主読者 | 役割 |
+|---|---|---|
+| `README.html` | 人間（開発者・新規参加者・顧客） | **真の仕様書**（挙動・なぜ・図表）。`<section data-section="…" data-customer="true\|false">` で章立てし、顧客提出時は `data-customer="true"` の章だけ抽出できる |
+| `README.md` | GitHub 閲覧者・AI エージェント | **短い索引**。要点＋ `README.html`（人間向け仕様）と `SKILL.md`（AI 向け規約）へのリンク |
+| `.claude/skills/<name>/SKILL.md` | AI エージェント | **実装の書き方ルール**（規約・DO/DON'T）。仕様説明は `README.html` に委ね相互リンク |
+
+- **棲み分け**: `README.html`＝「機能の仕様（人間向け）」、`SKILL.md`＝「コードの書き方（AI 向け）」。読者と目的が異なるため両立する。
+- **入口（TOP ページ）**: リポジトリルートの [`README.html`](./README.html) が全 `README.html` へのポータル（目次）。ビルド不要でブラウザで開ける。新しい `README.html` を配置したら、この目次にも 1 行追加する（漏れは CI `docs-check` が検出）。
+- **参照トポロジ**（既存の一方向ルールを維持）: `README.md`（索引）→ `README.html`（仕様）／ `SKILL.md`（規約）→ `AGENTS.md`（正典）。
+  上流（`AGENTS.md`）から個別 README への下向き内容参照は足さない。
+- **ドメイン詳細は複製しない**: 受注 ER・ステートマシン・計算仕様など doc4 に既出のものは `README.html` から `https://doc4.ec-cube.net/` へリンクする。
+- **テンプレートと粒度**の基準はパイロット [`src/Eccube/Service/PurchaseFlow/README.html`](./src/Eccube/Service/PurchaseFlow/README.html)（＋ 同ディレクトリの `README.md`）。新規配置時はこれを金型にする。
+  - `README.html` は自己完結 HTML。共通 CSS を将来当てられるよう過度なインライン装飾を避け、`data-customer="true"`＝顧客提出にも載る章 / `"false"`＝開発者向け（拡張・内部注意点）で振り分ける。
+  - Skill が無いディレクトリ（例 `Doctrine/` `DependencyInjection/` `Attribute/` `Service/AgentCommerce/`）は `README.md` の SKILL 行を省き `README.html` のみを指す。
+- **集約出力・鮮度維持**: `bin/console eccube:docs:export [--filter=customer]` で全 `README.html` を集約出力できる（`--filter=customer` は `data-customer="true"` の章だけ抽出）。鮮度は PR テンプレートのチェック項目と CI（`docs-check`）で維持する。静的サイト化・本番公開先（doc4 への統合を含む）は **Issue #6906** で検討（未確定）。
+
 ## プロジェクト概要
 
 EC-CUBE は日本で広く使われる OSS の EC プラットフォームです。本ブランチ（4.4）は **Symfony 7.4 / PHP 8.2+** 上に構築されています。

README.html

@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html lang="ja">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>EC-CUBE 仕様書ポータル</title>
+<style>
+ /* 最小限のスタイル。§8.2 の静的サイト側で共通 CSS を上書きできるよう、
+    装飾はクラス指定に寄せ、過度なインライン装飾は避ける。 */
+ body{font-family:system-ui,-apple-system,"Segoe UI",sans-serif;line-height:1.7;max-width:960px;margin:0 auto;padding:2rem;color:#222}
+ h1,h2{border-bottom:1px solid #ddd;padding-bottom:.3rem}
+ h1{margin-bottom:.2rem}
+ .nav{font-size:.9rem;color:#555;margin:.2rem 0 1.5rem}
+ table{border-collapse:collapse;width:100%;margin:1rem 0}
+ th,td{border:1px solid #ccc;padding:.4rem .6rem;text-align:left;vertical-align:top}
+ th{background:#f4f4f4}
+ code{background:#f4f4f4;padding:.1rem .3rem;border-radius:3px;font-size:.92em}
+ .flow{background:#f9f9f9;border:1px solid #ddd;padding:1rem;white-space:pre;overflow-x:auto;font-family:ui-monospace,monospace;font-size:.88rem;line-height:1.5}
+ .note{background:#fff8e1;border-left:4px solid #f0c040;padding:.6rem 1rem;margin:1rem 0}
+ .dev-only{font-size:.75rem;color:#888;font-weight:normal;margin-left:.5rem}
+ .badge{display:inline-block;background:#eef;border:1px solid #ccd;border-radius:3px;padding:0 .4rem;font-size:.8rem}
+</style>
+</head>
+<body>
+
+<h1>EC-CUBE 仕様書ポータル</h1>
+<p class="nav">
+ 索引: <a href="./README.md">README.md</a>
+ ／ 規約ハブ（正典）: <a href="./AGENTS.md">AGENTS.md</a>
+ ／ ドメイン詳細: <a href="https://doc4.ec-cube.net/">doc4.ec-cube.net</a>
+</p>
+
+<section data-section="overview" data-customer="true">
+ <h2>このページについて</h2>
+ <p>EC-CUBE の主要な機能ディレクトリには、コードと同じ場所へ <strong><code>README.html</code>（人間向けの仕様書）</strong>と
+ <code>README.md</code>（GitHub 表示用の短い索引）を配置しています（Issue #6906・<a href="./AGENTS.md">AGENTS.md</a> §8.1）。
+ このページは、それら各ディレクトリの <code>README.html</code> への<strong>入口（TOP ページ）</strong>です。</p>
+ <p>各 <code>README.html</code> は<strong>自己完結した HTML 文書</strong>なので、リポジトリを取得したあと
+ ビルド不要でそのままブラウザで開けます。下の表のディレクトリ名をクリックすると、そのディレクトリの仕様へ移動します。</p>
+ <div class="note">実装の書き方ルール（AI・開発者向けの規約 / DO・DON'T）は各 <code>README.html</code> からリンクする
+ <code>.claude/skills/&lt;name&gt;/SKILL.md</code> が正典です。<code>README.html</code>＝「機能の仕様」、<code>SKILL.md</code>＝「コードの書き方」で棲み分けます。</div>
+</section>
+
+<section data-section="core-layers" data-customer="true">
+ <h2>コアレイヤ（<code>src/Eccube/</code>）</h2>
+ <table>
+  <tr><th>ディレクトリ</th><th>役割</th></tr>
+  <tr><td><a href="src/Eccube/Controller/README.html"><code>Controller/</code></a></td><td>HTTP コントローラ（管理画面・フロント）</td></tr>
+  <tr><td><a href="src/Eccube/Entity/README.html"><code>Entity/</code></a></td><td>Doctrine エンティティ（<code>#[ORM\…]</code> 属性マッピング）</td></tr>
+  <tr><td><a href="src/Eccube/Repository/README.html"><code>Repository/</code></a></td><td>データアクセス（クエリ・検索）</td></tr>
+  <tr><td><a href="src/Eccube/Form/README.html"><code>Form/</code></a></td><td>フォーム（FormType・拡張・バリデーション・値変換）</td></tr>
+  <tr><td><a href="src/Eccube/Service/README.html"><code>Service/</code></a></td><td>ビジネスロジックの受け皿</td></tr>
+  <tr><td><a href="src/Eccube/EventListener/README.html"><code>EventListener/</code></a></td><td>イベントリスナ</td></tr>
+  <tr><td><a href="src/Eccube/Security/README.html"><code>Security/</code></a></td><td>認証・認可</td></tr>
+  <tr><td><a href="src/Eccube/Twig/Extension/README.html"><code>Twig/Extension/</code></a></td><td>Twig 拡張（Filter・Function）</td></tr>
+  <tr><td><a href="src/Eccube/Command/README.html"><code>Command/</code></a></td><td>コンソールコマンド（バッチ）</td></tr>
+  <tr><td><a href="src/Eccube/Plugin/README.html"><code>Plugin/</code></a></td><td>プラグイン管理</td></tr>
+  <tr><td><a href="src/Eccube/Attribute/README.html"><code>Attribute/</code></a></td><td>PHP 属性定義（フロー宣言 等）</td></tr>
+  <tr><td><a href="src/Eccube/DependencyInjection/README.html"><code>DependencyInjection/</code></a></td><td>DI 拡張・コンパイラパス</td></tr>
+  <tr><td><a href="src/Eccube/Doctrine/README.html"><code>Doctrine/</code></a></td><td>Doctrine 関連（マッピング・ライフサイクル支援）</td></tr>
+ </table>
+</section>
+
+<section data-section="subsystems" data-customer="true">
+ <h2>高複雑サブシステム</h2>
+ <table>
+  <tr><th>ディレクトリ</th><th>役割</th></tr>
+  <tr><td><a href="src/Eccube/Service/PurchaseFlow/README.html"><code>Service/PurchaseFlow/</code></a></td><td>受注処理パイプライン（計算・検証・確定）</td></tr>
+  <tr><td><a href="src/Eccube/Controller/Admin/Order/README.html"><code>Controller/Admin/Order/</code></a></td><td>管理画面の受注管理</td></tr>
+  <tr><td><a href="src/Eccube/Service/AgentCommerce/README.html"><code>Service/AgentCommerce/</code></a></td><td>エージェントコマース（ACP / UCP）基盤</td></tr>
+ </table>
+</section>
+
+<section data-section="agent-commerce" data-customer="true">
+ <h2>AgentCommerce サブドメイン（<code>src/Eccube/Service/AgentCommerce/</code>）</h2>
+ <table>
+  <tr><th>サブドメイン</th><th>役割</th></tr>
+  <tr><td><a href="src/Eccube/Service/AgentCommerce/Catalog/README.html"><code>Catalog/</code></a></td><td>カタログ（商品フィード）</td></tr>
+  <tr><td><a href="src/Eccube/Service/AgentCommerce/CheckoutSession/README.html"><code>CheckoutSession/</code></a></td><td>チェックアウトセッション</td></tr>
+  <tr><td><a href="src/Eccube/Service/AgentCommerce/Discovery/README.html"><code>Discovery/</code></a></td><td>ディスカバリ（capability 提示）</td></tr>
+  <tr><td><a href="src/Eccube/Service/AgentCommerce/Exception/README.html"><code>Exception/</code></a></td><td>例外</td></tr>
+  <tr><td><a href="src/Eccube/Service/AgentCommerce/Fulfillment/README.html"><code>Fulfillment/</code></a></td><td>フルフィルメント（出荷）</td></tr>
+  <tr><td><a href="src/Eccube/Service/AgentCommerce/Idempotency/README.html"><code>Idempotency/</code></a></td><td>冪等性（重複実行の防止）</td></tr>
+  <tr><td><a href="src/Eccube/Service/AgentCommerce/Payment/README.html"><code>Payment/</code></a></td><td>決済</td></tr>
+  <tr><td><a href="src/Eccube/Service/AgentCommerce/Security/README.html"><code>Security/</code></a></td><td>セキュリティ（認証・スコープ・メッセージ署名・鍵の保管）</td></tr>
+ </table>
+</section>
+
+<section data-section="app" data-customer="true">
+ <h2>プロジェクト領域（<code>app/</code>）</h2>
+ <table>
+  <tr><th>ディレクトリ</th><th>役割</th></tr>
+  <tr><td><a href="app/Customize/README.html"><code>app/Customize/</code></a></td><td>プロジェクト固有のカスタマイズ（アップグレード安全）</td></tr>
+  <tr><td><a href="app/DoctrineMigrations/README.html"><code>app/DoctrineMigrations/</code></a></td><td>DB マイグレーション</td></tr>
+  <tr><td><a href="app/Plugin/README.html"><code>app/Plugin/</code></a></td><td>インストール済みプラグイン</td></tr>
+ </table>
+</section>
+
+</body>
+</html>

README.md

@@ -16,6 +16,7 @@
 + 本体開発にあたって不明点などあれば[Issue](https://github.com/EC-CUBE/ec-cube/wiki/Issues%E3%81%AE%E5%88%A9%E7%94%A8%E6%96%B9%E6%B3%95)をご利用下さい。
 + EC-CUBE 3系の保守については、 [EC-CUBE/ec-cube3](https://github.com/EC-CUBE/ec-cube3/)にて開発を行っております。
 + EC-CUBE 2系の保守については、 [EC-CUBE/ec-cube2](https://github.com/EC-CUBE/ec-cube2/)にて開発を行っております。
++ コード近接の仕様書（各機能ディレクトリの `README.html`）の入口は [`README.html`（仕様書ポータル）](README.html) です。ビルド不要でブラウザで開けます。
 
 ## インストール
 
@@ -52,7 +53,7 @@ JavaScript のライブラリは esbuild でバンドル/minifyされます。
 バンドルするライブラリを変更する場合は、テンプレートごとに以下の bundle.js を修正し、リビルドしてください。
 - [html/template/admin/assets/js/bundle.js](html/template/admin/assets/js/bundle.js)
 - [html/template/default/assets/js/bundle.js](html/template/default/assets/js/bundle.js)
-- [html/template/install/assets/js/bundle.js](html/template/default/install/js/bundle.js)
+- [html/template/install/assets/js/bundle.js](html/template/install/assets/js/bundle.js)
 
 ```shell
 npm ci # 初回およびpackage-lock.jsonに変更があったとき