jorgemiranda-alt/cloudapper

cloudapper 是做什麼的？

CloudApper 是一個低程式碼平台：應用程式由表單（資料模型）、選單（導覽）、角色、UI 工作流程（用戶端）、後端工作流程（自動化）和 DevExpress 報表組成，全部在 App Studio（表單與選單的路徑為 /design/...，工作流程的路徑為 /studio/...）中編輯，並在執行階段應用程式（/<clientId>/app/<appId>/...）中使用。

此檔案包含適用於每項任務的規則。在執行任務前，請先閱讀與該任務相符的參考資料：

任務	參考資料
了解平台運作方式（表單、欄位、工作流程、報表、快取）	references/platform-model.md
呼叫 API（記錄、工作流程、表單、選單、角色、UI 工作流程、報表）	references/api-reference.md
建立或變更工作流程；除錯「未觸發」或緩慢的工作流程	references/workflow-patterns.md
使用 Playwright MCP 驅動瀏覽器	references/playwright-efficiency.md
將功能或整個應用程式從一個應用程式/帳戶複製到另一個	references/copy-between-apps.md
在設計工具中建立新的應用程式或表單	references/building-apps.md
設計、命名或審查任何內容（CloudApper 上的 SOLID 原則、命名慣例、工作流程/設定/報表慣例）	references/conventions.md
設計解決方案或整合架構（UKG、REST、webhook、SFTP、中介軟體；擴充性與效率）	references/architecture.md
記錄應用程式（技術/疑難排解指南，或 PM 交接指南）	references/documentation.md
審查應用程式或撰寫其發現/建議	references/app-review-checklist.md
處理 UKG（Pro、WFM、Recruiting、HRSD）連接器	references/integrations-ukg.md
使用者詢問如何在 CloudApper 上與您合作，或詢問此技能應包含哪些內容	references/learning-and-prompting.md

環境：變更前務必詢問

大多數 CloudApper 客戶都有一個生產應用程式和一個 UAT（測試）應用程式，通常位於不同的帳戶下。在進行任何變更（儲存表單、編輯或切換工作流程、編輯記錄、匯入報表、變更選單）之前，請確認此變更針對的是哪個環境，除非使用者已在本次對話中說明：

• 詢問：「這是針對生產環境還是 UAT 環境？」並說出您已登入的帳戶/應用程式，以便使用者能夠發現不符之處。
• 預設為 UAT。將生產環境視為唯讀：除非使用者明確要求該特定操作，否則不進行任何變更、不執行工作流程、不登入或讀取。從生產環境複製是讀取；複製到生產環境則是變更。
• 每次寫入前請檢查 URL 中的用戶端 ID（/<clientId>/app/<appId>）。如果頁面位於錯誤的用戶端，寫入腳本應拒絕執行。
• 專案事實（帳戶、用戶端/應用程式 ID、哪個應用程式是生產環境）不儲存在此技能中。請在專案自己的筆記或文件中以及記憶體中尋找；如果找不到，請詢問使用者。

適用於每項任務的安全規則

• 切勿自行執行、啟用或觸發工作流程。 執行由使用者發起。您僅可在被要求時儲存定義並開啟/關閉；清楚說明切換動作何時會改變即時行為。
• 編輯前務必備份。 將您將變更的每個工作流程/表單的目前定義儲存到一個帶有日期標籤的本地資料夾中，並保留到使用者確認結果為止。（過早刪除備份曾導致無法復原。）
• 機密資訊。 工作流程連接器包含憑證（UKG、其他供應商 API、金鑰）。切勿列印、記錄或將其放入文件中。檢查工作流程 JSON 時，屏蔽密碼/secret/apikey/token/clientId 等金鑰，僅列印結構。完成後刪除包含機密資訊的原始傾印，並告知使用者哪些本地資料夾仍包含這些內容。
• 使用者自行登入。 切勿輸入密碼。請使用者在 Playwright 瀏覽器中登入，並在完成後告知您。
• 個人資料。 在您保留或分享的螢幕截圖中，將姓名、電子郵件和 ID 模糊化。
• 如實回報。 如果測試顯示某些內容無法運作，請在提出下一個修正方案之前，連同證據（時間戳記、狀態、日誌行）一同說明。

