SC-007 メール画像ショートコード

概要

• 指定ホール・日付に対応するメール画像を取得し、ページ内に埋め込み表示する。
• hall（ホール名）と date（日付）を属性で受け取り、MailImageConverter でバリデーション・DTO 変換後、MailImageController → MailImageService 経由で画像情報を取得、View で HTML にレンダリングする。

ワイヤーフレーム

同一 UI の記事埋め込み枠は PUB-001 の MailImageBlock（P-7）と共有する。

ブロック一覧

ブロックID	ブロック名	表示内容	初期値	ユーザー操作	アクション
B-0	メール画像シェル	日時ラベル＋枠（P-WORLD メール HTML または空メッセージ）＋引用キャプション	静止画表示	GIF 切替（メール枠ごと）／スクロール有効化（本番 P-WORLD 時）	表示モード切替

表示条件・注記

• 属性: hall / date 必須。
• メール無し: date + empty content シェルを残す（読込中／失敗と区別）。
• 管理画面: 出力なし。日別記事テンプレ経路は先頭ホールを同期描画し、他ホールは REST 遅延取得あり。
• ワイヤーフレーム: メールありの通常ケースをサンプル表示。
• P-WORLD 表示既定: 代表静止画（JPEG）。表示可能な GIF があるメール枠のみ「GIFで表示」ボタンを有効化し、押下で GIF／静止画を双方向切替する。GIF が無い（未リンク・TTL 削除済み等）場合はボタンを disabled にする。
• GIF 読込: 初回切替まで GIF HTML は <template> に留め、DOM に載せない（不要な GIF 取得を避ける）。loading="lazy" / decoding="async" は GIF 表示時の img に付与される。

メイン画像のファイル名と配置（運用前提）

メインのブログ用静止画は、MailImageService が 画像ファイル名を規則に従って連結して URL を組み立て、View（MailImage）がその URL を img 等に渡して表示する実装になっている。表示に先立ち、次の規則で メディアサーバー（本番では wp-content/uploads/ 配下）に同名ファイルを保存・公開しておく必要がある。

ファイル名の規則

次の 1 ファイルを 1 枚のメイン画像として参照する。

{YYYYMMDD}{HallEnum の値}_blog.png

• {YYYYMMDD}: ショートコードの date 属性（例: 20240101）
• {HallEnum の値}: 対象ホールの HallEnum の 英小文字の列挙値（island / espasu / bigapple / uno）。日本語のホール名ではない。

ベース URL は AppConstants::IMAGE_BASE_URL（https://www.slotkouryaku.com/wp-content/uploads/）。
連結例: https://www.slotkouryaku.com/wp-content/uploads/20240101island_blog.png

ファイル名の例（保存が必要な名前）

ショートコード例（抜粋）	必要なファイル名（uploads/ 直下相当）
hall="アイランド秋葉原" date="20240101"	20240101island_blog.png
hall="エスパス秋葉原" date="20240101"	20240101espasu_blog.png
hall="ビッグアップル秋葉原" date="20240101"	20240101bigapple_blog.png
hall="秋葉原uno" date="20240101"	20240101uno_blog.png

※ コード参照: core_src/Service/mail_image_service/MailImageService.php（$image_url の組み立て）、core_src/Constants/AppConstants.php（IMAGE_BASE_URL）。

P-WORLD メール HTML の静止画既定と GIF 切替

公開画面の MailImage は processed_html（代表静止画 URL）を既定表示する。PworldMailStillGifSrcReplacer で GIF 差し替え可能な場合のみ、切替用に GIF 版 HTML を生成し <template> に保持する（管理画面プレビューの既定 GIF タブとは独立）。

P-WORLD メール HTML 内画像の遅延読み込み

GIF 版 HTML に対して PworldMailDisplayMediaCacheBust::append_to_fragment_html が同一 DOM 走査内で GIF の <img> に次を付与する（src のパスが .gif のもののみ。既存の loading / decoding 属性がある場合は上書きしない）。

属性	値	目的
loading	lazy	ビューポート外の GIF 取得を遅延し、初回表示のネットワーク負荷を軽減
decoding	async	画像デコードをメインスレッド負荷から切り離す

GIF は初回切替時のみ <template> から DOM に挿入し、以降はパネルの表示切替のみ行う（切替のたびに画像を再取得しない）。

日別記事テンプレート経路では 先頭ホール（hall_names[0]）のみ DailyArticleTemplateController が MailImageController::execute() で同期描画する（Issue #3609）。成功時は完成 HTML（mail-image-placeholder なし）を初回 Document に含め、MailImageView 経由で mail_image.css / mail_image.js を enqueue する（GIF は <template>、切替は初期 enqueue の JS）。失敗時はプレースホルダへフォールバックし Document 全体は落とさない。2 ホール目以降はプレースホルダ + REST（GET /async-mail-image-batch、失敗ホールは GET /async-mail-image）。既存投稿本文に直書きされた [MailImage] ショートコードは同期のまま（テンプレート SSR とは別経路で二重定義しない）。全体フローは 日別記事 初期描画フロー を参照。

外部インターフェース

ショートコードタグ

• タグ名: [MailImage]
• 入力例: [MailImage hall="アイランド秋葉原" date="20240101"]

属性一覧

属性	役割	必須
hall	対象ホール名（HallEnum 対応）	○
date	対象日付（YYYYMMDD 形式）	○

エラー

条件	ユーザー向け挙動	メッセージ / ログ
hall 未指定または不正値	バリデーションエラーメッセージ表示（esc 済）	ShortCodeHelper 経由でバリデーションログ出力
date 未指定または YYYYMMDD 形式不正	バリデーションエラーメッセージ表示（esc 済）	ShortCodeHelper 経由でバリデーションログ出力
サービス・コントローラーの Throwable	エラーが発生しました：execute_if_not_admin	error_log（先頭 [ShortCodeHelper]）

更新不可とみなすもの（git管理外の内容に依存し、リポジトリだけでは追従できない依存）

• ショートコード名 MailImage を変更しない
  • 理由: 既存投稿本文にショートコードタグが直書きされているため
• 属性名 hall / date を変更しない
  • 理由: 既存投稿本文に属性名が直書きされているため