Naly 工程筆記：Drizzle ORM、Neon Postgres 與型別化發佈狀態

摘要

這套架構讓 Naly 擁有型別化的發佈控制平面：Drizzle ORM 將文章、預測、來源、社群貼文、獎勵與 cron 紀錄作為 Neon Postgres 中的關聯式實體儲存，而非分散在執行時狀態。因為每個工作流程步驟都儲存為明確的資料列與 enum 狀態，Naly 可以安全地重新執行 cron 管線、從部分失敗中恢復，並保持編輯端介面資料與 API 可見狀態一致。截至 2026 年 6 月 26 日，這是該專案針對預測發佈的作業耐久契約。

Naly 中的位置

在目前的堆疊中，發佈行為在多個 Next.js 應用程式路徑與 cron 任務間共享，這些都會收斂到同一個資料庫契約。現有套件組合為—next@16.0.7, react@19.2.1, drizzle-orm@^0.44.7, @neondatabase/serverless@^1.0.2, tsx@^4.21.0, typescript@^5.9.3—對應於在 server-side routes/actions 與排程工作者中執行的類 serverful ORM 層。

Naly 將這些領域作為一流表格儲存：

文章與預測紀錄
來源網址與溯源快照
社群貼文＋發佈中繼資料
獎勵分數、校準中繼資料與稽核欄位
cron 執行中繼資料與發佈檢查點

其價值不只在持久化，而在共享語意。每個 renderer、worker 與 API action 都讀取同一份發佈狀態模型，且可在沒有隱藏跨程序旗標的情況下協同運作。

技術機制

Drizzle 為這類共享語意提供了 schema-first 的路徑。Drizzle 指南顯示了標準流程：以 TypeScript 定義 schema，設定 Neon's DATABASE_URL，初始化 drizzle，並使用產生的查詢型別進行插入/讀取/更新（總覽文件, Neon 教學）。

簡化的 Naly 式驅動初始化範式如下：

import { drizzle } from 'drizzle-orm/neon-http';
import { pgTable, text, timestamp, pgEnum, integer } from 'drizzle-orm/pg-core';

export const publicationState = pgEnum('publication_state', [
  'queued', 'draft_ready', 'published', 'failed',
]);

export const publications = pgTable('publications', {
  id: text('id').primaryKey(),
  slug: text('slug').notNull().unique(),
  state: publicationState('state').notNull(),
  stateVersion: integer('state_version').notNull().default(1),
  stateChangedAt: timestamp('state_changed_at').notNull().defaultNow(),
});

const db = drizzle(process.env.DATABASE_URL!);

這呼應了 Drizzle 文件中對 Neon's 傳輸選擇的支援： drizzle-orm/neon-http 與 drizzle-orm/neon-serverless ，對於 Neon，能針對一次性工作負載使用 HTTP，並在需要互動式交易作業時提供 WebSocket 類似的 session 行為。Drizzle 的 pg-core 定義也可啟用型別推斷（$inferInsert, $inferSelect），因此可在編譯時透過 TypeScript 驗證發佈負載，同時保留非關鍵中繼資料的彈性 JSON。

對 Naly 來說，關鍵的架構模式是：

定義狀態轉換（queued -> drafted -> approved -> published -> archived）為明確資料列，
將轉換邏輯集中在單一 server-only 模組，
使用冪等鍵（作業 ID + 狀態雜湊）記錄每次變更，
在需要原子性的情況下，將關鍵轉換放在資料庫交易內執行，
僅在狀態前進後才產生不可變的成果物（例如 blob URL、社群文案、schema 快照）。

其效果類似於一個在 Postgres 中持久化的微型有限狀態機，以嚴格 schema 契約為主軸，而非 cron worker 內隱含行為。

文獻說明

主要文件將其定位為 serverless 系統的實務設計選擇：

Drizzle 本身設計上類似 SQL 並且可直接支援 serverless，降低想要直接 SQL 語意與型別安全並存的團隊的 ORM 抽象負擔（Drizzle 概覽）。
Drizzle/Neon 教學明確支援原生 Neon HTTP/WebSocket 驅動組合與型別化 schema-first 建模，包含 @neondatabase/serverless 整合與型別推斷範例（Drizzle 搭配 Neon, 開始使用 Drizzle + Neon）。
Drizzle 的連線矩陣顯示了明確的執行時驅動分離，因此團隊可依工作負載與執行條件調整執行模式（資料庫連線文件）。
Neon 官方驅動文件與邊緣端指南都強調，serverless/postgres 存取通常透過 HTTP 或 websocket-based proxy 達成，這正說明為何邊緣執行決策必須針對每個工作負載明確設定（Neon serverless driver, 如何在邊緣端使用 Postgres）。

在 schema 面向，關於 schema 演進的研究說明了為何顯式遷移與狀態模型很重要。Tesseract 指出 schema 演進可視為一級交易操作，健壯系統應以設計層面降低停機（線上 schema 演進）。EvoSchema 顯示 schema 變更，特別是表層級擾動，可能使下游行為不穩定，這是對於隨意向發佈/狀態表進行即興新增的強力警訊（EvoSchema）。

設計權衡

Naly 的選擇實際上是嚴謹性與摩擦的平衡。強型別 schema 與明確的狀態 enum 可提升可觀測性與可靠性，但也提高前期建模成本，並要求遷移紀律。當發佈邏輯在 cron workers、AI 管線與公開頁面渲染器之間成為共用邏輯時，這種權衡曲線是有利的。

驅動程式選擇: neon-http 通常對一次性作業更簡單且更快； neon-serverless 需要互動式 session 時更好。
Schema-first 設計：編譯期安全性可降低執行時錯誤，但 schema 變更需要遷移規劃，若測試未涵蓋狀態轉換，可能會表現為部署被阻擋。
執行時可攜性：Neon 的邊緣友好驅動模型擴展部署選項，但傳輸模式會影響 session 行為、延遲特性與認證/TLS 路徑。
型別忠實度與操作便利性：明確 enum 可防止無效狀態，但若遷移腳本未事前核准，可能會拖慢深夜 hotfix。

失敗模式

工作負載使用錯誤驅動程式：對多步驟狀態轉換使用一次性 HTTP 查詢可能會失去原子保證，並產生部分發佈狀態。
工人與部署間的 schema 漂移：如果 publication_state 值在未協調遷移下變更，舊 cron 程式碼可能會寫入無效狀態。
非冪等重試：除非檢查點具有冪等性且以 run-id 作為唯一標識，否則 cron 重啟可能會重複寫入社群內容。
遷移延遲：對過時 schema 快照執行的排程工作可能會失敗，特別是在滾動部署期間。
邊緣冷啟動＋認證負載：在受限的邊緣層，若未調整 timeout 預算與作業 fanout，重複的連線建立會增加延遲並導致假性逾時。

對於本主題，失敗分析應將發佈狀態視為正確性構件，而非實作細節。每次狀態轉換都必須具備可重放安全性。

實作備註

保持 schema 檔案集中且具版本控管；從單一可信來源重新產生遷移產物。
將可變更的領域表與不可變的成果表分離。
將發佈轉換建模為交易邊界，並強制不變條件（例如不允許直接 queued -> published 跳轉）。
將排程中繼資料（last_run, next_run_at, error_count）存入獨立表格以進行警示與稽核。
偏好在 server-only 模組中進行 DB 初始化（DATABASE_URL 來自 .env.local cron/runtime 環境）。
對大多數操作使用結構化查詢，僅將原始 SQL 保留給遷移種子或報表。
將 stateVersion 及事件日誌作為 schema 演進時的相容性橋接。