# 05A-顧客リストページ

## 改訂履歴

| 日付 | バージョン | 変更種別 | 変更概要 | 変更者/ソース |
| --- | --- | --- | --- | --- |
| 2026-07-20 | v0.1 | 重大な要件変更 | 同期結果の確認を、同期ログのバッチ顧客リストへの一括集約に統一。KASIKA顧客同期情報ポップアップを結果の受け皿として削除。 | AI（要件に基づく変更） |

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

本書は、顧客リストページの表示、絞り込み、インポート/エクスポート、新規追加エントリ、全量同期チェックエントリ、同期タスクポップアップを定義します。

顧客ページの要件は、以下に分割されます：

- `05A-顧客リストページ.md`：リスト表示、インポート/エクスポート、新規追加エントリ、全量同期チェックエントリ。
- `05B-顧客詳細ページ.md`：顧客基本情報、KASIKA バインディング概要、直近の同期ステータス、顧客のローカル編集/削除。
- `05C-顧客権限ページ.md`：顧客タグ、タグ権限テンプレート合成結果、個人権限追加、最終権限。
- `05D-新規顧客追加.md`：新規 VISTA 顧客追加時の基本情報入力と初期タグ選択。

本書では、KASIKA -> VISTA のコア同期ルールは定義しません。同期の識別、マッチング、バインディング、作成、フィールドスナップショット、アクセスフィールドの書き戻し、権限判定、ログ分類は、`04-統一顧客連携同期フロー.md` および `07-同期ログとトレーサビリティ.md` に従います。

## 2. ページ目標

- 既存の HOME VISTA 顧客リストの情報構造と操作習慣を踏襲する。
- 顧客リストには軽量なエントリと VISTA タグ表示のみを保持し、KASIKA バインディング、同期、失敗詳細は展開しない。
- 連携が利用可能な場合、顧客リストページは唯一の手動同期エントリ「全量同期チェック」ボタンを提供する。
- 単一同期、チェックボックス同期、フロントエンドでの再試行は提供しない。
- VISTA 顧客ファイルのインポート完了後は、VISTA インポート結果のみを表示する。インポート結果に基づいて KASIKA への顧客作成または更新は行わない。

## 3. KASIKA 情報の表示/非表示ルール

1. 顧客リストページは、原則として KASIKA バインディングステータス、KASIKA customer_id、同期ステータス、直近の同期結果などの KASIKA 関連リストフィールドを表示しない。
2. KASIKA 関連情報は顧客詳細ページに集約して表示し、既存の顧客リストへの過度な干渉を避ける。
3. KASIKA 顧客同期に必要な 4 つの API KEY が不完全な場合、顧客リストページに「全量同期チェック」ボタンを表示しない。
4. 4 つの API KEY がすべて設定されている場合、B 端末管理者と営業マネージャーのみが「全量同期チェック」ボタンを表示できる。クリック可能かどうかは、同期タスク実行中かどうか、および KASIKA 呼び出し制限によっても制御される。営業担当者にはこのボタンを表示しない。
5. 本期では顧客情報同期スイッチを提供しない。PID、settingID、バインディング通知自動返信ID、アクセスパスワードスイッチの欠如は、「全量同期チェック」ボタンを非表示にする条件とはしないが、対応する機能に影響を与え、同期ログに明確な結果を記録する。
6. PID が空の場合はアクセスレポートにのみ影響し、顧客同期ボタンの無効化を決定しない。

## 4. ページ内容

### 4.1 表示フィールド

- 既存の HOME VISTA 顧客リストの情報構造とビジュアルレイアウトを踏襲する。
- 既存の列には以下が含まれる：選択ボックス、ID、お名前、累計閲覧ページ数、累計アクセス回数、平均滞在時間、最終アクセス日時、共有有効期限、担当スタッフ、固定アイコン、その他操作メニュー。
- 既存のテーブルに加えて、「タグ」表示のみを新規追加し、現在の顧客が保有する VISTA タグを表示する。
- 「タグ」列は表示のみを担当し、タグをクリックしても絞り込みはトリガーされず、タグ編集も開かない。タグ絞り込みは検索エリアの複数選択タグ条件で完了する。
- タグはチップ形式で表示し、単行では先頭の 2 つのタグを優先表示する。3 つ以上ある場合は `+N` に折りたたむ。完全なタグ編集は顧客詳細の `概要` の `タグ編集` または `権限` タブで行う。
- 顧客リストには KASIKA customer_id、KASIKA バインディングステータス、同期ステータス、直近の同期結果概要などの KASIKA 専用列を追加しない。
- KASIKA バインディング、同期、失敗理由、推奨アクションを確認する必要がある場合は、顧客詳細ページまたは同期ログで確認する。

