# 04-統一顧客連動同期フロー

## 1. ドキュメントの位置付け

本書は、今期 KASIKA 開発における顧客連動の中核ルールの事実ソースであり、KASIKA 顧客が VISTA に入った後のビジネスルール、結果の定義、ページフィードバック、異常トレーサビリティの要件を定義するものです。

同期の実装方式についてはプロダクト要件では展開しません。開発側は現在の同期モードを「KASIKA から現時点で取得可能な顧客データ集合を一括取得し、VISTA システム側でローカル比較・更新を行う」方式と確認済みです。具体的なページング、バッチ分割、並行処理、トランザクション境界、処理順序、リトライおよび中断ポリシーは、開発側が KASIKA API の能力とシステム安定性に基づいて設計します。プロダクトプロトタイプは、ページスタイル、操作エントリ、表示結果、ログのトレーサビリティ要件のみを定義します。

本書は「ルールがどのように成立するか」を説明するものであり、ページ UI やログ項目については重複して展開しません。

| 関連ドキュメント | 責任境界 |
| --- | --- |
| `01-KASIKA連動設定管理.md` | KASIKA API パラメータ、settingID、VISTA プロジェクト入口 URL、アクセスパスワード設定スイッチ、`customer_status` ステータス権限自動更新スイッチ |
| `03-タグ権限テンプレート.md` | VISTA タグと権限テンプレートの設定および権限計算方式 |
| `05A/05B/05C/05D` | 顧客リスト、詳細、権限ページ、新規顧客ページの表示と操作 |
| `07-同期ログとトレーサビリティ.md` | ログ項目、エラー辞書、ページサマリ、照会ルール |
| `08-KASIKA入口ページとVISTA初回アクセスアカウント開設.md` | 顧客が KASIKA 自動返信メールの入口をクリックした後の C 端リアルタイムアカウント開設 / バインドフロー |
| `09-C端顧客アクセス権限インターフェース.md` | C 端が実際にアクセス可能なコンテンツを読み取る際のインターフェースルール |

`08` の入口ページと本書の同期フローは、初回タッチポイントを共同でカバーします。

1. 顧客が KASIKA 自動返信メール内の入口をクリックした場合、`08` に従って本人検証、VISTA 顧客作成 / バインド、任意のパスワード設定を即時に完了し、初回バインド時に `customer_status` 同名タグの初期化と初期権限判定を強制実行します。
2. 顧客が入口をクリックしない場合、または顧客が引き続き KASIKA の後続メールによるタッチを希望する場合、本書のバッチ同期フローに従って自動バインドとアクセスフィールドの書き戻しを完了します。初回バインド完了後、KASIKA 自動返信メール API と設定ページに保存された自動返信ID を介して顧客通知をトリガーします。

## 2. 中核ルール総括表

| 番号 | ルール | プロダクト定義 |
| --- | --- | --- |
| R1 | API 前提条件 | KASIKA 顧客 API を呼び出す前に、完全な 4 つの API KEY が保存済みである必要があります。4 つの API KEY が不完全な場合は、取得・同期・書き戻しを行いません |
| R2 | 同期スイッチなし | 今期は顧客同期制御スイッチを提供しません。同期を実行するかどうかは、API パラメータの完全性、KASIKA API 呼び出し結果、システムタスク状態によって決定されます |
| R3 | マスタデータの方向 | 顧客マスタデータのソースは KASIKA -> VISTA が主体です。VISTA は KASIKA に顧客を作成せず、VISTA の氏名、メールアドレス、電話番号、会社名で KASIKA 顧客の基本情報を上書きしません |
| R4 | バインド主キー | KASIKA `customer_id` / `cid` は、KASIKA 顧客と VISTA 顧客のバインド主キーです |
| R5 | メール一致 | メールアドレスは、未バインドの KASIKA 顧客を既存の VISTA 顧客にマッチングする場合のみ使用します。一意に一致し、未バインドで、再バインド禁止でもない場合のみ自動バインドを許可します |
| R6 | フィールド保存 | KASIKA `customer_id`、KASIKA メールアドレス、`customer_status` は構造化関連フィールドとして保存する必要があります。完全なフィールドスナップショットは構造化保存の代替にはなりません |
| R7 | 権限ソース | `customer_status` は今期唯一の KASIKA 権限変更ソースフィールドです。初回バインド時は必ず同名 VISTA タグで初期化し、タグ権限テンプレートを通じて初期アクセス権限を計算する必要があります。その後の現在ステータスによるタグ / 権限の校正を行うかどうかは、設定ページの `customer_status` ステータス権限自動更新スイッチで制御されます |
| R8 | 初回書き戻し | 初回バインド成功後、KASIKA の `VISTAURL` にのみ HOMEVISTA アクセスリンクを書き込みます。プロジェクトでアクセスパスワードが有効な場合は、`VISTAPWD` に初回アクセスパスワードも書き込みます。VISTA 顧客 ID、バインド状態、初回アクセス完了時刻は KASIKA に書き戻しません |
| R9 | バインド通知 | 初回バインド完了後、VISTA は KASIKA 自動返信メール API を呼び出し、顧客が事前に設定した自動返信ID を渡して、KASIKA が返信テンプレートに従って顧客にメールを送信するようトリガーします |
| R10 | 権限変更境界 | 初回バインド完了後、スイッチがオンの場合、後続の同期は現在の `customer_status` に基づいて VISTA タグ、権限、ログを軽量校正し、URL / パスワードを再生成せず、KASIKA への再書き戻しも行いません。スイッチがオフの場合、構造化 `customer_status` とログのみを更新し、タグと権限は積極的に更新しません |
| R11 | バインド解除 | 今期の顧客詳細ページでは、KASIKA バインドの手動解除エントリを提供しません。VISTA 顧客を削除する場合のみ、その顧客の有効な KASIKA バインド関係をクリーンアップし、履歴バインドのトレーサビリティは保持します |
| R12 | 削除境界 | VISTA で顧客を削除しても KASIKA 顧客は削除されず、KASIKA 側に書き込まれた HOMEVISTA アクセス URL とパスワードもクリアされません。削除後の元 VISTA 顧客は、復元操作によって KASIKA 有効バインドが自動的に復元されることはありません |
| R13 | 実装境界 | プロダクト要件は、KASIKA 顧客データを一括取得した後に VISTA で比較・更新するビジネス定義のみを定義します。具体的な同期アルゴリズム、実行順序、ページング、並行処理、トランザクション、リトライ方式は開発側で設計します |

