backend-dev-guidelines

此技能作為在 Langfuse 單體倉庫中工作的開發人員的全面技術指南。它確保了 Web (Next.js 14) 和 Worker (Express) 套件之間嚴格的架構一致性，保證從 tRPC 流程到複雜的 BullMQ 隊列處理等後端實作均符合既定的工程標準。專為負責在多租戶環境中建構、測試和維護高性能後端服務的軟體工程師而設計。該技能為分層架構提供了明確的藍圖，幫助開發人員連結 HTTP 請求、業務邏輯服務與底層數據持久層。

• 標準化工作流程，用於建立 tRPC 路由、受保護的程序以及帶有中間件的公開 REST API 端點。

• BullMQ 隊列消費者的實作指南，包括隊列註冊、服務級邏輯和錯誤處理模式。

• Prisma (PostgreSQL) 和 ClickHouse 分析的資料庫交互協議，強調通過 projectId 過濾實現多租戶隔離。

• 使用 OpenTelemetry 進行分佈式追蹤、DataDog 整合以及用於結構化錯誤管理的 traceException 的可觀測性與可靠性架構。

• 利用 Zod v4 進行輸入驗證，並通過 env.mjs 進行環境變數管理。

• 後端組件的測試方法，包括使用 Jest 進行網頁組件測試和使用 Vitest 進行 Worker 處理器測試。

• 在搭建新功能時使用此技能，以確保符合架構分層：API 層 → 服務層 → 資料庫/隊列層。

• 當暴露新端點時，參考提供的檢查清單以快速驗證身份驗證、授權檢查和中間件實作。

• 對所有非同步操作使用 traceException 包裝器，以確保可觀測性和乾淨的調試日誌。

• 確保所有基於 Worker 的後台作業均在 WorkerManager 中註冊，並遵守 packages/shared 中的共享類型定義。

• 實作多租戶功能時，嚴格遵守基於項目的隔離模式，以防止租戶之間的數據洩露。

• 參考目錄結構說明，將功能特定的邏輯放置在適當的伺服器或 Worker 套件模組中。