# 00_10 変更履歴仕様書

| 項目 | 内容 |
|---|---|
| 版 | v1.1（v1.0 は真柴さん承認 2026-10-29。v1.1 は書き直し。承認待ち） |
| 作成 | 全体管理者 14代目（2026-10-29） |
| 対象 | 拠点・従事者・得意先・担当者など、マスタ系データの「変更履歴」と、その確認（Wチェック） |
| 実装の状況 | `work_order_db_migration.md`（作業書）を見る。テーブルの作成SQLは `schema_history.sql` |
| 保存先 | 00_07 と同じ扱い（DBの構造を含むため、公開してよい範囲は承認時に決める） |

---

## 1. 目的

- 「いつ、何が、何から何へ変わったか」を、あとから、画面の「履歴」ボタンで見られるようにする。
- 誤字などの訂正は、長く残さない。実際の変更だけを、ずっと残す。
- 「訂正か、変更か」は、修正した本人に決めさせない。別の権限者が確認して決める（Wチェック）。

## 2. 用語

| 用語 | 意味 |
|---|---|
| 訂正 | 誤字・入力ミスの直し。実際には何も変わっていないもの |
| 変更 | 実際に変わったこと（移転、名称変更、異動、昇進、契約変更、改姓、賞罰 など） |
| 有効日 | 変更が実際に効力を持つ日（例：移転日）。保存した日とは別 |
| 確認 | 修正した本人とは別の権限者が、記録を見て「変更」か「訂正」かを決めること |

## 3. 基本方針

1. **どのデータにも共通の仕組み**にする。データごとの別仕組みは作らない（拠点、従事者、得意先、担当者、権限、…）。
2. 保存の処理が、書き換わった項目を自動で検出し、履歴に記録する。**画面で、人に「訂正か変更か」を選ばせない。**
3. 記録は**追記のみ**。記録そのものは、書き換え・削除できない（短期保管の期限が来た「訂正」を、システムが消す場合を除く。6節）。
4. 余計に残るほうに倒す。迷うものは、残す。
5. パスワードの値は、履歴に書かない（00_03 §11.9、00_08 と同じ）。

## 4. 項目の区分

項目ごとに、区分をあらかじめ決める。一覧は、各画面の仕様書（05_xx、03_02 など）に、項目表として書き、承認を受ける。

| 区分 | 扱い | 例（案。確定は各画面の仕様書） |
|---|---|---|
| A 変更として記録 | 保存の時点で反映する。履歴に「未確認」で記録する。確認者が決める | 拠点の名称・住所・電話、従事者の拠点・部署・稼働状況、得意先担当者の異動・肩書き。従事者の職務（昇進・降格）は、4.1節の出来事として記録する |
| B 承認後に反映 | 確認者が承認するまで、現在の値を変えない（承認待ちとして保留） | **従事者の契約、賞罰、氏名、所属会社、権限**（2026-10-29 真柴さん決定） |
| C 訂正扱い | 履歴には残さない。短期の記録（編集ログ）だけに残す | 備考、メモ、フリガナ、写真 など |

- B は、影響の大きい項目に限る。多くなりすぎると、業務が止まるため。今の範囲は上のとおり。増やす・減らすときは、真柴さんが決める。
- 氏名のように、誤字の直しと、改姓・改名の両方が起こる項目は、保存時に「改姓・改名」のチェックを1つ付ける。チェックが無ければ、区分 C（訂正扱い）の編集ログに記録する。

### 4.1 出来事として記録するもの（2026-10-29 真柴さん決定）

- **賞罰、昇進・降格（職務の変更）** は、項目の値の変更ではなく、「出来事」として1件ずつ登録する（`employee_events`。7.3節）。
- 出来事は、日付（いつ）、種類（賞／罰／昇進／降格）、題名、内容を持つ。後から、従事者の履歴として、時系列で一覧できる。
- 賞罰は区分 B（確認者の承認が済むまで、出来事として確定しない）。昇進・降格は区分 A（登録と同時に、従事者の職務CDが変わる。履歴に「未確認」で残る）。昇進・降格で職務CDを変えられるのは、この出来事の登録だけにする（編集画面で職務CDだけを直接書き換えない）。
- 探偵業法の罰則に関する採用時の申告（`employees` の `detective_penalty`、`penalty_detail`）は、採用時の確認事項であり、出来事とは別。そのまま従事者の項目として持つ。

## 5. 確認（Wチェック）

### 5.1 流れ

