# 00_04_notification_system.md
# 通知システム 設計書

**保存先**: `public_html/docs/00_overview/00_04_notification_system.md`
**対象**: 全従事者・全管理者

---

## 1. 概要
本システムは、全従事者（役職・権限不問）に対してトップページで通知を配信する。
申請・報告・受電連絡などの「言った言わない」を防ぐため、通知の閲覧・確認・返信のログをすべて記録する。
また、確認漏れを防ぐため、アクション完了までは通知が消えない仕様とする。

## 2. 通知ランク（優先度）と宛先定義

### 2.1 通知ランク（優先度）
| ランク | 名称 | 色 | バッジ | 用途・例 |
|--------|------|----|--------|---------|
| Rank 1 | 緊急 (Urgent) | 赤 | 点滅/赤丸 | 事務からの受電連絡、至急確認申請、障害発生、全体緊急通知 |
| Rank 2 | 通常 (Normal) | 黄 | 黄丸 | 日報の確認依頼、経費承認依頼、業務報告 |
| Rank 3 | 低 (Low) | 青 | 青丸 | システムメンテナンス通知、一般的なお知らせ |

### 2.2 宛先区分（To / CC / 代理承認）
通知は「誰宛て」かを明確にするため、以下の3つの宛先区分を持つ。

| 区分 | 名称 | 役割 | アクション |
|------|------|------|-----------|
| `to` | 主承認者 (To) | 報告の承認、または確認を行う責任者。 | 承認/確認・返信・差し戻し |
| `cc` | 確認者 (CC) | 承認権限はないが、内容を確認・把握する必要がある人（閲覧のみ）。 | 閲覧、任意でコメント |
| `delegate` | 代理承認者 | 主承認者が不在（急を要する場合等）の際に、主承認者の代わりに承認できる人。 | 代理での承認・確認 |

- **承認のルール**：`to` または `delegate` のいずれか1人が承認アクションを行えば、その通知は `processed`（処理済み）となる。
- **全体通知（ブロードキャスト）**：宛先を指定せず、全従事者に配信する通知。

## 3. 通知データ構造とステータス
`/data/notifications/[ユーザーID].json` に各ユーザー宛ての通知を保存する。

### 3.1 ステータス遷移（消えない通知）
1. **`unread`（未読）**: 通知発行直後の状態。
2. **`read`（既読/確認中）**: 通知一覧を開く、または対象リンクをクリックした状態。**この状態では通知は消えず、リストに残り続ける。**
3. **`processed`（処理済み）**: 承認者（`to` または `delegate`）が対象のアクション（確認ボタン、返信ボタン等）を完了した状態。**この状態になった時点で通知リストから非表示（アーカイブ）となる。**

### 3.2 通知JSONスキーマ
```json
{
  "notifications": [
    {
      "notification_id": "N-001",
      "rank": 2,
      "type": "business_report",
      "title": "【業務報告】○○損保 定期訪問報告",
      "message": "真柴 直也 が報告書を提出しました。",
      "link_url": "/private/business/work_report.html?id=WR-001",
      "created_at": "2026-10-24T10:00:00+09:00",
      "recipient_role": "to", 
      "status": "read",
      "read_at": "2026-10-24T10:05:00+09:00",
      "processed_at": null,
      "log_history": [
        { "action": "issued", "at": "2026-10-24T10:00:00+09:00" },
        { "action": "read", "at": "2026-10-24T10:05:00+09:00" }
      ]
    }
  ]
}
```
- `recipient_role` にはそのユーザーが `to`（主承認者）、`cc`（確認者）、`delegate`（代理承認者）、`broadcast`（全体通知）のどれで受信したかを記録する。

## 4. UI仕様（スマホ対応）
### 4.1 ヘッダー（PC・スマホ共通）
- 画面右上に「🔔 通知」アイコンを固定表示。
- 未読（`unread`）または確認中（`read`）の通知がある場合、アイコンにバッジ（Rank 1は赤、Rank 2は黄、Rank 3は青）を表示。
- スマホの場合、指で押しやすいようにアイコンのタップ領域を `44px × 44px` 以上確保する。

