# AGENTS.md — @app/trpc

## 职责

API 层：**tRPC 路由 + service 业务逻辑**。service 可不依赖 tRPC 独立调用（脚本/测试）；DB 读写经 `@app/dao`，不直接写 SQL。

脚手架基线域：`user`、`auth`。新业务域在下游仓库按同样模式追加。

## 结构

```
src/
  context.ts              # initTRPC 单例 + TrpcContext
  router/
    index.ts              # appRouter 组装（权威定义）
    user.router.ts        # user 路由（与 index.ts 内定义重复，改路由时两边同步或收敛到一处）
    auth.router.ts        # auth 路由
  services/
    user.service.ts       # user 业务（调 userDao）
    auth.service.ts       # 会话 / 密码
    password.ts
  server.ts               # 独立 HTTP 服务（PORT，默认 4000）
  index.ts                # 对外：appRouter、类型、userService / authService
  router.ts               # 兼容旧入口的再导出
```

构建：`vite build`（`emptyOutDir: false`）→ `tsc -p tsconfig.dts.json` 产出 `.d.ts`。勿开 dts 的 incremental（vite 会先清产物，缓存会导致 tsc 跳过 emit）；勿改回 vite-plugin-dts。

## 请求流

```
web /api/trpc  ──►  appRouter  ──►  service  ──►  @app/dao  ──►  @app/db
```

也可 `yarn dev:api` 跑 `server.ts`（独立端口）；web SSR 内嵌时通常不用。

## 修改指南

1. **改入参**：先改 `@app/types` 的 Zod schema，再挂到 `t.procedure.input(...)`。
2. **加 procedure**：路由只做 input 映射 + 调 service；业务在 `services/*.service.ts`；SQL 在 `@app/dao`。
3. **加领域**：新建 `services/x.service.ts` + `router/x.router.ts`（必要时在 `@app/dao` 加 `xDao`），挂到 `appRouter`，并在 `index.ts` 导出。
4. 导出给前端的类型用 `RouterInputs` / `RouterOutputs`（来自 `router/index.ts`）。

## 约束

- `exactOptionalPropertyTypes`：service 的 update 入参写成 `name?: string | undefined`。
- `noUncheckedIndexedAccess`：判空逻辑在 DAO 内处理（参考 `userDao.create`）。
- 不要在 router/service 里写 SQL；不在 service 里依赖 HTTP/tRPC context（除非鉴权明确需要）。
- `router.ts` 仅兼容旧 import，新代码从 `index.ts` / `./router/index.js` 引入。

## 命令

```bash
yarn workspace @app/trpc typecheck
yarn workspace @app/trpc lint
yarn workspace @app/trpc build
yarn workspace @app/trpc dev      # tsx watch src/server.ts
```