docs: 更新 AGENTS.md 文档结构和内容

- 新增根目录 AGENTS.md 作为 monorepo 总览 - 移动 desktop AGENTS.md 从 src-tauri/ 到 apps/desktop/ - 修正 server AGENTS.md 目录结构 (src/server/api/ 而非 src/orpc/) - 明确 desktop 为纯 Tauri 壳子，无前端代码，通过 sidecar 加载 server
2026-02-07 03:29:51 +08:00
parent 49d1f706e7
commit e41c4e4515
4 changed files with 525 additions and 587 deletions
--- a/apps/server/AGENTS.md
+++ b/apps/server/AGENTS.md
@@ -1,155 +1,121 @@
-# AGENTS.md - AI Coding Agent Guidelines
+# AGENTS.md - Server App Guidelines

-本文档为 AI 编程助手提供此 TanStack Start 全栈项目的开发规范和指南。
+TanStack Start fullstack web app with ORPC (contract-first RPC).

-## 项目概览
+## Tech Stack

- **框架**: TanStack Start (React SSR 框架，文件路由)
- **运行时**: Bun
- **语言**: TypeScript (strict mode, ESNext)
- **样式**: Tailwind CSS v4
- **数据库**: PostgreSQL + Drizzle ORM
- **状态管理**: TanStack Query
- **路由**: TanStack Router (文件路由)
- **RPC**: ORPC (类型安全 RPC，契约优先)
- **构建工具**: Vite + Turbo
- **代码质量**: Biome (格式化 + Lint)
- **桌面壳** (可选): Tauri v2 (详见 `src-tauri/AGENTS.md`)
+- **Framework**: TanStack Start (React 19 SSR, file-based routing)
+- **Runtime**: Bun
+- **Language**: TypeScript (strict mode)
+- **Styling**: Tailwind CSS v4
+- **Database**: PostgreSQL + Drizzle ORM
+- **State**: TanStack Query v5
+- **RPC**: ORPC (contract-first, type-safe)
+- **Build**: Vite + Nitro

-## 构建、Lint 和测试命令
+## Commands

-### 开发
 ```bash
-bun dev                    # 使用 Turbo 并行启动 Tauri + Vite 开发服务器
-bun dev:vite               # 仅启动 Vite 开发服务器 (localhost:3000)
-bun dev:tauri              # 启动 Tauri 桌面应用
-bun db:studio              # 打开 Drizzle Studio 数据库管理界面
+# Development
+bun dev                    # Vite dev server (localhost:3000)
+bun db:studio              # Drizzle Studio GUI
+
+# Build
+bun build                  # Production build → .output/
+bun compile                # Compile to standalone binary
+
+# Code Quality
+bun fix                    # Biome auto-fix
+bun typecheck              # TypeScript check
+
+# Database
+bun db:generate            # Generate migrations from schema
+bun db:migrate             # Run migrations
+bun 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
 ```

-### 构建
-```bash
-bun build                  # 完整构建 (Vite → 编译 → Tauri 打包)
-bun build:vite             # 仅构建 Vite (输出到 .output/)
-bun build:compile          # 编译为独立可执行文件 (使用 build.ts)
-bun build:tauri            # 构建 Tauri 桌面安装包
+## Directory Structure
+
+```
+src/
+├── client/                # Client-side code
+│   ├── orpc.client.ts     # ORPC isomorphic client
+│   └── query-client.ts    # TanStack Query client
+├── components/            # React components
+├── routes/                # TanStack Router file routes
+│   ├── __root.tsx         # Root layout
+│   ├── index.tsx          # Home page
+│   └── api/
+│       └── rpc.$.ts       # ORPC HTTP endpoint
+├── server/                # Server-side code
+│   ├── api/               # ORPC layer
+│   │   ├── contracts/     # Input/output schemas (Zod)
+│   │   ├── middlewares/   # Middleware (db provider, auth)
+│   │   ├── routers/       # Handler implementations
+│   │   ├── context.ts     # Request context
+│   │   ├── server.ts      # ORPC server instance
+│   │   └── types.ts       # Type exports
+│   └── db/
+│       ├── schema/        # Drizzle table definitions
+│       └── index.ts       # Database instance
+├── env.ts                 # Environment variable validation
+├── router.tsx             # Router configuration
+├── routeTree.gen.ts       # Auto-generated (DO NOT EDIT)
+└── styles.css             # Tailwind entry
 ```

-### 代码质量
-```bash
-bun typecheck              # 运行 TypeScript 编译器检查 (tsc -b)
-bun fix                    # 运行 Biome 自动修复格式和 Lint 问题
-biome check .              # 检查但不自动修复
-biome format --write .     # 仅格式化代码
-```
+## ORPC Pattern

-### 数据库
-```bash
-bun db:generate            # 从 schema 生成迁移文件
-bun db:migrate             # 执行数据库迁移
-bun db:push                # 直接推送 schema 变更 (仅开发环境)
-```
-
-### 测试
-**注意**: 当前未配置测试框架。添加测试时:
- 使用 Vitest 或 Bun 内置测试运行器
- 运行单个测试文件: `bun test path/to/test.ts`
- 运行特定测试: `bun test -t "测试名称模式"`
-
-## 代码风格指南
-
-### 格式化 (Biome)
-
-**缩进**: 2 空格 (不使用 tab)
-**换行符**: LF (Unix 风格)
-**引号**: 单引号 `'string'`
-**分号**: 按需 (ASI - 自动分号插入)
-**箭头函数括号**: 始终使用 `(x) => x`
-
-示例:
+### 1. Define Contract (`src/server/api/contracts/feature.contract.ts`)
 ```typescript