1. 修正者が保存する。区分 A は、すぐ反映され、履歴に「未確認」で記録される。区分 B は、「承認待ち」になる。
2. 修正者とは**別の**確認権限者が、履歴の一覧で内容を見て、次のどちらかに決める。
   - **変更**：確認済み。履歴に、ずっと残る。B の場合は、このとき反映される。
   - **訂正**：入力ミスの直しと判断。通常の履歴の一覧からは外れる。短期保管のあと、消える（6節）。B の場合は、反映される。
   - **却下**（B のみ）：反映しない。元の値のまま。理由を残す。
3. 確認者が決められるのは、「変更」か「訂正」か「却下」かだけ。記録の内容は、確認者も変えられない。

### 5.2 ルール

| ルール | 内容 |
|---|---|
| 自己確認の禁止 | 自分が修正した記録は、自分で確認できない |
| 全権者の単独許可 | `supreme_access` を持つ人（真柴さん）は、自分の修正を、保存時に自分で「変更」か「訂正」かを決められる。その記録には「単独許可」と明記する |
| 未確認の放置 | 未確認の件数を、メニューに表示する（通知待ち一覧と同じ作り）。期限は**3日**（真柴さん指示「数日」。仮置き。運用して調整する）。期限を過ぎたものは、確認権限者全員に通知する。期限の経過で、自動で「確認済み」にはしない |
| 緊急時 | 全権者は、承認待ち（B）を、理由つきで決められる。記録に残る |

## 6. 保管期間

| 記録 | 期間 |
|---|---|
| 変更（確認済み） | 無期限 |
| 未確認・承認待ち | 確認されるまで（自動では消さない） |
| 訂正（確認者が「訂正」と決めたもの） | 90日（真柴さん承認）。そのあと、システムが消す |
| 編集ログ（区分 C） | 90日（同上） |
| 却下 | 無期限（理由つき） |

期間の変更は、真柴さんが決める。

## 7. データの持ち方（実行前に承認を受ける。作成SQLは `schema_history.sql`）

### 7.1 変更履歴（`change_history`）

| 列 | 内容 |
|---|---|
| id | 連番（主キー） |
| target_type | 対象の種類（branch、employee、client、client_contact、…） |
| target_id | 対象のID（K02、SPS01-99999、C001 など） |
| field_key | 項目名（address、position_cd など） |
| field_label | 画面に出す項目名（拠点の住所 など） |
| old_value / new_value | 変更前・変更後（文字列。複数の項目が入る塊は JSON） |
| effective_date | 有効日（空なら、保存日） |
| reason | 理由（任意。短い文） |
| recorded_by / recorded_at | 修正した人 / 保存した日時 |
| status | `unconfirmed`（未確認）、`pending`（承認待ち。B）、`change`（変更）、`correction`（訂正）、`rejected`（却下） |
| reviewed_by / reviewed_at / review_note | 確認した人 / 日時 / 確認時の一言 |
| solo | 単独許可（全権者の自己確認）なら 1 |
| batch_id | 同じ保存でまとめて変わった行の束ね用 |

- 保存1回で複数の項目が変わったら、項目ごとに1行にする。同じ保存は、同じ `batch_id` で束ねる。

### 7.2 編集ログ（`edit_logs`）

- 区分 C の編集と、確認で「訂正」になった記録の、短期保管用。誰が、いつ、どの項目を、何から何へ。保管期限を過ぎたものは、定期処理で消す。

### 7.3 出来事（`employee_events`）

| 列 | 内容 |
|---|---|
| id | 連番（主キー） |
| sps_id | 対象の従事者 |
| event_type | `award`（賞）、`penalty`（罰）、`promotion`（昇進）、`demotion`（降格） |
| event_date | 出来事の日付（いつ） |
| title | 題名（短く） |
| detail | 内容 |
| old_position_cd / new_position_cd | 昇進・降格のとき、変更前・後の職務ポジションCD（会社ごと） |
| recorded_by / recorded_at | 登録した人 / 日時 |
| status | `unconfirmed`、`pending`（賞罰。確認前）、`change`、`correction`、`rejected`（`change_history` と同じ意味） |
| reviewed_by / reviewed_at / review_note / solo | `change_history` と同じ |

- 確認の流れ・ルールは、5節と同じ。
- 昇進・降格は、`employees.position_cd` の変更も同時に行い、`change_history` にも記録する（出来事の `id` を `batch_id` の代わりに参照する）。

