# 01_code_definition/01_11_branches.md
# 拠点・サテライト・管轄

版：v1.4（承認待ち）　実装の状況は `work_order_db_migration.md`（作業書）を見る

## 1. 概要
拠点（事務所）と、事務所を持たない担当エリア（サテライト）、サテライトを管轄する拠点の対応を管理する。
保存先は `branches`、`satellites`、`branch_jurisdictions` の各テーブル（`schema_master.sql`）。

## 2. 用語
| 用語 | 意味 | コード | 番号に使うか |
|------|------|--------|-------------|
| 拠点 | 事務所。本社、京都、大阪など | K01 の形（01_10 の KB） | 使う（`id_part` の2桁） |
| サテライト | 事務所を持たない担当エリア。例：香川担当。調査員の住所が拠点になる場合など | S01 の形（01_10 の KS。案） | 使わない |
| 契約拠点 | 従事者が契約している拠点。従業員IDの採番に使う。採用時に決め、変えない | 拠点のコード | 従業員IDに使う |
| 管轄拠点 | 今、管轄している拠点。案件番号・書類番号の採番に使う | 拠点のコード | 案件番号・書類番号に使う |

## 3. テーブル
### 3.1 拠点（`branches`）
| 項目 | 必須 | 備考 |
|------|------|------|
| `branch_code` | ○ | K01 の形。永続（変更しない） |
| `id_part` | ○ | 従業員IDと案件番号に入る2桁（01）。重複不可。一度決めたら変更しない。新設するときは次の空き番号 |
| `name` | ○ | 拠点名（本社、京都、大阪、奈良、滋賀） |
| `location` | - | 所在地 |
| `is_headquarters` | ○ | 本社かどうか（1つの拠点だけ 1）。事務職・経理職が、他拠点の金額まわりを確認できるのは、本社の人だけ（`04_01_08`） |
| `active` | ○ | 使用中かどうか |
| `sort_order` | - | 表示順 |

### 3.2 サテライト（`satellites`）
| 項目 | 必須 | 備考 |
|------|------|------|
| `satellite_code` | ○ | S01 の形。永続 |
| `name` | ○ | 例：香川担当 |
| `area` | - | エリア名（県など）。**個人の住所は入れない**（従事者の住所の項目に入れる） |
| `active` | ○ | 使用中かどうか |
| `promoted_to` | - | 拠点に繰り上がったときの、新しい拠点コード |
| `note` | - | 備考 |

### 3.3 管轄（`branch_jurisdictions`）
サテライトを、どの拠点が管轄するかを、期間つきで持つ。
| 項目 | 必須 | 備考 |
|------|------|------|
| `satellite_code` | ○ | サテライト |
| `branch_code` | ○ | 管轄する拠点 |
| `valid_from` | ○ | 管轄の開始日 |
| `valid_to` | - | 終了日。空なら現在有効 |

- 管轄が移るときは、新しい行を足し、前の行の `valid_to` に終了日を入れる。上書きしない。
- 同じサテライトの期間が重ならないようにする。

### 3.4 従事者の所属（`employee_companies`）との関係
従事者×会社ごとに、次の3つを持つ（`02_01`）。
| 項目 | 備考 |
|------|------|
| `contract_branch`（契約拠点） | 必須。採用時に決める。従業員IDの採番に使う |
| `jurisdiction_branch`（管轄拠点） | 事務所勤務の人は、ここに入れる（通常は契約拠点と同じ）。**サテライトの人は空**にする |
| `satellite_cd`（サテライト） | 事務所勤務の人は空 |

## 4. 管轄拠点の決め方
従事者×会社の所属から、ある日付の管轄拠点は、次のとおり決める。
1. `satellite_cd` が空でなければ、`branch_jurisdictions` で、その日付に有効な行の `branch_code`。
2. 空であれば、`jurisdiction_branch`。

管轄が移るとき、サテライトの全員に自動で反映される（管轄の1行を直すだけ）。事務所勤務の人の管轄拠点を変えるときは、本人の所属を変更する（変更履歴に残る。`00_10`）。

## 5. 番号の決め方
| 番号 | 使う拠点 | いつ決めるか |
|------|---------|-------------|
| 従業員ID（SPS01-00005 の 01） | 契約拠点の `id_part` | 採用時。以後、変えない |
| 案件番号 | 案件の**管理拠点**の `id_part`（新規案件入力で、最初に選ぶ） | 新規案件の保存時。**一度決めたら、管理拠点を変えても、案件番号は変えない** |
| 見積書・請求書などの書類番号 | 書類を発行する時点の、案件の**現在の管理拠点**の `id_part` | 書類の発行時。管理拠点を変えたあとに発行する書類は、新しい拠点の番号になる。発行済みの書類の番号は変えない |

