术语表

这里收录本书使用的核心术语。它们不是产品术语的完整集合，而是阅读当前 repo 架构时最常遇到的词。

术语	含义
monorepo	一个仓库内包含多个应用和包，Langfuse 通过 pnpm workspace 和 Turborepo 组织。
workspace package	被 pnpm-workspace.yaml 纳入管理的包，例如 web、worker、packages/shared、docs。
dependency direction	包之间允许的 import 方向。Langfuse 的关键规则是 shared 不反向依赖 web、worker、ee。
contract	跨模块或跨进程必须共同遵守的输入输出约定，例如 Zod schema、队列 payload、API schema。
abstraction	把变化封装到稳定接口后的结构，例如 repository、query builder、procedure、queue producer。
tRPC	Web UI 调用服务端业务逻辑的类型安全 RPC 层。
Public API	面向外部 SDK/API client 的 REST API surface。
ingestion	接收 trace、observation、score、event 等写入数据的链路。
BullMQ	基于 Redis 的队列系统，用来连接请求侧生产者和 worker 消费者。
QueueName	队列名称枚举，属于跨进程契约。
QueueJobs	队列 job 名称和 payload 的契约集合。
Zod schema	运行时校验和 TypeScript 类型推断共同使用的 schema。
Prisma	Postgres schema、client 和迁移相关工具。
ClickHouse	面向高吞吐分析查询的列式存储，承载 tracing/event 类明细数据。
Postgres	面向事务一致性的关系型存储，承载项目、组织、用户、配置等元数据。
Redis	队列和缓存基础设施。
S3/blob	大对象或批量事件暂存层，常用于避免请求或队列 payload 过大。
repository	封装数据访问的服务端抽象，让调用方不直接关心具体 SQL 或存储细节。
query builder	把筛选、排序、分页等高层条件转换成 ClickHouse SQL 的抽象。
FilterState	UI 和查询层共享的筛选状态结构。
Search Bar grammar	搜索栏文本语法，负责把用户输入解析成结构化 filter。
feature directory	web/src/features/* 下按业务功能聚合 UI、server helper、README 或局部类型的目录。
generated files	由工具生成的文件，例如 generated/* 和 Prisma generated client，不手工编辑。

三组容易混淆的词

contract 和 abstraction

contract 关注“双方必须一致”，abstraction 关注“调用方不必知道细节”。queues.ts 里的 job payload 是 contract；worker processor 周围的服务类是 abstraction。

web 和 frontend

web 不是纯浏览器前端。它同时包含 Next.js UI、tRPC server、Public API route、ingestion HTTP route 和一部分服务端 glue code。

shared 和 utils

packages/shared 不是随手放工具函数的地方。它是被多个运行时共同消费的契约中心，放进去的东西会抬高变更成本。