refactor: 主动审计修复多处可观测性、依赖、代码质量缺口

通过并行 explore + librarian + 自查发现并修复:

代码缺陷
- shutdown.ts: db.$client.end().finally(...) 静默吞错——关闭失败会
  谎报 "DB pool closed" 后照常 exit 0。改用 await + try/catch
  分别记录成功/失败,setTimeout 也换成 Bun.sleep。
- interceptors.ts: 两条 instanceof ORPCError && instanceof
  ValidationError 重复检查,改用 early return + 单 if 分支区分 code。
- types.ts: 移除从未被引用的 RouterInputs 死代码(仅 RouterOutputs
  被 TodoItem 用到)。

Bun 原生 API(删/换 Node 兼容层)
- fields.ts: uuid v7 → Bun.randomUUIDv7(),删除 uuid 依赖
- migrate.ts: node:crypto.createHash → Bun.CryptoHasher.hash,
  少一个 Promise.all 项 + 一个 import
- shutdown.ts: setTimeout → Bun.sleep(顺带)

Biome 2.4 规则补强
- domains.types: "all"——开启类型感知规则集(noFloatingPromises /
  noMisusedPromises / useAwaitThenable / noUnnecessaryConditions
  等 Promise/异步陷阱)
- domains.drizzle: "recommended"、domains.react: "recommended"
- 显式开启 suspicious.noImportCycles(2.4 已 promote)

文档
- AGENTS.md 在 Stack & runtime 段加 "Prefer Bun-native APIs"
  原则,列出 UUIDv7/SHA-256/sleep/Bun.file 的优先路径
- AGENTS.md 在 Code style (Biome) 段记录本次启用的 lint domain
  与 noImportCycles 规则

验证:fix / typecheck / test 3/3 / build 568ms / compile 117M /
docker compose 全套(migrate JSON 日志 ✓、UUIDv7 写入 ✓、SIGTERM
shutdown 正确序列化 ✓)
This commit is contained in:
2026-04-25 17:06:22 +08:00
parent 815ee31f95
commit fafe02bdbd
9 changed files with 27 additions and 22 deletions
+2
View File
@@ -5,6 +5,7 @@ Compact, repo-specific notes for AI agents. Generic language/framework knowledge
## Stack & runtime
- **Bun-only** (`mise.toml` pins `bun = 1.3.13`). Never invoke `npm`/`npx`/`node`/`yarn`/`pnpm`. Use `bun run <script>` (bare `bun <script>` can collide with Bun built-in subcommands).
- **Prefer Bun-native APIs over external packages and `node:*` polyfills.** UUIDv7 → `Bun.randomUUIDv7()` (not the `uuid` package); SHA-256 → `Bun.CryptoHasher.hash('sha256', s, 'hex')` (not `node:crypto.createHash`); short sleeps → `Bun.sleep(ms)` (not raw `setTimeout` with promise wrapping); file I/O in build scripts → `Bun.file` / `Bun.write` are fine. The runtime is Bun, the deployment target is Bun, the test runner is Bun — there is no "portability" concern that would justify dragging in npm packages or Node compat shims for things Bun ships natively.
- TanStack Start (React 19 SSR, file-routed) + Vite 8 + Nitro (nightly, preset `bun`). Vite dev port is **strict 3000**.
- PostgreSQL + **Drizzle ORM `0.45.2` (0.x, NOT 1.0 beta)** — see "Drizzle" section, this matters a lot.
- ORPC (contract-first), TanStack Query v5, Tailwind v4.
@@ -97,6 +98,7 @@ Contract → Router → Handler → Client, all type-safe from a single contract
## Code style (Biome)
- 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"`.
- Lint domains enabled (Biome 2.4): `types: "all"` (catches `noFloatingPromises`, `noMisusedPromises`, `useAwaitThenable`, `noUnnecessaryConditions` — TS-aware async/promise traps), `drizzle: "recommended"`, `react: "recommended"`. `noImportCycles` is on under `suspicious`.
- **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`.