## 02_data_definition/02_01_employee_table.md

版：v2.1　実装の状況は `work_order_db_migration.md`（作業書）を見る
# Employee Table Definition (従事者マスタ)

## テーブル概要
従事者（調査員・営業・経理・管理者）の基本情報を管理するマスタデータ。
個人事業（SPS）と法人（SCSPS）の従事者を一元管理する。

## 保存先
DB の `employees`、`employee_companies`（所属）、`employee_permissions`（権限）の各テーブル（`00_07_database.md` 5.2節）。写真の画像ファイルは `/data/employees/photos/`。

### 項目とテーブルの対応
| 項目 | 保存先 |
|------|--------|
| SPS_ID、氏名、氏名カナ、primary_company、生年月日、住所各項目、建物名、電話、携帯、メール、最終学歴、卒業校名、前職、資格、探偵業罰則、罰則内容、採用時確認書類、確認書類内容、採用年月日、採用拠点CD、従事する探偵業務、稼働状況、終了区分、終了日、その他 | `employees` の各列（列名は `schema_employees.sql`） |
| 所属（会社ごとの契約CD、職務ポジションCD、部署CD、契約拠点、管轄拠点、サテライト） | `employee_companies`（従事者×会社で1行。掛け持ちは会社ごとに1行。主たる所属は `employees.primary_company`） |
| 権限 | `employee_permissions`（権限キーごとに1行。付与済みは granted = 真） |
| 業務委託契約、社会保険情報 | `employees` の JSON 列（入れ子のまま保持） |
| 写真 | `employees.photo_path`（画像実体は `/data/employees/photos/`） |

以下の「データ構造」は、APIの入出力で使うデータの形（JSON）を示す。

## データ構造（APIの入出力の形）

```json
{
  "employees": [
    {
      "SPS_ID": "SPS01-99999",
      "氏名": "テスト 太郎",
      "氏名カナ": "ﾃｽﾄ ﾀﾛｳ",
      "所属": [
        { "会社": "SPS", "契約CD": "C06", "職務ポジションCD": "P013", "部署CD": "D01",
          "契約拠点": "K01", "管轄拠点": null, "サテライト": "S01" },
        { "会社": "SCSPS", "契約CD": "C02", "職務ポジションCD": "P013", "部署CD": "D01",
          "契約拠点": "K01", "管轄拠点": "K01", "サテライト": null }
      ],
      "primary_company": "SPS",
      "生年月日": "1980-01-01",
      "郵便番号": "100-0001",
      "住所都道府県": "東京都",
      "住所市区町村": "千代田区",
      "住所町名": "千代田",
      "住所番地": "",
      "建物名": "",
      "電話": "03-0000-0000",
      "携帯": "090-0000-0000",
      "メール": "test@example.com",
      "最終学歴": "大学卒",
      "卒業校名": "○○大学",
      "前職": "○○株式会社",
      "資格": "簿記2級, FP技能士",
      "探偵業罰則": false,
      "罰則内容": "",
      "採用時確認書類": true,
      "確認書類内容": "身分証明書, 履歴書",
      "採用年月日": "2019-04-01",
      "採用拠点CD": "K01",
      "業務委託契約": null,
      "従事する探偵業務": "調査全般",
      "稼働状況": "常勤",
      "終了区分": null,
      "終了日": null,
      "社会保険情報": {
        "健康保険": {
          "加入状況": "加入",
          "被保険者番号": "12345678",
          "資格取得日": "2019-04-01",
          "資格喪失日": null,
          "標準報酬月額": 300000
        },
        "厚生年金": {
          "加入状況": "加入",
          "被保険者番号": "87654321",
          "基礎年金番号": "1234567890",
          "資格取得日": "2019-04-01",
          "資格喪失日": null,
          "標準報酬月額": 300000
        },
        "雇用保険": {
          "加入状況": "加入",
          "被保険者番号": "ABCD1234",
          "資格取得日": "2019-04-01",
          "資格喪失日": null
        },
        "被扶養者": [
          {
            "氏名": "テスト 花子",
            "続柄": "妻",
            "生年月日": "1982-01-01",
            "続柄コード": "1"
          }
        ],
        "適用除外該当": false,
        "適用除外理由": ""
      },
      "権限": {
        "company_access_sps": true,
        "company_access_sps_edit": true,
        "company_access_scsps": true,
        "company_access_scsps_edit": true,
        "case_view_all": true,
        "case_edit_all": true,
        "accounting_view": true,
        "accounting_edit": true,
        "permission_assign": true
      },
      "写真": {
        "path": "/data/employees/photos/SPS01-99999.jpg"
      },
      "その他": ""
    }
  ]
}
```