### 4.2 検索と絞り込み

- 顧客名検索を保持する。
- 顧客メールアドレス検索入力ボックスを追加する。
- VISTA 共有 ID 検索入力ボックスを追加する。VISTA 共有 ID とは、共有 URL 内で顧客のアクセスリンクを識別するための VISTA 側 ID を指し、KASIKA customer_id ではない。
- 担当スタッフ絞り込みを保持し、コントロールにはドロップダウンボックスを使用し、自由入力ボックスは使用しない。
- VISTA タグによる顧客の絞り込みをサポートする。タグ条件はコンパクトな折りたたみ式複数選択コントロールを使用し、検索エリアにすべてのタグを平置きしない。
- タグ絞り込みはデフォルトでエントリボタンと選択済み概要のみを表示する。例：`タグ`、`タグ 2件`、または選択済みタグの概要。クリック後にポップアップパネルを開き、パネル内で checkbox/タグ形式により複数のタグを複数選択する。
- タグの複数選択が空の場合はタグを制限しない。複数のタグを選択した場合、選択したいずれかのタグに一致する顧客を返す。
- 検索エリアには明確な `検索` 送信ボタンを提供する必要がある。入力ボックス、ドロップダウンボックス、タグ複数選択は、まずページローカルで送信待ち条件を形成し、`検索` クリック後に条件に基づいてリストをリクエスト/更新する。
- 顧客リスト上部の操作レイアウトは 2 つのグループに分かれる：
  - 検索グループ：顧客名、顧客メールアドレス、VISTA 共有 ID、担当スタッフ、タグ絞り込み、`検索` ボタンを同じ検索フォームエリアに配置する。
  - リスト操作グループ：`インポート`、`エクスポート`、`新規追加`、`全量同期チェック` を独立した操作エリアに配置し、絞り込み入力と混在させない。
- `検索` は検索グループの送信アクションである。`インポート`、`エクスポート` は副次的なリスト操作、`新規追加` は主要なリスト操作、`全量同期チェック` は KASIKA 同期操作であり、通常のインポート/エクスポート/新規追加アクションとは視覚的に区別する必要がある。
- KASIKA customer_id の検索条件を追加しない。
- KASIKA バインディングステータス、同期ステータス、直近の同期結果などの絞り込み条件を追加しない。

### 4.3 リスト操作

- 既存の検索、インポート、エクスポート、新規追加、行固定、その他操作メニューなどの操作を保持する。
- `新規追加` をクリックすると独立した新規顧客作成ページに入る。具体的な基本情報とタグ選択ルールは `05D-新規顧客追加.md` を参照。
- リスト最右端の三点ボタンをクリックすると行内メニューポップアップが開き、編集ドロワーは直接開かない。
- 三点メニューには少なくとも以下を含む：`顧客情報の編集`、`顧客情報のコピー`、`アクセスリンクのコピー`。
- `顧客情報の編集` は顧客情報編集エントリまたは顧客詳細編集パスに入る。`顧客情報のコピー` はその顧客の基本情報をクリップボードにコピーする。`アクセスリンクのコピー` はその顧客の VISTA アクセスリンクをクリップボードにコピーする。
- 本ページでは右側の編集ドロワーは不要。三点メニューには削除エントリを提供しない。
- 4 つの API KEY が不完全な場合、「全量同期チェック」ボタンを表示しない。
- 4 つの API KEY が完全な場合、B 端末管理者と営業マネージャーのみが「全量同期チェック」ボタンを表示できる。同期タスクの並行制限がなければ、クリックして全量同期チェックをトリガーできる。営業担当者にはこのボタンを表示せず、インターフェースを通じて同期をトリガーすることもできない。
- 単一同期、チェックボックス同期、フロントエンドでの再試行エントリを表示しない。
- バインディング済み顧客については、リストで KASIKA バインディング関係の操作、バインディング変更、同期操作を提供しない。VISTA 顧客を削除する必要がある場合は、顧客詳細ページの既存の削除ルールに従って処理する。
- 「同期失敗エクスポート」と「処理センター」を追加しない。

