# 03_ui_design/03_03_client_management.md

版：v2.0　実装の状況は `work_order_db_migration.md`（作業書）を見る

## 1. 概要
本設計書は、顧客管理機能（顧客マスタ、拠点、担当者、名刺）の管理画面（UI）の仕様を定義する。
営業管理担当が日常的に顧客情報を柔軟に修正・追加できる操作性を提供し、マスタ管理と閲覧の権限を明確に分離する。

## 2. 画面一覧

| 画面名 | ファイルパス | 概要 |
|--------|-------------|------|
| 顧客管理トップ | `clients/index.html` | 顧客管理機能のトップメニュー。各マスタ管理画面への導線。 |
| 新規顧客登録ウィザード | `clients/register.html` | 会社・拠点・担当者を一括登録するウィザード。 |
| 企業マスタ管理 | `clients/list.html` | 登録企業の検索・一覧表示。詳細表示（モーダル等）、編集への導線。 |
| 顧客編集 | `clients/edit.html` | 顧客基本情報、階層構造（拠点・担当者）、名刺情報の編集。 |
| 顧客区分管理 | `clients/client_type_edit.html` | 顧客区分（S, L等）の追加・名称変更・無効化・並び替え。 |
| 顧客拠点マスタ管理 | `clients/branch_edit.html` | 顧客拠点（`client_branches` テーブル）の追加・編集・無効化。 |
| 担当者情報管理 | `clients/contacts.html` | 全担当者の横断検索、異動履歴の確認。 |
| 名刺データ管理 | `clients/meishi.html` | 名刺画像の一覧、名刺交換履歴の確認。 |

---

## 3. 画面仕様詳細

### 3.1 顧客管理トップ画面（clients/index.html）
#### 3.1.1 アクセス権限
`client_edit` / `client_edit_cross` / `permission_assign` のいずれかを持つユーザー。
権限がない場合は SPS BACK OFFICE TOP へリダイレクトする。

#### 3.1.2 画面構成
- **ヘッダー**：「← 営業管理へ」戻るリンク、タイトル「顧客管理」、ユーザー名。
- **メニューボックス（6ボックス、3列×2段のグリッド配置）**：
  1. **新規顧客登録** (`register.html` へリンク)
     - 説明：会社・拠点・担当者を一括登録する。
  2. **顧客区分マスタ** (`client_type_edit.html` へリンク)
     - 説明：顧客区分（S, L, C等）の追加・名称変更・無効化・並び替え。
  3. **企業マスタ** (`list.html` へリンク)
     - 説明：登録企業の検索・一覧表示、詳細確認、編集。
  4. **拠点マスタ** (`branch_edit.html` へリンク)
     - 説明：顧客拠点（`client_branches` テーブル）の追加・編集・無効化。
  5. **担当者マスタ** (`contacts.html` へリンク)
     - 説明：登録されている全担当者の横断検索、異動・退任履歴の確認。
  6. **名刺データ管理** (`meishi.html` へリンク)
     - 説明：名刺画像の一覧、名刺交換履歴の確認、OCRデータの検索。

- **制約事項**：
  - localStorage / sessionStorage 使用禁止。
  - 権限チェックは `session.js` の `window.spsUser.permissions` で行う。
  - 各リンクには `?company=SPS` または `?company=SCSPS` のURLパラメータを引き継ぐ。
  - 個人識別情報を扱う画面（担当者マスタ・名刺データ管理）は、`client_edit_cross` を持たないユーザーにはボックスを非表示とする。

---

### 3.2 企業マスタ管理画面（clients/list.html）
#### 3.2.1 アクセス権限
`client_view` 権限を持つユーザー。