## フィールド説明

| フィールド名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SPS_ID | string | ✅ | 従事者ID |
| 氏名 | string | ✅ | 氏名（全角） |
| 氏名カナ | string | ✅ | ヨミガナ（半角カナ推奨） |
| 所属 | array | ✅ | 従事者が所属する会社ごとの情報の配列（SPS/SCSPS）。掛け持ちの場合は会社ごとに1件。各件の項目は下の「所属の項目」 |
| primary_company | string | ✅ | 主たる所属会社。デフォルト表示や給与計算の基準となる |
| 生年月日 | date | ✅ | YYYY-MM-DD形式 |
| 郵便番号 | string | | ハイフンあり |
| 住所都道府県 | string | ✅ | 都道府県（郵便番号APIの address1）。検索・抽出用 |
| 住所市区町村 | string | ✅ | 市区町村（郵便番号APIの address2） |
| 住所町名 | string | ✅ | 町域名（郵便番号APIの address3） |
| 住所番地 | string | | 番地・号。手入力。修正時はこのフィールドのみ編集する |
| 建物名 | string | | マンション名など |
| 電話 | string | | 固定電話 |
| 携帯 | string | ✅ | 携帯番号 |
| メール | string | ✅ | メールアドレス |
| 最終学歴 | string | | 中学校卒／高校卒／専門学校卒／大学卒など |
| 卒業校名 | string | | 学校名 |
| 前職 | string | | 前職の会社名・職種 |
| 資格 | string | | 簿記2級、FP技能士など（カンマ区切り） |
| 探偵業罰則 | boolean | | true=有／false=無 |
| 罰則内容 | string | | 「有」の場合の内容 |
| 採用時確認書類 | boolean | | true=有／false=無 |
| 確認書類内容 | string | | 確認した書類 |
| 採用年月日 | date | ✅ | 入社日 |
| 採用拠点CD | string | ✅ | 従業員IDの採番に使った拠点コード（採用時の契約拠点）。変更しない |
| 業務委託契約 | object | | 旧項目。会社ごとの契約（所属の契約CD）に置き換えたため、画面では使わない。取り込み時の元の値を保持するだけ。歩合率は使わない（業務委託の率は職務ポジションで決まる。`01_07`） |
| 従事する探偵業務 | string | | 担当業務 |
| **稼働状況** | string | ✅ | 値は `00_03_login_session.md` 3節の一覧のとおり（常勤／非常勤／在籍／休職／休業中／臨時／退職／契約終了／契約解除／解雇／緊急ロック）。ログインの可否は同節で定める。「緊急ロック」の内部値・表示名は、アカウント停止（`account_suspend`）との対応が未決 |
| **終了区分** | string | | 稼働状況が退職／契約終了／契約解除／解雇の場合の詳細（自己都合／定年退職／会社都合／懲戒解雇／契約解除） |
| **終了日** | date | | 退職・解雇・契約解除の日付 |
| 社会保険情報 | object | | 社会保険関連情報（将来拡張） |
| 権限 | object | | 個人単位の権限。オブジェクト形式（キー＝権限ID、値＝boolean）で保持する。全権キー `supreme_access` を格納できる。`supreme_access` が真の場合は全画面の権限チェックを通過する（`06_01_permission_design.md` 2.11節・3.4節参照）。緊急用の `emergency_override`（`users` テーブル側）とは独立であり、混同しないこと。権限の変更は、確認者の承認後に反映する（下の「変更履歴」） |
| 写真 | object | | 従事者写真。`path` に画像ファイルのパスを持つ（DBでは `photo_path`）。画像実体は `/data/employees/photos/` に保存。表示箇所は別途仕様を定める |
| その他 | string | | 備考 |

### 住所の入力仕様
- 郵便番号を入力すると、外部API（zipcloud等）を呼び出し、`住所都道府県`（address1）・`住所市区町村`（address2）・`住所町名`（address3）を自動入力する。
- `住所番地` は手入力とする。
- 修正時は `住所番地` のみを編集すればよい構造とする。

### 終了区分一覧
| 区分 | 説明 | 該当契約 |
|------|------|---------|
| 自己都合 | 従事者側の意思による終了 | 全契約 |
| 定年退職 | 定年到達による終了 | 雇用契約 |
| 会社都合 | 会社側の意思による解雇 | 雇用契約 |
| 懲戒解雇 | 重大な非違行為による解雇 | 雇用契約 |
| 契約解除 | 会社側の意思による契約終了 | 有期契約/業務委託 |

※ 表示時は契約コードに応じて「懲戒解雇」「契約解除」を使い分ける

