新增接口

创建与注册

先明确接口是公开查询还是私有操作，输入、返回字段和身份范围。下面创建一个当前用户摘要，不涉及新增数据表：

// apps/api/routers/profile.ts
import { protectedProcedure, router } from "../lib/trpc";

export const profileRouter = router({
  summary: protectedProcedure.query(({ ctx }) => ({
    id: ctx.user.id,
    name: ctx.user.name,
  })),
});

在 apps/api/lib/app.ts 导入并加入 appRouter 的 profile 属性。工作台即可通过统一客户端调用 trpcClient.profile.summary.query()。

查询模块

在 apps/app/lib/queries/ 定义唯一查询键与查询函数，再供组件使用。不要在多个页面各自创建不同键读取同一份数据。

变更使用 .mutation()，成功后刷新受影响查询。输入通过 Zod 校验；私有操作默认不重试，只有业务已具备幂等键时才能考虑自动重试。

数据与权限

按 ctx.user.id 或已校验组织范围过滤数据。组织账单、积分、权限及写后读用 ctx.db，不使用缓存连接。资源不存在与不可见如何返回，要避免泄露他人资源是否存在。

验证

使用私有路由调用测试合法输入、未登录和越权。涉及唯一约束、积分和事务时使用 PGlite 测试真实数据库语义，见 测试与排查。