## 3. 前提条件と機能への影響

### 3.1 API パラメータの完全性

1. 完全な 4 つの API KEY は、KASIKA 顧客照会、バッチ同期、初回バインドのアクセスフィールド書き戻しの基本前提条件です。
2. 4 つの API KEY のいずれかが欠落している場合:
   - 同期タスクを作成しません。
   - KASIKA 顧客 API を呼び出しません。
   - 顧客リストページに「全量同期チェック」ボタンを表示しません。
   - 初回バインドのアクセスフィールド書き戻しを実行しません。
   - 履歴バインド、履歴同期状態、ログは保持されます。
3. settingID は KASIKA バッチエクスポート / インポート API の呼び出しに使用されますが、4 つの API KEY の認証機能の代替にはなりません。settingID に依存する必要があるかどうかは、開発側が KASIKA API の実測能力に基づいて確認します。プロダクト側では、欠落または利用不可の場合に明確な失敗理由を記録することを要求します。

### 3.2 VISTA アクセスパスワード設定

1. VISTA アクセスパスワード設定スイッチは `01-KASIKA連動設定管理.md` で定義されます。
2. スイッチがオンの場合:
   - `08` の入口ページでは顧客に VISTA アクセスパスワードの設定を要求します。
   - 同期補完で VISTA 顧客を作成する場合、システムが初期アクセスパスワードを生成します。
   - 初回バインド書き戻し時にアクセスパスワードの書き込みが許可されます。
3. スイッチがオフの場合:
   - `08` の入口ページではメール本人検証は依然として必要ですが、パスワード設定はスキップされます。
   - 同期補完で VISTA 顧客を作成する場合、アクセスパスワードは生成されません。
   - 初回バインド書き戻しでは、空のパスワードや疑似パスワードを書き込んではなりません。

### 3.3 customer_status ステータス権限自動更新設定

1. `customer_status` ステータス権限自動更新スイッチは `01-KASIKA連動設定管理.md` で定義され、デフォルトはオンです。
2. 初回バインド時:
   - スイッチがオンかオフかに関わらず、システムは今回の `customer_status` に基づいて同名 VISTA タグの初期化を必ず 1 回実行する必要があります。
   - 同名タグおよびその権限テンプレートにヒットした場合、タグ権限テンプレートに従って初期権限判定をトリガーします。
3. 初回バインド完了後、スイッチがオンの場合:
   - 後続の同期で当該顧客を処理する際、現在の KASIKA `customer_status` に基づいて同名 VISTA タグを軽量校正します。
   - 同名 VISTA タグが存在する場合、当該顧客がそのタグを保持することを確認します。同名タグが存在しない場合、タグを自動作成せず、スキップログのみを記録します。
   - 今回の校正でタグ結果に変化が生じた場合、タグ権限テンプレートに従って顧客権限の再計算をトリガーします。
4. 初回バインド完了後、スイッチがオフの場合:
   - 同期フローは KASIKA 構造化関連フィールド、完全なフィールドスナップショット、構造化 `customer_status` を引き続き保存します。
   - 後続の `customer_status` 変化に基づいて VISTA タグを追加、削除、置換しません。
   - 後続の `customer_status` 変化によって顧客権限の再計算を積極的にトリガーしません。
   - 顧客の既存タグや既存権限を取り消しません。
5. 再びオンにした場合、後続の同期で処理される顧客にのみ有効です。履歴顧客を補計算するかどうかは、別途の手動同期 / 権限再計算フローに属し、スイッチによって自動的に遡及実行されることはありません。

## 4. データの主権と保存の定義

### 4.1 VISTA 主要フィールド

VISTA 主要フィールドには、VISTA 顧客 ID、氏名、メールアドレス、携帯電話番号、HOMEVISTA アクセス URL、アクセスパスワード、アクセス権限、KASIKA customer_id バインド関係が含まれます。

### 4.2 KASIKA 構造化関連フィールド

以下のフィールドは構造化して保存する必要があり、顧客詳細の表示、バインド整合性検証、権限変化、ログトレーサビリティに使用します。

| フィールド | ソース | 用途 |
| --- | --- | --- |
| KASIKA `customer_id` / `cid` | KASIKA 顧客照会、バッチ同期、入口ページ | バインド主キー |
| KASIKA メールアドレス | KASIKA 顧客情報 | メール整合性検証、競合判断、表示 |
| `customer_status` | KASIKA 顧客情報 | 構造化保存。ステータス権限自動更新スイッチがオンの場合、同名 VISTA タグを設定し権限計算をトリガー |
| KASIKA バインド状態 | VISTA バインド処理結果 | 未バインド、バインド済み、VISTA 顧客削除によるバインド無効、バインド異常、削除疑いなどの状態を表示 |
| KASIKA 情報更新日時 | 同期、入口ページ、VISTA 顧客削除操作 | KASIKA 関連情報の新しさを示す |
| 再バインド禁止マーク | バックエンド誤バインド処理 | 後続の同期や入口ページでの自動バインドを阻止。今期の顧客詳細ページでは書き込みエントリを提供しない |

### 4.3 KASIKA フィールドスナップショット