#### 3.2.2 画面構成（一覧）
- **ヘッダー**：「← 顧客管理メニューへ」戻るリンク、タイトル「企業マスタ管理」、ユーザー名。
- **ツールバー（上部）**：
  - **タイトル**：「企業一覧」。
  - **新規顧客登録ボタン**：`client_edit` 権限を持つユーザーのみ表示。権限を持たないユーザーはボタン自体を非表示とする（グレーアウトではない）。
  - **検索・絞り込みエリア**：
    - キーワード入力（顧客コード・顧客名・担当者名・電話番号・メールアドレスで部分一致）。
    - 顧客区分プルダウン（`get_client_types.php` から取得し、`sort_order` 昇順で表示。初期値は「すべての区分」）。
    - 「無効データも表示」チェックボックス。
- **一覧テーブル（表示項目）**：
  - **表示順**：顧客区分マスタの `sort_order` 昇順 → 同一区分内は `client_id` 昇順。
  - **列定義**：

| 列名 | データソース（APIの項目名） | 表示形式・備考 |
|---|---|---|
| 顧客コード | `client_id` | テキスト。リンクではない。 |
| 区分 | `type` | 顧客区分マスタ（`client_types`）の名称とコードを結合（例：損害保険会社 (S)）。 |
| 顧客名 | `name` | **クリック可能なリンク**（`<a class="link-name">`）。クリックで「顧客詳細モーダル」を開く。 |
| 代表電話 | `business_phone` | テキスト。空の場合は「-」。 |
| 締め日 | `closing_day` | テキスト。空の場合は「-」。 |
| 支払月 | `payment_month_offset` | 「翌月」「翌々月」等に変換して表示。空の場合は「-」。 |
| 支払日 | `payment_day` | テキスト。空の場合は「-」。 |
| 有効状態 | `active` | バッジ表示。`true`→「有効（緑背景）」、`false`→「無効（赤背景）」。 |
| 操作 | - | `client_edit` 権限を持つユーザーのみ「編集」リンク（`edit.html?id=...`）を表示。権限なしは「-」または非表示。 |

- **一覧のデフォルト表示**：「無効データも表示」がOFFの場合、`active: true` のレコードのみ表示。
- **通信エラー時**：テーブル内に「データの取得に失敗しました」と赤字で表示。

#### 3.2.3 顧客詳細モーダル（list.html内に実装）
顧客名クリックで開くモーダル。`get_client_detail.php?id=...` を叩き、4マスタ結合データを表示する。

- **表示項目（基本情報）**：
  - 顧客コード、顧客区分、顧客名、郵便番号、住所、代表電話、代表メール、締め日、支払月、支払日、有効状態。
- **表示項目（担当者・拠点一覧）**：
  - `contacts` 配列をループ表示。
  - 現在の担当者（`active: true`）を上に、過去の担当者（`active: false`）を下にソート。
  - 各行の表示：氏名、役職、所属拠点（`branches` から `branch_id` で引く）、部署名・係名、期間（`valid_from` ～ `valid_to`）、電話（会社・直通）、メール。
  - 名刺画像（`meishi_history`）がある場合、「▶ 名刺画像を見る」リンクを表示。
- **モーダルの制御**：
  - モーダル外クリック、または「閉じる」ボタンで閉じる。
  - 編集権限がないユーザーでも閲覧可能。
- **データ取得中の表示**：「読み込み中...」を表示。
- **エラー時**：モーダル内に「詳細の取得に失敗しました」と表示。

---

### 3.3 顧客編集画面（clients/edit.html）
#### 3.3.1 アクセス権限
`client_edit` 権限（または `client_edit_cross`）を持つユーザー。

#### 3.3.2 画面構成（基本情報）
- 顧客コード：新規時は「保存」時に自動採番されるため非編集（readonly）。
- 顧客区分：プルダウン選択（`client_types` から有効なものを `sort_order` 順で取得）。
- 顧客名（法人名・個人名）。
- 郵便番号：入力すると外部API（zipcloud等）を呼び出し、住所を自動補完する。
- 住所、代表電話、代表メール。
- 締め日：プルダウン（「月末」または「1」〜「31」）。
- 支払月：プルダウン（「翌月」「翌々月」）。
- 支払日：プルダウン（「末日」または「1」〜「31」）。
- 有効状態（active）：チェックボックスで切替（柔軟な無効化）。
- **枝番作成ボタン**：編集モード時のみ「枝番として新規作成（社名変更等）」ボタンを表示。クリックすると旧レコードを無効化し、新しい枝番コードで保存する。

