459 lines
14 KiB
Markdown
459 lines
14 KiB
Markdown
# マスタードキュメント - 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 | 初版作成。フロー登録・スケジュール設定・状態管理バグ修正を含む |
|