docs: 新增 README，AGENTS 同步至当前架构

- README: 用户向 quick-start、scripts 表、add-a-feature checklist、deploy 流程
- AGENTS:
  - 修订 stale 文案（VITE_APP_TITLE/experimental_defaults/.gitkeep/route 组件风格）
  - 新增 Testing 段（bun test 约定）和 Endpoints 段（/, /health, /api/*）
  - Layout 补 logger.ts、health.ts、components/、styles.css、根 drizzle/
  - 追加 10 条 room-to-grow 纪律（client query / middleware / interceptor / 测试等扩展边界）

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Compact, repo-specific notes for AI agents. Generic language/framework knowledge is omitted — only things that will bite you if you don't know.
+Compact, repo-specific notes for AI agents. Generic language/framework knowledge is omitted — only things that will bite you if you don't know. Pair this with `README.md` (user-facing quick-start + add-a-feature checklist + deploy flow).
 
 ## Stack & runtime
 
@@ -17,6 +17,7 @@ bun run build        # bunx --bun vite build → .output/
 bun run compile      # bun compile.ts → out/server-<target> (standalone CLI binary)
 bun run cli <cmd>    # bun bin.ts <cmd>  — run a CLI subcommand in source (dev)
 bun run typecheck    # tsc --noEmit
+bun run test         # bun test  — runs all *.test.ts files (colocated with source)
 bun run fix          # biome check --write  (lint + format + organize imports)
 bun run db:push      # dev only — push schema to DB, no migration file
 bun run db:generate  # produce SQL migration files in ./drizzle
@@ -26,7 +27,7 @@ bun run db:studio    # Drizzle Studio
 
 Cross-compile targets live under `compile:{linux,darwin,windows}[:arch]`. `compile.ts` accepts `--target bun-<os>-<arch>`; default derives from host.
 
-Before committing: `bun run fix && bun run typecheck`. No CI, no pre-commit hooks, no lint-staged — so these are on you.
+Before committing: `bun run fix && bun run typecheck && bun run test`. No CI, no pre-commit hooks, no lint-staged — so these are on you.
 
 ## Drizzle (v0.x — critical)
 
@@ -46,7 +47,7 @@ Before committing: `bun run fix && bun run typecheck`. No CI, no pre-commit hook
 - Every table must spread `...generatedFields` from `src/server/db/fields.ts` (`id` UUIDv7 via `$defaultFn(uuidv7)`, `createdAt`, `updatedAt` with `$onUpdateFn`). `generatedFieldKeys` (hand-written `as const`) feeds `createInsertSchema(...).omit(...)`.
 - `src/server/db/index.ts` exports a module-level `const db = drizzle(...)` — not a lazy singleton. On Bun this is a long-lived process, so top-level side effects are fine and requested. Don't reintroduce `getDB/closeDB` ceremony; the Nitro shutdown plugin calls `db.$client.end()` directly. (Cloudflare Workers would need per-request init — we don't support that deployment target.)
 - `drizzle.config.ts` runs outside Vite — `@/*` path aliases do NOT resolve there. It currently does `import { env } from './src/env'` (relative). Preserve that.
-- The `./drizzle/` migrations directory is gitignored-by-absence right now (no migrations yet). Migrations are applied via the CLI (`./server migrate`, see "CLI & single-binary deploy" below), NOT at server startup. Dev uses `db:push`. Don't mix `push` and `migrate` on the same DB.
+- The `./drizzle/` migrations directory ships empty with a `.gitkeep`. Migrations are applied via the CLI (`./server migrate`, see "CLI & single-binary deploy" below), NOT at server startup. Dev uses `db:push`. Don't mix `push` and `migrate` on the same DB.
 
 ## CLI & single-binary deploy
 
@@ -77,19 +78,31 @@ Contract → Router → Handler → Client, all type-safe from a single contract
   ```
   Barrel-aggregated in `contracts/index.ts` as `export const contract = { todo }`.
 - Routers (`src/server/api/routers/*.router.ts`) import `db` directly from `@/server/db` in their handlers. There is **no `middlewares/` directory** by default — `db` doesn't need one (module-level const). When you actually need per-request context (auth, tenant, rate-limit), create `src/server/api/middlewares/<name>.middleware.ts` with `os.middleware(...)` and extend `BaseContext` in `context.ts`.
-- **Interceptors are attached at the handler level, not in `server.ts` and not on `os`.** Both `src/routes/api/rpc.$.ts` (`RPCHandler`) and `src/routes/api/$.ts` (`OpenAPIHandler`) register `[onError(logError)]` (server) and `[onError(handleValidationError)]` (client). The validation interceptor rewrites `BAD_REQUEST + ValidationError` into `INPUT_VALIDATION_FAILED` (422) and output validation errors into `OUTPUT_VALIDATION_FAILED`.
+- **Interceptors are attached at the handler level, not in `server.ts` and not on `os`.** Both `src/routes/api/rpc.$.ts` (`RPCHandler`) and `src/routes/api/$.ts` (`OpenAPIHandler`) register `[onError(logError)]` (server) and `[onError(handleValidationError)]` (client). The validation interceptor rewrites `BAD_REQUEST + ValidationError` into `INPUT_VALIDATION_FAILED` (422) and output validation errors into `OUTPUT_VALIDATION_FAILED`. `logError` calls `logger.error` from `@/server/logger` — never `console.*` directly.
 - OpenAPI/Scalar: docs at `/api/docs`, spec at `/api/spec.json` (handler prefix `/api`, plugin paths `/docs` and `/spec.json`).
 - **SSR isomorphism** (`src/client/orpc.ts`): `createIsomorphicFn().server(createRouterClient(...)).client(new RPCLink(...))`. Server branch reads `getRequestHeaders()` for context; client branch POSTs to `${origin}/api/rpc`.
-- **Global mutation invalidation** uses `experimental_defaults` in `createTanstackQueryUtils(...)` — currently invalidates `orpc.todo.list.key()` on every `todo.{create,update,remove}` success. Add new features here rather than in each mutation site.
+- **Mutation invalidation is colocated at the call site** via `mutationOptions({ onSuccess })`, not in `src/client/orpc.ts`. `orpc` in `src/client/orpc.ts` is a plain `createTanstackQueryUtils(client)` — no `experimental_defaults`. Per-feature query helpers live in `src/client/queries/<feature>.ts` (e.g. `useInvalidateTodos`); routes/components compose those hooks rather than holding query keys inline. See `src/client/queries/todo.ts` + `src/routes/index.tsx` for the canonical shape.
 - SSR prefetch in route loaders: `await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions())`. Components use `useSuspenseQuery(orpc.feature.list.queryOptions())`.
 
 ## Code style (Biome)
 
-- 2-space, LF, single quotes, **semicolons as-needed** (omitted unless required), 120-col, arrow parens always, `useArrowFunction: "error"` — so React components must be `const Foo = () => {...}` not `function Foo() {}`. Also `noReactPropAssignments: "error"`.
+- 2-space, LF, single quotes, **semicolons as-needed** (omitted unless required), 120-col, arrow parens always, `useArrowFunction: "error"` (covers function *expressions* only). Also `noReactPropAssignments: "error"`.
+- **Route components use `function Foo()` declarations**, placed below the `Route` config so the file reads top-down (route on top, component below). This is the official TanStack Router/Start pattern and relies on hoisting — `const Foo = () => {}` would TDZ-error when referenced from `createFileRoute({ component: Foo })` above it. Inline arrows are fine for trivial leaf components (e.g. plain redirect routes). Non-route components (UI primitives in `src/components/`) use `const Foo = () => {}`.
 - Imports are auto-organized into two groups (external, then `@/*`), each alphabetical, with `import type` interleaved (NOT a separate group). `bun run fix` handles this; don't hand-sort.
 - Files: utils `kebab-case.ts`, components `PascalCase.tsx`.
 - `routeTree.gen.ts` is generated — ignored by Biome, never edit.
 
+## Testing
+
+`bun test` runs all `*.test.ts` files. Tests are colocated next to the source they exercise (e.g. `src/server/api/contracts/todo.contract.test.ts`). Use `import { describe, expect, test } from 'bun:test'`. The `@/*` alias resolves in tests via tsconfig paths. No Vitest, no Jest, no separate test config — keep it that way unless you need a browser/JSDOM environment.
+
+## Endpoints
+
+- `/` — Todos UI (file route).
+- `/health` — bare `GET` returning `ok` (200, `text/plain`). Liveness only — no DB check, so it stays green even when Postgres is down. Add a separate `/ready` if you ever need readiness.
+- `/api/rpc` — ORPC RPC handler (POST).
+- `/api/*` — ORPC OpenAPI handler. Docs at `/api/docs`, spec at `/api/spec.json`.
+
 ## TypeScript
 
 Strict mode, plus `noUncheckedIndexedAccess`, `verbatimModuleSyntax`, `erasableSyntaxOnly`, `noImplicitOverride`. No `as any` / `@ts-ignore` / `@ts-expect-error`.
@@ -98,7 +111,7 @@ Path alias: `@/* → src/*`. For files outside `src/` use `@/../<file>` (example
 
 ## Env
 
-`src/env.ts` via `@t3-oss/env-core`. Server: `DATABASE_URL` (required, `z.url()`). Client needs `VITE_` prefix (`VITE_APP_TITLE` optional). Never commit `.env`.
+`src/env.ts` via `@t3-oss/env-core`. Server: `DATABASE_URL` (required, `z.url()`). `client: {}` is empty by default — any client-side env must be `VITE_`-prefixed. Never commit `.env`.
 
 ## Docker / deploy
 
@@ -111,33 +124,44 @@ Path alias: `@/* → src/*`. For files outside `src/` use `@/../<file>` (example
 
 ```
 src/
-├── client/orpc.ts              # isomorphic ORPC client + experimental_defaults invalidation
+├── client/
+│   ├── orpc.ts                 # isomorphic ORPC client + TanStack Query utils (no global invalidation defaults)
+│   └── queries/                # per-feature query hooks: keys, options, `useInvalidate<Feature>` helpers
 ├── cli/                        # CLI subcommands (loaded lazily by bin.ts via citty)
 │   ├── serve.ts                # `./server serve` — imports the Nitro bridge on demand
 │   ├── migrate.ts              # `./server migrate` — drizzle migrate against ./drizzle
 │   ├── _serve-nitro.mjs        # bridge: `import('../../.output/server/index.mjs')`
 │   └── _serve-nitro.d.mts      # types for the bridge (build output has no .d.ts)
-├── routes/api/
+├── routes/
+│   ├── __root.tsx              # root route + RootDocument shell
+│   ├── index.tsx               # Todos UI
+│   ├── health.ts               # GET /health → "ok" (no DB)
+│   └── api/
 │       ├── $.ts                # OpenAPI + Scalar; interceptors registered here
 │       └── rpc.$.ts            # RPC; interceptors registered here
 ├── server/
+│   ├── logger.ts               # the only log entrypoint — wrap before swapping to pino/otel
 │   ├── api/
 │   │   ├── server.ts           # the ONLY place to build `os`
 │   │   ├── context.ts          # BaseContext (add per-request fields when you add middlewares)
-│   │   ├── interceptors.ts     # logError, handleValidationError
+│   │   ├── interceptors.ts     # logError (→ logger), handleValidationError
 │   │   ├── types.ts            # Router{Client,Inputs,Outputs} derived from Contract
-│   │   ├── contracts/          # Zod schemas from Drizzle tables (barrel: contract)
+│   │   ├── contracts/          # Zod schemas from Drizzle tables (barrel: contract); colocated *.test.ts
 │   │   └── routers/            # os.* handlers (barrel: router) — import db directly
 │   ├── db/
 │   │   ├── index.ts            # module-level `export const db = drizzle({...})`
 │   │   ├── fields.ts           # generatedFields (id/createdAt/updatedAt) + generatedFieldKeys
 │   │   └── schema/             # pgTable definitions; also put `relations()` here when adding
 │   └── plugins/
-│       └── shutdown.ts         # SIGINT/SIGTERM → db.$client.end() with 500ms delay
+│       └── shutdown.ts         # SIGINT/SIGTERM → db.$client.end() with 500ms delay (prod only)
+├── components/                 # non-route UI primitives (PascalCase, arrow const)
 ├── env.ts                      # t3-oss env validation
 ├── router.tsx                  # QueryClient + setupRouterSsrQueryIntegration
+├── styles.css                  # Tailwind v4 entry
 └── routeTree.gen.ts            # auto-generated, do not edit
 bin.ts                          # citty entry (root) — keep imports minimal (see "CLI" section)
+compile.ts                      # `bun build --compile` driver; resolves --target
+drizzle/                        # SQL migrations (.gitkeep until first `bun run db:generate`)
 ```
 
 Nitro plugins are wired in `vite.config.ts` (`nitro({ plugins: [...] })`), not via a Nitro config file.
@@ -154,3 +178,18 @@ Nitro plugins are wired in `vite.config.ts` (`nitro({ plugins: [...] })`), not v
 - Don't use `drizzle-orm/bun-sql`.
 - Don't use `@/*` aliases in `drizzle.config.ts`.
 - Don't commit `.env`.
+
+## Room-to-grow rules (discipline for the first real feature)
+
+These keep the starter from setting bad precedents as it grows. Append, don't restructure.
+
+1. Per-feature client query code — keys, options, `useInvalidate<Feature>` helpers — lives in `src/client/queries/<feature>.ts`. Routes/components compose these hooks; they don't hold query keys inline.
+2. Mutation invalidation stays explicit at the mutation call site (`mutationOptions({ onSuccess })`) or in a feature query helper. Do not reintroduce global `experimental_defaults` or any implicit cache policy.
+3. Client state defaults to route/component local state. Create a store (zustand or equivalent) only when state is shared across routes or needs persistence.
+4. Middlewares (`src/server/api/middlewares/<name>.middleware.ts`) derive request-scoped context or gate access. They do NOT orchestrate business flow, hold side effects, or replace handlers/services.
+5. Interceptors (`src/server/api/interceptors.ts`) do cross-cutting error logging, transport normalization, and validation rewrites. They do NOT read business data.
+6. One file per Drizzle table. Relations live in the same file and are exported as `<entity>Relations`. No global `relations.ts`.
+7. One router file per feature (`routers/<feature>.router.ts`). Only introduce `routers/<domain>/index.ts` when a domain grows past ~5 router files or needs shared domain helpers.
+8. All server-side logging goes through `src/server/logger.ts`. Do not call `console.error/info/warn` directly from business code.
+9. CLI subcommand modules keep top-level imports to `citty` + Node built-ins. Env, db, and server code are `await import(...)`-ed inside `run()` (see `bin.ts` comment for why).
+10. Every new business feature ships with at least one `bun test` covering a contract schema, a pure helper, or a router behavior.

README.md

@@ -0,0 +1,61 @@
+# fullstack-starter
+
+Opinionated single-binary fullstack starter. Bun + TanStack Start (React 19 SSR) + ORPC (contract-first) + Drizzle + PostgreSQL, deployed as one compiled executable.
+
+> Agent notes and non-obvious invariants live in [AGENTS.md](./AGENTS.md). Read it before making structural changes.
+
+## Quick start
+
+```bash
+cp .env.example .env
+bun install
+bun run db:push     # dev: sync schema without migration files
+bun run dev         # http://localhost:3000
+```
+
+RPC endpoint: `/api/rpc` · OpenAPI docs: `/api/docs` · Spec: `/api/spec.json` · Liveness: `/health`.
+
+## Scripts
+
+| Command | What it does |
+| --- | --- |
+| `bun run dev` | Vite dev server on port 3000 (strict) |
+| `bun run build` | Build to `.output/` |
+| `bun run compile` | Single-binary `out/server-<target>` via `bun build --compile` |
+| `bun run cli <cmd>` | Run a CLI subcommand in source (`serve`, `migrate`) |
+| `bun run typecheck` | `tsc --noEmit` |
+| `bun run fix` | Biome lint + format + organize imports |
+| `bun run db:push` | Dev-only schema sync (no migration files) |
+| `bun run db:generate` | Write SQL migrations to `./drizzle` |
+| `bun run db:migrate` | Apply migrations locally via drizzle-kit |
+| `bun run db:studio` | Drizzle Studio |
+
+Cross-compile: `bun run compile:{linux,darwin,windows}[:arch]`.
+
+## Add a feature (e.g. `post`)
+
+Contract-first, additive. Create or touch files in this order:
+
+1. `src/server/db/schema/post.ts` — define `postTable`, spread `...generatedFields`.
+2. `src/server/db/schema/index.ts` — `export * from './post'`.
+3. `src/server/api/contracts/post.contract.ts` — derive Zod from the table via `drizzle-zod`.
+4. `src/server/api/contracts/index.ts` — add `post` to the `contract` object.
+5. `src/server/api/routers/post.router.ts` — implement `os.post.*.handler(...)`.
+6. `src/server/api/routers/index.ts` — add `post` to the `router` object.
+7. `src/routes/<page>.tsx` — UI with `useSuspenseQuery` + loader `ensureQueryData`; invalidate affected list queries in mutation `onSuccess` handlers.
+8. `bun run db:generate` — emit SQL migrations to `./drizzle`.
+
+## Deploy
+
+Always **migrate-then-serve**. Migrations are an explicit deploy step, never a server startup hook.
+
+```bash
+./server migrate   # applies ./drizzle against $DATABASE_URL
+./server           # starts HTTP server (default subcommand)
+```
+
+`Dockerfile` copies `./drizzle/` next to the binary. `compose.yaml` models the pattern with a one-shot `migrate` service that `app` depends on (`service_completed_successfully`). On Kubernetes: run `./server migrate` as an initContainer or Helm `pre-upgrade` Job.
+
+```bash
+docker compose up --build
+```

compose.yaml

@@ -23,8 +23,6 @@ services:
 
   db:
     image: postgres:18-alpine
-    # ports:
-    #   - "5432:5432"
     volumes:
       - postgres_data:/var/lib/postgresql
     environment:

package.json

@@ -21,6 +21,7 @@
     "db:studio": "drizzle-kit studio",
     "dev": "bunx --bun vite dev",
     "fix": "biome check --write",
+    "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

public/robots.txt

@@ -1,3 +1,2 @@
-# https://www.robotstxt.org/robotstxt.html
 User-agent: *
 Disallow:

src/client/orpc.ts

@@ -24,30 +24,4 @@ const getORPCClient = createIsomorphicFn()
 
 const client: RouterClient = getORPCClient()
 
-export const orpc = createTanstackQueryUtils(client, {
-  experimental_defaults: {
-    todo: {
-      create: {
-        mutationOptions: {
-          onSuccess: (_, __, ___, ctx) => {
-            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
-          },
-        },
-      },
-      update: {
-        mutationOptions: {
-          onSuccess: (_, __, ___, ctx) => {
-            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
-          },
-        },
-      },
-      remove: {
-        mutationOptions: {
-          onSuccess: (_, __, ___, ctx) => {
-            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
-          },
-        },
-      },
-    },
-  },
-})
+export const orpc = createTanstackQueryUtils(client)

src/client/queries/todo.ts

@@ -0,0 +1,7 @@
+import { useQueryClient } from '@tanstack/react-query'
+import { orpc } from '@/client/orpc'
+
+export const useInvalidateTodos = () => {
+  const queryClient = useQueryClient()
+  return () => queryClient.invalidateQueries({ queryKey: orpc.todo.list.key() })
+}

src/env.ts

@@ -6,9 +6,7 @@ export const env = createEnv({
     DATABASE_URL: z.url(),
   },
   clientPrefix: 'VITE_',
-  client: {
-    VITE_APP_TITLE: z.string().min(1).optional(),
-  },
+  client: {},
   runtimeEnv: process.env,
   emptyStringAsUndefined: true,
 })

src/routeTree.gen.ts

@@ -9,10 +9,16 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
+import { Route as HealthRouteImport } from './routes/health'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as ApiSplatRouteImport } from './routes/api/$'
 import { Route as ApiRpcSplatRouteImport } from './routes/api/rpc.$'
 
+const HealthRoute = HealthRouteImport.update({
+  id: '/health',
+  path: '/health',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
@@ -31,36 +37,47 @@ const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/health': typeof HealthRoute
   '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/health': typeof HealthRoute
   '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/health': typeof HealthRoute
   '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/api/$' | '/api/rpc/$'
+  fullPaths: '/' | '/health' | '/api/$' | '/api/rpc/$'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/api/$' | '/api/rpc/$'
-  id: '__root__' | '/' | '/api/$' | '/api/rpc/$'
+  to: '/' | '/health' | '/api/$' | '/api/rpc/$'
+  id: '__root__' | '/' | '/health' | '/api/$' | '/api/rpc/$'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  HealthRoute: typeof HealthRoute
   ApiSplatRoute: typeof ApiSplatRoute
   ApiRpcSplatRoute: typeof ApiRpcSplatRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/health': {
+      id: '/health'
+      path: '/health'
+      fullPath: '/health'
+      preLoaderRoute: typeof HealthRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -87,6 +104,7 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  HealthRoute: HealthRoute,
   ApiSplatRoute: ApiSplatRoute,
   ApiRpcSplatRoute: ApiRpcSplatRoute,
 }

src/routes/__root.tsx

@@ -4,6 +4,7 @@ import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
 import { createRootRouteWithContext, HeadContent, Scripts } from '@tanstack/react-router'
 import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
 import type { ReactNode } from 'react'
+import { name } from '@/../package.json'
 import { ErrorComponent } from '@/components/Error'
 import { NotFoundComponent } from '@/components/NotFound'
 import appCss from '@/styles.css?url'
@@ -23,7 +24,7 @@ export const Route = createRootRouteWithContext<RouterContext>()({
         content: 'width=device-width, initial-scale=1',
       },
       {
-        title: 'Furtherverse',
+        title: name,
       },
     ],
     links: [

src/routes/health.ts

@@ -0,0 +1,9 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/health')({
+  server: {
+    handlers: {
+      GET: () => new Response('ok', { status: 200, headers: { 'content-type': 'text/plain' } }),
+    },
+  },
+})

src/routes/index.tsx

@@ -1,6 +1,7 @@
 import { useMutation, useSuspenseQuery } from '@tanstack/react-query'
 import { createFileRoute } from '@tanstack/react-router'
 import { orpc } from '@/client/orpc'
+import { useInvalidateTodos } from '@/client/queries/todo'
 import { TodoForm } from '@/components/TodoForm'
 import { TodoItem } from '@/components/TodoItem'
 
@@ -13,9 +14,11 @@ export const Route = createFileRoute('/')({
 
 function Todos() {
   const listQuery = useSuspenseQuery(orpc.todo.list.queryOptions())
-  const createMutation = useMutation(orpc.todo.create.mutationOptions())
-  const updateMutation = useMutation(orpc.todo.update.mutationOptions())
-  const deleteMutation = useMutation(orpc.todo.remove.mutationOptions())
+  const invalidateTodos = useInvalidateTodos()
+
+  const createMutation = useMutation(orpc.todo.create.mutationOptions({ onSuccess: invalidateTodos }))
+  const updateMutation = useMutation(orpc.todo.update.mutationOptions({ onSuccess: invalidateTodos }))
+  const deleteMutation = useMutation(orpc.todo.remove.mutationOptions({ onSuccess: invalidateTodos }))
 
   const todos = listQuery.data
   const completedCount = todos.filter((todo) => todo.completed).length
@@ -25,7 +28,6 @@ function Todos() {
   return (
     <div className="min-h-screen bg-slate-50 py-12 px-4 sm:px-6 font-sans">
       <div className="max-w-2xl mx-auto space-y-8">
-        {/* Header */}
         <div className="flex items-end justify-between">
           <div>
             <h1 className="text-3xl font-bold text-slate-900 tracking-tight">我的待办</h1>
