skills/youtube-28day-report/references/template-usage.md

# 承認済みの見た目を使って、HTMLレポートを作る

`assets/report-template.html` は、歌島さんが承認した「読みやすさ修正版2」の配色、18pxの日本語本文、章カード、結論の強調、変更元と案内先の区別を引き継ぐ、個人データを含まないひな形です。ひな形自体を完成したレポートとして渡してはいけません。

分析済みの結果をこのHTMLへ入れ、完成版を別のファイルへ保存します。ひな形や、その中の数値欄を直接使って分析を始めません。

## 作成の流れ

1. 入力ファイルと公開情報から、根拠のある結論・動画候補・数値・確認範囲を決める。元のレポートのチャンネル名や数値は引き継がない。
2. ひな形をコピーし、繰り返しブロックを必要な件数だけ複製して埋める。単純な全置換の前に、動画・企画ごとに値が異なるブロックを処理する。
3. 残りの `{{TOKEN}}` を埋め、不要な見本ブロックと `.template-notice` を取り除く。章ごとの確認とレポート検証を終え、完成版のみを保存する。

## 置換の約束

- 置換箇所は `{{UPPER_SNAKE_CASE}}`。`{{CHANNEL_NAME}}`、`{{PERIOD_START}}`、`{{PERIOD_END}}`、`{{CREATED_AT}}` などは全文共通です。日付は入力の実際の期間を使います。
- `<!-- BEGIN REPEAT: NAME -->` から対応する `<!-- END REPEAT: NAME -->` までは、必要な件数だけ複製する枠です。`EXTERNAL_CHANNEL` の中に `EXTERNAL_VIDEO` が入るため、入れ子に対応してください。
- 通常のトークンはテキストとしてHTMLエスケープします。引用符もエスケープします。URL欄は確認済みの `https://` URLだけを入れます。動画IDは確認済みの11文字IDだけを使います。
- `_HTML` で終わるトークンは、確認済みのリンクを含む短いHTML用です。既存の資料からHTMLをそのままコピーせず、必要なリンクと文章だけを組み立てます。スクリプトや任意の埋め込みを入れません。
- `*_WIDTH` は0から100までの有限な数値を入れます。棒グラフの値、分母、尺度を本文にも書きます。比率が算出できない場合はバーを削除し、数字を確認できない理由を短く示します。
- 未取得や非表示は「未取得」「公開情報では未確認」と書きます。0件に置き換えません。基準値が0の場合は増減率を無理に計算しません。
- 空欄があるたびに読者への質問を増やさず、重要な不足と次回の追加資料をまとめます。資料がない章は、確認できなかったことと次に必要な資料を短く残します。

## 章とブロック

| 固定アンカー | 内容・主な繰り返し枠 |
| --- | --- |
| `conclusion` | 今月の結論、優先する3つ、今日始める一つ。曖昧な「繰り返す」だけで終えず、対象動画と変更内容を書く。 |
| `overview` | 全体、前回との差、通常・Shorts・ライブ、期間内新作・過去動画。`OVERVIEW_METRIC`、`COHORT`、`OVERVIEW_BAR`。 |
| `external` | 最重要の参考チャンネルと具体動画。`EXTERNAL_CHANNEL_SUMMARY`、`EXTERNAL_CHANNEL`、`EXTERNAL_VIDEO`。選定理由は数値と視聴者の接点を示す。 |
| `own` | 自動画の再利用可能な点と改善。`OWN_VIDEO`、`OWN_DIAGNOSIS`。同形式・近い尺・公開後日数をそろえた比較を添える。 |
| `plans` | 制作できる本数に合わせる企画。`PLAN`。視聴者、今作る理由、冒頭、話す順、サムネ案、内外の参考動画、次動画、確認する数字。 |
| `search` | 実際に来た語、近い語のまとまり、需要を確認した別資料。`SEARCH_TERM`、`SEARCH_CLUSTER`。自チャンネル流入数を市場の検索数と呼ばない。 |
| `discovery` | 入口と次動画への案内。`TRAFFIC_SOURCE`、`RELATED_OWNER_CATEGORY`、`ROUTE`。自動画・外部確認済み・所有者未確認・明細未取得を区別する。 |
| `engagement` | 視聴維持・高評価・コメント・共有・登録等。`ENGAGEMENT_METRIC`。維持率グラフなしに離脱秒数を作らない。 |
| `playlists` | 順番と動画リンクが分かるリスト、トップの並び。`PLAYLIST`、`HOMEPAGE_ROW`。トップの未確認状態は明示する。 |
| `goals` | 各先生の目標、現在、残り、次の28日で注力すること。`GOAL_SCENARIO`。目標を10万・100万と固定せず、本人の入力を使う。 |
| `next` | 次回の比較と変更メモ。`NEXT_REVIEW_ACTION`。前回の提案を試したかを確認し、数字の変化を変更の効果と即断しない。 |
| `appendix` | `MONTHLY_METRIC`、`INPUT_FILE`、`METRIC_INVENTORY`、`METHOD`、`VIDEO_AUDIT`。合計と明細の取得範囲、指標の単位・分母・出典を残す。 |
| `sources` | `REFERENCE`。通し番号、短縮書誌、URL、要約、引用理由、限界。本文中の `(*1)` 等と一致させる。 |