#### 3.3.3 画面構成（階層構造：拠点・担当者）
- 拠点（`branches`）ごとにアコーディオンを動的に追加・削除可能。
- 各拠点の配下に、部署・係・担当者を動的に追加できるツリー形式UI。
- **担当者（contacts）の入力項目**：
  - 氏名、役職、職位、ダイヤルイン、会社共有携帯、業務メール。
  - 着任日（`valid_from`）、退任日（`valid_to`）、現役フラグ（`active`）。
  - **名刺読取機能**：
    - `[名刺読取（カメラ）]` と `[名刺ファイル選択（PDF/画像）]` ボタンを配置。
    - アップロード後、`ocr_meishi.php` を叩いて氏名等を自動補完。
    - アップロードされた画像/PDFは `/data/clients/meishi/` に保存され、`meishi_history` に追加される。
- **柔軟性の担保**：過去の担当者（`active: false`）も画面上で確認・編集可能とする。

#### 3.3.4 保存時バリデーション
- 顧客名、顧客区分は必須。
- 権限チェック（`client_edit` または `permission_assign`）をサーバー側でも行う。

---

### 3.4 顧客区分管理画面（clients/client_type_edit.html）
#### 3.4.1 アクセス権限
`client_edit` 権限を持つユーザー。

#### 3.4.2 画面構成
- **ヘッダー**：「← 顧客管理メニューへ」戻るリンク、タイトル「顧客区分マスタ管理」、ユーザー名。
- **区分コード一覧テーブル**：
  - 列：並び替え、コード、区分名、適用範囲、有効状態、操作（編集・無効化）。
  - **並び替え機能**：一覧の各行に「↑」「↓」ボタンを配置し、クリックすると表示順（`sort_order`）が入れ替わる。
  - 名称の修正、新規追加、論理削除（`active: false`）。
- 新規追加時、または既存データ編集時は、インラインのフォームまたはモーダルで入力。
  - 区分コード（半角英大文字1文字、登録後変更不可）
  - 区分名
  - 適用範囲（SPS/SCSPS）

---

### 3.5 顧客拠点マスタ管理画面（clients/branch_edit.html）
#### 3.5.1 アクセス権限
`client_edit` 権限を持つユーザー。

#### 3.5.2 画面構成
- **ヘッダー**：「← 顧客管理メニューへ」戻るリンク、タイトル「顧客拠点マスタ管理」、ユーザー名。
- **会社選択エリア**：
  - 顧客コードまたは会社名で検索し、会社を選択するプルダウン（`get_clients.php` から取得）。
- **拠点一覧テーブル（選択した会社の拠点）**：
  - 列：拠点コード（`branch_id`）、拠点名（`branch_name`）、部署名（`department_name`）、係名（`section_name`）、有効状態（`active`）、操作（編集・無効化）。
  - 「新規拠点追加」ボタン：クリックでインラインフォームまたはモーダルを開く。
- **入力項目（新規・編集）**：
  - 拠点名（必須）
  - 部署名（任意）
  - 係名（任意）
  - 有効状態（`active`）
- **保存API**：`POST /clients/api/save_branch.php`
- **制約事項**：物理削除は禁止。無効化は `active: false` による論理削除。

---

### 3.6 担当者情報管理画面（clients/contacts.html）
#### 3.6.1 アクセス権限
- 閲覧：`client_view` または `client_view_cross`
- 編集：`client_edit` または `client_edit_cross`
- 個人識別情報の閲覧：`client_view_cross`
- 個人識別情報の編集：`client_edit_cross`
- `client_view_cross` を持たないユーザーには、個人識別情報（`personal_mobile`、`personal_email`、`birthday` 等）を表示しない。API側でフィルタすること。

