速查表
这一页把全书反复出现的源码入口、命令和改动路线压缩成查阅表。读源码时可以先看这里，再回到对应章节展开。
仓库地图
| 目标 | 先看哪里 | 说明 |
|---|---|---|
| 看 Web UI 和 tRPC | web/src | Next.js 应用、页面、组件、服务端 router 都在这里。 |
| 看后台消费 | worker/src | 队列消费者、批处理、异步任务和 ClickHouse 写入集中在这里。 |
| 看稳定契约 | packages/shared/src | domain schema、queue payload、DB client、repository、查询抽象都在 shared。 |
| 看企业能力 | ee | 被 web 消费，但仍依赖 shared 里的基础契约。 |
| 看 API 定义 | fern/apis | Public API contract 变更应从 Fern 源头更新。 |
| 看生成产物 | generated | 只读，不手改。 |
| 看中文架构图 | architecture/langfuse-current-architecture.drawio 或 /architecture/langfuse-current-architecture.drawio | draw.io XML，可以用 diagrams.net 打开。 |
五层架构
| 层 | 主要职责 | 不应该做什么 |
|---|---|---|
| 外部入口层 | 浏览器、SDK、API client、webhook、LLM provider 进入系统 | 不保存业务状态。 |
web 层 | UI、tRPC、Public API、ingestion HTTP endpoint | 不直接复制 shared 已有契约。 |
packages/shared 层 | 类型、Zod schema、队列名、DB/query/repository 契约 | 不 import web、worker、ee。 |
worker 层 | 消费 BullMQ job、批量写入、异步处理 | 不定义新的跨进程 payload 契约。 |
| 数据设施层 | Postgres、ClickHouse、Redis、S3/blob、Prisma | 不把业务规则散落在脚本里。 |
常用命令
| 命令 | 用途 |
|---|---|
pnpm install | 安装 workspace 依赖。 |
pnpm run dev | 启动主要开发进程。 |
pnpm run dev:web | 只启动 web。 |
pnpm run dev:worker | 只启动 worker。 |
pnpm run lint | 全仓 lint。 |
pnpm run typecheck | 全仓类型检查。 |
pnpm run build:check | Next.js build check。 |
pnpm run seed -- list | 查看可用 seed 场景。 |
pnpm run dev | 启动这本书的本地阅读站点。 |
pnpm run build | 构建这本书的静态站点。 |
pnpm run preview | 预览构建产物。 |
改动路线
| 你要做什么 | 推荐路线 |
|---|---|
| 新增 UI 功能 | 找 feature 目录 -> 找 tRPC router -> 找 shared schema/query -> 加测试和浏览器验证。 |
| 新增 Public API | 改 Fern contract -> 改 public API type/route -> 用 Zod 校验输入输出 -> 回归 API 测试。 |
| 新增 worker job | 先改 packages/shared/src/server/queues.ts -> 再加 producer -> 最后加 worker processor。 |
| 修改 ingestion 字段 | 先确认事件 schema -> 更新 S3/queue/worker/ClickHouse 写入链路 -> 加迁移和回归。 |
| 修改筛选能力 | 先读 web/src/features/search-bar/README.md -> 保持 grammar、validate、lower、FilterState 一致。 |
| 修改数据查询 | 从 shared query builder 或 repository 下手，不把 SQL 拼到 UI 组件里。 |
| 复刻类似 infra | 先读 ingestion 链路 -> 抽 queue/schema/writer/query contract -> 做第 8 篇实验课。 |
验证选择
| 改动范围 | 至少验证 |
|---|---|
| 文档站点 | pnpm run build。 |
web/** | pnpm run lint + 目标测试 + 真实浏览器检查。 |
worker/** | pnpm run lint + 目标 worker 测试。 |
packages/shared/** | pnpm run lint + 一个 web 侧检查 + 一个 worker 侧检查。 |
| Prisma 或 ClickHouse schema | pnpm run lint + pnpm run db:generate + 目标回归。 |
| Public API contract | pnpm run lint + API 测试 + Fern 更新或再生成。 |
判断边界
看到一个文件时，先问四个问题：
- 它是入口、契约、执行器，还是数据访问？
- 它的输入输出有没有 Zod 或 TypeScript 类型固定？
- 它是否跨进程、跨包、跨存储？
- 改它以后，哪个消费者最容易坏？
这四个问题通常比文件名更快定位风险。