### 4.2 通知一覧の表示（スマホ対応）
- **PCの場合**: アイコンクリックでドロップダウン表示（幅400px程度）。
- **スマホの場合（画面幅768px以下）**: ドロップダウンではなく、**画面全体（または下部からスライドアップするモーダル）**で通知一覧を表示する。タップ領域を広く取り、誤タップを防ぐ。
- 一覧には「未読・確認中」の通知のみを表示し、`processed`（処理済み）の通知は「履歴を見る」等の別タブに移動する。

### 4.3 ログ記録（監査用）
`/data/logs/notification_log.json` に、全通知の `issued`（発行）, `read`（閲覧）, `processed`（処理完了）のタイムスタンプと操作ユーザー、宛先区分を記録する。

## 5. 通知・承認ルールの管理（管理画面）

### 5.1 宛先の自動決定
報告書や申請の宛先（To/CC/代理承認者）は、報告者が提出時に選択するのではなく、**事前にシステムに登録された「通知ルール」に基づいて自動決定される**。
報告者は所属部署や報告種別に応じて、システムが適切な承認者を割り当てる。

### 5.2 マスタデータ構造（`data/notification_rules.json`）
```json
{
  "rules": [
    {
      "rule_id": "R-001",
      "target_type": "work_report",
      "condition": { "department": "D01" },
      "to_roles": ["P006"],
      "cc_roles": ["P008"],
      "delegate_roles": ["P005"]
    }
  ]
}
```
- `target_type`: 報告種別（`daily_report`, `work_report`, `expense` 等）
- `condition`: 適用条件（部署、拠点、または `ALL`）
- `to_roles` / `cc_roles` / `delegate_roles`: 職務コード（`positions.json`）で指定。該当する職務を持つユーザー全員に通知が飛ぶ。

### 5.3 管理画面（`master/notification_rule_edit.html`）
- 管理者（`permission_assign` 保持者）のみアクセス可能。
- ルールの一覧表示、新規追加、編集、無効化（論理削除）が可能。
- 保存API：`POST /master/api/save_notification_rule.php`

### 5.4 全体通知（ブロードキャスト）
- 特定の宛先を指定せず、全従事者に通知を配信する機能。
- 管理画面から「全員へ通知」を選択して実行。
- 主にRank 1（緊急）のシステム障害や、全社的なお知らせに使用する。

## 6. API仕様

### 6.1 通知一覧取得API（GET /master/api/notification/get_notifications.php）
- リクエスト：なし（セッションから `userId` を特定）
- レスポンス例：
```json
{
  "success": true,
  "notifications": [
    {
      "notification_id": "N-001",
      "rank": 1,
      "type": "case_contact",
      "title": "【受電連絡】○○様より",
      "message": "進捗確認の連絡がありました。",
      "link_url": "/private/cases/view.html?case_id=...",
      "created_at": "2026-10-24T10:00:00+09:00",
      "recipient_role": "to",
      "status": "read"
    }
  ]
}
```

### 6.2 通知既読API（POST /master/api/notification/read_notification.php）
- リクエスト：`{"notification_id": "N-001"}`
- レスポンス：`{"success": true}`

### 6.3 通知処理済みAPI（POST /master/api/notification/process_notification.php）
- リクエスト：`{"notification_id": "N-001", "action": "confirmed"}`
- レスポンス：`{"success": true}`

## 7. 改訂履歴
| 日付 | 版 | 担当 | 内容 | 理由・影響範囲 |
|------|----|------|------|--------------|
| 2026-10-24 | 1.0 | 全体管理者（12代目） | 初版作成。トップページ通知、ランク定義、To/CC/代理承認、処理済みステータス、スマホUI、宛先の自動決定ルール、管理画面、監査ログ、全体通知、API詳細の全仕様を網羅。 | 全員必須の通知システムの基盤設計のため。 |