---
url: /docs/api.md
---
# 接口概览

## 入口与职责

`apps/api/lib/app.ts` 组合业务路由与认证处理，`apps/api/worker.ts` 初始化数据库和认证实例。`apps/api/local.ts` 在本地 workerd 中运行同一 Worker bundle，`apps/api/dev.ts` 在开发监听模式下复用本地入口。

| 路径          | 职责                                       |
| ------------- | ------------------------------------------ |
| `/api/auth/*` | Better Auth 登录、会话、组织和订阅插件接口 |
| `/api/trpc/*` | 类型化业务查询与变更                       |

具体健康检查等路径以 `lib/app.ts` 为准。接口类型从 `@repo/api` 导出，工作台通过 `apps/app/lib/trpc.ts` 创建客户端。

## 业务模块

`routers/config.ts` 返回可公开的功能配置；`routers/billing.ts` 查询套餐和账单状态；`routers/workspace.ts` 处理工具记录与积分。新增模块后在 `lib/app.ts` 注册，才能被客户端调用。

## 身份与授权

公共接口用 `publicProcedure`，私有接口用 `protectedProcedure`。后者只保证登录，仍要针对用户 ID、组织成员和角色检查资源归属。不要相信前端传来的用户身份或积分价格。

每次请求的上下文包含 `db`、`dbCached`、`user`、`session` 和服务环境。默认使用实时 `db`；缓存连接只用于能接受旧数据的读取。

## 排查入口

接口 404：检查注册路径与公开站分流。401：检查会话 cookie 与请求来源。403：检查成员和角色。输入错误：查看字段校验结果。数据库错误：先核对连接、迁移和表名。服务配置错误：运行 `bun run config:check`。

继续阅读 [查询与变更接口](./procedures.md)、[请求上下文](./context.md) 和 [错误处理](./validation-errors.md)。