### 7.4 「ある日付の時点で、どうだったか」

- 初版は、変更履歴（`change_history`）から、その日付までの変更を順に適用して、復元する。
- 拠点の住所のように、書類に「当時の値」を出す必要が出た項目だけ、後で、期間つき（有効開始・有効終了）の表を足す。今は作らない。

## 8. 画面

| 画面 | 内容 |
|---|---|
| 各編集画面の「履歴」ボタン | 押すと、その対象の履歴（確認済みの変更）が、日付順に出る。項目名、有効日、変更前→後、理由、記録した人、確認した人 |
| 保存時の入力 | 区分 A の項目が変わっているときだけ、保存の直前に、「有効日（任意）」と「理由（任意）」を聞く。空欄でも保存できる |
| 履歴の確認画面 | 未確認・承認待ちの一覧。内容を見て、「変更」「訂正」「却下」を決める。自分が修正したものは、操作できない |
| 出来事の登録 | 従事者の詳細画面に、「賞罰を登録」「昇進・降格を登録」のボタンと、出来事の一覧(時系列)を置く。権限は、その従事者を編集できる権限に従う |
| 入口 | 人事メニュー（`employees/menu.html`）の「変更履歴の確認」ボックス（`change_history_review`）。ボックスに未確認・承認待ちの件数を表示する（05_01 v1.3） |

- 「履歴」ボタンで見えるのは、その対象を閲覧できる人のうち、履歴の閲覧権限を持つ人だけ。

## 9. 権限（権限マスタ `permissions` に登録済み）

| 権限 | 内容 |
|---|---|
| `change_history_view` | 履歴を見る。範囲は、対象のデータの閲覧権限の範囲に従う |
| `change_history_view_sensitive` | 氏名・賞罰・権限など、機密性の高い項目の履歴を見る |
| `change_history_review` | 未確認・承認待ちを、確認する（変更／訂正／却下） |

権限の詳細は `06_01_permission_design.md` 2.13節。

## 10. 関連する仕様書

- `00_07_database.md`：テーブル（`change_history`、`edit_logs`、`employee_events`）。`audit_logs`＝権限変更・停止・書類発行など、操作の記録。`change_history`＝マスタ項目の値の変更の記録。
- `00_03_login_session.md` 6.5節：アカウントの停止・解除の2名承認。本書の確認と、考え方は同じ。
- `05_01_menu.md`、`05_03_employee_edit.md`、`05_09_admin_menu.md`、`03_02_master_management.md`：項目の区分、「履歴」ボタン、保存時の入力。
- `03_04_screen_map.md`：履歴の確認画面。人事メニューの「人事異動履歴」（`employees/transfer_history.html`）は、`change_history` と `employee_events` を時系列で見る閲覧専用の画面（別の記録は持たない。`05_08_transfer_history.md`）。
- `01_folder_structure.md`：画面・APIの置き場。

## 11. 未決事項

1. 未確認の通知の方法（メニューの件数表示のほか、確認権限者への通知）。
2. 履歴の確認画面・API の置き場（案：画面 `master/history_review.html`、API `master/api/`。ツリーで確定）。
3. 得意先の担当者の配置換えを、「得意先側の担当者」の変更として記録するか、「担当の割り当て」の記録として持つか（得意先の仕様書で決める）。

## 12. 決定事項（2026-10-29 真柴さん）

- 区分 B：契約、賞罰、氏名、所属会社、権限。
- 訂正・編集ログの保管：90日。
- 未確認の期限：数日（仮に3日）。
- 賞罰、昇進・降格は、出来事として1件ずつ持つ。
- 本仕様書を承認。

## 改訂履歴

| 日付 | 版 | 担当 | 内容 |
|---|---|---|---|
| 2026-10-29 | v1.1 | 全体管理者14代目 | DB前提の書き直し。状態欄を「実装の状況は作業書」に。9節を登録済みの権限として整理、10節を「関連する仕様書」に、11節から解決済みの項目を削除 |
| 2026-10-29 | v1.0 | 全体管理者14代目 | 真柴さん承認。B範囲・保管期間・未確認の期限を確定。4.1節（出来事）、7.3節（`employee_events`）を追加。例のIDをテスト用に差し替え |
| 2026-10-29 | v0.1 | 全体管理者14代目 | 新規作成（ドラフト） |
| 2026-10-30 | - | 全体管理者（14代目） | `employee_events` の説明を「職務ポジションCD（会社ごと）」に（`02_01` v2.1） |