# SNSハーネス連携ガイド

Mail Studio と LINE Harness / X Harness（33_SNSハーネス）の連結仕様。

---

## アーキテクチャ全体像

```
┌─────────────────┐     outgoing webhook / automation     ┌─────────────────┐
│  LINE Harness   │ ──────────────────────────────────── → │                 │
│  (form_submitted│   POST /api/integrations/line/:token   │   Mail Studio   │
│   friend_add等) │   {event,data:{email,fields,...}}     │  (メール配信)    │
└─────────────────┘                                       │                 │
                                                          │  intake → list  │
┌─────────────────┐     triggerMailHarness()               │  → enroll       │
│   X Harness     │ ──────────────────────────────────── → │  → step mail    │
│  (engagement    │   POST /api/integrations/x/:token      │  自動開始       │
│   gate cleared) │   {event,email,xUsername}              │                 │
└─────────────────┘                                       └─────────────────┘
```

## 前提: メールアドレスの収集

LINE/X のユーザーはメールアドレスを持っていない（SNS ID のみ）。
そのため、**メール配信に繋げるにはフォームでメールを収集するステップが必要**。

推奨フロー:
1. SNSで「メール講座に登録しませんか？」と案内
2. LINE Harness のフォーム / LIFF / X Harness のフォームでメールを入力してもらう
3. フォーム送信 → `form_submitted` イベント → outgoing webhook → Mail Studio
4. Mail Studio が購読者登録 + ステップ配信を自動開始

---

## LINE Harness → Mail Studio

### セットアップ手順

1. **Mail Studio 側**: ダッシュボード「連携リンク」で、対象リスト＋ステップ施策を紐付けたリンクを発行。
   → ③ LINE Harness 連携URL が表示される: `https://<worker>/api/integrations/line/<token>`

2. **LINE Harness 側（2つの方法）**:

   **方法A: Outgoing Webhook（推奨）**
   - LINE Harness 管理画面 → Outgoing Webhooks で URL を登録
   - 対象イベント: `form_submitted`（メール入力フォーム送信時）
   - URL: 上記の Mail Studio LINE連携URL

   **方法B: Automation Rule**
   - LINE Harness → オートメーション → IF: フォーム送信 → THEN: `send_webhook`
   - URL: 上記の Mail Studio LINE連携URL

### ペイロード形式（LINE Harness → Mail Studio）

```json
{
  "event": "form_submitted",
  "timestamp": 1700000000000,
  "data": {
    "friendId": "U1234567890",
    "email": "user@example.com",
    "fields": {
      "名前": "LINE太郎",
      "メールアドレス": "user@example.com"
    },
    "eventData": {
      "displayName": "LINE太郎"
    }
  }
}
```

### メールアドレスの解決優先順位
1. `data.email`（直接指定）
2. `data.fields.email`
3. `data.fields.メール`
4. `data.fields.メールアドレス`
5. いずれもなければ **400 エラー**（ヒントメッセージ付き）

### 名前の解決優先順位
1. `data.eventData.displayName`
2. `data.fields.name`
3. `data.fields.名前`
4. `data.fields.お名前`

---

## X Harness → Mail Studio

### セットアップ手順

1. **Mail Studio 側**: 連携リンク発行（上記と同じ）。
   → ④ X Harness 連携URL: `https://<worker>/api/integrations/x/<token>`

2. **X Harness 側**: `engagement-gate.ts` に `triggerMailHarness()` を追加。
   既存の `triggerLineHarness()` と並行して呼ぶ。

   ```typescript
   // X Harness 側に追加する関数（engagement-gate.ts）
   async function triggerMailHarness(env: Env, email: string, xUsername: string, event: string) {
     if (!env.MAIL_HARNESS_URL || !env.MAIL_HARNESS_TOKEN) return;
     await fetch(`${env.MAIL_HARNESS_URL}/api/integrations/x/${env.MAIL_HARNESS_TOKEN}`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ event, email, xUsername }),
     });
   }
   ```

   X Harness の `.dev.vars` / wrangler secrets に追加:
   ```
   MAIL_HARNESS_URL=https://<mail-studio-worker>.workers.dev
   MAIL_HARNESS_TOKEN=<連携リンクのトークン>
   ```

### ペイロード形式（X Harness → Mail Studio）

```json
{
  "event": "engagement_gate_cleared",
  "xUserId": "12345",
  "xUsername": "user_handle",
  "email": "user@example.com",
  "name": "表示名"
}
```

### メールの取得方法（X側）
X API ではメールアドレスは取得できないため、以下のいずれかで事前収集:
- X Harness のフォーム機能（DM等でメール入力を促す）
- 外部フォーム（Mail Studio の埋め込みフォーム `/f/:token` を X のプロフィールリンクに貼る）

---

## 共通仕様

### 冪等性
同一メールアドレスで複数回呼んでも:
- 購読者の重複登録なし（`created=false`）
- 同一キャンペーンへの重複 enroll なし（`enrolled=false`）

### ソース識別
購読者の `source` フィールドに連携元を記録:
- `line:form_submitted` / `line:friend_add` / `line:webhook`
- `x:engagement_gate_cleared` / `x:step_complete` / `x:webhook`

### エラーレスポンス
| 状態 | HTTP | レスポンス |
|---|---|---|
| メールなし | 400 | `{ok:false, error:"email not found...", hint:"..."}` |
| 無効トークン | 404 | `{ok:false, error:"hook not found"}` |
| 不正メール | 400 | `{ok:false, error:"invalid email"}` |
| 成功 | 200 | `{ok:true, created, enrolled, source}` |

### 認証
SNS連携エンドポイントは**認証Cookie不要**（外部システムからの受信）。
トークン（連携リンクのURL自体）が識別子として機能。

---

## ダッシュボードでの確認
連携リンク発行後、ダッシュボードに ①汎用Webhook ②フォーム ③LINE Harness ④X Harness の4種類のURLが表示されます。audit_log に `line_harness` / `x_harness` のアクションが記録されるので、ダッシュボードの操作ログで連携状況を確認できます。