1. KASIKA が返すマーケティングフィールド、ステータス、タグ、カスタムフィールド、担当者などの情報は、完全なフィールドスナップショットとして保存します。
2. フィールドスナップショットはトレーサビリティ、差分判断、トラブルシューティングに使用し、VISTA 主要フィールドを直接上書きしません。
3. 完全なフィールドスナップショットは、KASIKA `customer_id`、メールアドレス、`customer_status` の構造化保存の代替にはなりません。
4. 完全な KASIKA `customer_data` スナップショットは同期ログ詳細にのみ入り、顧客詳細の概要には入りません。

### 4.4 表示と機密情報の境界

1. 顧客詳細の `概要` タブでは、`05B-顧客詳細ページ.md` に従って独立した KASIKA 連動モジュールを表示し、KASIKA `customer_id`、KASIKA メールアドレス、`customer_status`、バインド状態、直近の同期日時 / 結果を確認できるようにします。今期は手動でのバインド解除エントリを提供しません。
2. KASIKA 関連フィールドは顧客基本情報モジュール内に混在させてはいけません。顧客基本情報エリアでは KASIKA 同期状態、失敗理由、KASIKA 内部フィールドを表示してはいけません。
3. KASIKA にバインド済みの顧客の場合、顧客詳細の基本情報エリアのメールアドレスフィールドは読み取り専用で、ページ編集による上書きは許可されません。
4. VISTA アクセスパスワードの平文は、業務上の必要で VISTA 側に保存する場合でも、同期ログ詳細や KASIKA スナップショット表示に入れてはいけません。
5. API KEY、Secret Key、settingID、アクセスパスワードの平文は、ページエラー、Toast、同期ログサマリ、インターフェースエラーサマリに表示してはいけません。

## 5. トリガーソースマトリクス

| トリガーソース | トリガーフロー | 説明 |
| --- | --- | --- |
| 顧客リストページの「全量同期チェック」ボタン | バッチ顧客同期フロー | B 端管理者と営業マネージャーは手動で 1 回 KASIKA 顧客全量同期チェックをトリガーできます。現在のリストのチェック項目には依存しません。4 つの API KEY が完全な場合のみ利用可能です。営業担当者はフロントエンドやインターフェースから表示・トリガーできません。 |
| システムの毎時定期チェック | バッチ顧客同期フロー | API パラメータが完全になった後、本プロジェクトの**保存済み KASIKA 連動設定の最終更新日時**をスケジュールアンカーとし、`最終更新日時 + N × 1 時間` の固定時点でトリガーします。毎回 KASIKA から現在取得可能な顧客データ集合を取得し、VISTA がローカル比較・更新を行います |
| 初回バインドアクセスフィールド書き戻し補償 | 単一顧客補償フロー | 初回バインドは成功したが `VISTAURL` または該当する場合の `VISTAPWD` の書き込みが失敗した場合、失敗したフィールドのみを補償します |
| 顧客が KASIKA 入口ページをクリック | KASIKA 入口ページフロー | 本書のバッチ同期メインフローには属しません。`08-KASIKA入口ページとVISTA初回アクセスアカウント開設.md` に従って実行します |
| 初回バインド後の自動返信メール送信 | バインド通知フロー | 初回バインド完了かつアクセスフィールドの準備が完了した後、KASIKA 自動返信メール API を呼び出して指定の自動返信ID をトリガーします |
| VISTA 顧客削除 | ローカル削除記録フロー | KASIKA の削除またはフィールドクリア用インターフェースは呼び出しません。削除対象が KASIKA にバインド済みの場合、VISTA 側の有効バインド関係をクリーンアップし、履歴バインド、バインド無効化、削除結果を記録します |

## 6. KASIKA -> VISTA バッチ同期決定ツリー

### 6.1 フローチャート

```mermaid
flowchart TB
  A["バッチトリガー<br/>手動全量同期チェック / 毎時定期チェック"] --> B{"4 つの API KEY は完全か"}
  B -->|いいえ| B1["同期を実行しない<br/>手動エントリを表示しない<br/>履歴状態を保持"]
  B -->|はい| C["KASIKA 顧客データ集合を一括取得"]
  C --> E["VISTA ローカル比較・更新結果生成"]

  E --> F{"KASIKA customer_id は VISTA 顧客にバインド済みか"}
  F -->|バインド済み| G["KASIKA 構造化フィールドとフィールドスナップショットを更新"]
  G --> H{"customer_status ステータス権限自動更新はオンか"}
  H -->|オン| I["customer_status に基づき同名 VISTA タグを設定"]
  I --> J["タグ権限テンプレートに従い権限を再計算"]
  H -->|オフ| H1["customer_status のみ保存<br/>タグと権限を更新しない"]
  J --> Z["成功 / 変化なし / 失敗を記録"]
  H1 --> Z

  F -->|未バインド| K{"同メール・未バインド・再バインド禁止でない VISTA 顧客が存在するか"}
  K -->|一意にヒット| L["既存 VISTA 顧客にバインド"]
  K -->|ヒットなし| M["VISTA 顧客を新規作成しアクセスフィールドを生成"]
  K -->|複数ヒット / バインド済み / 再バインド禁止| N["業務待処理<br/>自動バインドしない"]

  L --> O["構造化フィールドとフィールドスナップショットを保存"]
  M --> O
  O --> P["初回バインド時に強制実行<br/>customer_status 同名タグ初期化と初期権限判定"]
  P --> Q["初回バインド書き戻し VISTAURL<br/>設定に応じて VISTAPWD を書き戻し"]
  Q --> R["自動返信ID を呼び出し<br/>自動返信メールを送信"]
  R --> S["完了または部分失敗を記録"]

  E --> T["VISTA 未バインド顧客はスキャンしない<br/>KASIKA に顧客を作成しない"]
```

### 6.2 KASIKA 顧客データ取得と比較境界

