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 / 测试等扩展边界）
2026-04-25 13:31:45 +08:00
parent 6dc7f9f791
commit a3a62c24b9
2 changed files with 114 additions and 14 deletions
@@ -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
+```