## 5. 全量同期チェック

### 5.1 エントリルール

1. 「全量同期チェック」は顧客リストページで唯一の手動同期エントリである。
2. 「全量同期チェック」はリストのチェックボックスに依存せず、クリック後は KASIKA の取得結果に基づいて全量チェックを実行する。
3. ロール権限は以下のとおり固定する：B 端末管理者と営業マネージャーは「全量同期チェック」を表示・発起できる。営業担当者にはこのボタンを表示せず、直接リクエストインターフェースによる手動同期タスクの作成もできない。サーバー側でロールを検証する必要があり、フロントエンドの表示/非表示のみに依存してはならない。
4. このボタンは 4 つの API KEY が完全な場合にのみ表示・実行できる。4 つの API KEY のいずれかが欠けている場合は表示しない。
5. 本期では顧客情報同期スイッチを提供しない。定期同期と手動全量同期チェックを実行するかどうかは、API パラメータの完全性、KASIKA API 呼び出し結果、タスク並行ステータス、上記のロール権限によって決定される。
6. 「全量同期チェック」をクリックした際、サーバーはまずプロジェクト単位で同期タスクロックをチェックする。システムが自動定期同期または別の手動同期を実行中の場合は、「正在同步kasika数据，请稍后再尝试」というプロンプトを表示し、新しい同期タスクを作成しない。
7. 自動定期同期がトリガーされた際、システムが手動全量同期チェックを実行中の場合は、今回の定期同期をスキップし、次の定期トリガーを待つ。

### 5.2 同期タスクポップアップ

1. 「全量同期チェック」をクリックして確認し、サーバーがこのプロジェクトの同期タスクロックの取得に成功した後、同期タスクポップアップを表示する。バックグラウンドタスクは実行を継続し、ユーザーがポップアップを閉じる、ページを離れる、ページを更新する影響を受けない。
2. 同期タスクポップアップでは、「1/2/3/4」のフェーズ別フロー説明、パーセント進捗バー、予定完了時間、処理中数量、進捗統計を表示しない。KASIKA が先に顧客データを一括返却し、VISTA がその後で一括バインディングと CSV 一括書き戻しを完了するため、実行プロセスには信頼できる 1 件ごとの完了基準がない。
3. 実行中は、VISTA クラシックな「ゾウ回し」ローディングアニメーション、タイトル「正在同步 KASIKA 数据」、説明「正在获取顾客信息、完成 VISTA 比对与批量回写，请勿重复发起同步。」のみを表示する。キャンセル、閉じる、停止、再同期ボタンは表示しない。
4. 同期完了後、ゾウ回しアニメーションは消え、ポップアップに実際の結果概要と唯一の「確認」ボタンを表示する。概要はまず「本次已处理 N 名 KASIKA 顾客」を表示し、次に 3 つの結果数値を表示する：
   - 新規バインディング：今回作成した VISTA 顧客、または未バインディングの VISTA 顧客を KASIKA に初めてバインディングした数。
   - 更新完了：既存バインディング顧客について、構造化フィールド、ステータスタグ/権限調整、または KASIKA CSV 書き戻しを完了した数。
   - 失敗／処理待ち：データ競合、業務処理待ち、またはシステム障害により、今回の想定処理を完了できなかった数。
5. 3 つの数値は、バックグラウンドタスク完了後にログに記録できる実際の結果のみを使用し、実行中の予測やスクロール表示は行わない。「本次已处理 N 名」と 3 つの結果の統計基準は同期ログでトレース可能でなければならない。
6. ユーザーが確認をクリックするとポップアップを閉じ、顧客リストのステータスを更新する。同期結果の結論の代わりに Toast を追加で使用しない。

