# 04_04_01_meishi_management.md

版：v2.0　実装の状況は `work_order_db_migration.md`（作業書）を見る
# 名刺管理機能 設計書

**保存先**: `public_html/docs/04_business_flow/meishi_management/04_04_01_meishi_management.md`
**対象**: 営業管理担当・顧客管理担当・全管理者

---

## 1. 概要
本仕様書は、顧客・担当者管理と連携する「名刺管理機能」を定義する。
紙の名刺の画像・PDFデータを保存し、OCRによる自動入力、および名刺交換の履歴（誰が、いつ、どこで交換したか）を管理する。

## 2. データ構造
名刺レコードは、`meishi_history` テーブル（`00_07_database.md` 5.3節。1枚1行。`contact_id` で担当者マスタに紐づく）に保持する。画像・PDFのファイルは `/data/clients/meishi/`。APIの入出力では、担当者の `meishi_history` 配列として返す。形は次のとおり。

```json
"meishi_history": [
  {
    "meishi_id": "M-001",
    "person_id": "P-001",
    "contact_id": "CT-001",
    "image_front": "/data/clients/meishi/M-001_front.jpg",
    "original_file": "/data/clients/meishi/M-001_original.pdf",
    "ocr_data": {
      "company": "株式会社A",
      "name": "山田 太郎",
      "phone": "03-1234-5678",
      "email": "yamada@example.com"
    },
    "received_by": "SPS01-00001",
    "exchanged_at": "2026-10-24",
    "exchanged_place": "東京ビッグサイト",
    "tags": ["見込み客", "展示会"]
  }
]
```

## 3. 機能要件

### 3.1 名刺OCR自動入力
- 入力方法は以下の3つに対応する。
  1. スマホ・タブレットのカメラ撮影
  2. 画像ファイル（JPG/PNG）のアップロード
  3. PDFファイルのアップロード（スキャナで読み取った名刺など）
- `clients/api/ocr_meishi.php` を呼び出し、Google Cloud Vision APIでテキストを抽出。
- 抽出したテキストから、会社名・氏名・役職・電話・メール・住所を自動判別し、入力フォームに自動補完する。
- アップロードされた原本データは、証跡として `/data/clients/meishi/` に保存する。

### 3.2 名刺読取のUI（顧客編集画面）
- 担当者ブロックに以下のボタンを配置する。
  - `[名刺読取（カメラ）]` ：`<input type="file" accept="image/*" capture="environment">`
  - `[名刺ファイル選択]` ：`<input type="file" accept="image/*,application/pdf">`
- ファイル選択後、プレビューを表示し、「解析する」ボタンでOCRを実行。結果をフォームに反映する。

### 3.3 重複チェック（名寄せ）
- 名刺登録時、メールアドレスや携帯電話番号から既存の人物（`persons`）を検索。
- 重複がある場合は、「既存人物の所属履歴として追加するか」確認を促す。

### 3.4 名刺交換履歴の管理
- 「いつ、どこで、誰と」交換したかを記録し、名刺カードとして詳細画面で表示する。

## 4. 名刺カードビュー
- 顧客詳細画面にて、担当者の情報を「名刺の表裏」のようなカード形式で一覧表示する。

## 5. 今後の拡張（未実装）
- 名刺の一括スキャン・CSVインポート。
- 社内での名刺情報の共有（従事者間での検索・閲覧）。
- QRコード（vCard）からのインポート。

## 6. 改訂履歴
| 日付 | 版 | 担当 | 内容 | 理由・影響範囲 |
|------|----|------|------|--------------|
| 2026-10-24 | 1.0 | 全体管理者（12代目） | 初版作成。OCR（`ocr_meishi.php`）、名寄せ、名刺交換履歴、カードビューの仕様を定義。PDF対応も明記 | 担当者管理と密接な名刺管理機能を独立した仕様書として定義するため |
| 2026-10-29 | 2.0 | 全体管理者（14代目） | DB前提に書き直し。名刺レコードの保存先を `meishi_history` テーブルに |