- **管理拠点の変更**：案件の管理拠点は、案件詳細画面から変えられる（`04_01_04` 3.4節）。変えるのは、まれな場合。変更は履歴に残す（`case_branch_history`）。
- サテライトの数字（S01 など）は、どの番号にも入れない。
- 事務が代行で案件を入力する場合も、入力した人の拠点ではなく、選んだ**案件管理拠点**で決める。
- **案件管理拠点**は、その案件を管理する拠点。基本は受託した拠点だが、受託した拠点と管理する拠点が違う場合（例：本社で受託し、大阪が管理する）は、管理する拠点（大阪）の案件になる。案件番号も請求書も、この拠点で決まる。拠点には、サテライトではなく、拠点（K）を選ぶ。
- 管理担当者は、受託した案件の責任者（ふだんは営業担当。上位職が営業を通さずに受託したときは、その人）。管理担当者の選択肢は、案件管理拠点の管轄の人に絞って出す。現場の調査員（主担当・副担当）の拠点は使わない。
- 案件入力の画面では、一番上で案件管理拠点を選ぶと、案件番号の拠点の部分を仮に表示する。連番は保存したときに確定する（欠番を防ぐ）。

## 6. 権限の範囲（スコープ）
権限の範囲 `branch`（拠点の範囲）は、**管轄拠点**を基準にする（サテライトの人は、管轄マスタで決まる拠点）。同じ管轄拠点の従事者が、同じ範囲になる。（要確認：契約拠点を基準にする案もある。作業書 E-11）

## 7. 拠点の新設とサテライトの繰り上げ
- **新設**：拠点マスタ画面（`branch_edit.html`）で、拠点名、所在地を入力する。`branch_code`（K の次の番号）と `id_part`（次の空き）は自動で付ける。
- **サテライトの新設**：サテライトの管理画面で、名前とエリアを入力し、管轄する拠点を選ぶ。`satellite_code` は自動で付ける。
- **サテライトが拠点になるとき**：新しい拠点を新設する（新しい K と `id_part`）。サテライトの `active` を偽にし、`promoted_to` に新しい拠点コードを入れる。そのサテライトの人の所属は、`jurisdiction_branch` を新しい拠点にして、`satellite_cd` を空にする（変更履歴に残す）。すでに採番した従業員IDと案件番号は、変わらない。
- 拠点・サテライトは、削除しない。使わなくなったら `active` を偽にする。

## 8. APIの入出力の形（例）
```json
{
  "branches": [
    { "branch_code": "K01", "id_part": "01", "name": "本社", "location": "京都府", "active": true }
  ],
  "satellites": [
    { "satellite_code": "S01", "name": "香川担当", "area": "香川県", "active": true,
      "jurisdiction": { "branch_code": "K01", "valid_from": "2026-11-01", "valid_to": null } }
  ]
}
```

## 9. 画面
- 拠点マスタ：`master/branch_edit.html`（`permission_assign` が必要。`03_02`）。
- サテライト・管轄：同じ画面の別のタブ。

## 10. 現行データの取り込み
- 現行の `branches.json` は、コードが「01〜05」で、`id_part` を持たない。取り込み時に、`branch_code` を K01〜K05、`id_part` を 01〜05 に変換する（作業書 E-06）。
- サテライトと管轄は、現時点でデータがない（空の表から始める）。

## 変更履歴
| 日付 | 版 | 担当 | 変更内容 | 備考 |
|------|----|------|----------|------|
| 2026-10-30 | 1.0 | 全体管理者（14代目） | 新規作成 | 真柴さんの指示（契約拠点、管轄拠点、サテライトの3つ。案件番号は担当者の管轄拠点）。影響範囲：`01_03`、`02_01`、`03_02`、`schema_master.sql`、`schema_employees.sql` |
| 2026-10-30 | 1.1 | 全体管理者（14代目） | 5節：案件番号の拠点を「案件担当者」から「案件の管理担当者」（受託した案件の責任者）の管轄拠点に変更。請求書の発行拠点と同じ人で決まると明記。現場の調査員（主担当・副担当）の拠点は使わない | 真柴さんの指示。影響範囲：`04_01_02` 4.3節、`04_01_04` 4.6節、`04_01_01` 3節 |
| 2026-10-31 | 1.2 | 全体管理者（14代目） | 5節：案件番号の拠点を、新規案件入力の最初に選ぶ「案件管理拠点」で決めるルールに変更（管理担当者の管轄から導く方式をやめた）。請求書などの書類番号も、案件の管理拠点を使う。管理担当者の選択肢は管理拠点の人に絞る | 真柴さんの指示。影響範囲：`04_01_02`、`04_01_04`、`04_01_01`、`schema_cases.sql` |
| 2026-10-31 | 1.3 | 全体管理者（14代目） | 5節：案件の管理拠点を途中で変えられるようにした。案件番号は変えない。見積書・請求書などの書類番号は、発行時点の現在の管理拠点で付ける（v1.2の「案件に保存した拠点」から変更）。変更の履歴を残す | 真柴さんの指示。影響範囲：`04_01_02`、`04_01_04`、書類番号を付ける処理（見積書・請求書） |
| 2026-10-31 | 1.4 | 全体管理者（14代目） | 3.1節：`is_headquarters`（本社）を追加 | 真柴さんの指示（本社以外の事務職・経理職は自拠点だけ。`04_01_08` v2.0） |