#### 3.6.2 画面構成
- **ヘッダー**：「← 顧客管理メニューへ」戻るリンク、タイトル「担当者情報管理」、ユーザー名。
- **検索・絞り込みエリア**：
  - キーワード検索（担当者名・会社名・電話番号）。
  - 「現役のみ」「過去の担当者も含む」の切替。
- **一覧テーブル**：
  - 列：氏名、役職、所属顧客（会社名）、所属拠点、連絡先、状態（現役/過去）、操作（顧客詳細へ）。
  - 編集権限を持つユーザーのみ「編集」リンクを表示。
- **新規担当者追加ボタン**：`client_edit` または `client_edit_cross` を持つユーザーのみ表示。
- **新規・編集時の入力項目**：
  - 会社選択（既存企業から選択）、拠点選択（既存拠点から選択。ない場合は入力）、氏名、役職、職位、会社電話、直通、共有携帯、会社メール、着任日、退任日、現役フラグ。
  - 個人識別情報（個人携帯、個人メール、生年月日）は `client_edit_cross` 保有者のみ入力可。
- 顧客名をクリックすると、企業マスタ管理の詳細モーダル（`list.html` のモーダル）へ遷移、または同等の詳細を表示する。

---

### 3.7 名刺データ管理画面（clients/meishi.html）
#### 3.7.1 アクセス権限
`client_view` 権限を持つユーザー。

#### 3.7.2 画面構成
- **ヘッダー**：「← 顧客管理メニューへ」戻るリンク、タイトル「名刺データ管理」、ユーザー名。
- **検索・絞り込みエリア**：
  - キーワード検索（氏名・会社名・メールアドレス）。
  - タグ（見込み客・展示会等）でのフィルタ。
- **名刺カード一覧（グリッド表示）**：
  - 名刺画像（サムネイル）、氏名、会社名、交換日、交換場所、受領した従業員名をカード形式で表示。
  - 画像クリックで拡大表示。
  - 紐づく人物・顧客へのリンクを表示。

---

### 3.8 新規顧客登録ウィザード（clients/register.html）
#### 3.8.1 アクセス権限
`client_edit` 権限（個人識別情報を入力する場合は `client_edit_cross`）。

#### 3.8.2 画面構成（4ステップ）
- **ステップ1：企業基本情報**
  - 顧客区分、企業名、郵便番号、住所、代表電話、代表メール、締め日、支払月、支払日、有効状態。
- **ステップ2：拠点（任意・複数可・スキップ可）**
  - 拠点名、部署名、係名。
- **ステップ3：担当者（任意・複数可・スキップ可）**
  - 氏名、役職、職位、会社電話、直通、共有携帯、会社メール、着任日、現役フラグ。
  - 個人識別情報（個人携帯、個人メール、生年月日）は `client_edit_cross` 保有者のみ入力可。
- **ステップ4：確認・保存**
  - 入力内容の確認後、一括保存。
- **保存API**：`save_client.php`、`save_person.php`、`save_branch.php` を順次呼び出す。
- **エラー時**：各ステップでインライン表示。`alert()` は使用禁止。

---

## 4. 共通仕様

### 4.1 ボタン・UI
- **基本のボタン**：背景色 `#000080`（ネイビー）、文字色 `#fff`。
- **セカンダリボタン**：背景色 `#2a2a3a`、文字色 `#fff`。
- **危険操作（削除等）**：背景色 `#7a2c2c`、文字色 `#fff`。
- **押せないボタン（無効状態）**：`disabled` 属性を使用し、背景色 `#2a2a3a`、文字色 `#606070` にする。ただし、権限による非表示制御は「ボタン自体を非表示（`display: none;`）」を原則とする（グレーアウトさせない）。

