快速開始：採購審批流程
本教學使用一套最小採購申請完成「定義資產 → 建構流程 → 設計檢查 → 執行階段驗證」的完整流程。完成後，申請人可以提交採購申請，部門主管負責審批，高額採購則繼續進入財務審批。
1. 準備工作
開始前請確認：
- 目前應用程式有一個狀態為 DEVELOPING 的可編輯版本。
- 已準備 Applicant、Department Manager、Finance Approver 三類測試使用者或角色。
- 可以從申請人的部門解析出部門主管。
- 你有流程資產編輯和應用程式發佈權限。
2. 建立欄位
進入 Process Designer → Task Configuration → Fields，建立以下自訂欄位：
| Label | Field Type | 關鍵設定 |
|---|---|---|
| Applicant Department | Department | 單選部門 |
| Amount | Number | 可視需要設定貨幣單位 |
| Category | Select | Hardware、Software、Service |
| Required Date | Date | 日期 |
| Reason | Text Area | 長文字 |
| Attachments | Attachment | 視需要限制數量和檔案類型 |
| Department Review Comment | Text Area | 部門主管填寫審批意見 |
| Department Review Result | Select | 選項為 Approved、Rejected；由流程自動寫入 |
| Finance Review Comment | Text Area | 財務審批人填寫審批意見 |
| Finance Review Result | Select | 選項為 Approved、Rejected；由流程自動寫入 |
Field Key 會在儲存欄位時由系統自動產生，使用者不需要也不能自行填寫。後續設定流程條件、處理人規則或 TQL 時，應從編輯器提供的欄位候選項中選擇，不要根據 Label 猜測 Key。
標題、狀態、建立人、處理人、建立時間等應使用系統欄位，不要建立同義的自訂欄位。
Department Review Result 和 Finance Review Result 不設定預設值，也不要求申請人或審批人手動選擇。它們的初始值為空，由對應 Approve / Reject 流轉的 Post Function 寫入結果。
預期結果： Fields 清單同時顯示系統欄位和上述十個自訂欄位。
3. 建立表單
請先理解兩類繫結，避免把審批表單誤認為 Task Type 的第四種表單：
- Task Type 表單只有 Create Form、Edit Form 和 View Form 三個位置。
- 流轉表單繫結在 Workflow 的特定流轉上，只有使用者按一下 Approve 或 Reject 時才會開啟。
進入 Task Configuration → Forms，建立以下表單資產：
purchaseCreate：Create Form。申請人建立任務時填寫標題、部門、金額、類別、需求日期、原因和附件。
purchaseView：View Form。以唯讀方式統一顯示申請資訊、Department Review Result、Department Review Comment、Finance Review Result 和 Finance Review Comment，作為任務詳細資訊。本案例提交後不開放業務欄位編輯，因此 Edit Form 也選擇purchaseView；如果業務允許申請人修改尚未結束的任務，可以重複使用purchaseCreate，或另外建立purchaseEdit。managerReview：Department Review 的流轉表單。申請資訊為唯讀，只有 Department Review Comment 允許部門主管編輯。
financeReview：Finance Review 的流轉表單。申請資訊為唯讀，只有 Finance Review Comment 允許財務審批人編輯。
此時只需建立表單資產，不必立即繫結 Task Type。完成流程和權限方案後，再於第 6 節統一建立參照關係。
預期結果： Forms 清單中有 purchaseCreate、purchaseView、managerReview 和 financeReview 四個表單資產。
4. 建立 Step 和流程
在 Task Configuration → Steps 建立：
- Department Review
- Finance Review
Step 是可由多個 Workflow 參照的可重複使用業務環節資產，不只是目前流程節點的顯示名稱。Workflow 中的 Human Activity 繫結 Step 後，執行階段任務會記錄該 Step 穩定的 stepCode；跨流程報表、TQL、辦理時間和 SLA 等統計才能將不同 Workflow 中的同一業務環節彙總在一起。
例如，Purchase Approval 和 Expense Reimbursement 兩個流程都需要財務審批時，應讓兩個流程的財務人工節點共同參照這裡建立的 Finance Review Step。如此便能跨兩個流程統計 Finance Review 的任務量、平均辦理時間和 SLA 違約率。不要在兩個流程中分別建立只有名稱相同的暫時節點，否則它們沒有共同的 Step 識別碼，無法作為同一個可重複使用業務環節進行可靠統計。
Department Review 也適用相同原則：如果其他流程也有業務語意相同的部門審核環節，應重複使用這個 Step；如果職責、統計口徑或 SLA 定義不同，則應建立獨立 Step，避免錯誤合併不同的業務階段。
接著進入 Task Configuration → Workflows，建立：
- Name：Purchase Approval
- Key：依介面規則填寫穩定識別碼，例如
PURCHASEAPPROVAL；儲存後不要只為修改顯示名稱而更換 Key。 - Category：Procurement
- Allow Revoke：依業務需要開啟。
在畫布中設定：
Start → Department Review → Amount Gateway
├─ 低額 → Approved
└─ 高額 → Finance Review → Approved
Department Review / Finance Review 拒絕 → Rejected
上圖的設定分為路由、處理人、表單、驗證和結果寫入五部分：
- Task Type 繫結
purchaseCreate（Create）和purchaseView（View / Edit）。 - Department Review 的處理人從 Applicant Department 解析部門主管；Finance Review 的處理人選擇 Finance Approver 角色。
- Department Review 通過後進入 Amount Gateway。低額連線設定
Amount < 10000，直接前往 Approved；高額連線設定Amount >= 10000，進入 Finance Review。 - 選取 Department Review 的 Approve、Reject 離開連線，在右側 Transition Form 選擇
managerReview。 - 選取 Finance Review 的 Approve、Reject 離開連線，在右側 Transition Form 選擇
financeReview。 - 保持 Show Button 開啟，並分別設定清楚的流轉名稱、確認訊息和提示。
- 為審批意見增加必填驗證：部門流轉驗證 Department Review Comment，財務流轉驗證 Finance Review Comment。
- 為 Department Review 的 Approve 流轉新增 Functions → Set Task Field：Field Name 選擇 Department Review Result，Field Value 填寫
Approved。 - 為 Department Review 的 Reject 流轉新增 Functions → Set Task Field：Field Name 選擇 Department Review Result，Field Value 填寫
Rejected。 - 為 Finance Review 的 Approve / Reject 流轉依相同方式設定 Finance Review Result，分別寫入
Approved/Rejected。
同一個審批表單可以同時繫結該節點的 Approve 和 Reject 流轉。如此一來，處理人無論核准或拒絕，都會先開啟對應的流轉表單並填寫審批意見；驗證通過且流轉成功後，Set Task Field 再依實際按下的流轉自動寫入審批結果。最後，purchaseView 會以唯讀方式統一顯示意見和結果。
不要將 Result 欄位做成審批人可編輯的 Select，也不要只依賴表單按鈕修改頁面顯示。結果必須設定在對應流轉的 Functions 中，才能確保儲存的欄位值與實際執行的 Approve / Reject 路徑一致。
設定 Conditions、Validators 和 Functions 時，應從編輯器候選項中選擇欄位。不要手動複製 Field Label 或系統產生的 Field Key，以免儲存設計器無法正確解析或回顯的欄位參照。
下圖是實際設定的流程：
預期結果： 儲存流程後沒有未連接的節點；從 Start 到每個結束節點都有完整路徑。
如果本機已完成 Spark CLI 安裝與驗證，並安裝了 Codex 整合或 Claude Code 整合，可以直接將流程需求描述給 AI，由 AI 呼叫 Spark CLI 的語意化命令建立節點、連接路由、繫結 Step 和表單，並設定 Conditions、Validators 與 Post Functions。
建議在描述中明確指定目標 App、設計版本、節點、分支條件、處理人、流轉表單、驗證規則和欄位寫入規則。例如：
在 spark-sample 目前的 DEVELOPING 版本中設定 Purchase Approval：
重複使用 Department Review 和 Finance Review Step；部門通過後依 Amount 分支，
小於 10000 直接核准，大於等於 10000 進入財務審批；任一審批拒絕則以 Rejected 結束。
部門和財務流轉分別繫結 managerReview、financeReview，審批意見設為必填，
Approve / Reject 後分別將對應 Review Result 寫成 Approved / Rejected。
寫入前先顯示目標 App、版本、流程和完整變更清單，等待我確認後再執行，
最後執行流程檢查。
AI 輔助設定不會取代設計審查。確認前應核對目標 App、版本和流程；修改後仍需在 Process Designer 中檢查圖形結構，並於適當的執行環境中驗證真實使用者、權限、組織資料和分支。命令能力和完整範例請參閱流程語意化編輯。
5. 建立權限方案
第一次設定權限時，不需要從空白方案逐條建立授權規則。在 Data & Permission → Permissions 中按一下 Import System Default，系統會複製一份可編輯的預設權限方案：
匯入後進入 Configure 檢查授權規則。為了方便區分多個 Task Type，可以使用 Edit 將方案名稱改為 Purchase Request Permission；本案例截圖仍保留匯入時的 Default Task Permission 名稱。如果已手動建立空白方案，也可以進入 Configure，從空白狀態匯入同一組預設規則。
權限方案中的每一列都是一條 Permission Item + Grant Type + 選用 Grant Parameter 授權規則。對本案例而言，匯入的預設方案已包含以下關鍵規則：
| Permission Item | Grant Type | 在採購流程中的作用 |
|---|---|---|
| Create Task | System User | 允許已登入使用者建立採購申請 |
| View Task | Task Creator | Applicant 建立任務後，以任務建立人身分檢視自己的申請 |
| View Task | Current Assignee | Department Manager 或 Finance Approver 收到待辦後檢視任務 |
| View Task | Historical Assignee | 已處理過任務的審批人繼續檢視該任務 |
| Transition Task | Current Assignee | 只有目前待辦處理人可以執行 Approve / Reject 等流轉 |
| Revoke Task | Task Creator | Applicant 可以依流程規則撤回自己建立的申請 |
| Log Work | Current Assignee | 允許目前處理人登記工時；不控制 Approve / Reject |
這裡不需要再為 Finance Approver 設定 System Role 的 View Task 或 Transition Task 權限。Finance Approver 角色用於 Workflow 中 Finance Review 的處理人指派；高額採購進入該節點並完成指派後，實際收到任務的使用者就是 Current Assignee，會自動取得上表中的檢視和流轉權限。直接將 View Task 授予整個 Finance Approver 系統角色，會讓該角色下所有使用者都能檢視繫結此權限方案的全部採購任務，而不只是高額分支上的任務。
如果業務要求 Applicant 在提交後仍可修改任務，可以額外新增 Edit Task + Task Creator；特定狀態下是否真正允許編輯，還應同時由流程狀態和可用操作控制。Permission Item、Grant Type 和 Grant Parameter 的實際候選項來自目前系統註冊的擴充項目，請一律從介面候選項中選擇。
6. 建立 Task Type
進入 Task Configuration → Task Types，建立：
- Task Type Key：
PURCHASE - Task Type Name：Purchase Request
- Category：Procurement
- Default Workflow：Purchase Approval
- Permission Schema：選擇第 5 節確認過的權限方案（截圖中為 Default Task Permission）。
- Create Form：
purchaseCreate - View Form：
purchaseView - Edit Form：
purchaseView
managerReview 和 financeReview 不在 Task Type 中繫結，它們已透過 Transition Form 繫結到 Workflow 的特定流轉。
預期結果： Task Type 清單顯示 Purchase Request，完整度檢查通過，並且可以看到預設流程、權限方案和三個表單位置都已繫結。
7. 檢查設計並選擇驗證環境
返回 Designer Overview，選擇目前的 DEVELOPING 版本並執行 readiness check，修正未連接節點、缺少處理人、未繫結資產或權限不完整等阻斷項目。
完成結構檢查後，可以依目前階段選擇驗證環境：
- 快速設定和個人偵錯可以直接開啟 DEV 執行環境，驗證目前的 DEVELOPING 版本。本快速開始採用這種方式，後續截圖均來自 DEV 環境。
- 團隊整合、正式驗收或發佈前驗證可以先檢視目前版本與 TEST 已發佈版本之間的資產差異，確認後再發佈到 TEST。發佈到 TEST 是選用步驟，並非完成本快速開始的前置條件。
readiness check 只能發現結構性問題，不能取代真實組織資料、角色、權限和執行資料驗證。需要使用 TEST 時，發佈細節請參閱測試與發佈。
8. 在 DEV 執行驗證
本節截圖來自 DEV 環境。請使用準備好的測試使用者執行：
- Applicant 建立一筆 Amount 小於 10000 的採購申請；Department Manager 審批通過後，任務應直接進入 Approved。
- Applicant 建立一筆 Amount 大於等於 10000 的採購申請；部門審批通過後應進入 Finance Review，Finance Approver 審批後進入 Approved。
- 另外建立一筆任務，在部門或財務環節執行 Reject，確認進入 Rejected。
- 分別使用 Applicant、Department Manager 和 Finance Approver 檢查 My Created、My Pending 和已處理任務，確認只有目標使用者能夠檢視和辦理。
- 開啟
purchaseView，確認每次 Approve / Reject 後對應的 Review Result 顯示Approved/Rejected，審批意見保留處理人輸入的內容。
完成標準： DEV 中可以建立任務，處理人解析正確，兩個金額分支和拒絕分支都依預期執行，並可核對表單、權限和審批結果。如果選擇發佈到 TEST，應在 TEST 中重複相同案例並核對發佈記錄。