From d129777bf1ff9d6c2610388f1cee0dca5a58edf5 Mon Sep 17 00:00:00 2001 From: Akira Date: Tue, 3 Mar 2026 15:49:07 +0900 Subject: [PATCH] =?UTF-8?q?|=202026-03-03=20|=20=E9=81=8B=E7=94=A8?= =?UTF-8?q?=E5=8D=98=E4=BD=8D=E3=82=92=20workflow=20package=EF=BC=88flow?= =?UTF-8?q?=20+=20schedules=EF=BC=89=E3=81=B8=E5=A4=89=E6=9B=B4=E3=81=97?= =?UTF-8?q?=E3=80=81=E5=AE=9F=E8=A3=85=E8=A8=88=E7=94=BB=E3=81=A8Runbook?= =?UTF-8?q?=E3=82=92=E6=9B=B4=E6=96=B0=20|=20|=202026-03-03=20|=20`delete?= =?UTF-8?q?=20->=20create`=20=E3=81=A8=20hash=20=E7=AE=A1=E7=90=86?= =?UTF-8?q?=E3=81=AE=E9=81=8B=E7=94=A8=E3=82=AC=E3=83=BC=E3=83=89=EF=BC=88?= =?UTF-8?q?preflight=20/=20fail=20closed=20/=20post-verify=EF=BC=89?= =?UTF-8?q?=E3=81=8A=E3=82=88=E3=81=B3CRLF=E5=AF=BE=E7=AD=96=E3=82=92?= =?UTF-8?q?=E8=BF=BD=E8=A8=98=20|?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...ドキュメント_Windmillフロー管理_API一本化編.md | 99 ++++++++++++++----- 1 file changed, 77 insertions(+), 22 deletions(-) diff --git a/docs/flow-manage/10_マスタードキュメント_Windmillフロー管理_API一本化編.md b/docs/flow-manage/10_マスタードキュメント_Windmillフロー管理_API一本化編.md index b023fe0..655cb71 100644 --- a/docs/flow-manage/10_マスタードキュメント_Windmillフロー管理_API一本化編.md +++ b/docs/flow-manage/10_マスタードキュメント_Windmillフロー管理_API一本化編.md @@ -42,9 +42,10 @@ 1. ローカルリポジトリは、サーバー側Gitをリモートにしない 2. Windmillの実体変更は **Windmill REST API 経由のみ** 3. 作業開始時にAPIでサーバー状態を取り込み、サーバーが新しければローカルへ同期 -4. ローカル変更はAPIでサーバーへ反映 -5. サーバー側の Git Sync Workflow は定期記録用途として継続 -6. ローカルGitコミットは手動（またはAI）で実施し、監査/履歴用途として扱う +4. **運用単位は「workflow package（flow + schedules）」を基本**とする +5. ローカル変更はAPIでサーバーへ反映 +6. サーバー側の Git Sync Workflow は定期記録用途として継続 +7. ローカルGitコミットは手動（またはAI）で実施し、監査/履歴用途として扱う --- @@ -78,6 +79,13 @@ - ローカルファイルは「編集用ワークツリー + 監査ログ」 - ローカルGitはサーバー同期の必須経路ではない +### 管理単位（重要） + +- 単体オブジェクト運用（scriptだけ、flowだけ）は補助用途 +- 標準運用は **workflow package 単位** とする + - `flow` 本体 + - その `flow path` に紐づく `schedules`（`is_flow=true` かつ `script_path == flow.path`） + ### 既存の主要オブジェクト（例） - script: `u/admin/alexa_speak` @@ -98,11 +106,18 @@ - サーバー `updated_at` / `hash` とローカル管理メタ情報を比較 - サーバーが新しければローカルを更新 -### 対象API +### 対象API（オブジェクト単体） - `GET /api/w/{workspace}/scripts/get/p/{path}` - `GET /api/w/{workspace}/flows/get/{path}` -- `GET /api/w/{workspace}/schedules/get/{path}`（必要時） +- `GET /api/w/{workspace}/schedules/get/{path}` + +### workflow package Pull（標準） + +1. `GET /flows/get/{flow_path}` で flow 本体取得 +2. `GET /schedules/list` で schedule 一覧取得 +3. `script_path == flow_path` の schedule 群を抽出 +4. ローカルへ一括保存（flow + schedules） ## 5.2 Push（ローカル -> サーバー） @@ -132,6 +147,14 @@ 1. `DELETE /flows/delete/{path}` 2. `POST /flows/create` +### schedule反映API（workflow package の一部） + +- workflow package Push時は、対象 flow に紐づく schedule も同時同期する +- 原則: + 1. サーバー現行 schedule（`script_path == flow_path`）一覧取得 + 2. ローカル定義との差分計算（追加・更新・削除） + 3. `DELETE /schedules/delete/{path}` と `POST /schedules/create` で収束 + --- ## 6. 競合時の動作仕様 @@ -148,6 +171,15 @@ - 削除再作成前に最新を必ずPullしてローカル保存 - 競合が疑われる場合は自動実行せず手動確認にフォールバック +- **Preflight必須**: Push直前に `remote_index` の既知hashとサーバー現在hashを比較し、不一致ならPush中断（fail closed） +- Push後は `post-verify`（再取得して期待JSON一致確認）を必須化 + +### schedulePush競合 + +- `schedule.path` 重複や同名上書きに注意 +- workflow package Push時は、対象 flow の schedule 群をまとめて同期し、中途半端な状態を残さない +- 失敗時は flow と schedules の両方を再取得して整合を確認 +- schedule 同期も Preflight/`post-verify` の対象に含める --- @@ -157,7 +189,7 @@ - 本ドキュメント作成 -## Phase 1: API運用コマンド整備（次タスク） +## Phase 1: API運用コマンド整備（完了） `wm-api.sh` へ追加: @@ -168,17 +200,26 @@ 5. `pull-all`（scripts/flowsの一覧取得 + 一括保存） 6. `status-remote`（ローカルとサーバーのhash比較） -## Phase 2: メタ情報管理 +## Phase 2: workflow package 対応（次タスク） -- `state/remote_index.json` を導入し、`path -> hash/updated_at` を保持 -- Pull前後で差分判定可能にする +`wm-api.sh` へ追加: -## Phase 3: 標準化 +1. `pull-workflow `（flow + schedules 一括取得） +2. `push-workflow `（flow反映 + schedules差分同期） +3. `status-workflow [flow_path]`（workflow単位の差分表示） +4. `pull-all-workflows`（flow全件を workflow package で取得） + +## Phase 3: メタ情報管理 + +- `state/remote_index.json` を拡張し、`scripts/flows/schedules` を保持 +- `state/workflow_index.json` を導入し、`workflow -> flow_hash + schedule_hashes` を保持 + +## Phase 4: 標準化 - `docs/flow-manage` に操作例を固定 - 「作業開始時は必ずpull」を運用ルール化 -## Phase 4: 半自動化（任意） +## Phase 5: 半自動化（任意） - AI/スクリプトで - 変更検知 @@ -193,14 +234,16 @@ 1. `pull-all` でサーバー最新を取得 2. ローカル編集 -3. `push-script` / `push-flow` で反映 -4. 必要に応じてローカルGitにコミット +3. workflow修正時は `push-workflow` で反映（flow + schedules） +4. script単体修正時のみ `push-script` を使う +5. 必要に応じてローカルGitにコミット ### 8.2 サーバーで変更されたものを取り込む 1. `status-remote` 実行 -2. サーバー新規/更新分を `pull-*` で取得 -3. ローカル履歴としてコミット（任意） +2. workflow単位の変更は `status-workflow` / `pull-workflow` で取得 +3. 単体変更は `pull-*` で取得 +4. ローカル履歴としてコミット（任意） ### 8.3 `alexa_speak` 更新例（現在の具体例） @@ -228,7 +271,8 @@ 1. Push前に対象オブジェクトをバックアップ保存（必須） 2. Push後に `post-verify`（再取得して期待値比較）を必須化 -3. 失敗時は「再実行」ではなく「現状確認 -> 復旧」の順で実施 +3. Push直前に `preflight hash check` を必須化し、不一致時はPush停止（fail closed） +4. 失敗時は「再実行」ではなく「現状確認 -> 復旧」の順で実施 ### 10.2 標準復旧手順 @@ -246,6 +290,13 @@ 2. 依存スケジュールの有効性を確認 3. 関連ジョブの手動実行で動作確認 +### 10.4 delete -> create 運用ガード（必須） + +1. `push-flow` / `push-workflow` 前に対象flowのバックアップJSONを必ず保存 +2. Preflightで hash 不一致なら自動Pushしない（手動レビューへフォールバック） +3. Push後に flow と schedules を再取得し、ローカル期待値と一致確認 +4. 不一致時は即時にバックアップから復元し、復旧ログを残す + --- ## 11. Windmill依存を薄くする方針（必須） @@ -256,7 +307,7 @@ Windmill API依存は避けられないため、依存点を最小化する。 - `scripts`: `list/get/create` - `flows`: `list/get/create/delete` -- `schedules`: `list/get/create/delete`（必要時） +- `schedules`: `list/get/create/delete`（workflow package 同期で常用） 上記以外のAPIは原則使わない。 @@ -278,18 +329,20 @@ Windmill API依存は避けられないため、依存点を最小化する。 以下を満たせば「このプロジェクトはサーバーのワークフローを管理するためのもの」と言える状態: -1. ローカルから scripts/flows の Pull/Push がAPIで完結 -2. サーバー更新がローカルで検知できる（hash比較） -3. 競合時の復旧手順が定義済み +1. ローカルから workflow package（flow + schedules）の Pull/Push がAPIで完結 +2. サーバー更新が workflow 単位でローカル検知できる +3. 競合時の復旧手順が flow/schedule 両方で定義済み 4. 運用手順がこの文書だけで再現可能 --- ## 13. 既知の注意点 -1. `wm-api.sh` は現状 `bash` 前提だが、Windowsで改行がCRLFだと shebang 実行失敗する場合がある +1. `wm-api.sh` は `bash` 前提。WindowsのCRLF混入で shebang 実行失敗し得るため、`.gitattributes` で `*.sh text eol=lf` を固定し、実行は `bash wm-api.sh ...` を標準とする 2. フロー更新は環境により `PUT` できないため削除再作成を標準とする -3. API応答仕様はWindmillバージョン差で微差が出るため、初回導入時は `get` のレスポンス形を確認する +3. 削除再作成は `version_id/hash/edited_at` を更新するため、Preflight hash check がないと競合上書きを見落とす可能性がある +4. 1つのflowに複数scheduleが紐づくことがあるため、`script_path` ベースで束ねて管理する +5. API応答仕様はWindmillバージョン差で微差が出るため、初回導入時は `get` のレスポンス形を確認する --- @@ -299,3 +352,5 @@ Windmill API依存は避けられないため、依存点を最小化する。 |------|----------| | 2026-03-03 | 初版作成（API一本化方針、同期仕様、実装計画、Runbookを定義） | | 2026-03-03 | 障害前提の復旧設計、Windmill依存を薄くする方針を必須要件として追記 | +| 2026-03-03 | 運用単位を workflow package（flow + schedules）へ変更し、実装計画とRunbookを更新 | +| 2026-03-03 | `delete -> create` と hash 管理の運用ガード（preflight / fail closed / post-verify）およびCRLF対策を追記 |