## 社会保険情報（将来拡張）

### データ構造
```json
{
  "社会保険情報": {
    "健康保険": {
      "加入状況": "加入／未加入／適用除外",
      "被保険者番号": "文字列",
      "資格取得日": "YYYY-MM-DD",
      "資格喪失日": "YYYY-MM-DD or null",
      "標準報酬月額": 数値
    },
    "厚生年金": {
      "加入状況": "加入／未加入／適用除外",
      "被保険者番号": "文字列",
      "基礎年金番号": "文字列",
      "資格取得日": "YYYY-MM-DD",
      "資格喪失日": "YYYY-MM-DD or null",
      "標準報酬月額": 数値
    },
    "雇用保険": {
      "加入状況": "加入／未加入",
      "被保険者番号": "文字列",
      "資格取得日": "YYYY-MM-DD",
      "資格喪失日": "YYYY-MM-DD or null"
    },
    "被扶養者": [
      {
        "氏名": "文字列",
        "続柄": "文字列",
        "生年月日": "YYYY-MM-DD",
        "続柄コード": "1=配偶者,2=子,3=父母等"
      }
    ],
    "適用除外該当": false,
    "適用除外理由": "文字列"
  }
}
```

### 社会保険CSV出力時に必要な項目
- 氏名（漢字・カナ）
- 生年月日
- 性別（別途追加検討）
- 住所
- 基礎年金番号
- 健康保険被保険者番号
- 厚生年金被保険者番号
- 雇用保険被保険者番号
- 資格取得日・喪失日
- 標準報酬月額
- 被扶養者情報

### 所属の項目（`employee_companies`。1会社につき1件）
| 項目 | 必須 | 説明 |
|------|------|------|
| 会社 | ✅ | 会社コード（SPS / SCSPS） |
| 契約CD | ✅ | その会社での契約コード（`01_04`）。その会社で使える契約から選ぶ |
| 職務ポジションCD | ✅ | その会社での職務ポジション（`01_07`）。その会社で使えるものから選ぶ |
| 部署CD | | その会社での部署（`01_06`） |
| 契約拠点 | ✅ | その会社の契約を結んだ拠点（K01 の形）。原則、変えない |
| 管轄拠点 | | 今の管轄拠点。事務所勤務の人は、ここに入れる。サテライトの人は空にする |
| サテライト | | 実働の場所（S01 の形）。サテライトの人は、管轄をマスタ（`01_11`）で決める |

- 管轄拠点とサテライトは、どちらか一方だけを入れる（両方空、両方入りは不可）。
- 従業員IDの採番は契約拠点の `id_part`、案件番号と書類番号は管轄拠点の `id_part`（`01_11` 5節）。

## 兼任者・複数契約の扱い
- 1人の従事者が複数の会社に所属し、異なる契約形態を持つことができる
- 例：法人では正規雇用（C02）、個人事業では業務委託（C06）として活動
- 給与・報酬はそれぞれの契約に基づき別々に計算・支払われる（給与は会社ごとに `salaries`、業務委託の率は職務ポジション。`01_08`）
- 契約、職務ポジション、部署、拠点は、会社ごとに持つ。SCSPS では正規雇用、SPS では業務委託、両方とも業務委託、のどれでもよい
- ログイン時は「所属」に基づいてアクセス可能な会社を判定

## 退職者データ保存ポリシー
- 従事者情報は削除せず永続保存する
- 退職後もデータは保持し、稼働状況と終了区分で管理する
- 削除機能は実装しない

### 保存の理由
1. **法的要件**：給与台帳（7年/5年）、源泉徴収票、社会保険記録の保存義務
2. **過去案件参照**：退職者が担当した案件の担当者名表示に必要
3. **警察監査対応**：探偵業法に基づく従事者情報の開示要求対応
4. **税務調査対応**：退職者を含む給与支払報告書の作成

## 退職者表示ルール

| 対象 | 表示内容 | 権限 | 備考 |
|------|---------|------|------|
| 在籍者 | 全項目表示 | 通常権限 | 稼働状況=在籍/休職 |
| 退職後7年以内 | 氏名・SPS_ID・職務ポジションをグレー表示 | permission_assign保有者 | 終了日から7年経過していない者 |
| 退職後7年超 | 一覧には非表示 | permission_assign保有者のみ別画面で全件表示可 | アーカイブ画面を別途用意 |

### 表示制御の実装方針
- 従事者一覧画面（`employees/index.html`）に表示切替タブを実装：［現役］［退職者（7年以内）］［全退職者］
- 退職者表示時は行全体をグレー（opacity: 0.6）にする
- 退職者表示項目は制限（名前・ID・職務のみ）
- 権限チェックを実装し、permission_assign保有者のみ退職者表示タブを表示