1. バッチフローは、KASIKA から現在取得可能な顧客データ集合を一括取得することを前提とし、その後 VISTA システムがローカル比較・更新を行います。
2. プロダクト要件は、KASIKA データ取得のページング方式、並行方式、インターフェース組み合わせ、一時テーブル保存、トランザクション境界、処理順序、リトライ機構を定義しません。
3. バッチ処理範囲は、KASIKA が実際に返し今回の比較に参加したデータを基準とし、VISTA の現在のリストフィルタやチェック結果を基準としません。
4. プロダクト側は、比較に参加した各顧客の同期結果、フィールド変化サマリ、必要な失敗トレーサビリティ情報が最終的に形成されることのみを要求します。

### 6.3 バインド済み KASIKA 顧客

1. VISTA ローカル比較時、KASIKA `customer_id` を通じて、当該 KASIKA 顧客が VISTA 顧客にバインド済みかどうかを判断します。
2. バインド関係が既にある場合:
   - KASIKA 構造化関連フィールドを保存または更新します。
   - KASIKA フィールドスナップショットを保存または更新します。
   - `customer_status` フィールドを読み取ります。
   - `customer_status` ステータス権限自動更新スイッチを判断します。
   - スイッチがオンの場合、`customer_status` フィールド値に基づいて同名 VISTA タグを校正します。同名タグがない場合はタグを変更せず、タグを自動作成もしません。
   - スイッチがオンで、校正後にタグ結果が変化した場合、権限判定フローに入ります。
   - スイッチがオフの場合、構造化 `customer_status` とフィールドスナップショットのみを保存し、後続のステータス変化によって VISTA タグを更新せず、権限判定をトリガーしません。
3. バインド済み顧客の KASIKA フィールドスナップショット更新、`customer_status` タグ設定や権限変化は、KASIKA 顧客情報の書き戻しをトリガーしません。
4. バインド済み顧客の後続変化は、初回バインドのアクセスフィールド書き戻しをトリガーしません。

### 6.4 未バインド KASIKA 顧客: 既存 VISTA 顧客とのマッチング

1. KASIKA 顧客が VISTA 顧客にバインドされていない場合、システムはまず、メールアドレスが同じで、KASIKA 未バインド、かつ KASIKA 再バインド禁止とマークされていない VISTA 顧客が存在するかどうかをチェックします。
2. 一意に一致する VISTA 顧客が存在する場合:
   - VISTA 顧客と KASIKA `customer_id` のバインド関係を確立します。
   - KASIKA 構造化関連フィールドとフィールドスナップショットを保存します。
   - `customer_status` ステータス権限自動更新スイッチがオンかオフかに関わらず、今回の `customer_status` に基づいて同名 VISTA タグ初期化を 1 回実行し、初期権限判定をトリガーします。同名タグがない場合はタグを追加せず、バインドをブロックしません。
   - VISTA 側に既存の HOMEVISTA アクセスリンクを KASIKA の `VISTAURL` に書き込みます。プロジェクトでアクセスパスワードが有効な場合、現在有効な初回アクセスパスワードを `VISTAPWD` に書き込みます。
   - アクセスフィールド書き戻し完了後、初回バインド結果を記録します。
3. メールアドレスが複数の VISTA 顧客にヒットした場合、候補 VISTA 顧客が他の KASIKA 顧客にバインド済みの場合、または候補 VISTA 顧客が KASIKA 再バインド禁止とマークされている場合、業務待処理に入り、自動バインドしません。

### 6.5 未バインド KASIKA 顧客: VISTA 顧客の新規作成

1. メール一致する未バインド VISTA 顧客が検出されなかった場合、システムは VISTA 側で顧客を新規作成します。
2. 新規作成フィールドは少なくとも以下を含みます:
   - 氏名。
   - メールアドレス。
   - 携帯電話番号。
   - KASIKA `customer_id`。
3. VISTA での顧客作成時に HOMEVISTA アクセス URL を同時に生成します。アクセスパスワード設定スイッチがオンの場合、初期アクセスパスワードも同時に生成します。アクセス URL の有効期限は永久です。
4. KASIKA 構造化関連フィールドとフィールドスナップショットを保存します。
5. `customer_status` ステータス権限自動更新スイッチがオンかオフかに関わらず、システムは今回の `customer_status` に基づいて同名 VISTA タグ初期化を 1 回実行し、初期権限判定をトリガーします。同名タグがない場合はタグを追加せず、バインドをブロックしません。
6. VISTA 顧客の作成とバインドが成功した後、HOMEVISTA アクセスリンクを KASIKA の `VISTAURL` に書き込みます。アクセスパスワード設定スイッチがオンの場合は初回アクセスパスワードを `VISTAPWD` に書き込み、オフの場合は `VISTAPWD` を書き戻しません。
7. アクセスフィールド書き戻し完了後、初回バインド結果を記録します。

### 6.6 未バインド VISTA 顧客は処理しない

1. バッチフローは、VISTA 側で KASIKA 未バインドの顧客をスキャンしません。
2. VISTA 側の未バインド顧客がメールアドレスや電話番号を持っている場合でも、KASIKA に照会、作成、更新しません。
3. VISTA 顧客のファイルインポート、新規顧客作成、メールアドレスや電話番号の補充は、KASIKA 顧客の作成や上書きをトリガーしません。
4. その後、KASIKA 同期で対応する顧客が取得され、メールアドレスで一意にヒットし、未バインドかつ再バインド禁止でない VISTA 顧客が存在する場合のみ、バインド関係を確立します。

### 6.8 自動・手動同期の並行制御

