前言

一個 Shopify App 能在本機開啟，只代表 Web 程式有跑起來。真正準備上架時，還要同時確認 App URL、redirect URLs、必要 scopes、正式資料庫、migration、scheduler、隱私權政策、支援資訊、listing 素材、compliance webhooks 與營運 runbook。

上一篇處理的是 Prisma SQLite／PostgreSQL 雙 Schema 的部署邊界。這篇把資料庫以外的上線條件也收進同一個可重複執行的 Readiness CLI，目標不是替 App 蓋上「Shopify 已認證」的印章，而是讓團隊在提交審查前先攔下自己能判斷的缺口。

原本的做法與問題症狀

最早的上架準備是一份人工 checklist，加上一個顯示在 App 後台的 developer diagnostics 畫面。這兩種做法都能提醒人，但不適合當 release gate：

  • checklist 不知道目前部署讀到哪一份 App config 或 Prisma schema。
  • 同一項檢查在文件、畫面與 CI 各寫一次，很快就會產生不同答案。
  • 「已準備 listing」或「已審閱 runbook」若只存在某個人的記憶裡，下一次部署無法重現。
  • 後台顯示 ready 不會讓 shell command 失敗，release pipeline 仍可能繼續。
  • 商家登入後台不需要看到 datasource provider、migration lock 或內部安全審查狀態。

另一個極端是把所有事都交給 Shopify review 才發現。這會把可在本機抓到的錯誤——例如 redirect URL 仍指向測試環境、production schema 仍是 SQLite——拖到正式提交後才處理。

問題是怎麼推敲出來的？

來源 Git 歷史不是一次寫出完整 checklist，而是先建立純函式 getProductionReadinessChecks()，再逐步加入 runtime、URL、scope、database、scheduler、support、privacy、listing、runbook 與 dependency review。

接著才建立 CLI adapter。它從指定路徑讀取 Shopify App config、Prisma schema 與 migration lock，把檔案中的 facts 與環境設定一起交給同一組 rules。這樣 UI、測試與 CLI 不必各自解釋什麼叫 ready。

最後一層是 process exit code：報表可以讓人閱讀，但只要有一項 action_required，CLI 就回傳 1。CI 或 deployment script 因此能真的停止，而不是印完警告後繼續。

最後採用的架構

Readiness 被拆成四層：

Evidence adapters
  → App config / Prisma schema / migration lock / environment

Pure readiness rules
  → ready | action_required + non-secret detail

CLI adapter
  → readable report + exit code 0 / 1

Release process
  → tests / build / development-store smoke test
  → Shopify Review page automated checks
  → App Review team

自製 CLI 負責專案特有且能自動判斷的條件，例如 production artifact 是否選對、內部 runbook 是否有可追蹤審閱日期。Shopify Dev Dashboard／App Store Review 頁面仍負責平台設定、listing、protected customer data 與正式 review。

截至 2026-07-28，Shopify 也提供 AI Toolkit 的 /shopify-app-store-review self-review。官方明確說明它只涵蓋能從 codebase 判斷的要求；listing 內容、live behavior、merchant UX 與最終審查仍由其他檢查與 App Review team 負責。專案 CLI 應與這套官方工具互補，不應冒充同一件事。

關鍵實作

核心 rule 只回傳狀態與安全說明，不回傳 secret value：

type ReadinessCheck = {
  key: string;
  label: string;
  status: 'ready' | 'action_required';
  detail: string;
};

export function getReadinessChecks(input: ReadinessInput): ReadinessCheck[] {
  return [
    checkRuntime(input),
    checkAppUrls(input),
    checkScopes(input),
    checkDatabaseArtifacts(input),
    checkOperations(input),
    checkListingAndPrivacy(input),
  ];
}

CLI 只在全部通過時回 0：

const result = buildReadinessResult({
  configPath,
  schemaPath,
  migrationLockPath,
});

console.log(result.report);
process.exitCode = result.checks.every((item) => item.status === 'ready')
  ? 0
  : 1;

像「listing 文案已準備」這種無法由程式內容完全判斷的項目，可以用審閱日期當作可追蹤 gate；但日期只能證明有人完成一個流程步驟，不能證明素材一定符合 Shopify 最新規則。

實際驗證

來源 repository 的測試與 Git history 提供以下證據：

  • 完整 production-like input 時，所有 checks 可回 ready。
  • 缺少必要設定時，對應項目回 action required。
  • 非 HTTPS 或 placeholder App URLs 會被拒絕。
  • scopes、datasource provider 與 migration lock 不符預期時會阻擋。
  • listing、privacy、deployment 與 data request runbook 沒有審閱日期時會阻擋。
  • CLI report 會列出 ready／action-required 數量與逐項原因。
  • 只有所有 checks ready 時 exit code 才是 0。
  • CLI 的成功路徑、production Prisma artifacts 與 CI release gates 都有對應測試檔案。

這些是 source／test 證據，不是今天對正式環境執行 CLI 的結果，也不代表 App 已提交或通過 Shopify 審查。

仍然存在的限制

第一，configuration check 不等於 live check。案例中的公開隱私政策項目目前只確認程式提供該 route，沒有真的從 production 發 HTTP request 驗證 200、TLS、內容與可索引性。

第二，審閱日期容易被當成 checkbox theater。若沒有 reviewer、artifact version 與更新條件，填一個日期不代表法律、security 或 listing 品質真的完成。

第三，Shopify App Store requirements 會持續更新。CLI 的 rules 必須有 owner 與定期更新節奏；否則一個永遠全綠、但仍停在舊規則的工具反而更危險。

第四，CLI 不應印出 credential、connection string 或正式識別資料。即使 CI log 有存取限制，也應只顯示「缺少／不符合」，不要回顯原值。

最後，官方 self-review、Review page automated checks、development-store smoke test 與人工 review 各自看到不同層面。沒有任何一個單獨 gate 能證明商家從安裝、設定到解除安裝的完整旅程都正確。

可以延伸到哪些情境？

同一個模式適合把 release readiness 做成「evidence adapter＋pure rules＋CLI exit code」：

  • API scope 與資料最小化。
  • Webhook subscription 與 HMAC route。
  • production database migration。
  • scheduler／worker 與 monitoring。
  • privacy policy、support 與 incident runbook。
  • listing 文案、截圖與 review instructions。

下一篇會把這些 developer checks 從商家操作介面移開：商家後台不該出現開發者檢查項目

參考資料

以上平台文件查核日期：2026-07-28。