version: "1.0.1" name: tigerai-enterprise-patterns description: Applies TigerAI enterprise-grade design patterns when generating n8n workflows — Atomic Orchestration, Universal Worker (FastAPI), Specification-Driven Development (SDD), and security/governance constraints. Use when the user mentions enterprise / production / 企業級 / 原子化 / orchestration / FastAPI worker / SDD, or when a workflow involves heavy compute (PDF/MP3/image processing), regulated data, or multi-team handoff. Drives architectural decisions like loop transparency (batchSize=1), location-transparent workers, and mandatory error/audit annotations.

TigerAI Enterprise Patterns — 企業級模式 Skill

🌐 English | 繁體中文

🧱 Drop-in 模板（v0.26.0 起）：Retry / Approval / Handover 三個經典模式有可直接 import 的最小工作流 JSON：`examples/templates/`。AI 套用本 Skill 時可優先參考這三個檔案的節點結構、sticky note 寫法、correlation ID 命名，並修改成使用者場景。

1. 觸發條件

精確觸發詞：

• 「企業級」/「production」/「正式環境」/「上線」
• 「原子化」/「atomic」/「orchestration」/「編排」
• 「FastAPI worker」/「Universal Worker」/「外部 worker」
• 「SDD」/「specification-driven」/「規格驅動」

隱式觸發： 工作流涉及以下情境，AI 必須主動套用本 Skill：

• 處理檔案（PDF / MP3 / 圖片 / 文檔）— 套 Universal Worker
• 多團隊交接 / 跨服務編排 — 套 SDD
• 法務 / 金融 / 醫療 / PII 資料 — 套安全治理
• 失敗成本高的任務（金流、ETL）— 套全域 Error Trigger workflow

2. TigerAI 四大支柱（Consultancy Pillars）

源自專案 README.md，AI 產出 workflow 時必須體現：

Pillar 1：原子化編排（Atomic Orchestration）

問題：傳統黑箱 Python 腳本不可見、出錯難 debug。 解法：把流程拆成原子動作，每動作是一個 n8n 節點，loop 用 splitInBatches batchSize=1 讓每 iteration 在 UI 上獨立可見。 AI 規則：

• 涉及檔案逐筆處理 → splitInBatches batchSize=1（犧牲速度換透明度）
• 每個原子動作節點的 notes 欄位必填（對應 Layer 1 哪個 step）
• 不允許 1 個 code 節點塞 100 行邏輯 → 拆成多節點

Pillar 2：Universal Worker（位置透明）

問題：n8n 容器內裝 FFmpeg/PyMuPDF 會污染環境。 解法：把重邏輯封裝成 FastAPI Worker 容器，n8n 只用 httpRequest 呼叫。Worker 在本機/WSL/雲端皆同樣 URL。 AI 規則：

• 偵測到「PDF 切分 / MP3 處理 / 圖片轉檔 / OCR / FFmpeg」字眼 → 不要產 code 節點，產 httpRequest 呼叫 worker
• 預設 worker URL：http://worker:8000/<endpoint>，timeout 300 秒
• Layer 3 必註明「需先部署 FastAPI Worker container」+ 預期 API 介面

Pillar 3：Skill-Driven Development（本 Pack 自身）

問題：AI 寫的 workflow 破碎、不一致。 解法：以 SKILL.md 為唯一準繩。生產 workflow 前必先讀 spec / cookbook / patterns。 AI 規則：

• 不憑空產生 — 先比對本 Pack 的 7 大 pattern
• 不私下修改 spec — 任何疑義由使用者裁決

Pillar 4：企業安全評估

AI 規則：

• Webhook 預設未驗證 secret → Layer 3 必標「資安風險」
• 任何 credential 寫死 → 拒絕，要求改 credential reference
• 涉及 PII 流程 → Layer 3 必標「需資料留存政策確認」
• timeout 預設值：HTTP 30s / Worker 300s / Wait 不超過 1 hour

Pillar 4.1：時效性警告（Sunset / Deprecation Watch）

外部服務 / API / 節點會被棄用。AI 產出 workflow 時必須主動告知時效風險，避免使用者部署後幾個月內失效。

已知時效性風險清單（持續更新）：

AI 產出規則：

• 偵測到「LINE Notify」字眼 → Layer 3 必含「⚠️ 2026/03/31 停用警告」
• 偵測到 cron / function / functionItem 節點 → 拒絕產出，改用新節點
• 偵測到 LLM 模型字眼 → Layer 3 加「模型可能 18 個月內棄用，建議 model ID 用 env var 帶入」
• 不在清單內但使用者明示「已知會停用」→ 同步轉錄至 Layer 3