## 6. VISTA 顧客ファイルインポート結果

### 6.1 ページ内容

- VISTA 顧客ファイルのインポート結果を表示する：
  - 新規追加数。
  - 更新数。
  - 失敗数。
  - タグ書き込み結果。
  - 失敗明細。
- インポート完了後、今回の VISTA インポート結果に基づいて KASIKA への顧客作成または更新は行わない。その後の KASIKA 同期で同じ顧客が取得された場合、システムは KASIKA -> VISTA ルールに従ってマッチングとバインディングを実行する。
- インポート結果画面では KASIKA 同期明細を表示せず、「KASIKA 同期」ボタンも提供しない。
- KASIKA -> VISTA 一括同期の進捗、結果、失敗理由は、同期タスクポップアップ、バッチ顧客リスト、または同期ログで対応し、顧客リストに常設の同期ステータス列を追加しない。

### 6.2 インタラクション制約

1. VISTA インポート結果ポップアップ/結果パネルは VISTA インポートのクローズドループのみを担当し、KASIKA のコア同期ルールは担わない。
2. インポート完了は KASIKA への顧客作成または更新の同期タスクをトリガーしない。
3. 管理者または営業マネージャーが KASIKA 側に既に対応する顧客がいるか確認する必要がある場合、4 つの API KEY が完全なときに、顧客リストページの「全量同期チェック」を通じて KASIKA -> VISTA チェックをトリガーできる。
4. 本期では長期的なインポート履歴結果エントリを追加しない。

## 7. 受け入れ基準

1. 顧客リストは既存の HOME VISTA リストの情報構造と操作レイアウトを踏襲する。
2. 顧客リストは既存のテーブルに「タグ」表示のみを追加し、KASIKA customer_id、バインディングステータス、同期ステータス、直近の同期結果概要などの KASIKA 専用列を追加しない。
3. タグ列はチップで現在の顧客タグを表示し、3 つ以上ある場合は先頭の 2 つと `+N` を表示する。リストのタグチップはクリックによる絞り込みやリスト内編集を担わない。
4. 顧客リストの検索条件には、顧客名、顧客メールアドレス、VISTA 共有 ID、担当スタッフ、VISTA タグが含まれる。
5. 担当スタッフにはドロップダウンボックスを使用する。タグ絞り込みは折りたたみ式複数選択コントロールを使用し、検索エリアのスペースを占有せず、単一選択ドロップダウンも使用しない。
6. `検索` クリック後、現在の検索条件を送信してリストを更新する。入力過程での即時レスポンスに唯一の検索方法として依存しない。
7. `検索`、`インポート`、`エクスポート`、`新規追加`、`全量同期チェック` のレイアウトグループが明確であること：検索ボタンは検索フォームに属し、インポート/エクスポート/新規追加/同期はリスト操作エリアに属する。
8. 顧客リストに KASIKA customer_id、KASIKA バインディングステータス、同期ステータスの絞り込みを追加しない。
9. インポート、エクスポート、新規追加などの既存操作を保持する。
10. 三点ボタンで行内メニューポップアップを開き、顧客情報編集、顧客情報コピー、アクセスリンクコピーを含む。右側の編集ドロワーを直接開かず、削除エントリも提供しない。
11. 4 つの API KEY が不完全な場合、「全量同期チェック」ボタンを表示しない。
12. 本期では顧客情報同期スイッチを表示または使用しない。同期ボタンのステータスは、管理者/営業マネージャーのロール権限、4 つの API KEY、サーバー側のタスクロック、KASIKA 呼び出し制限のみに影響される。営業担当者にはこのボタンを表示せず、対応するインターフェースを呼び出すこともできない。
13. 管理者または営業マネージャーは、4 つの API KEY が完全で、サーバー側に並行タスクの妨害がない場合に「全量同期チェック」をクリックできる。クリック後、1 回の全量同期チェックタスクを作成し、具体的な処理範囲とデータルールは `04-統一顧客連携同期フロー.md` に従う。
14. リストには単一同期、チェックボックス同期、再試行アクションがない。
15. 連携異常または過去のバインディング情報は顧客詳細ページで表示し、リストでは KASIKA 同期概要を展開しない。
16. 手動全量同期チェック実行中は、ゾウ回しアニメーションと定量化できない同期説明のみを表示し、パーセント、1 件ごとの処理進捗統計、固定の 1/2/3/4 フェーズ説明を表示しない。
17. 同期開始後は停止、キャンセル、閉じる、再発起のエントリを提供しない。ページを閉じてもバックグラウンドタスクの実行は継続する。
18. 正常完了後、ポップアップに実際の処理総数、および新規バインディング、更新完了、失敗／処理待ちの 3 つの結果数値を表示する。確認クリック後にポップアップを閉じてリストを更新し、Toast を主要な結果フィードバックとして使用しない。
19. インポート完了後、VISTA インポートの新規追加、更新、失敗、タグ書き込み結果を確認できる。
20. インポート完了後、KASIKA への顧客作成または更新は行わない。KASIKA API 設定ステータスはインポート自体の結果を変更しない。
21. インポート画面には KASIKA 手動同期ボタンがなく、KASIKA 同期明細も表示しない。

