From 76db14cf1013f5fd0569fd791979ab4526841e28 Mon Sep 17 00:00:00 2001
From: Akira <akia@keinafarm.com>
Date: Sat, 21 Feb 2026 16:14:07 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20Windmill=E9=80=9A=E7=9F=A5=E3=83=AF?=
 =?UTF-8?q?=E3=83=BC=E3=82=AF=E3=83=95=E3=83=AD=E3=83=BC=20=E3=83=9E?=
 =?UTF-8?q?=E3=82=B9=E3=82=BF=E3=83=BC=E3=83=89=E3=82=AD=E3=83=A5=E3=83=A1?=
 =?UTF-8?q?=E3=83=B3=E3=83=88=E8=BF=BD=E5=8A=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 ...¿ãƒ¼ãƒ‰ã‚­ãƒ¥ãƒ¡ãƒ³ãƒˆ_Windmill通知ワークフロー編.md | 458 ++++++++++++++++++
 1 file changed, 458 insertions(+)
 create mode 100644 docs/shiraou/20_マスタードキュメント_Windmill通知ワークフロー編.md

diff --git a/docs/shiraou/20_マスタードキュメント_Windmill通知ワークフロー編.md b/docs/shiraou/20_マスタードキュメント_Windmill通知ワークフロー編.md
new file mode 100644
index 0000000..5ece1e3
--- /dev/null
+++ b/docs/shiraou/20_マスタードキュメント_Windmill通知ワークフロー編.md
@@ -0,0 +1,458 @@
+# マスタードキュメント - Windmill通知ワークフロー編
+
+> **最終更新**: 2026-02-21
+> **対象システム**: windmill.keinafarm.net（ワークスペース: admins）
+> **目的**: ��ドキュメント���Windmill通知ワークフロー�全容を把���る��
+
+---
+
+## 目次
+
+1. [機能概�](#1-機能概�)
+2. [フロー設計](#2-フロー設計)
+3. [変更履歴�得API仕様](#3-変更履歴�得api仕様)
+4. [LINE通知仕様](#4-line通知仕様)
+5. [Windmill設定仕様](#5-windmill設定仕様)
+6. [状態管�仕様](#6-状態管�仕様)
+7. [設計判断�制約](#7-設計判断�制約)
+8. [�用手順](#8-�用手順)
+9. [ソースファイル索引](#9-ソースファイル索引)
+10. [更新履歴](#更新履歴)
+
+---
+
+## 1. 機能概�
+
+### 目的
+
+`shiraou.keinafarm.net`（白皇集�営農組� 統�システム）�発生��予約・実績�変更を�LINE Messaging API 経由�管�者�通知�る。
+
+### ユーザーフロー
+
+```
+統�システム上�予約・実績�変更�発生
+  └→ Windmill �5分毎��ーリング
+        └→ 変更��れ�LINE�プッシュ通知
+              └→ 管�者�LINE�変更内容を確�
+```
+
+### 通知�れる�作一覧
+
+| 区分 | �作 | 説明 |
+|------|------|------|
+| 予約 | `create` | 予約�作��れ� |
+| 予約 | `update` | 予約�日時・機械�変更�れ� |
+| 予約 | `cancel` | 予約�キャンセル�れ� |
+| 実績 | `create` | 実績�登録�れ� |
+| 実績 | `update` | 実績�修正�れ� |
+| 実績 | `delete` | 実績�削除�れ� |
+
+---
+
+## 2. フロー設計
+
+### Windmillフロー情報
+
+| 項目 | 値 |
+|------|-----|
+| パス | `f/shiraou/shiraou_notification` |
+| 概� | 白皇集�営農 変更通知 |
+| ステップ数 | 1（�一Pythonスクリプト） |
+| スケジュール | `0 */5 * * * *`（5分毎�JST） |
+| スケジュールパス | `f/shiraou/shiraou_notification_every_5min` |
+
+### 実行フロー（擬似コード）
+
+```python
+# Step 1: シークレット・�回実行時刻を�得
+api_key        = get_variable("u/admin/NOTIFICATION_API_KEY")
+line_token     = get_variable("u/admin/LINE_CHANNEL_ACCESS_TOKEN")
+line_to        = get_variable("u/admin/LINE_TO")
+last_checked   = get_variable("u/admin/SHIRAOU_LAST_CHECKED_AT")  # 空�ら�回
+
+since = last_checked or (now() - 10分)
+
+# Step 2: 変更履歴を�得
+response = GET "https://shiraou.keinafarm.net/reservations/api/changes/?since={since}"
+  headers: { "X-API-Key": api_key }
+
+# Step 3: 変更��れ�LINE通知
+if response.reservations or response.usages:
+    message = format_message(response)
+    POST "https://api.line.me/v2/bot/message/push"
+      body: { "to": line_to, "messages": [{"type": "text", "text": message}] }
+
+# Step 4: �回実行時刻を更新（正常完了時��）
+set_variable("u/admin/SHIRAOU_LAST_CHECKED_AT", response.checked_at)
+```
+
+### エラー時�挙動
+
+- API呼�出�失敗�LINE�信失敗���れ�も例外�発生
+- 例外�発生��場��`SHIRAOU_LAST_CHECKED_AT` �更新�れ��
+- 次回実行時��� `since` ��試行�れる（変更��り�れ防止）
+
+---
+
+## 3. 変更履歴�得API仕様
+
+### エンド�イント
+
+```
+GET https://shiraou.keinafarm.net/reservations/api/changes/
+```
+
+### �証
+
+```
+X-API-Key: <NOTIFICATION_API_KEY>
+```
+
+APIキー��正�場�� `401 Unauthorized` �返る。
+
+### クエリパラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `since` | ISO8601文字列 | 必須 | ��日時以��変更を�得�る |
+
+**`since` �形�例**:
+- `2026-02-21T10:00:00+09:00`（タイムゾーン付��推奨）
+- `2026-02-21T10:00:00`（ナイーブ�JST���扱�れる）
+
+### レス�ンス（200 OK）
+
+```json
+{
+  "checked_at": "2026-02-21T12:00:00+09:00",
+  "since": "2026-02-21T10:00:00+09:00",
+  "reservations": [
+    {
+      "operation": "create",
+      "reservation_id": 123,
+      "user_name": "田中太郎",
+      "machine_name": "トラクター",
+      "start_at": "2026-02-25T09:00:00+09:00",
+      "end_at": "2026-02-25T12:00:00+09:00",
+      "operated_at": "2026-02-21T11:30:00+09:00",
+      "operator_name": "田中太郎",
+      "reason": ""
+    }
+  ],
+  "usages": [
+    {
+      "operation": "update",
+      "usage_id": 456,
+      "user_name": "山田次郎",
+      "machine_name": "コン�イン",
+      "amount": 4.0,
+      "unit": "時間",
+      "start_at": "2026-02-20T08:00:00+09:00",
+      "end_at": "2026-02-20T12:00:00+09:00",
+      "operated_at": "2026-02-21T11:55:00+09:00",
+      "operator_name": "管�者A",
+      "reason": "記録ミス���修正"
+    }
+  ]
+}
+```
+
+### 変更��時�レス�ンス
+
+```json
+{
+  "checked_at": "2026-02-21T12:05:00+09:00",
+  "since": "2026-02-21T12:00:00+09:00",
+  "reservations": [],
+  "usages": []
+}
+```
+
+### エラーレス�ンス
+
+| ステータス | 原因 |
+|-----------|------|
+| `401 Unauthorized` | APIキー��正���未設定 |
+| `400 Bad Request` | `since` パラメータ�欠�����正�日時形� |
+
+---
+
+## 4. LINE通知仕様
+
+### 使用API
+
+LINE Messaging API - Push Message
+
+```
+POST https://api.line.me/v2/bot/message/push
+Authorization: Bearer <LINE_CHANNEL_ACCESS_TOKEN>
+Content-Type: application/json
+```
+
+### リクエストボディ
+
+```json
+{
+  "to": "<LINE_TO>",
+  "messages": [
+    {
+      "type": "text",
+      "text": "<フォーマット済�メッセージ>"
+    }
+  ]
+}
+```
+
+### メッセージフォーマット
+
+```
+📋 営農システム 変更通知
+
+🟢 予約作�
+  機械: トラクター
+  利用者: 田中太郎
+  日時: 2026-02-25 09:00 〜 2026-02-25 12:00
+
+🔴 予約キャンセル
+  機械: 田�機
+  利用者: �藤花�
+  日時: 2026-02-22 08:00 〜 2026-02-22 17:00
+
+🔵 実績修正
+  機械: コン�イン
+  利用者: 山田次郎
+  利用�: 4.0時間
+  æ—¥: 2026-02-20
+  �由: 記録ミス���修正
+```
+
+### アイコン�則
+
+| アイコン | �味 |
+|---------|------|
+| 🟢 | 作�（create / 予約作� / 実績登録） |
+| 🔵 | 変更（update / 予約変更 / 実績修正） |
+| 🔴 | 削除・キャンセル（cancel / delete） |
+
+### 通知先�種別
+
+`LINE_TO` ��ユーザーID���グループIDを設定�る。
+
+| 種別 | ID形� |
+|------|-------|
+| ユーザー | `U` �始�る文字列 |
+| グループ | `C` �始�る文字列 |
+
+---
+
+## 5. Windmill設定仕様
+
+### Windmill Variables（シークレット）
+
+以下�変数を Windmill UI（Variables ページ）�作�・管��る。
+
+| 変数パス | Secret | 説明 | �得元 |
+|---------|--------|------|-------|
+| `u/admin/NOTIFICATION_API_KEY` | ✅ | shiraou.keinafarm.net �APIキー | Djangoサー�ー� `NOTIFICATION_API_KEY` 環境変数��一値 |
+| `u/admin/LINE_CHANNEL_ACCESS_TOKEN` | ✅ | LINE Messaging API �ャ�ルアクセストークン | LINE Developers Console |
+| `u/admin/LINE_TO` | ✅ | 通知先�LINEユーザーID���グループID | LINE webhook / profile API |
+| `u/admin/SHIRAOU_LAST_CHECKED_AT` | � | �回確�時刻（ワークフロー�自動更新） | ワークフロー�自動管�（�期値: 空文字） |
+
+### Django��設定（shiraou.keinafarm.net）
+
+`docker-compose.yml` �以下�環境変数を追加:
+
+```yaml
+environment:
+  - NOTIFICATION_API_KEY=<NOTIFICATION_API_KEY��一�値>
+```
+
+APIキー生�コマンド:
+```bash
+openssl rand -hex 32
+```
+
+---
+
+## 6. 状態管�仕様
+
+### 状態変数: `SHIRAOU_LAST_CHECKED_AT`
+
+| 項目 | 内容 |
+|------|------|
+| 格�場所 | Windmill Variable `u/admin/SHIRAOU_LAST_CHECKED_AT` |
+| 型 | ISO8601文字列（例: `2026-02-21T15:30:00+09:00`） |
+| �期値 | 空文字（�回実行時� `�在時刻 - 10分` を使用） |
+| 更新タイミング | フロー正常完了時���APIレス�ンス� `checked_at` を�存 |
+| �照タイミング | フロー実行開始時�`since` パラメータ���使用 |
+
+### �複通知防止�仕組�
+
+```
+実行1: since=T0, checked_at=T1 → LAST_CHECKED_AT = T1
+実行2: since=T1, checked_at=T2 → T1以��変更���得
+```
+
+- `since` � `checked_at`（API�確���時刻）を使�����変更��り����発生���
+- `since`（リクエスト�渡��時刻）���� `checked_at`（サー�ー�確���時刻）を�存�る���イント
+
+### 旧実装����（トラブルシュート記録）
+
+| | 旧実装 | �実装 |
+|---|--------|--------|
+| 状態�存方法 | `wmill.get_state()` / `set_state()` | `wmill.get_variable()` / `set_variable()` |
+| �題 | フロー�インラインスクリプト��実行を�����存�れ�� | - |
+| 症状 | 毎回 `since = �在 - 10分` ��り�毎回通知�飛� | 正常動作 |
+
+---
+
+## 7. 設計判断�制約
+
+### 絶対�変�������制約
+
+1. **`SHIRAOU_LAST_CHECKED_AT` �� `checked_at` を�存�る��**（`since` を�存���）
+   - `checked_at`: APIサー�ー�「��時刻��確��������証付��時刻
+   - ��変更�2度通知�れる��を防�
+
+2. **状態更新�正常完了後��行���**
+   - API呼�出�失敗・LINE�信失敗時� `SHIRAOU_LAST_CHECKED_AT` を更新���
+   - 次回実行���範囲を��得��通知��り�れを防�
+
+3. **`wmill.get_state()` �使用�����**
+   - Windmill�インラインフロースクリプト��実行を�����存�れ��
+   - 状態管��必� Windmill Variable を使���
+
+### 設計判断
+
+| 判断 | �由 |
+|------|------|
+| �一ステップフロー | 状態管�を1�所�集約�る��。`get_state()`/`set_state()` �スコープ�題を回� |
+| SSL検証スキップ | shiraou.keinafarm.net �自己署�証明書��能性��る�� |
+| タイムアウト 30秒 | 農業用途�多少�応答�延を許容����無�待機を防� |
+| 5分�ーリング間隔 | 農業機械�予約用途��数分��延�許容範囲。リアルタイム�� |
+
+---
+
+## 8. �用手順
+
+### フローを手動実行
+
+```bash
+curl -sk -X POST \
+  -H "Authorization: Bearer qLJ3VPZ61kTDiIwaUPUu1dXszGrsN1Dh" \
+  -H "Content-Type: application/json" \
+  -d '{}' \
+  "https://windmill.keinafarm.net/api/w/admins/jobs/run/f/f/shiraou/shiraou_notification"
+```
+
+### 動作確�（curl�直接API呼�出�）
+
+```bash
+# 変更��確�
+curl -H "X-API-Key: <キー>" \
+  "https://shiraou.keinafarm.net/reservations/api/changes/?since=2026-02-21T11:59:00%2B09:00"
+
+# 広�範囲�変更�得（�期確�用）
+curl -H "X-API-Key: <キー>" \
+  "https://shiraou.keinafarm.net/reservations/api/changes/?since=2026-01-01T00:00:00"
+```
+
+### フロー�更新デプロイ手順
+
+```bash
+cd /path/to/windmill_workflow
+
+# 1. flows/shiraou_notification.flow.json を編集
+
+# 2. 既存フローを削除���作�（PUT�405���）
+curl -sk -X DELETE \
+  -H "Authorization: Bearer qLJ3VPZ61kTDiIwaUPUu1dXszGrsN1Dh" \
+  "https://windmill.keinafarm.net/api/w/admins/flows/delete/f/shiraou/shiraou_notification"
+
+curl -sk -X POST \
+  -H "Authorization: Bearer qLJ3VPZ61kTDiIwaUPUu1dXszGrsN1Dh" \
+  -H "Content-Type: application/json" \
+  -d @flows/shiraou_notification.flow.json \
+  "https://windmill.keinafarm.net/api/w/admins/flows/create"
+
+# 3. スケジュール��作���（フロー�削除・�作��も維��れる）
+```
+
+### APIキーローテーション手順
+
+1. Djangoサー�ー��新��キーを生�: `openssl rand -hex 32`
+2. `docker-compose.yml` � `NOTIFICATION_API_KEY` を更新��デプロイ
+3. Windmill UI � `u/admin/NOTIFICATION_API_KEY` �値を��新��キー�更新
+4. フローを手動実行��動作確�
+
+### �去�ジョブ�果確�
+
+```bash
+curl -sk -H "Authorization: Bearer qLJ3VPZ61kTDiIwaUPUu1dXszGrsN1Dh" \
+  "https://windmill.keinafarm.net/api/w/admins/jobs/list?per_page=10&script_path_exact=f/shiraou/shiraou_notification&is_flow=true"
+```
+
+---
+
+## 9. ソースファイル索引
+
+### フロー定義
+
+| ファイル | 説明 |
+|---------|------|
+| [flows/shiraou_notification.flow.json](../../flows/shiraou_notification.flow.json) | フロー本体。�一Pythonステップ��ーリング・通知・状態更新を実行 |
+
+**フロー構造**:
+```json
+{
+  "path": "f/shiraou/shiraou_notification",
+  "value": {
+    "modules": [
+      {
+        "id": "a",
+        "value": {
+          "type": "rawscript",
+          "language": "python3",
+          "content": "..."
+        }
+      }
+    ]
+  }
+}
+```
+
+### ヘルパースクリプト
+
+| ファイル | 説明 |
+|---------|------|
+| [wm-api.sh](../../wm-api.sh) | Windmill REST API�作ヘルパー。フロー作�・スケジュール管��使用 |
+
+**主�コマンド**:
+```
+create-flow <file>          JSONファイル�らフローを作�
+create-schedule <file>      JSONファイル�らスケジュールを作�
+flows                        フロー一覧�得
+schedules                    スケジュール一覧�得
+```
+
+### ドキュメント
+
+| ファイル | 説明 |
+|---------|------|
+| [docs/shiraou/19_windmill_通知ワークフロー連�仕様.md](19_windmill_通知ワークフロー連�仕様.md) | 仕様書。API仕様・メッセージフォーマット�原典 |
+| [docs/shiraou/20_マスタードキュメント_Windmill通知ワークフロー編.md](20_マスタードキュメント_Windmill通知ワークフロー編.md) | 本ドキュメント |
+
+### エージェントワークフロー
+
+| ファイル | 説明 |
+|---------|------|
+| [.agent/workflows/windmill-push.md](../../.agent/workflows/windmill-push.md) | Windmill��push手順。wmill CLI�制��API代替�経緯を記録 |
+| [.agent/workflows/windmill-new-script.md](../../.agent/workflows/windmill-new-script.md) | 新�スクリプト作�手順 |
+
+---
+
+## 更新履歴
+
+| 日付 | 変更内容 |
+|------|---------|
+| 2026-02-21 | �版作�。フロー登録・スケジュール設定・状態管��グ修正を�む |