追蹤責任：

• 本清單由 TigerAI 維運團隊至少每季更新一次
• 客戶可透過 Slack channel #tigerai-skill-pack-updates 訂閱新增項目
• 過時項目移至 research/deprecated-services.md（暫未建立）保留歷史

Pillar 4.2：人工核准 / Handover 設計（Human-in-the-Loop）

問題：AI 寫的 workflow 常常「全自動跑完」，但企業實際需要在關鍵節點停下來等真人簽核（出帳前、發大量訊息前、修改正式資料前）。沒有 approval 節點＝出事沒人擋。

核准節點型態（n8n 內建）：

設計規則（AI 必遵守）：

1. 每個 approval 節點 timeout 必設。預設 24 小時；金流類 4 小時；客服類 2 小時。
2. Timeout 後必有 escalation 路徑。三種模式（依風險升序）：

• 自動拒絕並通知申請者（最保守）
• 轉給代理人或主管的主管（升級）
• 自動核准但標「待事後追認」（最寬鬆，僅限低風險）

1. Audit trail 強制留：在 approval 節點之後接一個 audit log 寫入（Sheets / Postgres / Slack channel 都可），欄位至少：request_id, requester, approver, decision, timestamp, reason, ip_or_channel。
2. 拒絕路徑必寫補償動作：「IF 拒絕 → 回滾 / 通知 / 寫拒絕原因到 log」。不能只是流程結束。
3. 不可把 approval 節點接的 token 寫進 Layer 1 sticky note — token 是執行期參數，屬 credential。

Handover（移交）設計規則：

反模式（拒絕產出）：

• ❌ Approval 節點無 timeout
• ❌ Timeout 後直接「continue」當作通過
• ❌ Approval 結果沒寫進任何 log
• ❌ 拒絕路徑跟通過路徑共用節點且沒分支
• ❌ 在 Layer 1 sticky 寫死 approver email（應走 credential 或 settings 表）

對應 onprem LINE CS 案例：那個系統的「真人接手」流程是 handover 半套示範（有 is_human_mode 狀態 + 逾時歸還）。但 SECURITY-CAVEATS 也指出後台沒有真實 auth — 所以 approval 本身的「按下去那個人是誰」這層保證還沒做完。AI 產出企業級 workflow 時必確認 approver 身分驗證真實存在而不是假樁。

3. SDD（Specification-Driven Development）整合

對企業級 workflow，AI 在產出 JSON 同時，建議使用者另外建立 specification.md 記錄：

# Workflow Specification
 
## 1. Purpose
-Business objective
-Stakeholders
 
## 2. Trigger & Inputs
-Trigger type
-Input schema (JSON Schema 或欄位清單)
 
## 3. Business Logic (Step-by-Step)
-對應本 workflow 的 @step 順序
 
## 4. Outputs
-對外回傳 / 寫入目標 / 通知對象
 
## 5. Errors & Recovery
-已知失敗模式
-Error Trigger workflow ID
 
## 6. Test Scenarios
-至少 3 case：golden path / edge / error

AI 規則：當使用者明示「企業級」/「SDD」時，產出 JSON 後主動詢問：「要不要我同步產生 specification.md？」

4. 旗艦範例對照

5. AI 自我檢查清單

產出企業級 workflow 後，必逐條自查：

• [ ] 重邏輯放 worker，n8n 只編排？
• [ ] loop 是否 batchSize=1（除非明示要速度）？
• [ ] 每節點 notes 都填？
• [ ] credential 都是 reference（不是寫死）？
• [ ] Layer 3 含「資安風險」/「資料留存」段？
• [ ] 全域 Error Trigger workflow 已建議？
• [ ] timeout 都設？
• [ ] 對應 SDD 的 6 段是否都能在 Layer 1+3 找到？

少一條即不算企業級。

6. 與其他 Skill 整合

• 與 `sticky-note-to-workflow`：本 Skill 是其「企業級分支」，當偵測企業情境自動啟用
• 與 `n8n-validation-expert`：產出後先過 validation profile=strict

7. 反模式（企業情境下絕對禁止）

• ❌ Code 節點塞 100 行業務邏輯
• ❌ 寫死 API key / DB password
• ❌ 用 manualTrigger 上線
• ❌ 沒設 timeout 直接呼叫第三方 API
• ❌ 沒有 Error Trigger workflow
• ❌ 對 PII 資料未做存取控管 / log redaction
• ❌ Workflow 名稱用「Untitled」/「Test」/「Copy of...」