# 進捗管理ダッシュボード タスク管理ツール（Linear）のデータを自動で取得し、AIが健康度を判定、HTMLダッシュボードを生成してSlackに画像付きで通知するツールです。 ``` ┌──────────────────────────────────────────────────────────────┐ │ 📊 マガジン進捗管理ダッシュボード │ │ │ │ 💊 進捗健康度 │ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ 企画案 │ │ 構成 │ │ 原稿 │ │ 動画 │ │ │ │ 🟢 │ │ 🟡 │ │ 🟢 │ │ 🔴 │ │ │ │ 順調 │ │ 注意 │ │ 順調 │ │ 危険 │ │ │ └────────┘ └────────┘ └────────┘ └────────┘ │ │ │ │ 🤖 AIからの提案 │ │ 🔥 優先度：高 ─ 動画編集が3日遅延... │ │ 🧭 優先度：中 ─ 原稿の引き継ぎを... │ │ 🌱 優先度：低 ─ ナレッジを蓄積... │ │ │ │ 📋 マガジン別ステータス / 📅 カレンダー │ └──────────────────────────────────────────────────────────────┘ ``` Slackにはこのダッシュボードのスクリーンショットが3枚届きます。ブラウザで詳細も確認できます。 一人でも使えます。自分のLinearにタスクを登録すればダッシュボードが動きます。チームメンバーがいなくても問題ありません。 --- ## 料金について このツールで使う外部サービスはすべて無料枠で利用できます。 | サービス | 用途 | 料金 | |---|---|---| | Linear | タスク管理（データの取得元） | Free プランで十分 | | Gemini API | AIによる改善提案の生成 | 無料枠あり | | Surge | ダッシュボードHTMLの公開 | 無料 | | Slack | ダッシュボード画像の通知先 | 無料ワークスペースで可 | | GitHub Actions | 定期自動実行（オプション） | 毎月 2,000 分無料 | --- ## このツールの4パーツ 第3回講義で学んだ「4パーツ」が、このツールではどのファイルに対応しているかを示します。 ``` ┌─────────────┐ │ トリガー │ .github/workflows/run-dashboard.yml │ （いつ動く） │ → 毎朝9時 or 手動実行 └──────┬──────┘ ▼ ┌─────────────┐ │ ソース元 │ scripts/fetch-data.js │ （データ） │ → Linear API からタスクデータを取得 └──────┬──────┘ ▼ ┌─────────────┐ scripts/calculate-health.js ← 健康度を計算 │ 処理する場所 │ scripts/generate-ai-suggestions.js ← AIが提案を生成 │ （加工） │ scripts/generate-dashboard.js ← HTMLを組み立てる └──────┬──────┘ ▼ ┌─────────────┐ scripts/deploy-to-surge.js → ウェブに公開 │ 届ける先 │ scripts/take-screenshot.js → 画像に変換 │ （配信） │ scripts/post-to-slack.js → Slack に通知 └─────────────┘ ``` --- ## セットアップ ### 準備するもの - Node.js 18 以上（持っていない場合は AI に「Node.jsをインストールして」と依頼） - Linear アカウント（持っていない場合は Part B で作成します） - Google アカウント（持っていない場合は Part C の前に作成してください） - Slack ワークスペース（持っていない場合は Part D で作成します） ### Part A: リポジトリを開く 1. Giteaからリポジトリをクローンする 2. Cursorでフォルダを開く 3. ターミナルを開いて依存関係をインストールする ターミナルの開き方: Cursor/VSCode のメニュー「Terminal」→「New Terminal」、またはキーボードで `` Ctrl + ` ``（バッククォート）を押す。 ```bash npm install ``` ### Part B: Linear API キーを取得する Linear はタスク管理ツールです。このツールのデータ取得元になります。 1. [Linear](https://linear.app/) にアカウントを作成する（または既存のワークスペースを使う） アカウント作成中に GitHub 連携・メンバー招待・メール通知の設定画面が表示されますが、**すべてスキップ（「I'll do this later」）して問題ありません**。後からいつでも設定できます。 2. Settings → 左メニューの「Account」→「Security & Access」→ Personal API keys で新しいキーを作成する > 「Settings → API」で見つからない場合は、画面左メニューの「Account」セクションの下にある「Security & Access」を探してください。 **APIキーは作成時の一度だけ表示されます。** コピーし忘れて画面を閉じてしまった場合は、古いキーを削除して新しく作り直せば大丈夫です。 3. `.env` ファイルを作成し、キーを設定する ```bash cp .env.example .env ``` `.env` を開いて以下を設定: ``` MAGAZINE_LINEAR_API_KEY=lin_api_ここにコピーしたキーを貼る MAGAZINE_LINEAR_TEAM_KEY=あなたのチームキー ``` `MAGAZINE_LINEAR_TEAM_KEY` は Linear のチーム設定画面の URL に含まれるキー（例: `MYTEAM`）です。 **チェックポイント**: 以下のコマンドでデータが取得できることを確認: ```bash node scripts/fetch-data.js ``` `data/linear-data.json` にデータが保存されれば成功です。 :::info Linear のラベル設定 このツールは Linear のラベルグループを使って進捗を判定します。初期設定では「マガジン作成ステータス（イシュー）」というラベルグループを参照します。自分のプロジェクトに合わせて `config/settings.js` のラベル名を変更してください。 ::: ### Part C: Gemini API キーを取得する Gemini は Google の AI です。健康度データから改善提案を自動生成します。APIキーの発行は [Google AI Studio](https://aistudio.google.com/) という管理画面で行います（Gemini を直接使うのではなく、API キーだけをここで取得します）。 Google アカウントが必要です。持っていない場合は先に作成してください。 1. [Google AI Studio](https://aistudio.google.com/) にアクセスする 2. 「Get API key」→「Create API key」でキーを作成する（既にキーがある場合はそれを使っても OK） 3. `.env` に追記する ``` MAGAZINE_GEMINI_API_KEY=ここにコピーしたキーを貼る ``` **チェックポイント**: 以下のコマンドで提案が生成されることを確認: ```bash npm run calculate-health npm run ai-suggestions ``` 「生成されたAI提案」が3件表示されれば成功です。Gemini API が使えない場合も、フォールバック機能で提案は自動生成されます。 ### Part D: Slack Bot を作成する Slack にダッシュボードの画像を投稿するための Bot を作ります。 Slack アカウントとワークスペースを持っていない場合は、先に [Slack](https://slack.com/) でワークスペースを作成してください。 1. [Slack API](https://api.slack.com/apps) にアクセスし「Create New App」→「From scratch」 2. 左メニューの「OAuth & Permissions」を開き、「Scopes」セクションまでスクロールする 3. 「Bot Token Scopes」の「Add an OAuth Scope」ボタンをクリックし、検索ボックスに入力して以下の2つを追加する: - `chat:write` - `files:write` 4. ページ上部の「Install to Workspace」（または左メニューの「Install App」）をクリックしてインストールする 5. インストール後に表示される「Bot User OAuth Token」（`xoxb-` で始まる文字列）をコピーする > トークンが見つからない場合は、左メニューの「OAuth & Permissions」を開くと「OAuth Tokens for Your Workspace」セクションに表示されています。 6. 投稿先チャンネルで `/invite @あなたのBot名` を実行 7. チャンネル ID を取得（チャンネル名を右クリック → 「チャンネル詳細を表示」の最下部） 8. `.env` に追記する ``` MAGAZINE_SLACK_BOT_TOKEN=xoxb-ここにトークンを貼る MAGAZINE_SLACK_CHANNEL_ID=C0ここにチャンネルIDを貼る ``` ### Part E: Surge アカウントを準備する Surge はHTMLを無料で公開できるサービスです。ダッシュボードをウェブで見られるようにします。 1. 以下のコマンドでアカウントを作成する ```bash npx surge login ``` メールアドレスとパスワードの入力を求められます。**初回はアカウントが自動作成されます。** 既存のアカウントにログインするのではなく、好きなパスワードを新しく設定してください。 > **ターミナルでのパスワード入力について**: パスワードを入力しても画面には何も表示されません（`****` も出ません）。これはセキュリティ上の仕様です。そのまま入力してEnterを押せば反映されます。 2. トークンを取得する ```bash npx surge token ``` 3. `.env` に追記する ``` MAGAZINE_SURGE_LOGIN=あなたのメールアドレス MAGAZINE_SURGE_TOKEN=ここにトークンを貼る MAGAZINE_SURGE_DOMAIN=あなたのプロジェクト名-dashboard.surge.sh ``` `MAGAZINE_SURGE_DOMAIN` は好きな名前を設定できます（例: `my-team-dashboard.surge.sh`）。 ### Part F: 動作確認 すべての環境変数が設定できたら、動作確認に進みます。 まず、スクリーンショット撮影に必要な Playwright のブラウザをインストールします: ```bash npx playwright install chromium ``` 次に、全パイプラインを実行します: ```bash npm run run-all ``` 成功すると: - `output/dashboard.html` にダッシュボードが生成される - Surge にデプロイされてブラウザで見られる - Slack にスクリーンショット3枚が投稿される ここまでで手動実行は完了です。毎朝自動でダッシュボードを更新してSlackに届くようにしたい場合は、次の「自動実行の設定（GitHub Actions）」に進んでください。 --- ## 自動実行の設定（GitHub Actions） GitHub Actions を使うと、毎朝自動でダッシュボードを更新してSlackに投稿できます。手動で毎朝コマンドを打つ必要がなくなります。 GitHub アカウントを持っていない場合は、先に [GitHub](https://github.com/) でアカウントを作成してください。 ### 設定手順 1. GitHub にリポジトリを作成し、コードをプッシュする Gitea からクローンした場合、GitHub は別のリモートとして追加します。AIに「このリポジトリを GitHub にもプッシュしたい」と相談すれば手順を案内してもらえます。 > **`npm ci` のエラーについて**: GitHub Actions のワークフローは `npm ci` を使って依存関係をインストールします。`package-lock.json` がコミットされていないと失敗するので、プッシュ前に `package-lock.json` が含まれていることを確認してください。 2. Settings → Secrets and variables → Actions で以下のシークレットを追加: | シークレット名 | 値 | |---|---| | `MAGAZINE_LINEAR_API_KEY` | Linear API キー | | `MAGAZINE_LINEAR_TEAM_KEY` | Linear チームキー | | `MAGAZINE_GEMINI_API_KEY` | Gemini API キー | | `MAGAZINE_SLACK_BOT_TOKEN` | Slack Bot トークン | | `MAGAZINE_SLACK_CHANNEL_ID` | Slack チャンネル ID | | `MAGAZINE_SURGE_LOGIN` | Surge メールアドレス | | `MAGAZINE_SURGE_TOKEN` | Surge トークン | | `MAGAZINE_SURGE_DOMAIN` | Surge ドメイン | 3. `.github/workflows/run-dashboard.yml` の `schedule` 行のコメントを外す ```yaml schedule: - cron: '0 0 * * 1-5' # 毎朝9時（JST）、平日のみ ``` 4. Actions タブで「ダッシュボード更新」を手動実行して動作を確認する :::info 企画案ストック判定の制限 GitHub Actions では実行ごとにワークスペースがリセットされるため、企画案ストックの週次判定は正確に機能しません（毎回初回扱いになります）。正確な判定が必要な場合は、`data/stock-tracker.json` を永続化する設計を追加してください。 ::: --- ## カスタマイズの手順 ### Linear のラベル構造を変更する `config/settings.js` を開いて、あなたの Linear ワークスペースのラベル名に合わせて変更してください。 ```javascript export const LABEL_GROUPS = { parentStatus: 'あなたのラベルグループ名', subIssueStatus: 'あなたのサブイシューラベルグループ名', }; export const STATUS_LABELS = { stock: '1.企画案ストック', // あなたのラベル名に変更 composition: '2.構成作成中', // あなたのラベル名に変更 manuscript: '3.原稿執筆中', // あなたのラベル名に変更 video: '4.動画編集中', // あなたのラベル名に変更 }; ``` ### 担当者名を変更する `config/mappings.js` の `ASSIGNEE_MAPPINGS_INCLUDE` と `ASSIGNEE_MAPPINGS_STARTS_WITH` を編集して、チームメンバーの Linear ユーザー名と表示名の対応を設定してください。 ### 健康度の閾値を調整する `config/health-thresholds.yaml` を編集します。コードを変更する必要はありません。 ```yaml stock: healthy: 8 # ≥8本で順調（🟢） warning: 5 # 5-7本で注意（🟡） delay: healthy: 0 # 遅延なしで順調 warning: 1 # 1日遅延で注意 ``` ### AI提案のプロンプトを調整する `config/ai-prompts/unified.md` を編集します。`{{CONTEXT}}` の部分に健康度データが自動で挿入されます。 ### 見た目（CSS）を変更する `config/dashboard-styles.css` を編集します。ダッシュボードのデザインを自由に変更できます。 --- ## 仕組みの解説 このツールは7つのスクリプトがパイプラインとして順番に実行されます。 ``` npm run run-all ① fetch-data Linear API からタスクデータを取得 → data/linear-data.json ② calculate-health 健康度を計算 → data/health-data.json ③ ai-suggestions Gemini で改善提案を生成 → data/ai-suggestions.json ④ generate-dashboard HTML ダッシュボードを組み立て → output/dashboard.html ⑤ deploy Surge にデプロイ → data/deployed-url.txt ⑥ screenshot Playwright でスクリーンショット → output/screenshot-*.png ⑦ post-slack Slack に画像とサマリーを投稿 ``` 各スクリプトは独立しており、個別に実行できます: ```bash npm run fetch-data # ①だけ実行 npm run calculate-health # ②だけ実行 npm run ai-suggestions # ③だけ実行 npm run generate-dashboard # ④だけ実行 npm run deploy # ⑤だけ実行 npm run screenshot # ⑥だけ実行 npm run post-slack # ⑦だけ実行 ``` ### 設定ファイルの役割 | ファイル | 役割 | |---|---| | `config/settings.js` | Linear のチームキー・ラベル名など、プロジェクト固有の設定 | | `config/mappings.js` | 担当者名の変換ルール | | `config/health-thresholds.yaml` | 健康度判定の閾値（コード変更不要で調整可能） | | `config/ai-prompts/unified.md` | AI提案生成のプロンプト | | `config/dashboard-styles.css` | ダッシュボードの見た目 | --- ## セキュリティについて - `.env` ファイルには API キーやトークンが含まれます。**Git にコミットしてはいけません** - `.gitignore` で `.env` は除外済みです - `.env.example` はキーの形式だけを示したテンプレートで、実際のキーは含まれていません **⚠️ API キーやパスワードを AI チャットに貼り付けないでください。** Cursor のチャットやその他の AI ツールに API キーを送ると、外部サーバーに送信される可能性があります。キーの設定は `.env` ファイルへの直接入力で行い、チャット欄には貼らないようにしてください。 --- ## 困ったときは つまずいたときは、以下の順で相談してください。 1. **AIに聞く** — エラー文やスクリーンショットを貼って質問する 2. **Slackのチームホームチャンネルで相談する** — 「AIにこう聞いたけど解決しなかった」と経緯を添える 3. [**問い合わせフォーム**](https://tayori.com/form/59d283f664136f1bf4525b0a7eef7d3814bcdd72)**から運営に連絡する** — 試したことを一緒に書く ### よくあるトラブル | 症状 | 対処 | |---|---| | `fetch-data.js` でデータが0件 | Linear のラベルグループ名が `settings.js` と一致しているか確認 | | Gemini API エラー | フォールバック機能が自動で動くので、提案は生成されます | | Slack `not_in_channel` | 投稿先チャンネルで `/invite @あなたのBot名` を実行 | | Surge デプロイ失敗 | `npx surge login` でログイン状態を確認 | | スクリーンショットが真っ白 | `npx playwright install chromium` を実行 | :::info 環境制約がある場合 会社のSlackにBot追加不可、APIキーが取れないなどの制約がある場合は、ソース元をJSONファイルに変えてローカルで動かすこともできます。AIに「Linear API を使わずにサンプルデータで動かしたい」と相談してみてください。 :::