1. 自動定期同期と手動全量同期チェックは相互排他です。同一プロジェクトの同一時刻には 1 つの同期タスクのみ実行を許可します。
2. 自動定期同期は、当該プロジェクトの**保存済み KASIKA 連動設定の最終更新日時**をアンカーとし、`最終更新日時 + N × 1 時間`（`N` は正の整数）で後続のトリガー時点を生成します。全プロジェクト一斉の正時トリガーではなく、複数プロジェクト同時のバッチ同期による性能負荷を分散します。
3. KASIKA 連動設定の保存に成功した場合のみ、このスケジュールアンカーを更新します。ユーザーがフォームで編集したが保存していない場合、保存が検証で阻止された場合、または保存に失敗した場合は、既存の自動同期タイミングを変更してはいけません。設定保存成功後、新しい最終更新日時から次の自動同期時刻を再計算します。
4. 自動定期タスクのトリガー時も、手動タスクと同じプロジェクト単位のアトミックなタスクロックを使用する必要があります。ロック取得に成功した場合のみ同期タスクを作成します。既に自動または手動同期が占有している場合、今回の定期トリガーはスキップし、当該プロジェクトの次の固定トリガー時点を待ちます。フロントエンドへのプロンプトは発生せず、スキップしたタスクの補実行も行いません。
5. 手動全量同期チェックのトリガー時（管理者または営業マネージャーが「全量同期チェック」をクリック）、サーバー側はプロジェクト単位で原子的に同期タスクロックをチェックし占有する必要があります。自動定期同期や他の手動同期が既に占有している場合、新しい同期タスクは作成しません。
6. 上記の競合が発生した場合、フロントエンドはポップアップで「kasikaデータを同期中です。しばらくしてからお試しください」と表示し、閉じた後も顧客リストに留まります。フロントエンドのボタン無効化判定のみに依存してはいけません。
7. 同期タスクが開始されたら、手動停止、キャンセル、再発起はサポートされません。ユーザーがブラウザを閉じる、ポップアップを閉じる、ページを離れるといった操作は、バックグラウンドタスクの継続実行に影響を与えません。
8. 一括取得、VISTA ローカル比較、バッチ CSV 書き戻しは、中断不可のバックグラウンドタスクに属します。プロダクトは擬似進捗、処理中件数、予定完了時間を表示しません。タスクの最終結果は、バックグラウンドタスク完了後に生成される結果サマリとログを基準とします。

## 7. バインド時のメール通知方式

初回バインド完了後、VISTA は KASIKA の自動返信メール機能を使用して顧客に通知します。

### 7.1 設定前提条件

1. 顧客は先に KASIKA 側で自動返信メールテンプレートを事前設定する必要があります。
2. 自動返信メールテンプレートには、HOMEVISTA 顧客招待リンクやアクセスパスワードなどの変数を設定できます。
3. VISTA は KASIKA 連動設定ページで、このテンプレートをトリガーするための KASIKA `自動返信ID` を保存します。
4. 4 つの API KEY が不完全、または自動返信ID が未設定の場合、バインド通知メールはトリガーされませんが、顧客作成、バインド、アクセスフィールド書き戻し、`customer_status` 初期タグ、初期権限判定には影響しません。

### 7.2 トリガータイミング

1. 初回バインドが完了し、HOMEVISTA アクセス URL が生成された後、VISTA は KASIKA 自動返信メール API を呼び出します。
2. プロジェクトでアクセスパスワード設定が有効な場合、アクセスパスワードが生成されるか、顧客がパスワードを設定した後にのみ自動返信メールをトリガーします。メールテンプレートにパスワードを組み込めることを保証するためです。
3. プロジェクトでアクセスパスワード設定がオフの場合、メールテンプレートはアクセスパスワードフィールドに依存してはいけません。VISTA は空のパスワードや疑似パスワードを書き込みません。
4. バインド済み顧客が再度 KASIKA 入口ページにアクセスした場合、自動返信メールを重複トリガーしません。
5. 初回バインド後に VISTA 側の顧客情報、アクセスパスワード、バインド状態に後続の変化が生じた場合、自動返信メールを再度トリガーしません。

### 7.3 送信内容と変数

1. メール本文は KASIKA 側の自動返信ID に対応するテンプレートに準拠します。VISTA は今期、KASIKA メールテンプレートエディタを提供しません。
2. メールテンプレートには HOMEVISTA 顧客招待リンクを組み込めます。
3. プロジェクトでアクセスパスワード設定が有効な場合、メールテンプレートには HOMEVISTA アクセスパスワードを組み込めます。
4. VISTA は初回バインド後に指定の自動返信ID を呼び出すことのみを担当します。メール本文、タイトル、送信者、送信対象などのメール表現は KASIKA 自動返信テンプレートの設定で決定されます。

### 7.4 失敗処理

1. 自動返信メールの送信失敗は、VISTA 顧客作成、バインド保存、アクセスフィールド書き戻し、`customer_status` 初期タグ、初期権限判定をロールバックしません。
2. 送信失敗は同期ログに記録する必要があります。KASIKA customer_id、VISTA 顧客 ID、自動返信ID、トリガーソース、失敗サマリ、後続処理状態を含みます。
3. 後続の補償は自動返信メール送信の継続実行のみ許可され、顧客の重複作成、重複バインド、成功済みアクセスフィールドの重複書き戻し、状態タグの重複設定は行ってはいけません。

## 8. `customer_status` から権限への処理

### 8.1 タグ設定

