LINE Friends Tracker — システム解説書

LINE 公式アカウントの友だち数を毎日自動取得し、Web ダッシュボードと Lark 通知で可視化するシステムの構成・処理内容・データベース・運用情報を網羅したスタッフ向け資料。

プロジェクト概要

目的

LINE 公式アカウント（L ステップ・UTAGE 接続）の友だち数（累計追加・有効友だち・累計ブロック）の推移を毎日自動で記録し、ブラウザでいつでも確認できる状態にする。あわせて、業務チャットツール Lark のグループへ毎朝集計結果を通知する。

解決したい課題

• 従来は Excel に手作業で記録しており、転記ミスや作業負荷が大きかった
• L ステップ・UTAGE のダッシュボードを個別に開かないと現状が把握できなかった
• 過去推移を時系列で振り返れる形式の資料が手元にあると望ましい

提供している機能

監視対象アカウント

システムアーキテクチャ

全体構成

3 つの主要コンポーネント

設計上の主要な選択

コンポーネント詳細

ingest（Python・Windows ローカル実行）

ローカル PC のタスクスケジューラから毎日起動される Python バッチ。配置場所は C:\AItools\AI_cursor_data\01_APP\line-friend-tracker\ingest。

ファイル構成

ingest/
├── .env                    # 機密情報（gitignore）
├── accounts.json           # アカウント定義
├── requirements.txt        # Python 依存
├── src/
│   ├── config.py           # .env + accounts.json + DB から設定を読み込む
│   ├── fetch.py            # LINE API クライアント
│   ├── store.py            # Neon Postgres への書き込み
│   ├── notify.py           # Lark Webhook 通知（インタラクティブカード）
│   ├── revalidate.py       # Vercel ISR の再生成トリガー
│   └── main.py             # 統合エントリ
├── scripts/
│   ├── run_daily.ps1       # タスクスケジューラから呼ばれるラッパー
│   ├── install_scheduler.ps1   # スケジューラ登録（初回のみ）
│   ├── uninstall_scheduler.ps1 # スケジューラ解除
│   ├── init_db.py          # DB スキーマ初期化（sql/*.sql を全適用）
│   ├── migrate_db.py       # 旧 Neon DB から新 DB へのデータ移行（一度きり）
│   ├── seed_app_settings.py # .env の Lark 設定値を app_settings へ移植
│   ├── import_csv.py       # 過去 Excel データ取り込み（移行時のみ）
│   └── test-api.ps1        # LINE API の動作確認用
├── sql/
│   ├── 001_init.sql        # accounts / daily_snapshots
│   ├── 002_auth.sql        # staff / password_reset_tokens
│   ├── 003_preferences.sql # staff.preferences カラム追加
│   ├── 004_staff_last_login.sql # staff.last_login_at カラム追加
│   └── 005_app_settings.sql # app_settings テーブル
└── data/
    └── logs/YYYY-MM-DD.log # 日次の実行ログ

主要モジュールの責務

web（Next.js・Vercel デプロイ）

Vercel 上で動作する Next.js アプリ。URL は https://line-friend-tracker.vercel.app/。

ディレクトリ構成（src 配下）

web/src/
├── app/
│   ├── layout.tsx                  # ルートレイアウト
│   ├── page.tsx                    # / → /dashboard リダイレクト
│   ├── login/page.tsx              # ログイン画面
│   ├── api/
│   │   ├── auth/login/route.ts     # ログイン処理
│   │   ├── auth/logout/route.ts    # ログアウト処理
│   │   └── revalidate/route.ts     # ingest からのキャッシュ再生成
│   └── (app)/                      # 認証必須エリア
│       ├── layout.tsx              # サイドバー付きレイアウト
│       ├── dashboard/page.tsx
│       ├── graphs/page.tsx
│       ├── accounts/[slug]/page.tsx
│       ├── reports/[slug]/page.tsx
│       ├── settings/page.tsx       # 個人設定
│       ├── staff/page.tsx          # スタッフ一覧（admin）
│       └── integrations/page.tsx   # 外部連携設定（admin）
├── components/
│   ├── app-sidebar.tsx
│   ├── charts/
│   │   ├── trend-chart.tsx
│   │   └── daily-changes-chart.tsx
│   ├── period-control.tsx
│   └── ui/                         # shadcn ベースの汎用 UI
└── lib/
    ├── auth/
    │   ├── jwt.ts                  # JWT 発行/検証
    │   ├── password.ts             # bcrypt ハッシュ
    │   ├── session.ts              # requireSession / requireRole
    │   └── staff.ts                # スタッフ DB ヘルパー
    ├── db/
    │   ├── client.ts               # Drizzle + Neon HTTP クライアント
    │   ├── schema.ts               # 全テーブルの Drizzle スキーマ
    │   ├── queries.ts              # 再利用クエリ
    │   └── seed-admin.ts           # 初期 admin 作成スクリプト
    ├── preferences.ts              # ユーザー UI 設定の型と定数
    ├── period.ts                   # 期間指定ロジック
    └── utils.ts