@@ -42,7 +44,6 @@ function Todos() {
 
         <TodoForm onSubmit={(title) => createMutation.mutate({ title })} isPending={createMutation.isPending} />
 
-        {/* Progress Bar */}
         {totalCount > 0 && (
           <div className="h-1.5 w-full bg-slate-200 rounded-full overflow-hidden">
             <div
@@ -52,7 +53,6 @@ function Todos() {
           </div>
         )}
 
-        {/* Todo List */}
         <div className="space-y-3">
           {todos.length === 0 ? (
             <div className="py-20 text-center">

src/server/api/contracts/todo.contract.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'bun:test'
+import { createInsertSchema } from 'drizzle-zod'
+import { generatedFieldKeys } from '@/server/db/fields'
+import { todoTable } from '@/server/db/schema'
+
+describe('todo insert schema', () => {
+  const insertSchema = createInsertSchema(todoTable).omit(generatedFieldKeys)
+
+  test('accepts a minimal valid input', () => {
+    expect(insertSchema.safeParse({ title: 'buy milk' }).success).toBe(true)
+  })
+
+  test('rejects missing title', () => {
+    expect(insertSchema.safeParse({}).success).toBe(false)
+  })
+
+  test('rejects non-string title', () => {
+    expect(insertSchema.safeParse({ title: 42 }).success).toBe(false)
+  })
+})

src/server/api/interceptors.ts

@@ -1,13 +1,14 @@
 import { ORPCError, ValidationError } from '@orpc/server'
 import { z } from 'zod'
+import { logger } from '@/server/logger'
 
 export const logError = (error: unknown) => {
-  console.error(error)
+  logger.error(error)
 }
 
 export const handleValidationError = (error: unknown) => {
   if (error instanceof ORPCError && error.code === 'BAD_REQUEST' && error.cause instanceof ValidationError) {
-    // If you only use Zod you can safely cast to ZodIssue[] (per ORPC official docs)
+    // ORPC ValidationError.issues are Zod issues in this app.
     const zodError = new z.ZodError(error.cause.issues as z.core.$ZodIssue[])
 
     throw new ORPCError('INPUT_VALIDATION_FAILED', {

src/server/db/index.ts

@@ -6,5 +6,3 @@ export const db = drizzle({
   connection: env.DATABASE_URL,
   schema,
 })
-
-export type DB = typeof db

src/server/logger.ts

@@ -0,0 +1,5 @@
+export const logger = {
+  error: (error: unknown) => console.error(error),
+  warn: (...args: unknown[]) => console.warn(...args),
+  info: (...args: unknown[]) => console.info(...args),
+}

src/server/plugins/shutdown.ts

@@ -5,15 +5,14 @@ export default () => {
 
   let exiting = false
 
-  const shutdown = async () => {
+  const shutdown = () => {
     if (exiting) {
       process.exit(0)
     }
     exiting = true
 
-    setTimeout(async () => {
-      await db.$client.end()
-      process.exit(0)
+    setTimeout(() => {
+      db.$client.end().finally(() => process.exit(0))
     }, 500)
   }