1. システムは KASIKA が返す `customer_status` フィールド値を読み取り、構造化関連フィールドとして保存します。
2. 初回バインド時、`customer_status` ステータス権限自動更新スイッチがオンかオフかに関わらず、同名 VISTA タグ初期化を必ず 1 回試行する必要があります。
3. 初回バインド時、フィールド値が空、欠落、または解析不能な場合、VISTA タグを設定せず、バインドやアカウント開設をブロックしませんが、「初回ステータスが空 / 解析不能」ログを記録する必要があります。
4. 初回バインド時、VISTA プロジェクトに `customer_status` フィールド値と文字通り同一のタグが存在する場合、当該 VISTA 顧客にそのタグを設定します。
5. 初回バインド時、同名タグが存在しない場合、システムはタグを自動作成せず、その状態タグを追加せず、バインドやアカウント開設をブロックしませんが、「初回ステータスに同名タグなし」ログを記録する必要があります。
6. 初回バインド完了後、`customer_status` ステータス権限自動更新スイッチがオフの場合、後続処理はここまでとします。VISTA タグを設定せず、前のステータスタグを削除せず、権限判定をトリガーしません。同期ログには「ステータスは保存済み、タグ / 権限自動更新はオフ」と記録します。
7. 初回バインド完了後、スイッチがオンだがフィールド値が空、欠落、または解析不能な場合、VISTA タグを設定せず、後続の同期をブロックしません。
8. 初回バインド完了後、スイッチがオンで、VISTA プロジェクトに `customer_status` フィールド値と文字通り同一のタグが存在する場合、当該 VISTA 顧客がそのタグを保持することを確認します。そのタグが VISTA 側で人為的に顧客から削除されていた場合、今回の同期で再付与されます。
9. 初回バインド完了後、スイッチがオンで、今回の `customer_status` が前回保存済みの `customer_status` と一致しない場合、システムは最新ステータスに従って顧客タグを更新する必要があります。新ステータスに対応する同名タグを追加し、前ステータスに対応する旧タグを削除します。
10. 初回バインド完了後、スイッチがオンだが同名タグが存在しない場合、システムはタグを自動作成せず、その状態タグを追加しません。今回がステータス変化と確認された場合でも、前ステータスに対応する旧タグは削除する必要があります。
11. VISTA 側の管理者がタグを新規追加、編集、削除したり、顧客権限ページで顧客タグを調整したりしても、KASIKA に書き戻さず、KASIKA `customer_status` も変更しません。後続の同期は VISTA 側で現在の `customer_status` に基づいて軽量校正のみを行います。

### 8.2 権限計算

1. 初回バインド時、システムは今回の `customer_status` タグ初期化結果に基づいて初期権限判定をトリガーする必要があり、`customer_status` ステータス権限自動更新スイッチの影響を受けません。
2. 初回バインド完了後、`customer_status` ステータス権限自動更新スイッチがオンで、かつタグ校正によって顧客タグ結果が変化した場合のみ、システムは権限判定をトリガーします。
3. 権限判定時、C 端顧客アクセス権限インターフェースは `09-C端顧客アクセス権限インターフェース.md` の統一ルールに従ってリアルタイムでアクセス可能なコンテンツを返します。タグ権限テンプレートの和集合 + 個人権限の追加分。
4. `customer_status` 同名タグが権限テンプレートにヒットした場合、システムは顧客の現在タグがヒットした権限テンプレートの和集合でアクセス権限を計算します。
5. タグにヒットしない、またはヒットしたタグに権限テンプレートが設定されていない場合、システムは追加のデフォルトコンテンツを付与しません。最終アクセスコンテンツは、現在のタグ権限テンプレートの和集合と個人権限の追加分で引き続き計算され、結果は空でも構いません。
6. 初回バインド完了後、スイッチがオフの場合、システムは後続の `customer_status` 変化によって権限を積極的に再計算しません。顧客の最終アクセス可能コンテンツは、現在の既存タグと個人権限の追加分によって決定されます。
7. タグ設定や権限計算の失敗は、完了済みの顧客バインドやアクセスフィールド書き戻し結果をロールバックしてはいけませんが、ログの記録は必要です。

### 8.3 権限変化の境界

1. KASIKA 顧客の `customer_status` が変化した後、VISTA は常にフィールドスナップショットと構造化 `customer_status` を更新します。
2. 初回バインド時、VISTA は `customer_status` に基づいて同名タグ初期化と初期権限判定を必ず 1 回実行する必要があります。
3. 初回バインド完了後、`customer_status` ステータス権限自動更新スイッチがオンの場合のみ、VISTA は現在のステータスに基づいて同名 VISTA タグとアクセス権限を校正します。
4. スイッチがオンの場合、毎回の同期で当該顧客を処理する際、現在の `customer_status` に基づいて同名タグを校正します。同名タグが存在すれば顧客がそのタグを保持することを確認し、同名タグが存在しなければ自動作成せずスキップを記録します。
5. スイッチがオンで `customer_status` が変化した場合、タグ更新は「新規追加 + 旧削除」方式を採用します。新ステータスの同名タグを追加し、前ステータスの同名タグを削除します。
6. スイッチがオフの場合、後続のステータス変化によって新ステータスタグを追加せず、前ステータスタグを削除せず、権限を積極的に再計算せず、既存タグや既存権限も取り消しません。
7. 権限変化は、顧客のアクセス URL をデフォルトでは変更しません。
8. 権限変化は、KASIKA に権限結果や権限サマリを書き戻しません。

## 9. アクセスフィールド書き戻しの境界

### 9.1 初回バインド書き戻しフィールド

初回バインド成功後、システムは KASIKA に以下を書き戻せます:

- `VISTAURL`: HOMEVISTA アクセスリンク。必ず書き戻す必要があります。
- `VISTAPWD`: 初回アクセスパスワード。プロジェクトでアクセスパスワード設定が有効な場合のみ書き戻します。

VISTA 顧客 ID、バインド状態、初回アクセス完了時刻は VISTA 内でのみ保存・トレースし、KASIKA には書き戻しません。

### 9.2 VISTA マスタデータの逆方向同期は行わない

1. VISTA で顧客を作成する場合、既存の VISTA 顧客作成フローに従って HOMEVISTA アクセスフィールドのみを生成し、KASIKA に顧客を作成しません。
2. VISTA 未バインド顧客がメールアドレスや電話番号を補充する場合、KASIKA に照会、作成、更新しません。
3. VISTA バインド済み顧客が氏名、メールアドレス、電話番号、会社名などの基本情報を変更する場合、KASIKA 顧客の基本情報を上書きせず、KASIKA 顧客を自動的に変更バインドもしません。
4. VISTA 顧客のファイルインポート完了後、KASIKA に顧客を作成または更新しません。

### 9.3 VISTA でのアクセスパスワード変更