## 8. ユーザーケース

### ケース 1：連携未設定時に同期エントリを非表示
- 前提：プロジェクトに 4 つの KASIKA API KEY が設定されておらず、過去の KASIKA バインディング関係も存在しない。
- 操作：管理者、営業マネージャー、または営業担当者が顧客リストページに入る。
- 期待結果：
  - 顧客リストに「全量同期チェック」ボタンが表示されない。
  - 顧客リストに KASIKA customer_id、バインディングステータス、同期ステータス、直近の同期結果などの KASIKA 専用列が表示されない。
  - 既存の顧客リスト、インポート、エクスポート、新規追加、検索などの VISTA 機能は変更されない。

### ケース 2：連携設定済みかつ利用可能な場合のリスト表示
- 前提：プロジェクトの 4 つの API KEY が完全である。
- 操作：ユーザーが顧客リストページに入る。
- 期待結果：
  - 顧客リストは既存の列構造を踏襲し、「タグ」表示のみを追加する。
  - タグ列は VISTA タグのチップのみを表示し、3 つ以上ある場合は `+N` に折りたたむ。タグはリストページでクリックによる絞り込みや編集ができない。
  - 顧客リストに KASIKA customer_id、バインディングステータス、同期ステータス、直近の同期結果概要などの KASIKA 専用列を表示しない。
  - バインディングまたは失敗の詳細を確認する必要がある場合、ユーザーは顧客詳細または同期ログに入る。

### ケース 2-1：検索条件を送信して顧客を検索
- 前提：顧客リストに複数の顧客が存在し、顧客が異なるメールアドレス、VISTA 共有 ID、担当スタッフ、VISTA タグを保有している。
- 操作：ユーザーが顧客名、顧客メールアドレス、または VISTA 共有 ID を入力し、担当スタッフを選択し、タグ絞り込みで 1 つまたは複数の VISTA タグを複数選択した後、`検索` をクリックする。
- 期待結果：
  - システムは送信時の条件に基づいて顧客リストを更新する。
  - 顧客名、メールアドレス、VISTA 共有 ID はテキスト入力条件である。
  - 担当スタッフはドロップダウン選択条件である。
  - タグ絞り込みはデフォルトでコンパクトなエントリとして表示され、クリック後に複数選択パネルが開く。複数選択時は選択したいずれかのタグに一致する顧客を返す。
  - 検索条件に KASIKA customer_id、KASIKA バインディングステータス、KASIKA 同期ステータスは含まれない。

### ケース 2-2：三点メニューで行操作を実行
- 前提：ユーザーが顧客リストページにいる。
- 操作：ユーザーが任意の行の最右端にある三点ボタンをクリックする。
- 期待結果：
  - ページがその行の近くにメニューポップアップを表示する。
  - メニューに `顧客情報の編集`、`顧客情報のコピー`、`アクセスリンクのコピー` が含まれる。
  - `顧客情報のコピー` クリック後、その顧客の基本情報がコピーされる。
  - `アクセスリンクのコピー` クリック後、その顧客の VISTA アクセスリンクがコピーされる。
  - 三点ボタンは右側の編集ドロワーを直接開かず、メニューに削除操作も提供しない。

