メインコンテンツまでスキップ

Trackable Links 仕様書

1. 概要​

QRコードによるリンク追跡・転送システム。設置場所ごとのアクセスログを記録し、分析に活用する。

1.1 ユースケース図​

1.2 ドメイン​

  • API: fwd.soshosai.com（QR転送・管理API）

1.2 アーキテクチャ​

2. 機能​

2.1 QR転送機能​

QRコードをスキャンすると、設定された転送先URLにリダイレクトする。

フロー:

  1. QRコードスキャン → fwd.soshosai.com?id={qrId}
  2. QRコード情報をDBから取得
  3. 場所未設定の場合 → 場所設定画面を表示
  4. アクセスログを記録
  5. 転送先URLにリダイレクト（301）

2.2 プロジェクト管理​

プロジェクト単位でQRコードを管理する。

項目説明
プロジェクトQRコードのグループ。転送先URLを持つ
QRコード個別のQRコード。場所情報を持つ
アクセスログQRスキャン時の記録

2.3 LINE Bot連携​

LIFFを使用したQRスキャナー機能を提供。

3. エンドポイント​

3.1 転送系（認証不要）​

MethodPath説明
GET/?id={qrId}QR転送（メイン機能）
GET/view/:qrIdQRコード情報表示
GET/linebot/scannerLIFFスキャナー画面

3.2 プロジェクト管理系（スタッフ認証必須）​

MethodPath説明
GET/projectsプロジェクト一覧
POST/projects/createプロジェクト作成
GET/projects/:idプロジェクト詳細
PUT/projects/:idプロジェクト更新
DELETE/projects/:idプロジェクト削除
GET/projects/:id/getAccessLogsアクセスログ取得

3.3 QRコード管理系（スタッフ認証必須）​

MethodPath説明
GET/projects/getQRCodeQRコード一覧
GET/projects/getQRCode/:idQRコード詳細
POST/projects/createQRCodeQRコード作成
PUT/projects/updateQRCode/:idQRコード更新
DELETE/projects/deleteQRCode/:idQRコード削除

3.4 場所設定系（スタッフ認証 + パスコード）​

MethodPath説明
POST/api/set-location場所設定
POST/api/edit-location/:qrId場所編集

4. データベース​

データベース名: soshosai-qr-forwarder

4.0 ER図​

4.1 Projects​

CREATE TABLE Projects (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT NOT NULL UNIQUE,
    name TEXT NOT NULL,
    destination_url TEXT NOT NULL,
    admin_user_id TEXT,
    created_at TEXT NOT NULL
);

4.2 QRCodes​

CREATE TABLE QRCodes (
    id TEXT PRIMARY KEY,          -- UUID
    project_id TEXT NOT NULL,
    location TEXT,                -- 設置場所
    creator_id TEXT,              -- 作成者のDiscord ID
    created_at TEXT NOT NULL,
    FOREIGN KEY (project_id) REFERENCES Projects(project_id)
);

4.3 AccessLogs​

CREATE TABLE AccessLogs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT NOT NULL,
    qr_id TEXT NOT NULL,
    accessed_at TEXT NOT NULL,
    user_agent TEXT,
    ip_address TEXT
);

5. 認証​

5.1 スタッフ認証​

/projects 以下のエンドポイントはスタッフ認証が必須。

認証フロー:

  1. soshosai_staff_jwt Cookieから JWT を取得
  2. unified-auth-worker で JWT を検証
  3. userType === 'staff' を確認

5.2 パスコード認証​

場所設定時は追加でパスコード認証が必要。

const expectedPasscode = c.env.LOCATION_SETUP_PASSCODE;
if (passcode !== expectedPasscode) {
	return c.json({ message: 'パスコードが正しくありません' }, 401);
}

6. 環境変数​

変数名説明
D1_DBD1 Database Binding
AUTH_SERVICEunified-auth-worker Binding
LOCATION_SETUP_PASSCODE場所設定用パスコード
LIFF_IDLINE LIFFアプリID
LOGGERログサービス Binding