1. VISTA で顧客のアクセスパスワードを変更する場合、VISTA 側の現在のアクセスパスワードのみを更新し、KASIKA に新しいパスワードの平文を書き戻しません。
2. バインド済み顧客が初回バインド時に KASIKA に書き込んだ HOMEVISTA アクセスパスワードフィールドは、VISTA の後続のパスワード変更によって自動更新されません。
3. 後日パスワード変更の書き戻しサポートが必要になった場合、独立した要件としてトリガー条件、上書きルール、ログルールを再確認する必要があります。

## 10. 誤バインド処理、削除、再バインド禁止

### 10.1 誤バインド処理の境界

1. 顧客詳細ページの KASIKA 連動モジュールは KASIKA 関連情報とバインド状態のみを表示し、今期は手動でのバインド解除エントリを提供しません。
2. 今期は再バインド、変更バインド、KASIKA 顧客の手動選択、KASIKA バインドの手動解除エントリを提供しません。
3. 後日複雑な誤バインドの処理が本当に必要な場合は、バックエンドのデータガバナンス、同期ログ処理、または別途の管理復旧要件として扱うべきです。
4. バックエンドで誤バインドを処理する際、VISTA はその顧客が最後に保存した KASIKA `customer_id`、KASIKA メールアドレス、`customer_status` を削除すべきではありません。同期ログのトレーサビリティと問題調査のために保持する必要があります。
5. バックエンド処理で「KASIKA 再バインド禁止」マークが書き込まれた場合、そのマークを持つ VISTA 顧客は KASIKA -> VISTA 同期のメール一致候補として扱ってはいけません。KASIKA 入口ページで同メールによる自動バインドもできず、他の KASIKA 顧客アカウントにバインドもできません。
6. 今期はバインド復旧、変更バインド、再バインド禁止マークのクリアを行うページ機能を提供しません。

### 10.2 VISTA 顧客の削除

1. VISTA で顧客を削除する場合、KASIKA の顧客を削除しません。
2. VISTA で顧客を削除する場合、KASIKA 対応顧客のカスタムフィールドにある HOMEVISTA アクセス URL とアクセスパスワードも削除またはクリアしません。
3. その顧客が KASIKA `customer_id` にバインド済みの場合、システムはその VISTA 顧客の有効な KASIKA バインド関係をクリーンアップし、削除された顧客が有効なバインド対象として同期、入口ページ検証、メール一致に参加しないようにする必要があります。
4. 削除時には、履歴バインド記録、最後に保存された KASIKA `customer_id`、KASIKA メールアドレス、`customer_status`、削除操作者、削除日時、バインド無効状態を保持し、同期ログのトレーサビリティに使用する必要があります。
5. 後日 KASIKA が同じ KASIKA 顧客を再度取得した場合、システムは未バインド KASIKA 顧客として再マッチングと新規作成フローを実行できますが、バインドを削除済みの元 VISTA 顧客に自動復旧してはいけません。
6. 削除済みの VISTA 顧客が後日復元された場合、復元操作は元の KASIKA 有効バインドを自動復旧してはいけません。新規作成された顧客と 1 対多のリスクが生じる場合は、バインド異常または業務待処理として記録し、具体的な復旧はバックエンドのデータガバナンスで判断する必要があります。

## 11. 異常マトリクス

| 異常 | 処理ルール | 完了済み結果をロールバックするか |
| --- | --- | --- |
| KASIKA 取得失敗 | 今回のバッチ同期を中止または一部中止。完了済み顧客はロールバックしない。未処理データは失敗または KASIKA 処理待ちとして記録 | いいえ |
| マッチング競合 | 複数メールヒット、候補バインド済み、候補再バインド禁止の場合、業務待処理に入り、自動バインドしない | いいえ |
| VISTA 作成失敗 | バインド関係を保存せず、KASIKA に書き戻さない。失敗理由を記録 | いいえ |
| バインド保存失敗 | VISTA 顧客を重複作成しない。作成済みの VISTA 顧客 ID と KASIKA `customer_id` をログに記録し、後続処理に備える | いいえ |
| URL 書き戻し失敗 | VISTA 顧客とバインド関係を保持。後続は失敗したフィールドのみ補書き | いいえ |
| パスワード書き戻し失敗 | プロジェクトでアクセスパスワードが有効な場合、バインド関係を保持。後続はパスワードフィールドのみ補書き | いいえ |
| 自動返信メール送信失敗 | VISTA 顧客、バインド関係、アクセスフィールド書き戻し結果、権限結果を保持。後続はメール送信のみ補償 | いいえ |
| フィールドスナップショット保存失敗 | そのスナップショットに基づく `customer_status` タグ設定と権限判定は実行しない。失敗理由を記録 | いいえ |
| `customer_status` に同名タグなし | インターフェース異常とはみなさず、業務待処理にもしない。変化なしまたはスキップとして記録 | いいえ |
| 権限判定失敗 | 完了済みの顧客バインドとアクセスフィールド書き戻しには影響しない。失敗理由を記録 | いいえ |
| バインド済み顧客の VISTA 削除 | VISTA 側の有効な KASIKA バインド関係をクリーンアップ。KASIKA の URL、アクセスパスワード、バインドフィールドは削除またはクリアしない。元バインド関係、履歴フィールド保持結果、削除結果、バインド無効状態を記録 | いいえ |

## 12. ログと結果分類

ログルール、エラー辞書、ページサマリは統一して `07-同期ログとトレーサビリティ.md` に従います。本書はカバーすべきトリガーソース、フロントエンド表示結果、ログトレーサビリティ要件のみを定義し、内部処理フェーズの分割は定義しません。

### 12.1 トリガーソース

- 手動全量同期チェック。
- 毎時定期チェック。
- 初回バインドアクセスフィールド書き戻し補償。
- 初回バインド自動返信メール送信または送信補償。
- KASIKA 入口ページフロー。
- VISTA 顧客削除のローカル操作。
- バックエンド誤バインド処理。