## 変更履歴（`00_10_change_history.md`）

従事者の項目を変更したときの、履歴の扱い。人が「訂正／変更」を選ぶ操作は無い。項目ごとの区分で、自動的に決まる。確認（変更／訂正／却下）は、修正した本人とは別の権限者が行う。

| 区分 | 項目 | 扱い |
|---|---|---|
| B 承認後に反映 | 氏名、氏名カナ、所属（会社の追加・削除、会社ごとの契約CD、契約拠点）、primary_company、業務委託契約、権限 | 保存すると「承認待ち」。確認者が承認するまで、現在の値は変わらない |
| 出来事 | 賞罰、職務ポジション（昇進・降格） | 項目の直接編集ではなく、出来事として1件ずつ登録する（`employee_events`）。賞罰は B（承認後に確定）、昇進・降格は A（登録と同時に、その会社の職務ポジションが変わる） |
| A 変更として記録 | 生年月日、郵便番号、住所各項目、建物名、電話、携帯、メール、採用年月日、採用拠点CD、会社ごとの部署CD・管轄拠点・サテライト、従事する探偵業務、稼働状況、終了区分、終了日、探偵業罰則、罰則内容、採用時確認書類、確認書類内容、社会保険情報 | 保存と同時に反映。履歴に「未確認」で記録（有効日・理由は任意） |
| C 訂正扱い | 最終学歴、卒業校名、前職、資格、写真、その他 | 履歴には残さない。短期の編集ログのみ（90日） |

- 氏名の保存時は、「改姓・改名」のチェックを1つ付ける。チェックが無い氏名の変更は、訂正扱い（編集ログのみ）とする。
- 機密性の高い項目（氏名、氏名カナ、生年月日、権限、賞罰、探偵業罰則、社会保険情報）の履歴は、`change_history_view_sensitive` を持つ人だけが見られる。
- 上の区分は案。真柴さんの承認で確定する。項目を増やしたときは、この表に区分を追記する（追記漏れの項目は、A として扱う）。

## 保存処理API仕様

### 1. 概要
従事者情報の保存は、専用のAPI（`/employees/api/save_employee.php`）を介して行う。
新規登録時は自動採番機能を含む。

### 2. リクエスト仕様
| 項目 | 内容 |
|------|------|
| メソッド | POST |
| エンドポイント | `/employees/api/save_employee.php` |
| リクエストヘッダー | `Content-Type: application/json` |

### 3. リクエストボディ
```json
{
  "employee": {
    "SPS_ID": "SPS01-00005",
    "氏名": "テスト 花子",
    "氏名カナ": "ﾃｽﾄ ﾊﾅｺ",
    "所属": [
      { "会社": "SCSPS", "契約CD": "C02", "職務ポジションCD": "P014", "部署CD": "D01",
        "契約拠点": "K01", "管轄拠点": "K01", "サテライト": null }
    ],
    "primary_company": "SCSPS",
    "生年月日": "1990-01-01",
    "郵便番号": "150-0002",
    "住所都道府県": "東京都",
    "住所市区町村": "渋谷区",
    "住所町名": "渋谷",
    "住所番地": "2-15-1",
    "稼働状況": "常勤",
    "終了区分": null,
    "終了日": null,
    "採用年月日": "2026-04-01",
    "権限": {
      "case_view_self": true,
      "expense_view_self": true
    }
  },
}
```
※ 新規の場合は `SPS_ID` を null または省略可。
※ 更新者の情報は、リクエストで受け取らない。サーバーが、セッションから取得する（`06_01_permission_design.md` 10.3節）。

### 4. レスポンス仕様
**成功時**
```json
{
  "success": true,
  "message": "保存しました",
  "sps_id": "SPS01-00005",
  "timestamp": "2026-03-16 15:30:00"
}
```

**エラー時**
```json
{
  "success": false,
  "message": "エラーメッセージ"
}
```

### 5. 処理内容
1. リクエストデータのバリデーション
2. トランザクションを開始
3. 新規登録の場合：拠点コードから拠点番号を取得し、`id_counters` から次回の連番を取得（`01_03_id_generation.md` 5.3節）。ID生成（例：SPS01-00005）
4. `employees`（および `employee_companies`、`employee_permissions`）を、新規追加 or 変更項目のみ更新
5. 更新日時・更新者情報の記録（更新者はセッションから取得）
6. 変更履歴の記録（上の区分に従う。区分Bは承認待ちとして保存し、現在の値は変えない）
7. コミット。途中で失敗したらロールバックする