-const myFunc = (value: string) => {
-  return value.toUpperCase()
-}
-```
-
-### 导入组织
-
-Biome 自动组织导入。顺序:
-1. 外部依赖
-2. 内部导入 (使用 `@/*` 别名)
-3. 类型导入 (仅导入类型时使用 `type` 关键字)
-
-示例:
-```typescript
-import { createFileRoute } from '@tanstack/react-router'
 import { oc } from '@orpc/contract'
+import { createSelectSchema } from 'drizzle-zod'
 import { z } from 'zod'
-import { db } from '@/db'
-import { todoTable } from '@/db/schema'
-import type { ReactNode } from 'react'
+import { featureTable } from '@/server/db/schema'
+
+const selectSchema = createSelectSchema(featureTable)
+
+export const list = oc.input(z.void()).output(z.array(selectSchema))
+export const create = oc.input(insertSchema).output(selectSchema)
 ```

-### TypeScript
-
-**严格模式**: 启用了额外的严格检查
- `strict: true`
- `noUncheckedIndexedAccess: true` - 数组/对象索引返回 `T | undefined`
- `noImplicitOverride: true`
- `noFallthroughCasesInSwitch: true`
-
-**模块解析**: `bundler` 模式 + `verbatimModuleSyntax`
- 导入时始终使用 `.ts`/`.tsx` 扩展名
- 使用 `@/*` 路径别名指向 `src/*`
-
-**类型注解**:
- 公共 API 的函数参数和返回类型必须注解
- 优先使用显式类型而非 `any`
- 对象形状用 `type`，可扩展契约用 `interface`
- 不可变 props 使用 `Readonly<T>`
-
-### 命名规范
-
- **文件**: 工具函数用 kebab-case，组件用 PascalCase
-  - `utils.ts`, `todo.tsx`, `NotFound.tsx`
- **路由**: 遵循 TanStack Router 约定
-  - `routes/index.tsx` → `/`
-  - `routes/__root.tsx` → 根布局
- **组件**: PascalCase 箭头函数 (Biome 规则 `useArrowFunction` 强制)
- **函数**: camelCase
- **常量**: 真常量用 UPPER_SNAKE_CASE，配置对象用 camelCase
- **类型/接口**: PascalCase
-
-### React 模式
-
-**组件**: 使用箭头函数
+### 2. Implement Router (`src/server/api/routers/feature.router.ts`)
 ```typescript
-const MyComponent = ({ title }: { title: string }) => {
-  return <div>{title}</div>
-}
-```
+import { ORPCError } from '@orpc/server'
+import { db } from '../middlewares'
+import { os } from '../server'

-**路由**: 使用 `createFileRoute` 定义路由
-```typescript
-export const Route = createFileRoute('/')({
-  component: Home,
+export const list = os.feature.list.use(db).handler(async ({ context }) => {
+  return await context.db.query.featureTable.findMany()
 })
 ```

-**数据获取**: 使用 TanStack Query hooks
- `useSuspenseQuery` - 保证有数据
- `useQuery` - 数据可能为空
+### 3. Register in Index Files
+```typescript
+// src/server/api/contracts/index.ts
+import * as feature from './feature.contract'
+export const contract = { feature }

-**Props**: 禁止直接修改 props (Biome 规则 `noReactPropAssignments`)
+// src/server/api/routers/index.ts
+import * as feature from './feature.router'
+export const router = os.router({ feature })
+```

-### 数据库 Schema (Drizzle)
+### 4. Use in Components
+```typescript
+import { useSuspenseQuery, useMutation } from '@tanstack/react-query'
+import { orpc } from '@/client/orpc.client'

- 在 `src/db/schema/*.ts` 定义 schema
- 从 `src/db/schema/index.ts` 导出
- 使用 `drizzle-orm/pg-core` 的 PostgreSQL 类型
- 主键使用 `uuidv7()` (需要 PostgreSQL 扩展)
- 始终包含 `createdAt` 和 `updatedAt` 时间戳
+const { data } = useSuspenseQuery(orpc.feature.list.queryOptions())
+const mutation = useMutation(orpc.feature.create.mutationOptions())
+```
+
+## Database Schema (Drizzle)

-示例:
 ```typescript
 import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
 import { sql } from 'drizzle-orm'
@@ -162,116 +128,74 @@ export const myTable = pgTable('my_table', {
 })
 ```

-### 环境变量
+## Code Style

- 使用 `@t3-oss/env-core` 进行类型安全的环境变量验证
- 在 `src/env.ts` 定义 schema
- 服务端变量: 无前缀
- 客户端变量: 必须有 `VITE_` 前缀
- 使用 Zod schema 验证
+### 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 { ... }`)

- 异步操作使用 try-catch
- 抛出带有描述性消息的错误
- 用户界面错误优先使用 Result 类型或错误边界
- 适当记录错误 (避免记录敏感数据)
-
-### 样式 (Tailwind CSS)
-
- 使用 Tailwind v4 工具类
- 通过 `@/styles.css?url` 导入样式
- 优先使用组合而非自定义 CSS
- 响应式修饰符: `sm:`, `md:`, `lg:`
- UI 文本适当使用中文
-
-## 目录结构
-
-```
-src/
-├── components/            # 可复用 React 组件
-├── db/
-│   ├── schema/           # Drizzle schema 定义
-│   └── index.ts          # 数据库实例
-├── integrations/         # 第三方集成 (TanStack Query/Router)
-├── lib/                  # 工具函数
-├── orpc/                 # ORPC (RPC 层)
-│   ├── contracts/        # 契约定义 (input/output schemas)
-│   ├── handlers/         # 服务端过程实现
-│   ├── middlewares/      # 中间件 (如 DB provider)
-│   ├── contract.ts       # 契约聚合
-│   ├── router.ts         # 路由组合
-│   ├── server.ts         # 服务端实例
-│   └── client.ts         # 同构客户端
-├── routes/               # TanStack Router 文件路由
-│   ├── __root.tsx        # 根布局
-│   ├── index.tsx         # 首页
-│   └── api/rpc.$.ts      # ORPC HTTP 端点
-├── env.ts                # 环境变量验证
-└── router.tsx            # 路由配置
-```
-
-## 重要提示
-
- **禁止** 编辑 `src/routeTree.gen.ts` - 自动生成
- **禁止** 提交 `.env` 文件 - 使用 `.env.example` 作为模板
- **必须** 在提交前运行 `bun fix`
- **必须** 使用 `@/*` 路径别名而非相对导入
- **必须** 利用 React Compiler (babel-plugin-react-compiler) - 避免手动 memoization
-
-## Git 工作流
-
-1. 按照上述风格指南进行修改
-2. 运行 `bun fix` 自动格式化和 lint
-3. 运行 `bun typecheck` 确保类型安全
-4. 使用 `bun dev` 本地测试变更
-5. 使用清晰的描述性消息提交
-
-## 常见模式
-
-### 创建 ORPC 过程
-
-**步骤 1: 定义契约** (`src/orpc/contracts/my-feature.ts`)
 ```typescript
-import { oc } from '@orpc/contract'
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+import { db } from '@/server/db'
+import type { ReactNode } from 'react'
+```
+
+### 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` |
+
+### React
+- Use arrow functions for components (Biome enforced)
+- Use `useSuspenseQuery` for guaranteed data
+- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)
+
+## Environment Variables
+
+```typescript
+// src/env.ts - using @t3-oss/env-core
+import { createEnv } from '@t3-oss/env-core'
 import { z } from 'zod'

-export const myContract = {
-  get: oc.input(z.object({ id: z.uuid() })).output(mySchema),
-  create: oc.input(createSchema).output(mySchema),
-}
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+  },
+  clientPrefix: 'VITE_',
+  client: {
+    VITE_API_URL: z.string().optional(),
+  },
+})
 ```

-**步骤 2: 实现处理器** (`src/orpc/handlers/my-feature.ts`)
-```typescript
-import { os } from '@/orpc/server'
-import { dbProvider } from '@/orpc/middlewares'
+## Critical Rules

-export const get = os.myFeature.get
-  .use(dbProvider)
-  .handler(async ({ context, input }) => {
-    return await context.db.query.myTable.findFirst(...)
-  })
-```
+**DO:**
+- Run `bun fix` before committing
+- Use `@/*` path aliases
+- Include `createdAt`/`updatedAt` on all tables
+- Use `ORPCError` with proper codes

-**步骤 3: 注册到契约和路由**
-```typescript
-// src/orpc/contract.ts
-export const contract = { myFeature: myContract }
-
-// src/orpc/router.ts
-import * as myFeature from './handlers/my-feature'
-export const router = os.router({ myFeature })
-```
-
-**步骤 4: 在组件中使用**
-```typescript
-import { orpc } from '@/orpc'
-const query = useSuspenseQuery(orpc.myFeature.get.queryOptions({ id }))
-const mutation = useMutation(orpc.myFeature.create.mutationOptions())
-```
-
---
-
-**最后更新**: 2026-01-18
-**项目版本**: 基于 package.json 依赖版本
+**DON'T:**
+- Edit `src/routeTree.gen.ts` (auto-generated)
+- Use `as any`, `@ts-ignore`, `@ts-expect-error`
+- Commit `.env` files
+- Use empty catch blocks