`GOAL_SCENARIO` は十分なデータがあるときだけ使います。初回の28日間から達成日を約束しません。単純な試算を出す場合は仮定と不確実性を明示します。入力に目標や現在数がない場合は、その欄を確認待ちとして、架空の試算を作りません。

`CHANGELOG_DATE`、`CHANGELOG_ACTION`、`CHANGELOG_CONTEXT` は本人が残した記録があれば使います。記録がなければ完成レポートの空欄例として「変更した日を記入」などに置換し、実施済みのようには書きません。

## 動画の見せ方と数字

外部動画の `EXT_*` と自動画の `OWN_*` には、確認したタイトル、チャンネルURL、公開日、長さ、確認日、具体的な数値と出典を入れます。3つの `METRIC_*_LABEL/VALUE` の見本行は、必要な行数に増減できます。

外部動画は少なくとも、取得できた公開累計再生数と公開日を記載します。関連流入が分かる動画なら当該28日間の流入数と流入後の自チャンネル側の視聴時間を優先します。流入が確認できない動画は「テーマの参考候補」等と表示し、実際の関連元と混同させません。登録者数、公開後日数、同チャンネルの近い動画との比較は、確認できた範囲で添えます。比較数値が確認できないときは作りません。

自動画には、当該28日間の視聴回数、視聴時間・率、インプレッションとクリック率、登録増加等の取得できた値を入れます。公開累計と28日間の値を同じ指標として比較しません。`REVIEW_SCOPE` には「タイトルと説明欄の章立てを確認」など実際に見た範囲を書き、未視聴なのに冒頭や映像を見たようには書きません。

画像、プレーヤー、直接リンクは、同じ確認済み動画IDから作ります。画像は実際のYouTubeサムネイルで、生成画像を代用しません。iframeは最初からHTMLに置きます。`loading="lazy"` は読み込み量を抑える設定で、説明やプレーヤーをボタンの裏に隠すものではありません。自動再生しません。

動画カードのIDは `video-動画ID-external` と `video-動画ID-own`。同じ動画の詳細カードを何度も複製せず、企画からこのカードへリンクします。`PLAN_*_VIDEO_ID` は、必ず実際に作成した該当カードのIDと一致させます。確認できる参考動画がない企画では、リンク欄を未確認の説明に差し替えます。

回遊の案内先は `video-動画ID-destination-ROUTE_KEY` とし、同じ案内先が複数回出てもIDを重複させません。`ROUTE_KEY`、`PLAN_KEY`、`EXTERNAL_CHANNEL_KEY` は半角英数字とハイフンで一意にします。`ROUTE_DEST_ID` と変更元IDを区別し、自分自身を終了画面で案内する指定にしません。終了画面で案内する1本と、固定コメント・概要欄に貼る動画を一致させます。

## 見た目と仕上げ

- 本文は日本語18px、1段の長文を基本にし、18pxから縮めて詰め込みません。補助情報の出典・確認日は小さくして構いません。表はスマートフォンで項目名付きカードに変わるため、全セルの `data-label` を見出しと一致させます。
- 折りたたみ、タブ、ドロップダウン、説明を隠すボタンは追加しません。すべて本文に展開します。グラフは実際の値に合わせ、単位・期間・分母を併記します。
- すべての未置換トークン、見本用注意書き、不要な繰り返しコメントを除きます。IDの重複、目次と内部リンクの不一致、動画URL・画像・iframeのID不一致を確認します。
- 医学的な断定は確認した原著と対応させます。外部動画の人気を治療効果の根拠にしません。医療の具体的主張がない章へ無関係な論文を足しません。
- 見出しには結論か読者が行うことを入れ、専門語は最初に短く説明します。「繰り返す」「伸ばす」「改善する」で止めず、どの動画の何を変えるかまで書きます。

CSSはテンプレート内に同梱しています。フォントは端末の日本語フォントを優先します。動画の再生・サムネイル表示にはネット接続が必要です。印刷時はiframeを省いてサムネイルと直接リンクを残します。完成レポートには、今回のチャンネル名・対象期間・作成日が分かるファイル名を付けます。