### 6. エラーハンドリング
| エラー状況 | HTTPステータス | メッセージ |
|-----------|---------------|-----------|
| 必須パラメータ不足 | 400 | 必須パラメータが不足しています |
| DBの更新失敗（ロールバック） | 500 | 保存できませんでした |
| 更新対象不存在 | 404 | 更新対象の従事者データが見つかりません |
| ID採番失敗 | 500 | IDの採番に失敗しました |

## 改訂履歴
| 日付 | 版 | 内容 |
|------|----|------|
| 2026-03-12 | 1.0 | 初版作成 |
| 2026-03-15 | 1.1 | 所属フィールド、兼任者対応を追加 |
| 2026-03-15 | 1.2 | 社会保険情報（将来拡張）を追記 |
| 2026-03-16 | 1.3 | 終了区分と退職者表示ポリシーを追記 |
| 2026-03-16 | 1.4 | 保存処理API仕様を追記 |
| 2026-10-08 | 1.5 | ファイル名規則を「フォルダ番号＋ファイル番号」形式に変更したことに伴い、参照名と保存先表記を機械的に置換（内容の変更なし） |
| 2026-10-25 | 1.6 | 住所を `住所都道府県`・`住所市区町村`・`住所町名`・`住所番地` の4フィールドに分割（郵便番号APIの address1〜3 と対応、番地は修正用に分離）。`写真` フィールドを追加（画像実体は `/data/employees/photos/`、JSONはパスのみ保持）。担当：Deepseek |
| 2026-10-25 | 1.7 | `権限` フィールドの説明に、オブジェクト形式である旨と全権付与用マスターキー `master_access` の格納・効力（`06_01_permission_design.md` 2.11節・3.4節参照）を追記。緊急用 `isAdmin`（`users.json` 側）との独立性を明記 | `06_01_permission_design.md` v1.9 の `master_access` 新設に伴う整合。影響範囲：`employees.json` の `権限`、`login.php` / `get_session.php` の返却値 |
| 2026-10-26 | 1.8 | 保存ファイルのパスを `/master/employees.json` から `/data/employees/employees.json` に訂正（ツリーv2.6のファイル移動に合わせる）。保存処理APIのエンドポイントを `/master/api/save_employee.php` から `/employees/api/save_employee.php` に変更（`06_01_permission_design.md` v2.0に合わせる）。採番カウンターのパスを `/data/employees/counters/employee_counter.json` に訂正。退職者表示の画面名を `employees/index.html` に訂正。担当：全体管理者（13代目）。影響範囲：`06_01_permission_design.md` 10節、`03_02_master_management.md` 11節、`save_employee.php` の実装（保存先・カウンターのパス） |
| 2026-10-29 | 1.9 | 全体管理者（14代目） | ①例の人名・ID・住所・電話・メールをテスト用（テスト 太郎、`SPS01-99999`）に差し替え（公開サイトに実名・実在の連絡先を出さないため）。②稼働状況の値を `00_03` 3節の一覧に合わせた。③`権限` の説明を `supreme_access`・`emergency_override`（旧名併記）に改名。④保存リクエストの例から `user` を削除（更新者はセッションから取得）。⑤「変更履歴」節を新設（項目の区分。案）。保存処理に履歴の記録を追加 | 変更履歴仕様（`00_10`）、権限キーの改名の反映。影響範囲：`05_03`、`save_employee.php`、`load_employee.php`、`06_01` 10.3節 |
| 2026-10-29 | 2.0 | DB前提に書き直し。保存先を `employees`・`employee_companies`・`employee_permissions` に（項目とテーブルの対応表を追加）。保存処理を、トランザクションと `id_counters` による採番に。`isAdmin`・`master_access` の旧名の記述を削除。リクエスト例の人名をテスト用に |
| 2026-10-30 | 2.1 | 全体管理者（14代目） | 契約・職務ポジション・部署・拠点を、従事者×会社ごとの所属（`employee_companies`）に移した（所属を、会社ごとの情報の配列に）。契約拠点、管轄拠点、サテライトを追加。現在契約CD・現在拠点CD・部署CD・職務CD を従事者本体から削除。業務委託契約（旧項目）は画面で使わないと明記。変更履歴の区分を所属ベースに更新。「職務CD」を「職務ポジション」に | 真柴さんの指示（SCSPS と SPS の掛け持ち、サテライト、管轄）。影響範囲：`00_07` 5.2節、`schema_employees.sql`、`01_11`、`03_02` 11節、`05_xx`、`save_employee.php`、`load_employee_list.php` |