### 4.2 エラーハンドリング
- `alert()` / `confirm()` / `prompt()` は使用禁止。画面内のメッセージエリアまたはインラインで通知する。
- API通信エラー時、権限エラー（403）時は、画面内に「アクセス権限がありません」等を表示する。

### 4.3 データ連携
- `window.spsUser.permissions` を用いて画面表示を制御する。
- 個人情報保護のため、`client_view_cross` 権限を持たないユーザーには、個人（K/P）の識別情報を表示しない。

---

## 5. 改訂履歴

| 日付 | 版 | 担当 | 内容 | 理由・影響範囲 |
|------|----|------|------|--------------|
| 2026-10-24 | 1.0 |Deepseek | 顧客管理画面（一覧・編集・区分管理）のUI仕様を新設。 | 顧客マスタ機能の実装に先立ち、画面仕様を確定させるため。 |
| 2026-10-24 | 1.1 | Deepseek | 3.4.2節に顧客区分の「並び替え機能（上へ・下へ）」を追記 | 実務において受託の多い区分を上位に表示させる要望に対応するため。 |
| 2026-10-24 | 1.2 | Deepseek | 3.2.2節に「表示順（顧客区分マスタの `sort_order` 昇順）」の仕様を追記 | 未契約の顧客が一覧の上部を占めるのを防ぎ、受託の多い区分を上位に表示させるため。 |
| 2026-10-24 | 1.3 | Deepseek | 3.3.2節に郵便番号補完、3.3.3節に階層UIの仕様を追記 | 入力の利便性向上と既存データの復元機能の担保のため。 |
| 2026-10-24 | 1.4 | Deepseek | 3.3.2節に枝番作成ボタン、3.3.3節に担当者の履歴管理（有効期間・現役フラグ）のUI仕様を追記 | 社名変更や担当者の異動履歴を正しく管理するため。 |
| 2026-10-24 | 1.5 | Deepseek | 3.2.3節「顧客詳細モーダル」を新設。マスタ編集権限がないユーザーでも顧客の住所・担当者・履歴を確認できる仕様を追加。ボタンカラーの規定（グレーアウトは押せないボタンのみ）を明記 | マスタ管理画面と閲覧画面の役割を分離し、営業担当等が顧客情報を正しく確認できるようにするため。 |
| 2026-10-24 | 1.6 | Deepseek | 4マスタ構造（顧客・拠点・人物・所属）に対応。3.3.3節に名刺読取機能（カメラ・PDF選択）、名刺画像の保存・履歴表示のUIを追記 | 名刺管理機能（`04_04_01_meishi_management.md`）の導入に伴い、担当者ブロックから直接名刺を登録できるようにするため。 |
| 2026-10-24 | 1.7 | Deepseek | 画面構成を再編。トップメニュー（`index.html`）の新設に伴い、顧客一覧画面を `list.html` に変更。担当者情報管理（`contacts.html`）と名刺データ管理（`meishi.html`）の画面仕様を追加。権限によるボタン非表示の原則を明記。 | 顧客管理機能のトップメニュー新設および各マスタ管理画面への導線整理のため。 |
| 2026-10-25 | 1.8 | Deepseek | 顧客管理トップを6ボックス構成に変更（新規顧客登録・顧客区分・企業・拠点・担当者・名刺）。顧客管理トップの必要権限を `client_edit` / `client_edit_cross` / `permission_assign` に変更。新規顧客登録ウィザード（`register.html`）と顧客拠点マスタ管理（`branch_edit.html`）の画面仕様を新設。企業マスタの一覧・詳細・編集に締め日・支払月・支払日を追加。担当者情報管理の編集権限を明記。 | 顧客管理メニューの再編、新規顧客登録フローの確立、締め日・入金日の管理要件に対応するため。 |
| 2026-10-29 | 2.0 | 全体管理者（14代目） | DB前提に書き直し。保存先の記述をテーブルに |