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 套件模块中。