### 12.2 フロントエンド表示結果

- 同期更新成功。
- 変化なし未更新。
- 同期更新失敗。

マッチング競合、バインド競合、権限不足、KASIKA 呼び出し制限、フィールド書き込み失敗、権限計算失敗、一部フェーズ失敗などの異常は、フロントエンドの顧客同期結果では一律「同期更新失敗」に分類します。バックエンドログではエラーコード、失敗理由、処理範囲を引き続き記録できます。

### 12.3 バックエンドログのトレーサビリティ次元

バックエンドログは、失敗理由、影響対象、トリガーソース、フィールド変化、後続処理の判断基準をトレースできる必要があります。KASIKA 取得、マッチング、VISTA 作成、バインド保存、URL / パスワード書き戻し、フィールドスナップショット保存、`customer_status` タグ設定、権限判定などの内部フェーズに分割するかどうかは、開発側が実際の同期実装に基づいて設計します。プロダクトページはこれらのフェーズを直接表示しません。

## 13. 受入基準

1. 4 つの API KEY が不完全な場合、「全量同期チェック」ボタンを表示せず、同期や書き戻しを実行しない。
2. システムは顧客同期制御スイッチを提供しない。
3. KASIKA `customer_id`、KASIKA メールアドレス、`customer_status` はすべて構造化保存され、完全なフィールドスナップショットはこれらのフィールドの代替にはならない。
4. バインド済み顧客の同期時、常にスナップショット、構造化 `customer_status`、ログを更新する。`customer_status` ステータス権限自動更新スイッチがオンの場合のみ、現在のステータスに基づいて VISTA タグと権限を校正する。KASIKA への書き戻しは行わない。
5. 未バインド KASIKA 顧客は、メールアドレスが一意にヒットし、未バインドかつ再バインド禁止でない VISTA 顧客が存在する場合のみ自動バインドする。それ以外は業務待処理に入る。
6. VISTA 顧客にマッチングされなかった場合、システムは VISTA 顧客を新規作成し、アクセスフィールドを生成し、バインドを完了し、KASIKA には `VISTAURL` と該当する場合の `VISTAPWD` のみを書き戻す。
7. 初回バインド時、`customer_status` に基づいて同名 VISTA タグ初期化と初期権限判定を必ず 1 回実行する必要があり、`customer_status` ステータス権限自動更新スイッチの影響を受けない。
8. 初回バインド完了後、`customer_status` ステータス権限自動更新スイッチがオンの場合、毎回の同期で当該顧客を処理する際、現在のステータスに基づいて同名 VISTA タグを校正する。ステータス変化時は「新規追加 + 旧削除」でタグを更新し、同名タグが存在しない場合はタグを自動作成せず、バインドをブロックしない。
9. 初回バインド完了後、`customer_status` ステータス権限自動更新スイッチがオフの場合、ステータスのみを保存し、新ステータスタグを追加せず、前ステータスタグを削除せず、権限を積極的に再計算せず、既存タグや既存権限を取り消さない。
10. 権限結果はタグ権限テンプレートの和集合 + 個人権限の追加分で計算する。
11. 顧客詳細ページの KASIKA 連動モジュールには、手動バインド解除、再バインド、変更バインドのエントリを提供しない。複雑な誤バインドを処理する必要がある場合は、バックエンド処理または別途の管理復旧要件として扱う。
12. VISTA でバインド済み顧客を削除する場合、VISTA 側の有効な KASIKA バインド関係をクリーンアップする必要がある。KASIKA 顧客は削除せず、KASIKA 側の HOMEVISTA アクセス URL とアクセスパスワードもクリアしない。削除済み VISTA 顧客が復元された場合、元の KASIKA 有効バインドを自動復旧してはいけない。
13. 初回バインド後、KASIKA 自動返信メール API と設定ページに保存された自動返信ID を介してメールをトリガーでき、メールには顧客招待リンクとアクセスパスワードを組み込める。
14. 自動返信メールの送信失敗は、完了済みのバインドと権限結果をロールバックせず、後続はメール送信のみ補償する。
15. すべての同期更新失敗、変化なし未更新、タスクロック競合、タスク異常結果について、同期ログでトリガーソース、対象、理由、後続処理の判断基準をトレースできる。内部処理フェーズを表示・分割するかどうかは、開発側がログ実装に基づいて設計する。

## 14. 修订履歴

| 日付 | 修订内容 |
| --- | --- |
| 2026-07-13 | KASIKA が「一括取得 → VISTA 比較 / バインド → CSV 一括書き戻し」という非ストリーミングタスク方式を採用したため、手動停止、キャンセル、擬似進捗を廃止。タスクは開始後、ページを閉じたりポップアップを閉じたりしても影響を受けない。同期エントリは B 端管理者と営業マネージャーが表示・発起可能に調整し、営業担当者は不可。プロジェクト単位でサーバー側タスクロックを追加し、競合時は一律「kasikaデータを同期中です。しばらくしてからお試しください」と表示。タスク完了後は実際の処理結果に基づいてログを書き込む。 |
| 2026-07-13 | 自動同期スケジュールルールを追加: 保存済み KASIKA 連動設定の最終更新日時をアンカーとし、その時刻から毎時固定間隔でトリガーし、複数プロジェクトの同期負荷を分散。設定保存に成功した場合のみ本プロジェクトのスケジュールタイミングをリセット。自動タスクもプロジェクト単位のタスクロックを取得する必要があり、ロック取得失敗時は今回の固定トリガーをスキップし、補実行しない。 |
| 2026-08-04 | 初回バインド書き戻し境界を厳格化: KASIKA の `VISTAURL` と該当する場合の `VISTAPWD` にのみ書き戻す。VISTA 顧客 ID、バインド状態、初回アクセス完了時刻は VISTA にのみ保存する。 |