### ケース 3：顧客リストページで全量同期チェックをトリガー
- 前提：プロジェクトの 4 つの API KEY が完全で、現在他の同期タスクが実行されていない。
- 操作：管理者または営業マネージャーが顧客リストページで「全量同期チェック」をクリックし、確認ポップアップで確認する。
- 期待結果：
  - システムが 1 回の全量同期チェックタスクを作成し、処理範囲は KASIKA の取得結果に基づき、現在のリストの絞り込みやチェックに依存しない。
  - ページはゾウ回しアニメーションと同期説明のみを含む同期タスクポップアップを表示し、進捗パーセント、処理中数量、停止ボタンを表示しない。
  - 同期完了後、ゾウ回しアニメーションが消え、実際の処理総数、新規バインディング数、更新完了数、失敗／処理待ち数、確認ボタンを表示する。
  - ユーザーが確認後、ポップアップを閉じて顧客リストを更新する。

### ケース 4：既存の同期タスク実行中に全量同期チェックをブロック
- 前提：プロジェクトの 4 つの API KEY は完全だが、システムが自動定期同期または手動全量同期チェックを実行中である。
- 操作：ユーザーが顧客リストページに入る。
- 期待結果：
  - 顧客リストに「全量同期チェック」ボタンは表示されるが、クリック時は「正在同步kasika数据，请稍后再尝试」とプロンプト表示され、新しい同期タスクは作成されない。
  - 顧客リストは通常どおり検索、インポート、エクスポート、新規追加、詳細表示ができる。
  - 定期同期が手動タスク実行中に遭遇した場合、今回のトリガーをスキップし、フロントエンドのプロンプトを表示しない。

### ケース 5：VISTA 顧客ファイルインポート結果
- 前提：ユーザーが VISTA で顧客ファイルインポートを実行する。
- 操作：インポート完了後、インポート結果ポップアップまたは結果パネルを確認する。
- 期待結果：
  - ページに VISTA インポートの新規追加数、更新数、失敗数、タグ書き込み結果、失敗明細が表示される。
  - インポート完了は KASIKA への顧客作成または更新をトリガーしない。
  - インポート結果画面に KASIKA 同期明細は表示されず、「KASIKA 同期」ボタンも提供されない。
- 管理者または営業マネージャーが KASIKA 側に既に対応する顧客がいるか確認する必要がある場合、同期条件が満たされているときにのみ、顧客リストページから「全量同期チェック」をトリガーできる。

### ケース 6：手動同期が自動同期の実行中に遭遇
- 前提：システムが自動定期同期を実行中である。
- 操作：管理者または営業マネージャーが顧客リストページで「全量同期チェック」をクリックする。
- 期待結果：ページに「正在同步kasika数据，请稍后再尝试」というプロンプトが表示され、新しい同期タスクは作成されない。

### ケース 7：自動同期が手動同期の実行中に遭遇
- 前提：管理者または営業マネージャーが顧客リストページで手動全量同期チェックを開始し、タスクが実行中である。

- 操作：システムが自動定期同期のトリガー時間に達する。
- 期待結果：今回の定期同期は実行されず、次のトリガーを待つ。フロントエンドのプロンプトは表示されない。

## 9. 改訂履歴

| 日付 | 改訂内容 |
| --- | --- |
| 2026-07-13 | KASIKA が「一括取得 → VISTA 照合/バインディング → CSV 一括書き戻し」のストリーミング不可タスクを採用したため、手動停止、キャンセル、擬似進捗を取り消し。実行中は VISTA のゾウ回しアニメーションと重複発起防止の説明のみを表示し、完了後は実際の処理総数と新規バインディング、更新完了、失敗／処理待ちの 3 つの結果を表示し、確認ボタンのみを保持。同期エントリは管理者と営業マネージャーが表示・発起可能に調整し、営業担当者は不可。同一プロジェクトではサーバー側タスクロックを採用し、競合時のプロンプトは「正在同步kasika数据，请稍后再尝试」に統一。 |