最常造成問題的六大平台事實

這些是從經驗中學到的教訓；詳細資訊和證據請參閱 references/workflow-patterns.md。

1. 工作流程順序很重要 (WP-001)。 由某個工作流程建立的記錄，只會觸發位於該工作流程之後（較高的順序編號）的工作流程。放置在目標之後的工作流程不會觸發任何動作。請確保環境之間的清單順序完全相同。
2. 設計工具會執行 API 不會執行的隱藏操作。 在設計工具中建立表單也會授予管理員角色存取權限（權限 32655）。透過 API 儲存表單主體會建立表單及其預設選單，但不會建立權限，因此選單在執行階段會保持隱藏。子表單也需要它們自己的父子關係呼叫。
3. 狀態觸發器需要實際的變更 (WP-002)。 在 Status _IsUpdated 上觸發的工作流程，如果新值與舊值相同，則不會啟動（狀態卡在「Running」的記錄無法透過再次設為「Running」來重新執行）。
4. 觸發執行的工作流程會一個接一個地執行，且迴圈不一定會等待它們完成 (WP-005)。 更新 24 筆記錄的迴圈可能在幾秒內完成，而它所觸發的 24 個工作流程執行實例則在接下來的一小時內執行；同時啟動的第二個批次可能會遺失其觸發的執行實例。一次只執行一個批次。
5. 執行階段會快取應用程式。 在設計變更後，按一下應用程式名稱旁邊的重新整理圖示（或重新登入）；角色無權存取的表單選單會被隱藏，因此新表單需要角色權限（請參閱複製檢查清單）。
6. 路由器會執行每個條件為真的路由 (WP-009)，而不僅僅是第一個。當只需要一個結果時，請確保路由條件是互斥的。

如何高效工作

• 優先使用 API 而非點擊操作：它們更快、更精確且成本更低。僅在沒有已知 API 的情況下使用 UI，並使用 UI 來確認使用者將看到的內容。
• 在 Playwright 中，從檔案執行程式碼（使用 filename 參數的 browser_run_code_unsafe），從 localhost 輔助伺服器提供大型 payload，並回傳精簡摘要（計數、名稱、狀態），永遠不要回傳完整的 JSON。請參閱 references/playwright-efficiency.md。
• 在編輯工作流程之前，請透過 API 讀取其節點樹（名稱、動作類型、表單），而不是開啟設計工具。
• 每次變更後，透過讀回驗證（使用 API），對於工作流程，則開啟建置器一次以檢查其是否能正確呈現。
• 大型或重複性任務：編寫一個小型的建置器腳本（Python），從現有節點的範本產生 JSON，然後編寫一個受保護的套用腳本。將兩者都保留在專案中，以便變更可重複且可審查。

文件預設值

僅限 Markdown（僅在要求時提供 PDF），僅限內部讀者（無客戶電子郵件），文件中的開放性問題需說明原因與目的，圖表僅顯示執行中的應用程式及其使用者/外部系統。完整方法：references/documentation.md。當應用程式已有文件或專案筆記時，請先閱讀它們，然後再探索該應用程式。

向此技能新增知識

當使用者要求將內容新增到此技能（「將此新增到 cloudapper 技能」）時：

1. 讀取此技能資料夾中的 inbox/TEMPLATE.md，並將草稿寫入 inbox/<yyyy-mm-dd>-<short-name>.md，狀態設為 Hypothesis。請以通用方式撰寫：不包含客戶、應用程式、表單、工作流程或人員名稱、ID、真實主機或憑證。
2. 在 references/ 中搜尋草稿確認或反駁的條目，並將它們列在草稿的審查筆記中。
3. 除非使用者聲明自己是維護者並正在套用已審查的變更，否則請不要自行編輯 SKILL.md 或 references/。告知使用者應使用草稿提出拉取請求（CONTRIBUTING.md 中有流程說明）。