imbytecat/kairos
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 重新梳理 AGENTS.md — 精简去重 + 修正过时模式 + 新增 DnD/Virtual 文档

Browse Source 
- 根 AGENTS.md 242→135 行，去掉冗余 compile 命令和重复目录树
- server AGENTS.md 408→220 行，移除与根重复的 Code Style 章节
- 修正 ORPC 契约/路由路径（定义在模块内，非 server/api/）
- 新增 @dnd-kit/helpers move()、@tanstack/react-virtual、MutationCache 模式
This commit is contained in:
imbytecat
2026-03-31 17:42:56 +08:00
parent 001d171111
commit d67aaa723e
2 changed files with 213 additions and 420 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+31 -126
View File
@@ -6,37 +6,16 @@ Guidelines for AI agents working in this Bun monorepo.
> **Kairos 是一个人生操作系统（Personal Life OS）。所有开发决策必须服务于这个愿景。** > **Kairos 是一个人生操作系统（Personal Life OS）。所有开发决策必须服务于这个愿景。**
Kairos 将个人生活的每一个维度 —— 财务、订阅、健康、资产、决策 —— 整合进一个统一的、自托管的平台。它不是又一个效率工具或仪表盘，而是一个完整的操作系统。 Kairos 将个人生活的每一个维度 —— 财务、订阅、健康、资产、决策 —— 整合进一个统一的、自托管的平台。
### 核心模块
| 模块 | 职责 |
|------|------|
| **财务** | 银行账户、交易流水、消费分析、预算追踪 |
| **订阅** | 周期性服务管理 —— 费用、续期、使用频率 |
| **健康** | 身体指标、习惯、睡眠、营养 |
| **资产** | 实体与数字资产、保修、生命周期追踪 |
| **日志** | 决策、复盘、人生事件 |
| **集成** | API 对接、数据导入、自动化 |
每个模块是同一个统一数据层的不同视角，模块之间的数据可以交叉关联和分析。
### 设计信条 ### 设计信条
1. **数据主权** —— 自托管、本地优先。用户数据不离开用户的机器，除非用户自己决定。所有功能必须在无外部云依赖的情况下完整可用。 1. **数据主权** —— 自托管、本地优先。用户数据不离开用户的机器，除非用户自己决定。
2. **关联即洞察** —— 孤立数据是噪音，关联数据是洞察。所有模块共享统一数据层，设计时必须考虑跨模块的数据关联能力。 2. **关联即洞察** —— 孤立数据是噪音，关联数据是洞察。所有模块共享统一数据层。
3. **可扩展基座** —— Kairos 是有主见的基座，不是封闭成品。架构必须支持模块的独立扩展和自定义。 3. **可扩展基座** —— 架构必须支持模块的独立扩展和自定义。
### 架构原则
- **契约优先 API** —— 每个端点从类型化契约定义开始，实现紧随其后。一份契约，Web 和 CLI 两个消费者共享。
- **Web + CLI 双入口** —— Web 应用是主界面；CLI 调用同一套 API，支持脚本编排、自动化、快速数据录入。
- **编译为单文件** —— 服务端编译为独立 Bun 二进制，零运行时依赖，部署极简。
### Agent 决策指南 ### Agent 决策指南
在做任何设计或实现决策时，用以下问题自检：
- **这是否让用户更完整地掌控自己的数据？** 如果否，重新考虑。 - **这是否让用户更完整地掌控自己的数据？** 如果否，重新考虑。
- **这个模块的数据是否可以被其他模块关联使用？** 如果不能，说明数据模型设计有问题。 - **这个模块的数据是否可以被其他模块关联使用？** 如果不能，说明数据模型设计有问题。
- **这个功能是否可以在完全离线/自托管环境下工作？** 如果不能，必须提供无外部依赖的替代方案。 - **这个功能是否可以在完全离线/自托管环境下工作？** 如果不能，必须提供无外部依赖的替代方案。
@@ -44,78 +23,46 @@ Kairos 将个人生活的每一个维度 —— 财务、订阅、健康、资
## Project Overview ## Project Overview
> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run <script>` for scripts. Always prefer `bun run <script>` over `bun <script>` to avoid conflicts with Bun built-in subcommands (e.g. `bun build` invokes Bun's bundler, NOT your package.json script). Never use `npm`, `npx`, or `node`.** > **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. Always prefer `bun run <script>` over `bun <script>` to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, or `node`.**
- **Monorepo**: Bun workspaces + Turborepo orchestration - **Monorepo**: Bun workspaces + Turborepo orchestration
- **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js** - **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js**
- **Package Manager**: Bun — **NOT npm / yarn / pnpm** - **Package Manager**: Bun — **NOT npm / yarn / pnpm**
- **Apps**: - **Apps**: `apps/server` — TanStack Start fullstack web app (see `apps/server/AGENTS.md`)
- `apps/server` - TanStack Start fullstack web app (see `apps/server/AGENTS.md`) - **Packages**: `packages/tsconfig` — shared TS configs
- **Packages**: `packages/tsconfig` (shared TS configs)
## Build / Lint / Test Commands ## Build / Lint / Test Commands
### Root Commands (via Turbo)
```bash ```bash
# Root (via Turbo)
bun run dev # Start all apps in dev mode bun run dev # Start all apps in dev mode
bun run build # Build all apps bun run build # Build all apps
bun run compile # Compile server to standalone binary (current platform) bun run compile # Compile server to standalone binary
bun run compile:darwin # Compile server for macOS (arm64 + x64)
bun run compile:linux # Compile server for Linux (x64 + arm64)
bun run compile:windows # Compile server for Windows x64
bun run fix # Lint + format (Biome auto-fix) bun run fix # Lint + format (Biome auto-fix)
bun run typecheck # TypeScript check across monorepo bun run typecheck # TypeScript check across monorepo
```
### Server App (`apps/server`) # Database (in apps/server)
```bash bun run db:generate # Generate migrations from schema
bun run dev # Vite dev server (localhost:3000) bun run db:migrate # Run migrations
bun run build # Production build -> .output/ bun run db:push # Push schema (dev only)
bun run compile # Compile to standalone binary (current platform) bun run db:studio # Open Drizzle Studio
bun run compile:darwin # Compile for macOS (arm64 + x64)
bun run compile:darwin:arm64 # Compile for macOS arm64
bun run compile:darwin:x64 # Compile for macOS x64
bun run compile:linux # Compile for Linux (x64 + arm64)
bun run compile:linux:arm64 # Compile for Linux arm64
bun run compile:linux:x64 # Compile for Linux x64
bun run compile:windows # Compile for Windows (default: x64)
bun run compile:windows:x64 # Compile for Windows x64
bun run fix # Biome auto-fix
bun run typecheck # TypeScript check
# Database (Drizzle) # Testing (not yet configured)
bun run db:generate # Generate migrations from schema bun test path/to/test.ts # Run single test file
bun run db:migrate # Run migrations
bun run db:push # Push schema (dev only)
bun run db:studio # Open Drizzle Studio
```
### Testing
No test framework configured yet. When adding tests:
```bash
bun test path/to/test.ts # Run single test file
bun test -t "pattern" # Run tests matching pattern
``` ```
## Code Style (TypeScript) ## Code Style (TypeScript)
### Formatting (Biome) ### Formatting (Biome)
- **Indent**: 2 spaces | **Line endings**: LF - **Indent**: 2 spaces | **Line width**: 120 | **Line endings**: LF
- **Quotes**: Single `'` | **Semicolons**: Omit (ASI) - **Quotes**: Single `'` | **Semicolons**: Omit (ASI)
- **Arrow parentheses**: Always `(x) => x` - **Arrow parentheses**: Always `(x) => x`
### Imports ### Imports
Biome auto-organizes. Order: 1) External packages → 2) Internal `@/*` aliases → 3) Type imports (`import type { ... }`) Biome auto-organizes. Order: 1) External packages → 2) Internal `@/*` aliases → 3) Type imports (`import type { ... }`)
```typescript
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'
import { db } from '@/server/db'
import type { ReactNode } from 'react'
```
### TypeScript Strictness ### TypeScript Strictness
- `strict: true`, `noUncheckedIndexedAccess: true`, `noImplicitOverride: true`, `verbatimModuleSyntax: true` - `strict: true`, `noUncheckedIndexedAccess: true`, `verbatimModuleSyntax: true`
- Use `@/*` path aliases (maps to `src/*`) - Use `@/*` path aliases (maps to `src/*`)
### Naming Conventions ### Naming Conventions
@@ -127,16 +74,16 @@ import type { ReactNode } from 'react'
| Functions | camelCase | `getUserById` | | Functions | camelCase | `getUserById` |
| Constants | UPPER_SNAKE | `MAX_RETRIES` | | Constants | UPPER_SNAKE | `MAX_RETRIES` |
| Types/Interfaces | PascalCase | `UserProfile` | | Types/Interfaces | PascalCase | `UserProfile` |
| Drizzle tables | camelCase, no suffix | `user`, `category` (NOT `userTable`) |
### React Patterns ### React Patterns
- Components: arrow functions (enforced by Biome) - Components: arrow functions (enforced by Biome)
- Routes: TanStack Router file conventions (`export const Route = createFileRoute(...)`)
- Data fetching: `useSuspenseQuery(orpc.feature.list.queryOptions())` - Data fetching: `useSuspenseQuery(orpc.feature.list.queryOptions())`
- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`) - Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)
### Error Handling ### Error Handling
- Use `try-catch` for async operations; throw descriptive errors - Use `try-catch` for async operations; throw descriptive errors
- ORPC: Use `ORPCError` with proper codes (`NOT_FOUND`, `INPUT_VALIDATION_FAILED`) - ORPC: Use `ORPCError` with proper codes (`NOT_FOUND`, `UNAUTHORIZED`, `INTERNAL_SERVER_ERROR`)
- Never use empty catch blocks - Never use empty catch blocks
## Database (Drizzle ORM v1 beta + postgres-js) ## Database (Drizzle ORM v1 beta + postgres-js)
@@ -144,17 +91,8 @@ import type { ReactNode } from 'react'
- **ORM**: Drizzle ORM `1.0.0-beta` (RQBv2) - **ORM**: Drizzle ORM `1.0.0-beta` (RQBv2)
- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`) - **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package) - **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts` (contains schema info, so `drizzle()` only needs `{ relations }`) - **Relations**: Defined via `defineRelations()` — RQBv2 object syntax
- **Query style**: RQBv2 object syntax (`orderBy: { createdAt: 'desc' }`, `where: { id: 1 }`) - **Query style**: `db.query.tableName.findMany({ orderBy: { createdAt: 'desc' }, where: { id: 1 } })`
```typescript
export const myTable = pgTable('my_table', {
id: uuid().primaryKey().default(sql`uuidv7()`),
name: text().notNull(),
createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow().$onUpdateFn(() => new Date()),
})
```
## Environment Variables ## Environment Variables
@@ -170,11 +108,9 @@ export const myTable = pgTable('my_table', {
## Development Principles ## Development Principles
> **These principles apply to ALL code changes. Agents MUST follow them on every task.** 1. **No backward compatibility** — Always use the latest API and patterns. Never keep deprecated code paths.
2. **Always sync documentation** — When code changes, immediately update `AGENTS.md` and related docs.
1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks "just in case". 3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API.
2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart. This includes updating code snippets in docs when imports, APIs, or patterns change.
3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns in the same codebase.
## Critical Rules ## Critical Rules
@@ -183,7 +119,6 @@ export const myTable = pgTable('my_table', {
- Use `@/*` path aliases (not relative imports) - Use `@/*` path aliases (not relative imports)
- Include `createdAt`/`updatedAt` on all tables - Include `createdAt`/`updatedAt` on all tables
- Use `catalog:` for dependency versions - Use `catalog:` for dependency versions
- Update `AGENTS.md` and other docs whenever code patterns change
**DON'T:** **DON'T:**
- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx` - Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
@@ -194,49 +129,19 @@ export const myTable = pgTable('my_table', {
- Hardcode dependency versions in workspace packages - Hardcode dependency versions in workspace packages
- Leave docs out of sync with code changes - Leave docs out of sync with code changes
## Git Workflow
1. Make changes following style guide
2. `bun run fix` - auto-format and lint
3. `bun run typecheck` - verify types
4. `bun run dev` - test locally
5. Commit with descriptive message
## Directory Structure ## Directory Structure
``` ```
. .
├── apps/ ├── apps/
│ ├── server/ # TanStack Start fullstack app │ └── server/ # TanStack Start fullstack app (see apps/server/AGENTS.md)
│ │ ├── components.json # shadcn/ui configuration
│ │ ├── src/
│ │ │ ├── client/ # ORPC client + TanStack Query utils
│ │ │ ├── components/
│ │ │ │ ├── ui/ # shadcn/ui components (auto-managed)
│ │ │ │ └── AdminSidebar.tsx # Admin panel sidebar
│ │ │ ├── hooks/ # Custom React hooks
│ │ │ ├── lib/ # Utilities (cn, etc.)
│ │ │ ├── modules/ # Feature modules (bookmarks, etc.)
│ │ │ ├── routes/ # File-based routing
│ │ │ │ ├── _protected/ # Auth guard
│ │ │ │ │ ├── index.tsx # Dashboard homepage
│ │ │ │ │ ├── admin.tsx # Admin layout (sidebar)
│ │ │ │ │ └── admin/ # Admin pages
│ │ │ │ │ ├── index.tsx # Admin overview
│ │ │ │ │ └── bookmarks.tsx # Bookmark management
│ │ │ │ └── api/ # API routes
│ │ │ └── server/ # API layer + database + auth
│ │ │ ├── api/ # ORPC contracts, routers, middlewares
│ │ │ ├── auth/ # Better Auth (schema, instance, client)
│ │ │ └── db/ # Drizzle schema + relations
│ │ └── AGENTS.md
├── packages/ ├── packages/
│ └── tsconfig/ # Shared TS configs │ └── tsconfig/ # Shared TS configs
├── biome.json # Linting/formatting config ├── biome.json # Linting/formatting config
├── turbo.json # Turbo task orchestration ├── turbo.json # Turbo task orchestration
└── package.json # Workspace root + dependency catalog └── package.json # Workspace root + dependency catalog
``` ```
## See Also ## See Also
- `apps/server/AGENTS.md` - Detailed TanStack Start / ORPC patterns - `apps/server/AGENTS.md` — Detailed server app architecture, ORPC patterns, UI conventions
apps/server/AGENTS.md
+182 -294
View File
@@ -4,405 +4,293 @@ TanStack Start fullstack web app with ORPC (contract-first RPC) and shadcn/ui.
## Tech Stack ## Tech Stack
> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, or `node`.** > **⚠️ This project uses Bun — NOT Node.js / npm. Always use `bun run <script>` (not `bun <script>`). Never use `npm`, `npx`, or `node`.**
- **Framework**: TanStack Start (React 19 SSR, file-based routing) - **Framework**: TanStack Start (React 19 SSR, file-based routing)
- **Runtime**: Bun — **NOT Node.js** - **Styling**: Tailwind CSS v4 + shadcn/ui (base-nova style, `@base-ui/react`)
- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
- **Language**: TypeScript (strict mode)
- **Styling**: Tailwind CSS v4 + shadcn/ui (base-nova style, OKLCH colors)
- **UI Components**: shadcn/ui (copy-paste components in `src/components/ui/`)
- **Database**: PostgreSQL + Drizzle ORM v1 beta (`drizzle-orm/postgres-js`, RQBv2) - **Database**: PostgreSQL + Drizzle ORM v1 beta (`drizzle-orm/postgres-js`, RQBv2)
- **State**: TanStack Query v5 - **State**: TanStack Query v5 (with MutationCache auto-invalidation)
- **RPC**: ORPC (contract-first, type-safe) - **RPC**: ORPC (contract-first, type-safe)
- **Auth**: Better Auth (email+password, self-hosted) - **Auth**: Better Auth (email+password, self-hosted)
- **DnD**: @dnd-kit/react - **DnD**: @dnd-kit/react + @dnd-kit/helpers (`move()` for sortable)
- **Virtualization**: @tanstack/react-virtual (`useVirtualizer`)
- **Build**: Vite + Nitro - **Build**: Vite + Nitro
## Commands
```bash
# Development
bun run dev # Vite dev server (localhost:3000)
bun run db:studio # Drizzle Studio GUI
# Build
bun run build # Production build → .output/
bun run compile # Compile to standalone binary (current platform, depends on build)
bun run compile:darwin # Compile for macOS (arm64 + x64)
bun run compile:linux # Compile for Linux (x64 + arm64)
bun run compile:windows # Compile for Windows (default: x64)
# Code Quality
bun run fix # Biome auto-fix
bun run typecheck # TypeScript check
# Database
bun run db:generate # Generate migrations from schema
bun run db:migrate # Run migrations
bun run db:push # Push schema directly (dev only)
# Testing (not yet configured)
bun test path/to/test.ts # Run single test
bun test -t "pattern" # Run tests matching pattern
```
## Architecture Overview ## Architecture Overview
### Route Architecture (Display + Admin separation) ### Route Architecture
``` ```
/ → Dashboard homepage (bookmark display, daily use) / → Dashboard homepage (bookmark display, daily use)
/admin → Admin panel overview (module cards) /admin → Admin panel overview (module cards)
/admin/bookmarks → Bookmark management (CRUD, DnD, Dialog forms) /admin/bookmarks → Bookmark management (CRUD, DnD, Dialog forms)
/login → Login page /login → Login page
/signup → Signup page /signup → Signup page
``` ```
- **Display pages** (`/`): Clean, no management UI. What users see daily. - **Display pages** (`/`): Clean, no management UI. What users see daily.
- **Admin pages** (`/admin/*`): Full CRUD, management, configuration. Sidebar navigation. - **Admin pages** (`/admin/*`): Full CRUD, management, configuration. Sidebar navigation.
- All authenticated routes are under `_protected` layout (auth guard → redirect to `/login`). - All authenticated routes under `_protected` layout (auth guard → redirect to `/login`).
### Module System ### Module System
Modules are directory-based under `src/modules/`. Each module is independent and pluggable. Modules are directory-based under `src/modules/`. Each module provides:
- `index.ts` — `ModuleMetadata` (id, name, icon, adminRoute)
- `schema.ts` — Drizzle tables
- `contract.ts` — ORPC contracts (input/output Zod schemas)
- `router.ts` — ORPC handlers (business logic)
- `components/` — React UI components
```typescript Contracts and routers are registered centrally:
// src/modules/registry.ts - `src/server/api/contracts/index.ts` — imports all module contracts
export interface ModuleMetadata { - `src/server/api/routers/index.ts` — imports all module routers
id: string
name: string
description: string
icon: string // lucide-react icon name
adminRoute: string // Admin management route (e.g., '/admin/bookmarks')
enabled: boolean
}
```
Each module provides: `schema.ts` (Drizzle tables), `contract.ts` (ORPC contracts), `router.ts` (ORPC handlers), `components/` (UI), and `index.ts` (metadata).
## Directory Structure ## Directory Structure
``` ```
src/ src/
├── client/ # Client-side code ├── client/
│ └── orpc.ts # ORPC client + TanStack Query utils │ └── orpc.ts # ORPC client (isomorphic: SSR direct call / CSR fetch)
├── components/ # Shared React components ├── components/
│ ├── AdminSidebar.tsx # Admin panel sidebar navigation │ ├── AdminSidebar.tsx # Admin sidebar (reads module registry)
│ ├── Error.tsx # Error boundary fallback │ ├── Error.tsx # Error boundary fallback
│ ├── NotFound.tsx # 404 fallback │ ├── NotFound.tsx # 404 fallback
│ └── ui/ # shadcn/ui components (DO NOT manually edit) │ └── ui/ # shadcn/ui components (DO NOT manually edit)
│ ├── button.tsx ├── hooks/
│ ├── card.tsx │ └── use-mobile.ts
│ ├── dialog.tsx ├── lib/
│ ├── dropdown-menu.tsx │ └── utils.ts # cn() utility
│ ├── input.tsx ├── modules/
│ ├── separator.tsx │ ├── registry.ts # ModuleMetadata interface + modules[]
│ ├── sheet.tsx │ └── bookmarks/ # Bookmarks module (schema, contract, router, components/)
│ ├── sidebar.tsx ├── routes/ # TanStack Router file routes
│ ├── skeleton.tsx │ ├── __root.tsx # Root layout (HTML shell, Toaster)
│ ├── sonner.tsx │ ├── _protected.tsx # Auth guard layout
│ ├── tooltip.tsx
│ ├── avatar.tsx
│ └── badge.tsx
├── hooks/ # Custom React hooks
│ └── use-mobile.ts # Mobile detection (shadcn sidebar dep)
├── lib/ # Utility functions
│ └── utils.ts # cn() utility (clsx + tailwind-merge)
├── modules/ # Feature modules
│ ├── registry.ts # Module metadata registry
│ └── bookmarks/ # Bookmarks module
│ ├── index.ts # Module metadata
│ ├── schema.ts # Drizzle tables (category, bookmark)
│ ├── contract.ts # ORPC contracts
│ ├── router.ts # ORPC handlers
│ └── components/ # Module UI
│ ├── BookmarkCard.tsx # Display: clean card (icon + name)
│ ├── CategoryGrid.tsx # Display: category grid for homepage
│ ├── BookmarkFormDialog.tsx # Admin: create/edit bookmark dialog
│ ├── BookmarkManager.tsx # Admin: bookmark list with DnD
│ ├── CategoryFormDialog.tsx # Admin: create/edit category dialog
│ ├── CategoryManager.tsx # Admin: category list with DnD
│ ├── IconPickerDialog.tsx # Admin: icon picker in dialog
│ ├── GreetingHeader.tsx # Display: time-based greeting
│ └── SearchBar.tsx # Display: multi-engine search
├── routes/ # TanStack Router file routes
│ ├── __root.tsx # Root layout (HTML shell, Toaster, TooltipProvider)
│ ├── _protected.tsx # Auth guard layout (redirect to /login)
│ ├── _protected/ │ ├── _protected/
│ │ ├── index.tsx # Dashboard homepage (bookmark display) │ │ ├── index.tsx # Dashboard homepage
│ │ ├── admin.tsx # Admin layout (SidebarProvider + Outlet) │ │ ├── admin.tsx # Admin layout (SidebarProvider)
│ │ └── admin/ │ │ └── admin/bookmarks.tsx
│ │ ├── index.tsx # Admin overview (module cards) │ ├── login.tsx, signup.tsx
│ │ └── bookmarks.tsx # Bookmark management page │ └── api/ # $.ts (OpenAPI), auth.$.ts, health.ts, rpc.$.ts
│ ├── login.tsx # Login page ├── server/
│ ├── signup.tsx # Signup page │ ├── api/
│ └── api/ │ │ ├── contracts/index.ts # Central contract registry
│ ├── $.ts # OpenAPI handler + Scalar docs │ │ ├── routers/index.ts # Central router registry
│ ├── auth.$.ts # Better Auth handler │ │ ├── middlewares/ # dbMiddleware, authMiddleware
│ ├── health.ts # Health check endpoint │ │ ├── interceptors.ts # Validation error transform
│ └── rpc.$.ts # ORPC RPC handler │ │ ├── context.ts # BaseContext type
├── server/ # Server-side code │ │ ├── server.ts # `os = implement(contract).$context<BaseContext>()`
│ ├── api/ # ORPC layer │ │ └── types.ts # RouterClient type export
│ │ ├── contracts/ # Input/output schemas (Zod) │ ├── auth/ # Better Auth (schema, instance, client, getSession)
│ │ ├── middlewares/ # Middleware (dbMiddleware, authMiddleware) │ └── db/ # Drizzle (fields, relations, singleton instance)
│ │ ├── routers/ # Handler implementations ├── env.ts # @t3-oss/env-core validation
│ │ ├── interceptors.ts # Shared error interceptors ├── router.tsx # TanStack Router + QueryClient + MutationCache
│ │ ├── context.ts # Request context types ├── routeTree.gen.ts # Auto-generated (DO NOT EDIT)
│ │ ├── server.ts # ORPC server instance └── styles.css # Tailwind + shadcn CSS variables
│ │ └── types.ts # Type exports
│ ├── auth/ # Better Auth
│ │ ├── schema.ts # Auth tables (user, session, account, verification)
│ │ ├── index.ts # Auth instance (betterAuth + drizzleAdapter)
│ │ ├── client.ts # Auth client (createAuthClient)
│ │ └── functions.ts # Server functions (getSession)
│ └── db/
│ ├── schema/ # Drizzle table re-exports
│ ├── fields.ts # Shared field builders (id, createdAt, updatedAt)
│ ├── relations.ts # Drizzle relations (defineRelations, RQBv2)
│ └── index.ts # Database singleton (module-level export)
├── env.ts # Environment variable validation
├── router.tsx # Router configuration
├── routeTree.gen.ts # Auto-generated (DO NOT EDIT)
└── styles.css # Tailwind + shadcn CSS variables
``` ```
## ORPC Pattern ## ORPC Pattern
### 1. Define Contract (`src/server/api/contracts/feature.contract.ts`) ### 1. Define Contract (in module: `src/modules/feature/contract.ts`)
```typescript ```typescript
import { oc } from '@orpc/contract' import { oc } from '@orpc/contract'
import { createSelectSchema } from 'drizzle-orm/zod' import { createInsertSchema, createSelectSchema, createUpdateSchema } from 'drizzle-orm/zod'
import { z } from 'zod' import { z } from 'zod'
import * as schema from '@/modules/feature/schema' import * as schema from '@/modules/feature/schema'
import { generatedFieldKeys } from '@/server/db/fields'
const selectSchema = createSelectSchema(schema.myTable) const selectSchema = createSelectSchema(schema.myTable)
const insertSchema = createInsertSchema(schema.myTable).omit(generatedFieldKeys).omit({ userId: true })
const updateSchema = createUpdateSchema(schema.myTable).omit(generatedFieldKeys).omit({ userId: true })
export const list = oc.input(z.void()).output(z.array(selectSchema)) export const myResource = {
export const create = oc.input(insertSchema).output(selectSchema) list: oc.input(z.void()).output(z.array(selectSchema)),
create: oc.input(insertSchema).output(selectSchema),
update: oc.input(z.object({ id: z.uuid(), data: updateSchema })).output(selectSchema),
remove: oc.input(z.object({ id: z.uuid() })).output(z.void()),
}
``` ```
### 2. Implement Router (`src/server/api/routers/feature.router.ts`) ### 2. Implement Router (in module: `src/modules/feature/router.ts`)
```typescript ```typescript
import { ORPCError } from '@orpc/server' import { ORPCError } from '@orpc/server'
import * as schema from '@/modules/feature/schema' import * as schema from '@/modules/feature/schema'
import { authMiddleware, dbMiddleware } from '@/server/api/middlewares' import { authMiddleware, dbMiddleware } from '@/server/api/middlewares'
import { os } from '@/server/api/server' import { os } from '@/server/api/server'
export const list = os.feature.list export const myResource = {
.use(dbMiddleware) list: os.feature.myResource.list
.use(authMiddleware) .use(dbMiddleware).use(authMiddleware)
.handler(async ({ context }) => { .handler(async ({ context }) => {
return await context.db.query.myTable.findMany({ return await context.db.query.myTable.findMany({
orderBy: { createdAt: 'desc' }, where: { userId: context.user.id },
}) orderBy: { createdAt: 'desc' },
}) })
}),
create: os.feature.myResource.create
.use(dbMiddleware).use(authMiddleware)
.handler(async ({ context, input }) => {
const [created] = await context.db.insert(schema.myTable)
.values({ ...input, userId: context.user.id }).returning()
if (!created) throw new ORPCError('INTERNAL_SERVER_ERROR', { message: 'Failed to create' })
return created
}),
}
``` ```
### 3. Register in Index Files ### 3. Register (`src/server/api/contracts/index.ts` + `routers/index.ts`)
```typescript ```typescript
// src/server/api/contracts/index.ts // contracts/index.ts
import * as feature from '@/modules/feature/contract' import * as feature from '@/modules/feature/contract'
export const contract = { feature } export const contract = { feature }
// src/server/api/routers/index.ts // routers/index.ts
import * as feature from '@/modules/feature/router' import * as feature from '@/modules/feature/router'
export const router = os.router({ feature }) export const router = os.router({ feature })
``` ```
### 4. Use in Components ### 4. Use in Components
```typescript ```typescript
import { useSuspenseQuery, useMutation } from '@tanstack/react-query' const { data } = useSuspenseQuery(orpc.feature.myResource.list.queryOptions())
import { orpc } from '@/client/orpc' const mutation = useMutation(orpc.feature.myResource.create.mutationOptions())
const { data } = useSuspenseQuery(orpc.feature.list.queryOptions())
const mutation = useMutation(orpc.feature.create.mutationOptions())
``` ```
## UI Component Patterns (shadcn/ui) ### MutationCache Auto-Invalidation
`router.tsx` configures a global `MutationCache` that auto-invalidates queries in the same module when any mutation succeeds. No need for manual `queryClient.invalidateQueries()` in most cases.
### Dialog Forms (for CRUD operations) ## UI Component Patterns
### base-ui `render` Prop (CRITICAL)
shadcn/ui uses `@base-ui/react`. The `render` prop replaces Radix's `asChild`:
```typescript ```typescript
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog' // ✅ CORRECT
import { Button } from '@/components/ui/button' <DialogTrigger render={<Button />} />
<SidebarMenuButton render={<Link to="/admin" />}>
// Use render prop on DialogTrigger to avoid nested <button> // ❌ WRONG — asChild does NOT exist
<DialogTrigger asChild><Button /></DialogTrigger>
```
### Dialog Forms
```typescript
<Dialog open={open} onOpenChange={setOpen}> <Dialog open={open} onOpenChange={setOpen}>
<DialogTrigger render={<Button>打开</Button>} /> <DialogTrigger render={trigger} />
<DialogContent> <DialogContent>
{/* Form content */} <form onSubmit={handleSubmit}>
<DialogHeader><DialogTitle>标题</DialogTitle></DialogHeader>
{/* fields */}
<DialogFooter><Button type="submit">提交</Button></DialogFooter>
</form>
</DialogContent> </DialogContent>
</Dialog> </Dialog>
``` ```
### DropdownMenu (for action menus) ### DnD Sortable (with @dnd-kit/helpers)
```typescript ```typescript
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@/components/ui/dropdown-menu' import { move } from '@dnd-kit/helpers'
import { DragDropProvider } from '@dnd-kit/react'
import { useSortable } from '@dnd-kit/react/sortable'
// Use render prop on trigger to avoid nested <button> // In sortable item:
<DropdownMenu> const { ref, handleRef, isDragging } = useSortable({ id, index, group })
<DropdownMenuTrigger render={<Button variant="ghost" size="icon-sm" />}>
<MoreHorizontal className="size-4" /> // In container — use move() for reordering:
</DropdownMenuTrigger> const handleDragEnd = (event) => {
<DropdownMenuContent> if (event.canceled) return
<DropdownMenuItem>操作</DropdownMenuItem> const reordered = move(items, event) // @dnd-kit/helpers handles index mapping
</DropdownMenuContent> setItems(reordered)
</DropdownMenu> reorderMutation.mutate(reordered.map((item, i) => ({ id: item.id, orderId: i })))
}
<DragDropProvider onDragEnd={handleDragEnd}>
{items.map((item, index) => <SortableItem key={item.id} index={index} />)}
</DragDropProvider>
```
### Virtual Scrolling in Dialogs
Use `useState` callback ref (NOT `useRef`) for scroll elements inside Dialogs — `useRef` doesn't trigger re-render when Dialog mounts:
```typescript
import { useVirtualizer } from '@tanstack/react-virtual'
const [scrollElement, setScrollElement] = useState<HTMLDivElement | null>(null)
const virtualizer = useVirtualizer({
count: rowCount,
getScrollElement: () => scrollElement, // useState, NOT useRef
estimateSize: () => ROW_HEIGHT,
overscan: 5,
})
<div ref={setScrollElement} className="max-h-80 overflow-y-auto">
<div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
{virtualizer.getVirtualItems().map((row) => (
<div key={row.key} style={{ position: 'absolute', transform: `translateY(${row.start}px)` }}>
{/* row content */}
</div>
))}
</div>
</div>
``` ```
### Toast Notifications ### Toast Notifications
```typescript ```typescript
import { toast } from 'sonner' import { toast } from 'sonner'
toast.success('操作成功') toast.success('操作成功')
toast.error('操作失败') toast.error('操作失败')
``` ```
### Admin Sidebar
- Uses shadcn `SidebarProvider` + `Sidebar` + `SidebarInset` pattern
- Navigation items from module registry
- `SidebarMenuButton` uses `render` prop for `Link` integration (NOT `asChild`)
### base-ui `render` Prop (IMPORTANT)
shadcn/ui v4 uses `@base-ui/react` instead of Radix primitives. The `render` prop replaces `asChild`:
```typescript
// CORRECT: render prop delegates element rendering
<DialogTrigger render={<Button />} />
<SidebarMenuButton render={<Link to="/admin" />}>
// WRONG: asChild does NOT exist in base-ui components
<DialogTrigger asChild><Button /></DialogTrigger> // ❌ asChild is NOT supported
```
## Database (Drizzle ORM v1 beta) ## Database (Drizzle ORM v1 beta)
- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`) - **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package) - **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts` - **Relations**: `defineRelations()` in `src/server/db/relations.ts` — RQBv2 object syntax
- **Query**: RQBv2 — use `db.query.tableName.findMany()` with object-style `orderBy` and `where` - **Table naming**: No `Table` suffix — `user`, `category`, `bookmark`
- **Table naming**: No `Table` suffix — use `user`, `category`, `bookmark` (NOT `userTable`) - **DB instance**: Module-level singleton `export const db = drizzle(...)` (NOT factory pattern)
- **DB instance**: Module-level singleton `export const db = drizzle(...)` (NOT factory/closure pattern) - **Shared fields**: Use `...generatedFields` spread for id/createdAt/updatedAt
### Schema Definition
```typescript ```typescript
import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core' // Schema — use generatedFields spread
import { sql } from 'drizzle-orm'
export const myTable = pgTable('my_table', { export const myTable = pgTable('my_table', {
id: uuid().primaryKey().default(sql`uuidv7()`), ...generatedFields, // id (uuid v7), createdAt, updatedAt
name: text().notNull(), name: text('name').notNull(),
createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(), userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow().$onUpdateFn(() => new Date()),
}) })
```
### Relations (RQBv2)
```typescript
import { defineRelations } from 'drizzle-orm'
import * as schema from './schema'
// Relations — RQBv2 defineRelations
export const relations = defineRelations(schema, (r) => ({ export const relations = defineRelations(schema, (r) => ({
user: { myTable: {
categories: r.many.category(), user: r.one.user({ from: r.myTable.userId, to: r.user.id }),
},
category: {
user: r.one.user({ from: r.category.userId, to: r.user.id }),
bookmarks: r.many.bookmark(),
}, },
})) }))
``` ```
### DB Instance
```typescript
import { drizzle } from 'drizzle-orm/postgres-js'
import { relations } from '@/server/db/relations'
export const db = drizzle({ connection: env.DATABASE_URL, relations })
export type DB = typeof db
```
## Auth (Better Auth) ## Auth (Better Auth)
- **Instance**: `src/server/auth/index.ts` — `betterAuth()` with `drizzleAdapter(db, { provider: 'pg', schema: authSchema })` - **Instance**: `src/server/auth/index.ts` — `betterAuth()` with `drizzleAdapter(db, { provider: 'pg', schema })`
- **Client**: `src/server/auth/client.ts` — `createAuthClient()` for React - **Client**: `src/server/auth/client.ts` — `createAuthClient()` for React
- **Server function**: `src/server/auth/functions.ts` — `getSession()` via `createServerFn` - **Server function**: `src/server/auth/functions.ts` — `getSession()` via `createServerFn`
- **Auth tables**: Use `text` IDs (Better Auth manages its own IDs), NOT project's UUID v7 - **Auth tables**: Use `text` IDs (Better Auth manages its own IDs), NOT project's UUID v7
- **Schema key naming**: Export names must match Better Auth model names exactly (`user`, `session`, `account`, `verification`) - **Route guard**: `beforeLoad` in `_protected.tsx` calls `getSession()` → redirect to `/login`
- **ORPC middleware**: `authMiddleware` calls `auth.api.getSession({ headers })` → injects `context.user`
### Auth Middleware (ORPC)
```typescript
const sessionData = await auth.api.getSession({ headers: context.headers })
// Injects context.user and context.session
```
## Code Style
### Formatting (Biome)
- **Indent**: 2 spaces
- **Quotes**: Single `'`
- **Semicolons**: Omit (ASI)
- **Arrow parens**: Always `(x) => x`
### Imports
Biome auto-organizes:
1. External packages
2. Internal `@/*` aliases
3. Type imports (`import type { ... }`)
### TypeScript
- `strict: true`
- `noUncheckedIndexedAccess: true` — array access returns `T | undefined`
- Use `@/*` path aliases (maps to `src/*`)
### Naming
| Type | Convention | Example |
|------|------------|---------|
| Files (utils) | kebab-case | `auth-utils.ts` |
| Files (components) | PascalCase | `UserProfile.tsx` |
| Components | PascalCase arrow | `const Button = () => {}` |
| Functions | camelCase | `getUserById` |
| Types | PascalCase | `UserProfile` |
| Drizzle tables | camelCase, no suffix | `user`, `category` (NOT `userTable`) |
### React
- Use arrow functions for components (Biome enforced)
- Use `useSuspenseQuery` for guaranteed data
- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)
## Development Principles
> **These principles apply to ALL code changes. Agents MUST follow them on every task.**
1. **No backward compatibility** — Always use the latest API and patterns.
2. **Always sync documentation** — When code changes, immediately update all related documentation.
3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API.
## Critical Rules ## Critical Rules
**DO:** **DO:**
- Run `bun run fix` before committing - Run `bun run fix` before committing
- Use `@/*` path aliases - Use `@/*` path aliases (not relative imports)
- Include `createdAt`/`updatedAt` on all tables
- Use `ORPCError` with proper codes
- Use `drizzle-orm/zod` (NOT `drizzle-zod`) for schema validation
- Use RQBv2 object syntax for `orderBy` and `where`
- Use `render` prop (NOT `asChild`) for base-ui component delegation - Use `render` prop (NOT `asChild`) for base-ui component delegation
- Use Dialog modals for forms (NOT inline forms) - Use `ORPCError` with proper codes
- Use `toast` from `sonner` for CRUD notifications - Use `drizzle-orm/zod` (NOT `drizzle-zod`)
- Update `AGENTS.md` and other docs whenever code patterns change - Use RQBv2 object syntax for `orderBy` and `where`
- Use `move()` from `@dnd-kit/helpers` for DnD reordering
- Use `useState` callback ref for virtualizer scroll elements inside Dialogs
**DON'T:** **DON'T:**
- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
- Edit `src/routeTree.gen.ts` (auto-generated)
- Manually edit `src/components/ui/*.tsx` (use `bunx shadcn@latest add`) - Manually edit `src/components/ui/*.tsx` (use `bunx shadcn@latest add`)
- Use `as any`, `@ts-ignore`, `@ts-expect-error` - Edit `src/routeTree.gen.ts` (auto-generated)
- Use `asChild` prop (use `render` prop instead — base-ui, NOT Radix) - Use `asChild` prop (base-ui uses `render`, NOT Radix)
- Commit `.env` files - Import from `drizzle-zod` (use `drizzle-orm/zod`)
- Use empty catch blocks - Use `drizzle-orm/bun-sql` driver
- Import from `drizzle-zod` (use `drizzle-orm/zod` instead) - Pass `schema` to `drizzle()` constructor (only `relations` needed in RQBv2)
- Use RQBv1 callback-style `orderBy` / old `relations()` API
- Use `drizzle-orm/bun-sql` driver (use `drizzle-orm/postgres-js`)
- Pass `schema` to `drizzle()` constructor (only `relations` is needed in RQBv2)
- Use `getDB()` factory pattern (use module-level `db` export instead)
- Add `Table` suffix to Drizzle table exports - Add `Table` suffix to Drizzle table exports
- Leave docs out of sync with code changes - Use `useRef` for scroll elements inside Dialog/conditional rendering