主要なライブラリ

database（Neon Postgres）

Vercel と同じ AWS リージョン us-east-1 に配置。Pooled / Unpooled の 2 種類の接続文字列を用途別に使い分ける。

日次処理フロー

毎日 11:00 (JST) に Windows タスクスケジューラから scripts\run_daily.ps1 が起動し、以下を実行する。

失敗時の挙動

• LINE API が status: "unready" を返した場合（前日データがまだ確定していない）、そのアカウントは SKIP され、Lark には通知されない
• 全アカウントが失敗した場合のみ、Lark にプレーンテキストで失敗通知を送る
• ログは ingest/data/logs/YYYY-MM-DD.log に追記される

データベース詳細

5 テーブル構成。スキーマ定義は Drizzle ORM（web/src/lib/db/schema.ts）と SQL マイグレーション（ingest/sql/*.sql）の両方に存在し、内容は揃えてある。

テーブル一覧と関係

accounts — LINE 公式アカウントマスタ

daily_snapshots — 日次スナップショット

インデックス: (date DESC) と (account_id, date DESC) の 2 本。

staff — ダッシュボード閲覧ユーザー

password_reset_tokens — パスワードリセット用ワンタイムトークン

UUID 主キー、staff_id 外部キー、token_hash（送信した平文トークンの SHA ハッシュ）、expires_at、used_at（NULL のものが有効）。短期間で使い捨てる前提。

app_settings — 管理画面で編集可能な key/value 設定

現在登録されているキー

主要画面の説明

ダッシュボード /dashboard

ログイン直後の画面。2 アカウントの最新指標（有効友だち・前日比・7 日純増など）と直近のミニグラフを並べて表示。

グラフ /graphs

2 アカウントを 1 つのグラフに重ねて表示。期間セレクタ（直近 30 日 / 90 日 / 全期間 / カスタム）で範囲を切り替え可能。

アカウント詳細 /accounts/[slug]

アカウント別の KPI カード、累計推移グラフ、日次差分グラフ、データ表。期間セレクタで範囲調整可能。右上に「レポート出力」ボタンあり。

全期間レポート /reports/[slug]

PDF 出力を前提とした印刷向けレイアウト。

• 全期間（実行月を除く完了月のみ）の累計追加・有効友だち・累計ブロック 3 系列エリアグラフ
• 月末日スナップショット表（行数 18 超で 2 列横並びレイアウト）
• 右上の「印刷 / PDF保存」ボタンでブラウザの印刷ダイアログを開く
• 印刷時はサイドバー等が非表示になり、A4 縦に最適化された専用チャートで描画される

個人設定 /settings

ログインユーザーごとに保存される UI 設定。現在は「グラフ表示スタイル」（linear / monotone / step / area）の選択肢を提供。

スタッフ一覧 /staff（admin のみ）

ダッシュボード閲覧ユーザーの管理。追加・編集・無効化・パスワードリセットが可能。新規追加時とリセット時に初回パスワードが 1 度だけ表示される。

外部連携 /integrations（admin のみ）

Lark 通知の宛先設定。Webhook URL と署名シークレットを編集できる。シークレットはマスク表示で、変更時のみ新しい値を入力する。「テスト送信」ボタンで現在保存中の設定で動作確認可能。

認証と権限

認証方式

独自実装の Cookie ベース認証。外部 IdP（Clerk 等）には依存していない。

• ログイン: メールアドレス + パスワード
• パスワードハッシュ: bcryptjs
• セッション: jose で署名した JWT を Cookie に格納（有効期間 7 日）
• サインアップ機能なし。新規ユーザーは admin が /staff 画面から作成する

権限ロール

初期管理者の追加

初回セットアップ時のみ、ローカルから npm run seed:admin を実行することでメール+パスワードを指定して admin アカウントを作成可能。

外部サービス連携

LINE Messaging API 外部

短期トークンを毎回新規発行する方式なので、L ステップ・UTAGE が発行している長期トークンと干渉せず共存できる。

Lark Webhook 外部

カスタム Bot の Webhook に対して、HMAC-SHA256 で署名した JSON を POST する。

string_to_sign = "{timestamp}\n{signing_secret}"
signature      = base64( HMAC-SHA256( key=string_to_sign, msg=b"" ) )

POST body:
{
  "timestamp": "1700000000",
  "sign": "...",
  "msg_type": "interactive",
  "card": { ... }
}

Vercel Revalidate API 内部

ingest が DB 書き込み完了後に Vercel 側の ISR キャッシュを更新するために叩く内部 API。REVALIDATE_TOKEN でアクセス制御。

環境変数・設定

ingest 側（ingest/.env）

ingest 側（ingest/accounts.json）

監視対象アカウントの定義。スキーマ:

{
  "accounts": [
    {
      "slug": "saki",
      "name": "新さきの海外不動産",
      "description": "Lステップ接続",
      "channel_id_env": "LINE_SAKI_CHANNEL_ID",
      "channel_secret_env": "LINE_SAKI_CHANNEL_SECRET",
      "display_color": "#3b82f6",
      "display_order": 1
    },
    { ... utage 側 ... }
  ]
}

web 側（Vercel 環境変数）

開発・運用情報

ローカル開発環境（ingest）

cd C:\AItools\AI_cursor_data\01_APP\line-friend-tracker\ingest

# 仮想環境
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 依存インストール
pip install -r requirements.txt

# 環境変数
Copy-Item .env.example .env
notepad .env   # 各値を埋める

# 動作確認（API のみ・DB/Lark には触れない）
powershell -File scripts\test-api.ps1

# 全工程の手動実行
python -m src.main
python -m src.main --no-notify        # Lark 通知をスキップ
python -m src.main --no-revalidate    # Vercel 再生成をスキップ
python -m src.main --date 2026-04-29  # 過去日のバックフィル

ローカル開発環境（web）

cd C:\AItools\AI_cursor_data\01_APP\line-friend-tracker\web

npm install

# ローカル DB に接続して開発サーバー起動
npm run dev                # http://localhost:3000

# 本番ビルドの確認
npm run build && npm run start

# DB マイグレーション関連
npm run db:generate        # Drizzle スキーマから SQL 生成
npm run db:push            # スキーマを直接 DB に反映
npm run db:studio          # Drizzle Studio で DB を覗く

# 初期 admin 追加
npm run seed:admin

デプロイ

定期実行（Windows タスクスケジューラ）

登録

powershell -ExecutionPolicy Bypass -File ingest\scripts\install_scheduler.ps1

• タスク名: LineFriendTracker
• 初回実行: 翌日 11:00（インストール当日の意図せぬ実行を避ける）
• 失敗時は 5 分間隔で 2 回まで再試行
• バッテリー駆動でも実行可、最大実行時間 30 分

状態確認

Get-ScheduledTask -TaskName "LineFriendTracker" | Get-ScheduledTaskInfo
Get-ScheduledTask -TaskName "LineFriendTracker" | Start-ScheduledTask  # 手動実行

解除

powershell -ExecutionPolicy Bypass -File ingest\scripts\uninstall_scheduler.ps1

ログ

毎日の実行ログは ingest\data\logs\YYYY-MM-DD.log に追記される。標準出力・エラー出力の両方を含む。

運用上の注意

• Windows PC がスリープ・シャットダウン中は実行されない。当日の朝 PC が起動しているか確認しておく
• LINE API は前日データの確定タイミングが不定。status: "unready" が返ることがあるが、翌日の実行で自動的にリカバリされる（古い日付の UPSERT は許容）
• Lark の通知先グループを変える場合、ソースコードや .env ではなく /integrations 画面から変更する
• 新しい LINE 公式アカウントを監視対象に追加する場合、accounts.json への追記と accounts テーブルへの INSERT、対応する .env へのチャネル情報追加が必要

主要な機能追加履歴

git の main ブランチに記録された主要な変更（新しいものが上）。

完全な履歴は git log で確認可能。

関連URL・参照先

関連内部ドキュメント

• README.md — プロジェクトの一行サマリ
• ingest/README.md — ingest 側のセットアップ手順
• docs/architecture.md — アーキテクチャ早見表（このドキュメントの簡易版）
• web/AGENTS.md — Next.js 16 を扱う際の注意事項メモ

本資料の対象コミット: 8d689f7（2026-05-16 時点）。資料更新時はファイル末尾のこの行と冒頭のメタ情報の更新日を併せて変更してください。