feat: 添加本地工具包依赖支持项目功能

- 添加本地工具包依赖 @furtherverse/utils 以支持项目功能。
- 添加对 workspace 内 utils 包的依赖引用

.gitignore

@@ -6,6 +6,12 @@
 # Nitro
 .output/
 
+# Bun build
+*.bun-build
+
+# Turborepo
+.turbo/
+
 ### Node ###
 
 # Logs

.vscode/settings.json

@@ -37,7 +37,8 @@
   "files.associations": {
     ".env": "dotenv",
     ".env.*": "dotenv",
-    "**/tsconfig*.json": "jsonc",
+    "**/tsconfig.json": "jsonc",
+    "**/tsconfig.*.json": "jsonc",
     "**/biome.json": "jsonc",
     "**/opencode.json": "jsonc"
   },

AGENTS.md

@@ -1,323 +0,0 @@
-# AGENTS.md - AI Coding Agent Guidelines
-
-This document provides comprehensive guidelines for AI coding agents working in this TanStack Start fullstack starter codebase.
-
-## Project Overview
-
-- **Framework**: TanStack Start (React SSR framework with file-based routing)
-- **Runtime**: Bun
-- **Language**: TypeScript (strict mode, ESNext)
-- **Styling**: Tailwind CSS v4
-- **Database**: PostgreSQL with Drizzle ORM
-- **State Management**: TanStack Query
-- **Routing**: TanStack Router (file-based)
-- **RPC**: ORPC (type-safe RPC with contract-first design)
-- **Build Tool**: Vite
-- **Linter/Formatter**: Biome
-
-## Build, Lint, and Test Commands
-
-### Development
-```bash
-bun dev                    # Start development server
-bun db:studio              # Open Drizzle Studio for database management
-```
-
-### Building
-```bash
-bun build                  # Build for production (outputs to .output/)
-bun compile                # Compile to standalone executable (out/server)
-bun serve                  # Preview production build
-```
-
-### Code Quality
-```bash
-bun typecheck              # Run TypeScript compiler (tsc -b)
-bun fix                    # Run Biome linter and formatter (auto-fix issues)
-biome check .              # Check without auto-fix
-biome format --write .     # Format code only
-```
-
-### Database
-```bash
-bun db:generate            # Generate migration files from schema
-bun db:migrate             # Run migrations
-bun db:push                # Push schema changes directly (dev only)
-```
-
-### Testing
-**Note**: No test framework is currently configured. When adding tests:
-- Use Vitest or Bun's built-in test runner
-- Run single test file: `bun test path/to/test.ts`
-- Run specific test: `bun test -t "test name pattern"`
-
-## Code Style Guidelines
-
-### Formatting (Biome)
-
-**Indentation**: 2 spaces (not tabs)
-**Line Endings**: LF (Unix-style)
-**Quotes**: Single quotes for strings
-**Semicolons**: As needed (ASI - automatic semicolon insertion)
-**Arrow Parens**: Always use parentheses `(x) => x`
-
-Example:
-```typescript
-const myFunc = (value: string) => {
-  return value.toUpperCase()
-}
-```
-
-### Import Organization
-
-Imports are auto-organized by Biome. Order:
-1. External dependencies
-2. Internal imports using `@/*` alias
-3. Type imports (use `type` keyword when importing only types)
-
-Example:
-```typescript
-import { createFileRoute } from '@tanstack/react-router'
-import { createServerFn } from '@tanstack/react-start'
-import { db } from '@/db'
-import type { ReactNode } from 'react'
-```
-
-### TypeScript
-
-**Strict Mode**: Enabled with additional strictness flags
-- `strict: true`
-- `noUncheckedIndexedAccess: true` - Array/object indexing returns `T | undefined`
-- `noImplicitOverride: true`
-- `noFallthroughCasesInSwitch: true`
-
-**Module Resolution**: `bundler` mode with `verbatimModuleSyntax`
-- Always use `.ts`/`.tsx` extensions in imports
-- Use `@/*` path alias for `src/*`
-
-**Type Annotations**:
-- Always annotate function parameters and return types for public APIs
-- Prefer explicit types over `any`
-- Use `type` for object shapes, `interface` for extendable contracts
-- Use `Readonly<T>` for immutable props
-
-Example:
-```typescript
-function getTodos(): Promise<Todo[]> {
-  return db.query.todoTable.findMany()
-}
-
-type Props = Readonly<{
-  children: ReactNode
-}>
-```
-
-### Naming Conventions
-
-- **Files**: kebab-case for utilities, PascalCase for components
-  - `utils.ts`, `todo.tsx`, `NotFound.tsx`
-- **Routes**: Use TanStack Router conventions
-  - `routes/index.tsx` → `/`
-  - `routes/todo.tsx` → `/todo`
-  - `routes/__root.tsx` → Root layout
-- **Components**: PascalCase function declarations
-- **Functions**: camelCase
-- **Constants**: UPPER_SNAKE_CASE for true constants, camelCase for config objects
-- **Types/Interfaces**: PascalCase
-
-### React Patterns
-
-**Components**: Use arrow functions (enforced by Biome rule `useArrowFunction`)
-```typescript
-const MyComponent = ({ title }: { title: string }) => {
-  return <div>{title}</div>
-}
-```
-
-**Server Functions**: Use TanStack Start's `createServerFn`
-```typescript
-const getTodos = createServerFn({ method: 'GET' }).handler(async () => {
-  const todos = await db.query.todoTable.findMany()
-  return todos
-})
-```
-
-**Routing**: Use `createFileRoute` for route definitions
-```typescript
-export const Route = createFileRoute('/todo')({
-  component: Todo,
-})
-```
-
-**Data Fetching**: Use TanStack Query hooks
-- `useSuspenseQuery` for guaranteed data
-- `useQuery` when data might be optional
-
-**Props**: No direct prop mutations (enforced by `noReactPropAssignments`)
-
-### Database Schema (Drizzle)
-
-- Define schemas in `src/db/schema/*.ts`
-- Export from `src/db/schema/index.ts`
-- Use PostgreSQL types from `drizzle-orm/pg-core`
-- Use `uuidv7()` for primary keys (requires PostgreSQL extension)
-- Always include `createdAt` and `updatedAt` timestamps
-
-Example:
-```typescript
-import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
-import { sql } from 'drizzle-orm'
-
-export const myTable = pgTable('my_table', {
-  id: uuid('id').primaryKey().default(sql`uuidv7()`),
-  name: text('name').notNull(),
-  createdAt: timestamp('created_at', { withTimezone: true })
-    .notNull()
-    .defaultNow(),
-  updatedAt: timestamp('updated_at', { withTimezone: true })
-    .notNull()
-    .defaultNow()
-    .$onUpdateFn(() => new Date()),
-})
-```
-
-### Environment Variables
-
-- Use `@t3-oss/env-core` for type-safe env validation
-- Define schema in `src/env.ts`
-- Server vars: No prefix
-- Client vars: Must have `VITE_` prefix
-- Always validate with Zod schemas
-
-### Error Handling
-
-- Use try-catch for async operations
-- Throw errors with descriptive messages
-- Prefer Result types or error boundaries for user-facing errors
-- Log errors appropriately (avoid logging sensitive data)
-
-### Styling (Tailwind CSS)
-
-- Use Tailwind v4 utility classes
-- Import styles via `@/styles.css?url`
-- Prefer composition over custom CSS
-- Use responsive modifiers: `sm:`, `md:`, `lg:`
-- Use Chinese text for UI when appropriate (as seen in codebase)
-
-## File Structure
-
-```
-src/
-├── components/         # Reusable React components
-├── db/
-│   ├── schema/        # Drizzle schema definitions
-│   └── index.ts       # Database instance
-├── lib/               # Utility functions
-├── orpc/              # ORPC (RPC layer)
-│   ├── contracts/     # Contract definitions (input/output schemas)
-│   ├── handlers/      # Server-side procedure implementations
-│   ├── middlewares/   # Middleware (e.g., DB provider)
-│   ├── contract.ts    # Contract aggregation
-│   ├── router.ts      # Router composition
-│   ├── server.ts      # Server instance
-│   ├── client.ts      # Isomorphic client
-│   └── types.ts       # Type utilities
-├── routes/            # TanStack Router file-based routes
-│   ├── __root.tsx     # Root layout
-│   ├── index.tsx      # Home page
-│   └── api/rpc.$.ts   # ORPC HTTP endpoint
-├── env.ts             # Environment variable validation
-├── index.ts           # Application entry point
-├── router.tsx         # Router configuration
-├── routeTree.gen.ts   # Auto-generated (DO NOT EDIT)
-└── styles.css         # Global styles
-```
-
-## Important Notes
-
-- **DO NOT** edit `src/routeTree.gen.ts` - it's auto-generated
-- **DO NOT** commit `.env` files - use `.env.example` for templates
-- **DO** run `bun fix` before committing to ensure code quality
-- **DO** use the `@/*` path alias instead of relative imports
-- **DO** leverage React Compiler (babel-plugin-react-compiler) - avoid manual memoization
-
-## Git Workflow
-
-1. Make changes following the style guidelines above
-2. Run `bun fix` to auto-format and lint
-3. Run `bun typecheck` to ensure type safety
-4. Test changes locally with `bun dev`
-5. Commit with clear, descriptive messages
-
-## Common Patterns
-
-### Adding a New Route
-1. Create `src/routes/my-route.tsx`
-2. Export route with `createFileRoute`
-3. Route tree auto-updates on save
-
-### Adding Database Table
-1. Create schema in `src/db/schema/my-table.ts`
-2. Export from `src/db/schema/index.ts`
-3. Run `bun db:generate` to create migration
-4. Run `bun db:migrate` to apply migration
-
-### Creating Server Function
-```typescript
-const myServerFn = createServerFn({ method: 'POST' })
-  .validator((data) => mySchema.parse(data))
-  .handler(async ({ data }) => {
-    // Server-side logic here
-    return result
-  })
-```
-
-### Creating ORPC Procedures
-
-**Step 1: Define Contract** (`src/orpc/contracts/my-feature.ts`)
-```typescript
-import { oc } from '@orpc/contract'
-import { z } from 'zod'
-
-export const myContract = {
-  get: oc.input(z.object({ id: z.uuid() })).output(mySchema),
-  create: oc.input(createSchema).output(mySchema),
-}
-```
-
-**Step 2: Implement Handler** (`src/orpc/handlers/my-feature.ts`)
-```typescript
-import { os } from '@/orpc/server'
-import { dbProvider } from '@/orpc/middlewares'
-
-export const get = os.myFeature.get
-  .use(dbProvider)
-  .handler(async ({ context, input }) => {
-    const item = await context.db.query.myTable.findFirst(...)
-    return item
-  })
-```
-
-**Step 3: Register in Contract & Router**
-```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 })
-```
-
-**Step 4: Use in Component**
-```typescript
-import { orpc } from '@/orpc'
-const query = useSuspenseQuery(orpc.myFeature.get.queryOptions({ id }))
-const mutation = useMutation(orpc.myFeature.create.mutationOptions())
-```
-
----
-
-**Last Updated**: 2026-01-18
-**Project Version**: Based on package.json dependencies

apps/desktop/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

apps/desktop/copy.ts

@@ -0,0 +1,470 @@
+import * as path from 'node:path'
+import { Schema } from '@effect/schema'
+import { $ } from 'bun'
+import { Console, Context, Data, Effect, Layer } from 'effect'
+
+// ============================================================================
+// Domain Models & Schema
+// ============================================================================
+
+/**
+ * Bun 构建目标后缀
+ */
+const BunTargetSuffixSchema = Schema.Literal(
+  'windows-x64',
+  'darwin-arm64',
+  'darwin-x64',
+  'linux-x64',
+  'linux-arm64',
+)
+
+/**
+ * Tauri sidecar 目标三元组
+ */
+const TauriTargetSchema = Schema.Literal(
+  'x86_64-pc-windows-msvc',
+  'aarch64-apple-darwin',
+  'x86_64-apple-darwin',
+  'x86_64-unknown-linux-gnu',
+  'aarch64-unknown-linux-gnu',
+)
+
+/**
+ * 目标映射配置
+ */
+const TargetMappingSchema = Schema.Struct({
+  bunSuffix: BunTargetSuffixSchema,
+  tauriTarget: TauriTargetSchema,
+})
+
+type TargetMapping = Schema.Schema.Type<typeof TargetMappingSchema>
+
+/**
+ * 复制配置
+ */
+const CopyConfigSchema = Schema.Struct({
+  sourceDir: Schema.String.pipe(Schema.nonEmptyString()),
+  targetDir: Schema.String.pipe(Schema.nonEmptyString()),
+  baseName: Schema.String.pipe(Schema.nonEmptyString()),
+  mappings: Schema.Array(TargetMappingSchema).pipe(Schema.minItems(1)),
+})
+
+type CopyConfig = Schema.Schema.Type<typeof CopyConfigSchema>
+
+/**
+ * 复制结果
+ */
+const CopyResultSchema = Schema.Struct({
+  bunSuffix: BunTargetSuffixSchema,
+  tauriTarget: TauriTargetSchema,
+  sourceFile: Schema.String,
+  targetFile: Schema.String,
+  success: Schema.Boolean,
+})
+
+type CopyResult = Schema.Schema.Type<typeof CopyResultSchema>
+
+// ============================================================================
+// Error Models
+// ============================================================================
+
+class ConfigError extends Data.TaggedError('ConfigError')<{
+  readonly message: string
+  readonly cause: unknown
+}> {}
+
+class FileSystemError extends Data.TaggedError('FileSystemError')<{
+  readonly operation: string
+  readonly path: string
+  readonly cause: unknown
+}> {}
+
+class CopyError extends Data.TaggedError('CopyError')<{
+  readonly source: string
+  readonly target: string
+  readonly cause: unknown
+}> {}
+
+// ============================================================================
+// Services
+// ============================================================================
+
+/**
+ * 配置服务
+ */
+class CopyConfigService extends Context.Tag('CopyConfigService')<
+  CopyConfigService,
+  CopyConfig
+>() {
+  /**
+   * 从原始数据创建并验证配置
+   */
+  static fromRaw = (raw: unknown) =>
+    Effect.gen(function* () {
+      const decoded = yield* Schema.decodeUnknown(CopyConfigSchema)(raw)
+      return decoded
+    }).pipe(
+      Effect.catchAll((error) =>
+        Effect.fail(
+          new ConfigError({
+            message: '配置验证失败',
+            cause: error,
+          }),
+        ),
+      ),
+    )
+
+  /**
+   * 默认配置 Layer
+   */
+  static readonly Live = Layer.effect(
+    CopyConfigService,
+    CopyConfigService.fromRaw({
+      sourceDir: path.join(__dirname, '..', 'server', 'out'),
+      targetDir: path.join(__dirname, 'src-tauri', 'binaries'),
+      baseName: 'server',
+      mappings: [
+        {
+          bunSuffix: 'windows-x64',
+          tauriTarget: 'x86_64-pc-windows-msvc',
+        },
+        {
+          bunSuffix: 'darwin-arm64',
+          tauriTarget: 'aarch64-apple-darwin',
+        },
+        {
+          bunSuffix: 'darwin-x64',
+          tauriTarget: 'x86_64-apple-darwin',
+        },
+        {
+          bunSuffix: 'linux-x64',
+          tauriTarget: 'x86_64-unknown-linux-gnu',
+        },
+        {
+          bunSuffix: 'linux-arm64',
+          tauriTarget: 'aarch64-unknown-linux-gnu',
+        },
+      ],
+    } satisfies CopyConfig),
+  )
+}
+
+/**
+ * 文件系统服务
+ */
+class FileSystemService extends Context.Tag('FileSystemService')<
+  FileSystemService,
+  {
+    readonly ensureDir: (dir: string) => Effect.Effect<void, FileSystemError>
+    readonly fileExists: (
+      filePath: string,
+    ) => Effect.Effect<boolean, FileSystemError>
+    readonly dirExists: (
+      dirPath: string,
+    ) => Effect.Effect<boolean, FileSystemError>
+    readonly copyFile: (
+      source: string,
+      target: string,
+    ) => Effect.Effect<void, CopyError>
+  }
+>() {
+  static readonly Live = Layer.succeed(FileSystemService, {
+    ensureDir: (dir: string) =>
+      Effect.tryPromise({
+        try: async () => {
+          await $`mkdir -p ${dir}`
+        },
+        catch: (cause: unknown) =>
+          new FileSystemError({
+            operation: 'ensureDir',
+            path: dir,
+            cause,
+          }),
+      }),
+
+    fileExists: (filePath: string) =>
+      Effect.tryPromise({
+        try: async () => {
+          const file = Bun.file(filePath)
+          return await file.exists()
+        },
+        catch: (cause: unknown) =>
+          new FileSystemError({
+            operation: 'fileExists',
+            path: filePath,
+            cause,
+          }),
+      }),
+
+    dirExists: (dirPath: string) =>
+      Effect.tryPromise({
+        try: async () => {
+          const { default: fs } = await import('node:fs/promises')
+          try {
+            const stat = await fs.stat(dirPath)
+            return stat.isDirectory()
+          } catch {
+            return false
+          }
+        },
+        catch: (cause: unknown) =>
+          new FileSystemError({
+            operation: 'dirExists',
+            path: dirPath,
+            cause,
+          }),
+      }),
+
+    copyFile: (source: string, target: string) =>
+      Effect.tryPromise({
+        try: async () => {
+          await $`cp ${source} ${target}`
+        },
+        catch: (cause: unknown) =>
+          new CopyError({
+            source,
+            target,
+            cause,
+          }),
+      }),
+  })
+}
+
+/**
+ * 复制服务
+ */
+class CopyService extends Context.Tag('CopyService')<
+  CopyService,
+  {
+    readonly copyBinary: (
+      config: CopyConfig,
+      mapping: TargetMapping,
+    ) => Effect.Effect<CopyResult, CopyError | FileSystemError>
+    readonly copyAllBinaries: (
+      config: CopyConfig,
+    ) => Effect.Effect<ReadonlyArray<CopyResult>, CopyError | FileSystemError>
+  }
+>() {
+  static readonly Live = Layer.effect(
+    CopyService,
+    Effect.gen(function* () {
+      const fs = yield* FileSystemService
+
+      return {
+        copyBinary: (config: CopyConfig, mapping: TargetMapping) =>
+          Effect.gen(function* () {
+            const { sourceDir, targetDir, baseName } = config
+            const { bunSuffix, tauriTarget } = mapping
+
+            // 确定文件扩展名（Windows 需要 .exe）
+            const ext = tauriTarget.includes('windows') ? '.exe' : ''
+
+            // 构建源文件和目标文件路径
+            const sourceFile = path.join(
+              sourceDir,
+              `${baseName}-${bunSuffix}${ext}`,
+            )
+            const targetFile = path.join(
+              targetDir,
+              `${baseName}-${tauriTarget}${ext}`,
+            )
+
+            // 检查源文件是否存在
+            const exists = yield* fs.fileExists(sourceFile)
+            if (!exists) {
+              yield* Console.log(`⚠️  跳过 ${bunSuffix}: 源文件不存在`)
+              return {
+                bunSuffix,
+                tauriTarget,
+                sourceFile,
+                targetFile,
+                success: false,
+              } satisfies CopyResult
+            }
+
+            // 复制文件
+            yield* fs.copyFile(sourceFile, targetFile)
+
+            yield* Console.log(`✓ ${bunSuffix} → ${tauriTarget}`)
+            yield* Console.log(`  ${sourceFile}`)
+            yield* Console.log(`  → ${targetFile}\n`)
+
+            return {
+              bunSuffix,
+              tauriTarget,
+              sourceFile,
+              targetFile,
+              success: true,
+            } satisfies CopyResult
+          }),
+
+        copyAllBinaries: (config: CopyConfig) =>
+          Effect.gen(function* () {
+            const effects = config.mappings.map((mapping) =>
+              Effect.gen(function* () {
+                const { sourceDir, targetDir, baseName } = config
+                const { bunSuffix, tauriTarget } = mapping
+
+                const ext = tauriTarget.includes('windows') ? '.exe' : ''
+                const sourceFile = path.join(
+                  sourceDir,
+                  `${baseName}-${bunSuffix}${ext}`,
+                )
+                const targetFile = path.join(
+                  targetDir,
+                  `${baseName}-${tauriTarget}${ext}`,
+                )
+
+                const exists = yield* fs.fileExists(sourceFile)
+                if (!exists) {
+                  yield* Console.log(`⚠️  跳过 ${bunSuffix}: 源文件不存在`)
+                  return {
+                    bunSuffix,
+                    tauriTarget,
+                    sourceFile,
+                    targetFile,
+                    success: false,
+                  } satisfies CopyResult
+                }
+
+                yield* fs.copyFile(sourceFile, targetFile)
+
+                yield* Console.log(`✓ ${bunSuffix} → ${tauriTarget}`)
+                yield* Console.log(`  ${sourceFile}`)
+                yield* Console.log(`  → ${targetFile}\n`)
+
+                return {
+                  bunSuffix,
+                  tauriTarget,
+                  sourceFile,
+                  targetFile,
+                  success: true,
+                } satisfies CopyResult
+              }),
+            )
+
+            return yield* Effect.all(effects, { concurrency: 'unbounded' })
+          }),
+      }
+    }),
+  )
+}
+
+/**
+ * 报告服务
+ */
+class ReporterService extends Context.Tag('ReporterService')<
+  ReporterService,
+  {
+    readonly printSummary: (
+      results: ReadonlyArray<CopyResult>,
+    ) => Effect.Effect<void>
+  }
+>() {
+  static readonly Live = Layer.succeed(ReporterService, {
+    printSummary: (results: ReadonlyArray<CopyResult>) =>
+      Effect.gen(function* () {
+        const successful = results.filter((r) => r.success)
+        const failed = results.filter((r) => !r.success)
+
+        yield* Console.log('\n📦 复制摘要:')
+        yield* Console.log(`  ✅ 成功: ${successful.length}`)
+        yield* Console.log(`  ⚠️  跳过: ${failed.length}`)
+
+        if (successful.length > 0) {
+          yield* Console.log('\n成功复制的文件:')
+          for (const result of successful) {
+            yield* Console.log(
+              `  • ${result.bunSuffix} → ${result.tauriTarget}`,
+            )
+          }
+        }
+
+        if (failed.length > 0) {
+          yield* Console.log('\n跳过的文件:')
+          for (const result of failed) {
+            yield* Console.log(`  • ${result.bunSuffix} (源文件不存在)`)
+          }
+        }
+      }),
+  })
+}
+
+// ============================================================================
+// Main Program
+// ============================================================================
+
+const program = Effect.gen(function* () {
+  const config = yield* CopyConfigService
+  const fs = yield* FileSystemService
+  const copier = yield* CopyService
+  const reporter = yield* ReporterService
+
+  yield* Console.log('📦 开始复制二进制文件到 Tauri sidecar 目录...\n')
+
+  // 1. 检查源目录
+  const sourceExists = yield* fs.dirExists(config.sourceDir)
+  if (!sourceExists) {
+    yield* Console.error(`❌ 源目录不存在: ${config.sourceDir}`)
+    yield* Console.log(
+      '💡 提示: 请先在 apps/server 中运行 bun run compile 构建服务器二进制文件',
+    )
+    return yield* Effect.fail(
+      new FileSystemError({
+        operation: 'checkSourceDir',
+        path: config.sourceDir,
+        cause: '源目录不存在',
+      }),
+    )
+  }
+
+  // 2. 创建目标目录
+  yield* fs.ensureDir(config.targetDir)
+  yield* Console.log(`✓ 目标目录: ${config.targetDir}\n`)
+
+  // 3. 并行复制所有二进制文件
+  const results = yield* copier.copyAllBinaries(config)
+
+  // 4. 输出摘要
+  yield* reporter.printSummary(results)
+
+  return results
+})
+
+// ============================================================================
+// Layer Composition
+// ============================================================================
+
+const MainLayer = Layer.mergeAll(
+  CopyConfigService.Live,
+  FileSystemService.Live,
+  CopyService.Live.pipe(Layer.provide(FileSystemService.Live)),
+  ReporterService.Live,
+)
+
+// ============================================================================
+// Runner
+// ============================================================================
+
+const runnable = program.pipe(
+  Effect.provide(MainLayer),
+  Effect.catchTags({
+    ConfigError: (error) =>
+      Console.error(`❌ 配置错误: ${error.message}`, error.cause),
+    FileSystemError: (error) =>
+      Console.error(
+        `❌ 文件系统错误 [${error.operation}]: ${error.path}`,
+        error.cause,
+      ),
+    CopyError: (error) =>
+      Console.error(
+        `❌ 复制失败: ${error.source} → ${error.target}`,
+        error.cause,
+      ),
+  }),
+  Effect.tapErrorCause((cause) => Console.error('❌ 未预期的错误:', cause)),
+)
+
+Effect.runPromise(runnable).catch(() => {
+  process.exit(1)
+})

apps/desktop/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@furtherverse/desktop",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "bun run copy && tauri build",
+    "copy": "rm -rf binaries && bun --bun copy.ts",
+    "dev": "bun run copy && tauri dev"
+  },
+  "devDependencies": {
+    "@effect/schema": "catalog:",
+    "@furtherverse/tsconfig": "workspace:*",
+    "@tauri-apps/cli": "catalog:",
+    "@types/bun": "catalog:",
+    "effect": "catalog:",
+    "typescript": "catalog:"
+  }
+}

apps/desktop/src-tauri/AGENTS.md

@@ -6,8 +6,10 @@
 
 - **项目类型**: Tauri v2 桌面应用（轻量级壳子）
 - **后端**: Rust (Edition 2021)
-- **架构**: Sidecar 模式 - Sidecar Server 承载主要业务逻辑
-- **设计理念**: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Sidecar Server 处理
+- **架构**: Sidecar 模式 - Sidecar App 承载主要业务逻辑
+- **设计理念**: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Sidecar App 处理
+- **开发模式**: 使用 localhost:3000（需手动启动开发服务器）
+- **生产模式**: 自动启动 Sidecar 二进制
 - **异步运行时**: Tokio
 - **Rust 版本**: 1.92.0+
 - **工具管理**: 使用 mise 管理 Rust 和 Tauri CLI 版本（见 `mise.toml`）
@@ -16,13 +18,22 @@
 
 ### 开发运行
 ```bash
-# 开发模式运行 (带 hot-reload)
+# 开发模式运行 (需要先启动开发服务器)
+# 终端 1: 启动前端开发服务器
+bun run dev
+
+# 终端 2: 启动 Tauri 应用
 tauri dev
 
-# 仅运行 Rust 二进制 (不推荐，需要手动启动 Sidecar Server)
-cargo run
+# 或者使用单命令并行启动（需要配置 package.json）
+bun run dev:tauri
 ```
 
+**开发模式说明**：
+- 开发模式下，Tauri 直接连接到 `localhost:3000`（不启动 sidecar 二进制）
+- 需要手动运行 `bun run dev` 来启动开发服务器
+- 支持热重载（HMR），无需重启 Tauri 应用
+
 ### 构建
 ```bash
 # 开发构建 (debug mode)
@@ -80,7 +91,7 @@ cargo clean
 ## 项目结构
 
 ```
-tauri-shell/
+server-desktop/
 ├── src/
 │   ├── main.rs          # 入口文件 (仅调用 lib::run)
 │   ├── lib.rs           # 核心应用逻辑 (注册插件、命令、状态)
@@ -88,7 +99,7 @@ tauri-shell/
 │   │   └── mod.rs       # 原生桌面功能命令 (文件对话框、通知等)
 │   └── sidecar.rs       # Sidecar 进程管理 (启动、端口扫描、清理)
 ├── binaries/            # Sidecar 二进制文件
-│   └── server-*   # Sidecar Server 可执行文件 (示例: server)
+│   └── app-*   # Sidecar App 可执行文件 (示例: app)
 ├── capabilities/        # Tauri v2 权限配置
 │   └── default.json
 ├── icons/               # 应用图标资源
@@ -171,14 +182,14 @@ async fn is_port_available(port: u16) -> bool {
 // ✅ 推荐
 let sidecar = app_handle
     .shell()
-    .sidecar("server")
-    .expect("无法找到 server sidecar");
+    .sidecar("app")
+    .expect("无法找到 app sidecar");
 
 let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
 
 // 日志记录
-eprintln!("✗ Sidecar Server 启动失败");
-println!("✓ Sidecar Server 启动成功！");
+eprintln!("✗ Sidecar App 启动失败");
+println!("✓ Sidecar App 启动成功！");
 
 // ❌ 避免
 let data = read_file().unwrap();  // 无上下文信息
@@ -215,7 +226,7 @@ tauri::async_runtime::spawn(async move {
 
 ```rust
 // ✅ 推荐
-// 全局状态：存储 Sidecar Server 进程句柄
+// 全局状态：存储 Sidecar App 进程句柄
 struct SidecarProcess(Mutex<Option<CommandChild>>);
 
 // 检查端口是否可用
@@ -286,9 +297,9 @@ if let Some(state) = app_handle.try_state::<SidecarProcess>() {
 // 启动 sidecar
 let sidecar = app_handle
     .shell()
-    .sidecar("server")
-    .expect("无法找到 server sidecar")
-    .env("NITRO_PORT", port.to_string());
+    .sidecar("app")
+    .expect("无法找到 app sidecar")
+    .env("PORT", port.to_string());
 
 // 清理进程
 match event {
@@ -323,12 +334,17 @@ tokio = { version = "1", features = ["net"] }
 
 ## 最佳实践
 
-1. **进程生命周期**: 始终在应用退出时清理子进程和资源
-2. **端口管理**: 使用端口扫描避免硬编码端口冲突
-3. **超时处理**: 异步操作设置合理的超时时间 (如 5 秒)
-4. **日志**: 使用表情符号 (✓/✗) 和中文消息提供清晰的状态反馈
-5. **错误退出**: 关键错误时调用 `std::process::exit(1)`
-6. **窗口配置**: 使用 `WebviewWindowBuilder` 动态创建窗口
+1. **开发环境配置**: 
+   - 开发模式下需先启动前端开发服务器（`bun run dev`），再启动 Tauri（`tauri dev`）
+   - 生产构建自动打包 sidecar 二进制，无需额外配置
+2. **进程生命周期**: 始终在应用退出时清理子进程和资源
+3. **端口管理**: 
+   - 开发模式固定使用 3000 端口（与开发服务器匹配）
+   - 生产模式使用端口扫描避免硬编码端口冲突
+4. **超时处理**: 异步操作设置合理的超时时间 (如 5 秒)
+5. **日志**: 使用表情符号 (✓/✗/🔧/🚀) 和中文消息提供清晰的状态反馈
+6. **错误退出**: 关键错误时调用 `std::process::exit(1)`
+7. **窗口配置**: 使用 `WebviewWindowBuilder` 动态创建窗口
 
 ## 提交代码前检查清单
 

apps/desktop/src-tauri/Cargo.lock

@@ -2902,6 +2902,17 @@ dependencies = [
  "syn 2.0.114",
 ]
 
+[[package]]
+name = "server-desktop"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "tauri",
+ "tauri-build",
+ "tauri-plugin-shell",
+ "tokio",
+]
+
 [[package]]
 name = "servo_arc"
 version = "0.2.0"
@@ -3423,17 +3434,6 @@ dependencies = [
  "wry",
 ]
 
-[[package]]
-name = "tauri-shell"
-version = "0.1.0"
-dependencies = [
- "serde",
- "tauri",
- "tauri-build",
- "tauri-plugin-shell",
- "tokio",
-]
-
 [[package]]
 name = "tauri-utils"
 version = "2.8.1"

apps/desktop/src-tauri/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "tauri-shell"
+name = "server-desktop"
 version = "0.1.0"
 description = "A Tauri App"
 authors = ["imbytecat"]
@@ -11,7 +11,7 @@ edition = "2021"
 # The `_lib` suffix may seem redundant but it is necessary
 # to make the lib name unique and wouldn't conflict with the bin name.
 # This seems to be only an issue on Windows, see https://github.com/rust-lang/cargo/issues/8519
-name = "tauri_shell_lib"
+name = "server_desktop_lib"
 crate-type = ["staticlib", "cdylib", "rlib"]
 
 [build-dependencies]

apps/desktop/src-tauri/capabilities/default.json

@@ -3,13 +3,22 @@
   "identifier": "default",
   "description": "Capability for the main window",
   "windows": ["main"],
+  "local": true,
+  "remote": {
+    "urls": [
+      "http://localhost:*",
+      "http://127.0.0.1:*",
+      "http{s}?://localhost(:\\d+)?/*"
+    ]
+  },
   "permissions": [
     "core:default",
+    "core:window:allow-set-title",
     {
       "identifier": "shell:allow-execute",
       "allow": [
         {
-          "name": "binaries/server",
+          "name": "binaries/app",
           "sidecar": true
         }
       ]

apps/desktop/src-tauri/src/lib.rs

@@ -25,11 +25,9 @@ pub fn run() {
         .expect("error while building tauri application")
         .run(|app_handle, event| {
             // 监听应用退出事件，清理 Sidecar 进程
-            match event {
-                tauri::RunEvent::ExitRequested { .. } | tauri::RunEvent::Exit => {
+            if let tauri::RunEvent::Exit = event {
+                // 只在 Exit 事件时清理，避免重复执行
                 sidecar::cleanup_sidecar_process(app_handle);
             }
-                _ => {}
-            }
         });
 }

apps/desktop/src-tauri/src/main.rs

@@ -2,5 +2,5 @@
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
 fn main() {
-    tauri_shell_lib::run()
+    server_desktop_lib::run()
 }

apps/desktop/src-tauri/src/sidecar.rs

@@ -7,7 +7,7 @@ use tauri_plugin_shell::ShellExt;
 
 // ===== 配置常量 =====
 
-/// Sidecar Server 启动超时时间（秒）
+/// Sidecar App 启动超时时间（秒）
 const STARTUP_TIMEOUT_SECS: u64 = 5;
 
 /// 默认起始端口
@@ -30,7 +30,7 @@ const WINDOW_TITLE: &str = "Tauri App";
 /// 全局状态：存储 Sidecar 进程句柄
 pub struct SidecarProcess(pub Mutex<Option<CommandChild>>);
 
-// 检查端口是否可用
+// 检查端口是否可用（未被占用）
 async fn is_port_available(port: u16) -> bool {
     tokio::net::TcpListener::bind(format!("127.0.0.1:{}", port))
         .await
@@ -49,7 +49,36 @@ async fn find_available_port(start: u16) -> u16 {
 
 /// 启动 Sidecar 进程并创建主窗口
 pub fn spawn_sidecar(app_handle: tauri::AppHandle) {
+    // 检测是否为开发模式
+    let is_dev = cfg!(debug_assertions);
+
+    if is_dev {
+        // 开发模式：直接创建窗口连接到 Vite 开发服务器
+        println!("🔧 开发模式");
+
+        match tauri::WebviewWindowBuilder::new(
+            &app_handle,
+            "main",
+            tauri::WebviewUrl::External("http://localhost:3000".parse().unwrap()),
+        )
+        .title(WINDOW_TITLE)
+        .inner_size(DEFAULT_WINDOW_WIDTH, DEFAULT_WINDOW_HEIGHT)
+        .center()
+        .build()
+        {
+            Ok(_) => println!("✓ 开发窗口创建成功"),
+            Err(e) => {
+                eprintln!("✗ 窗口创建失败: {}", e);
+            }
+        }
+
+        return;
+    }
+
+    // 生产模式：启动 sidecar 二进制
     tauri::async_runtime::spawn(async move {
+        println!("🚀 生产模式");
+
         // 查找可用端口
         let port = find_available_port(DEFAULT_PORT).await;
         println!("使用端口: {}", port);
@@ -58,8 +87,8 @@ pub fn spawn_sidecar(app_handle: tauri::AppHandle) {
         let sidecar = app_handle
             .shell()
             .sidecar("server")
-            .expect("无法找到 server")
-            .env("NITRO_PORT", port.to_string());
+            .expect("无法找到 app")
+            .env("PORT", port.to_string());
 
         let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
 
@@ -71,17 +100,17 @@ pub fn spawn_sidecar(app_handle: tauri::AppHandle) {
         // 监听 stdout，等待服务器就绪信号
         let start_time = std::time::Instant::now();
         let timeout = Duration::from_secs(STARTUP_TIMEOUT_SECS);
-        let mut server_ready = false;
+        let mut app_ready = false;
 
         while let Some(event) = rx.recv().await {
             if let CommandEvent::Stdout(line) = event {
                 let output = String::from_utf8_lossy(&line);
-                println!("Server: {}", output);
+                println!("App: {}", output);
 
-                // 检测服务器启动成功的标志
+                // 检测 App 启动成功的标志
                 if output.contains("Listening on:") || output.contains("localhost") {
-                    server_ready = true;
-                    println!("✓ Server 启动成功！");
+                    app_ready = true;
+                    println!("✓ App 启动成功！");
 
                     // 创建主窗口
                     let url = format!("http://localhost:{}", port);
@@ -102,16 +131,13 @@ pub fn spawn_sidecar(app_handle: tauri::AppHandle) {
 
             // 超时检查
             if start_time.elapsed() > timeout {
-                eprintln!(
-                    "✗ 启动超时: Server 未能在 {} 秒内启动",
-                    STARTUP_TIMEOUT_SECS
-                );
+                eprintln!("✗ 启动超时: App 未能在 {} 秒内启动", STARTUP_TIMEOUT_SECS);
                 break;
             }
         }
 
-        if !server_ready {
-            eprintln!("✗ Server 启动失败");
+        if !app_ready {
+            eprintln!("✗ App 启动失败");
             std::process::exit(1);
         }
     });
@@ -119,6 +145,15 @@ pub fn spawn_sidecar(app_handle: tauri::AppHandle) {
 
 /// 清理 Sidecar 进程 (在应用退出时调用)
 pub fn cleanup_sidecar_process(app_handle: &tauri::AppHandle) {
+    let is_dev = cfg!(debug_assertions);
+
+    if is_dev {
+        // 开发模式：退出时发送异常信号（exit 1），让 Turbo 停止 Vite 服务器
+        println!("🔧 开发模式退出，终止所有依赖任务...");
+        std::process::exit(1);
+    }
+
+    // 生产模式：正常清理 sidecar 进程
     println!("应用退出，正在清理 Sidecar 进程...");
     if let Some(state) = app_handle.try_state::<SidecarProcess>() {
         if let Ok(mut process) = state.0.lock() {

apps/desktop/src-tauri/tauri.conf.json

@@ -1,13 +1,8 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
-  "productName": "tauri-shell",
+  "productName": "server-desktop",
   "version": "0.1.0",
-  "identifier": "com.imbytecat.tauri-shell",
-  "build": {
-    "beforeDevCommand": "bun run dev:vite",
-    "devUrl": "http://localhost:3000",
-    "beforeBuildCommand": "bun run build"
-  },
+  "identifier": "com.imbytecat.server-desktop",
   "app": {
     "withGlobalTauri": true,
     "windows": [],

apps/desktop/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@furtherverse/tsconfig/bun.json",
+  "exclude": ["node_modules", "src-tauri"]
+}

apps/desktop/turbo.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "../../node_modules/turbo/schema.json",
+  "extends": ["//"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["@furtherverse/server#compile"],
+      "outputs": ["src-tauri/target/release/**"]
+    },
+    "dev": {
+      "dependsOn": ["@furtherverse/server#compile"],
+      "with": ["@furtherverse/server#dev"]
+    }
+  }
+}

apps/server/AGENTS.md

@@ -0,0 +1,277 @@
+# AGENTS.md - AI Coding Agent Guidelines
+
+本文档为 AI 编程助手提供此 TanStack Start 全栈项目的开发规范和指南。
+
+## 项目概览
+
+- **框架**: 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`)
+
+## 构建、Lint 和测试命令
+
+### 开发
+```bash
+bun dev                    # 使用 Turbo 并行启动 Tauri + Vite 开发服务器
+bun dev:vite               # 仅启动 Vite 开发服务器 (localhost:3000)
+bun dev:tauri              # 启动 Tauri 桌面应用
+bun db:studio              # 打开 Drizzle Studio 数据库管理界面
+```
+
+### 构建
+```bash
+bun build                  # 完整构建 (Vite → 编译 → Tauri 打包)
+bun build:vite             # 仅构建 Vite (输出到 .output/)
+bun build:compile          # 编译为独立可执行文件 (使用 build.ts)
+bun build:tauri            # 构建 Tauri 桌面安装包
+```
+
+### 代码质量
+```bash
+bun typecheck              # 运行 TypeScript 编译器检查 (tsc -b)
+bun fix                    # 运行 Biome 自动修复格式和 Lint 问题
+biome check .              # 检查但不自动修复
+biome format --write .     # 仅格式化代码
+```
+
+### 数据库
+```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`
+
+示例:
+```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 { z } from 'zod'
+import { db } from '@/db'
+import { todoTable } from '@/db/schema'
+import type { ReactNode } from 'react'
+```
+
+### 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 模式
+
+**组件**: 使用箭头函数
+```typescript
+const MyComponent = ({ title }: { title: string }) => {
+  return <div>{title}</div>
+}
+```
+
+**路由**: 使用 `createFileRoute` 定义路由
+```typescript
+export const Route = createFileRoute('/')({
+  component: Home,
+})
+```
+
+**数据获取**: 使用 TanStack Query hooks
+- `useSuspenseQuery` - 保证有数据
+- `useQuery` - 数据可能为空
+
+**Props**: 禁止直接修改 props (Biome 规则 `noReactPropAssignments`)
+
+### 数据库 Schema (Drizzle)
+
+- 在 `src/db/schema/*.ts` 定义 schema
+- 从 `src/db/schema/index.ts` 导出
+- 使用 `drizzle-orm/pg-core` 的 PostgreSQL 类型
+- 主键使用 `uuidv7()` (需要 PostgreSQL 扩展)
+- 始终包含 `createdAt` 和 `updatedAt` 时间戳
+
+示例:
+```typescript
+import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
+import { sql } from 'drizzle-orm'
+
+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()),
+})
+```
+
+### 环境变量
+
+- 使用 `@t3-oss/env-core` 进行类型安全的环境变量验证
+- 在 `src/env.ts` 定义 schema
+- 服务端变量: 无前缀
+- 客户端变量: 必须有 `VITE_` 前缀
+- 使用 Zod schema 验证
+
+### 错误处理
+
+- 异步操作使用 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 { z } from 'zod'
+
+export const myContract = {
+  get: oc.input(z.object({ id: z.uuid() })).output(mySchema),
+  create: oc.input(createSchema).output(mySchema),
+}
+```
+
+**步骤 2: 实现处理器** (`src/orpc/handlers/my-feature.ts`)
+```typescript
+import { os } from '@/orpc/server'
+import { dbProvider } from '@/orpc/middlewares'
+
+export const get = os.myFeature.get
+  .use(dbProvider)
+  .handler(async ({ context, input }) => {
+    return await context.db.query.myTable.findFirst(...)
+  })
+```
+
+**步骤 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 依赖版本

apps/server/biome.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": "//",
+  "files": {
+    "includes": ["**", "!**/routeTree.gen.ts"]
+  }
+}

apps/server/build.ts

@@ -6,14 +6,6 @@ import { Console, Context, Data, Effect, Layer } from 'effect'
 // Domain Models & Schema
 // ============================================================================
 
-const targetMap = {
-  'bun-windows-x64': 'x86_64-pc-windows-msvc',
-  'bun-darwin-arm64': 'aarch64-apple-darwin',
-  'bun-darwin-x64': 'x86_64-apple-darwin',
-  'bun-linux-x64': 'x86_64-unknown-linux-gnu',
-  'bun-linux-arm64': 'aarch64-unknown-linux-gnu',
-} as const
-
 const BunTargetSchema = Schema.Literal(
   'bun-windows-x64',
   'bun-darwin-arm64',
@@ -22,11 +14,19 @@ const BunTargetSchema = Schema.Literal(
   'bun-linux-arm64',
 )
 
+/**
+ * 将 bun target 转换为文件后缀 (去掉 'bun-' 前缀)
+ */
+const getTargetSuffix = (target: BunTarget): string => {
+  return target.replace('bun-', '')
+}
+
 type BunTarget = Schema.Schema.Type<typeof BunTargetSchema>
 
 const BuildConfigSchema = Schema.Struct({
   entrypoint: Schema.String.pipe(Schema.nonEmptyString()),
   outputDir: Schema.String.pipe(Schema.nonEmptyString()),
+  outfile: Schema.String.pipe(Schema.nonEmptyString()),
   targets: Schema.Array(BunTargetSchema).pipe(Schema.minItems(1)),
 })
 
@@ -93,11 +93,11 @@ class BuildConfigService extends Context.Tag('BuildConfigService')<
   static readonly Live = Layer.effect(
     BuildConfigService,
     BuildConfigService.fromRaw({
-      entrypoint: './.output/server/index.mjs',
-      // outputDir: './out',
-      outputDir: './src-tauri/binaries',
+      entrypoint: '.output/server/index.mjs',
+      outputDir: 'out',
+      outfile: 'server',
       targets: ['bun-windows-x64', 'bun-darwin-arm64', 'bun-linux-x64'],
-    }),
+    } satisfies BuildConfig),
   )
 }
 
@@ -150,7 +150,7 @@ class BuildService extends Context.Tag('BuildService')<
             Bun.build({
               entrypoints: [config.entrypoint],
               compile: {
-                outfile: `server-${targetMap[target]}`,
+                outfile: `${config.outfile}-${getTargetSuffix(target)}`,
                 target: target,
               },
               outdir: config.outputDir,
@@ -181,7 +181,7 @@ class BuildService extends Context.Tag('BuildService')<
                 Bun.build({
                   entrypoints: [config.entrypoint],
                   compile: {
-                    outfile: `server-${targetMap[target]}`,
+                    outfile: `${config.outfile}-${getTargetSuffix(target)}`,
                     target: target,
                   },
                   outdir: config.outputDir,

apps/server/drizzle.config.ts

@@ -3,7 +3,7 @@ import { env } from '@/env'
 
 export default defineConfig({
   out: './drizzle',
-  schema: './src/db/schema/index.ts',
+  schema: './src/server/db/schema/index.ts',
   dialect: 'postgresql',
   dbCredentials: {
     url: env.DATABASE_URL,

apps/server/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@furtherverse/server",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "compile": "bun build.ts",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "dev": "vite dev",
+    "fix": "biome check --write",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@furtherverse/utils": "workspace:*",
+    "@orpc/client": "catalog:",
+    "@orpc/contract": "catalog:",
+    "@orpc/openapi": "catalog:",
+    "@orpc/server": "catalog:",
+    "@orpc/tanstack-query": "catalog:",
+    "@orpc/zod": "catalog:",
+    "@t3-oss/env-core": "catalog:",
+    "@tanstack/react-query": "catalog:",
+    "@tanstack/react-router": "catalog:",
+    "@tanstack/react-router-ssr-query": "catalog:",
+    "@tanstack/react-start": "catalog:",
+    "@tauri-apps/api": "catalog:",
+    "drizzle-orm": "catalog:",
+    "drizzle-zod": "catalog:",
+    "postgres": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "uuid": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/platform": "catalog:",
+    "@effect/schema": "catalog:",
+    "@furtherverse/tsconfig": "workspace:*",
+    "@tailwindcss/vite": "catalog:",
+    "@tanstack/devtools-vite": "catalog:",
+    "@tanstack/react-devtools": "catalog:",
+    "@tanstack/react-query-devtools": "catalog:",
+    "@tanstack/react-router-devtools": "catalog:",
+    "@types/bun": "catalog:",
+    "@vitejs/plugin-react": "catalog:",
+    "babel-plugin-react-compiler": "catalog:",
+    "drizzle-kit": "catalog:",
+    "effect": "catalog:",
+    "nitro": "catalog:",
+    "tailwindcss": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-tsconfig-paths": "catalog:"
+  }
+}

apps/server/src/client/orpc.client.ts

@@ -0,0 +1,24 @@
+import { createORPCClient } from '@orpc/client'
+import { RPCLink } from '@orpc/client/fetch'
+import { createRouterClient } from '@orpc/server'
+import { createIsomorphicFn } from '@tanstack/react-start'
+import { getRequestHeaders } from '@tanstack/react-start/server'
+import { router } from '@/server/api/routers'
+import type { RouterClient } from '@/server/api/types'
+
+const getORPCClient = createIsomorphicFn()
+  .server(() =>
+    createRouterClient(router, {
+      context: () => ({
+        headers: getRequestHeaders(),
+      }),
+    }),
+  )
+  .client(() => {
+    const link = new RPCLink({
+      url: `${window.location.origin}/api/rpc`,
+    })
+    return createORPCClient<RouterClient>(link)
+  })
+
+export const orpc: RouterClient = getORPCClient()

apps/server/src/client/query-client.ts

@@ -0,0 +1,30 @@
+import { createTanstackQueryUtils } from '@orpc/tanstack-query'
+import { orpc as orpcClient } from './orpc.client'
+
+export const orpc = createTanstackQueryUtils(orpcClient, {
+  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() })
+          },
+        },
+      },
+    },
+  },
+})

apps/server/src/routeTree.gen.ts

@@ -9,20 +9,20 @@
 // 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 TodosRouteImport } from './routes/todos'
 import { Route as IndexRouteImport } from './routes/index'
+import { Route as ApiSplatRouteImport } from './routes/api/$'
 import { Route as ApiRpcSplatRouteImport } from './routes/api/rpc.$'
 
-const TodosRoute = TodosRouteImport.update({
-  id: '/todos',
-  path: '/todos',
-  getParentRoute: () => rootRouteImport,
-} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiSplatRoute = ApiSplatRouteImport.update({
+  id: '/api/$',
+  path: '/api/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
   id: '/api/rpc/$',
   path: '/api/rpc/$',
@@ -31,43 +31,36 @@ const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
-  '/todos': typeof TodosRoute
+  '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
-  '/todos': typeof TodosRoute
+  '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
-  '/todos': typeof TodosRoute
+  '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/todos' | '/api/rpc/$'
+  fullPaths: '/' | '/api/$' | '/api/rpc/$'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/todos' | '/api/rpc/$'
-  id: '__root__' | '/' | '/todos' | '/api/rpc/$'
+  to: '/' | '/api/$' | '/api/rpc/$'
+  id: '__root__' | '/' | '/api/$' | '/api/rpc/$'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
-  TodosRoute: typeof TodosRoute
+  ApiSplatRoute: typeof ApiSplatRoute
   ApiRpcSplatRoute: typeof ApiRpcSplatRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
-    '/todos': {
-      id: '/todos'
-      path: '/todos'
-      fullPath: '/todos'
-      preLoaderRoute: typeof TodosRouteImport
-      parentRoute: typeof rootRouteImport
-    }
     '/': {
       id: '/'
       path: '/'
@@ -75,6 +68,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/$': {
+      id: '/api/$'
+      path: '/api/$'
+      fullPath: '/api/$'
+      preLoaderRoute: typeof ApiSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/rpc/$': {
       id: '/api/rpc/$'
       path: '/api/rpc/$'
@@ -87,7 +87,7 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
-  TodosRoute: TodosRoute,
+  ApiSplatRoute: ApiSplatRoute,
   ApiRpcSplatRoute: ApiRpcSplatRoute,
 }
 export const routeTree = rootRouteImport

apps/server/src/routes/__root.tsx

@@ -1,15 +1,15 @@
 import { TanStackDevtools } from '@tanstack/react-devtools'
 import type { QueryClient } from '@tanstack/react-query'
+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 { ErrorComponent } from '@/components/Error'
 import { NotFoundComponent } from '@/components/NotFount'
-import { devtools as queryDevtools } from '@/integrations/tanstack-query'
-import { devtools as routerDevtools } from '@/integrations/tanstack-router'
 import appCss from '@/styles.css?url'
 
 export interface RouterContext {
@@ -27,7 +27,7 @@ export const Route = createRootRouteWithContext<RouterContext>()({
         content: 'width=device-width, initial-scale=1',
       },
       {
-        title: 'Fullstack Starter',
+        title: 'Furtherverse',
       },
     ],
     links: [
@@ -54,7 +54,16 @@ function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
           config={{
             position: 'bottom-right',
           }}
-          plugins={[routerDevtools, queryDevtools]}
+          plugins={[
+            {
+              name: 'TanStack Router',
+              render: <TanStackRouterDevtoolsPanel />,
+            },
+            {
+              name: 'TanStack Query',
+              render: <ReactQueryDevtoolsPanel />,
+            },
+          ]}
         />
         <Scripts />
       </body>

apps/server/src/routes/api/$.ts

@@ -0,0 +1,86 @@
+import { OpenAPIHandler } from '@orpc/openapi/fetch'
+import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
+import { ORPCError, onError, ValidationError } from '@orpc/server'
+import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+import { name, version } from '@/../package.json'
+import { router } from '@/server/api/routers'
+
+const handler = new OpenAPIHandler(router, {
+  plugins: [
+    new OpenAPIReferencePlugin({
+      docsProvider: 'scalar',
+      schemaConverters: [new ZodToJsonSchemaConverter()],
+      specGenerateOptions: {
+        info: {
+          title: name,
+          version,
+        },
+        // components: {
+        //   securitySchemes: {
+        //     bearerAuth: {
+        //       type: 'http',
+        //       scheme: 'bearer',
+        //     },
+        //   },
+        // },
+      },
+      docsPath: '/docs',
+      specPath: '/spec.json',
+    }),
+  ],
+  interceptors: [
+    onError((error) => {
+      console.error(error)
+    }),
+  ],
+  clientInterceptors: [
+    onError((error) => {
+      if (
+        error instanceof ORPCError &&
+        error.code === 'BAD_REQUEST' &&
+        error.cause instanceof ValidationError
+      ) {
+        // If you only use Zod you can safely cast to ZodIssue[]
+        const zodError = new z.ZodError(
+          error.cause.issues as z.core.$ZodIssue[],
+        )
+
+        throw new ORPCError('INPUT_VALIDATION_FAILED', {
+          status: 422,
+          message: z.prettifyError(zodError),
+          data: z.flattenError(zodError),
+          cause: error.cause,
+        })
+      }
+
+      if (
+        error instanceof ORPCError &&
+        error.code === 'INTERNAL_SERVER_ERROR' &&
+        error.cause instanceof ValidationError
+      ) {
+        throw new ORPCError('OUTPUT_VALIDATION_FAILED', {
+          cause: error.cause,
+        })
+      }
+    }),
+  ],
+})
+
+export const Route = createFileRoute('/api/$')({
+  server: {
+    handlers: {
+      ANY: async ({ request }) => {
+        const { response } = await handler.handle(request, {
+          prefix: '/api',
+          context: {
+            headers: request.headers,
+          },
+        })
+
+        return response ?? new Response('Not Found', { status: 404 })
+      },
+    },
+  },
+})

apps/server/src/routes/api/rpc.$.ts

@@ -2,7 +2,7 @@ import { ORPCError, onError, ValidationError } from '@orpc/server'
 import { RPCHandler } from '@orpc/server/fetch'
 import { createFileRoute } from '@tanstack/react-router'
 import { z } from 'zod'
-import { router } from '@/orpc/router'
+import { router } from '@/server/api/routers'
 
 const handler = new RPCHandler(router, {
   interceptors: [
@@ -49,7 +49,9 @@ export const Route = createFileRoute('/api/rpc/$')({
       ANY: async ({ request }) => {
         const { response } = await handler.handle(request, {
           prefix: '/api/rpc',
-          context: {},
+          context: {
+            headers: request.headers,
+          },
         })
 
         return response ?? new Response('Not Found', { status: 404 })

apps/server/src/routes/index.tsx

@@ -1,10 +1,12 @@
 import { useMutation, useSuspenseQuery } from '@tanstack/react-query'
 import { createFileRoute } from '@tanstack/react-router'
+import { isTauri } from '@tauri-apps/api/core'
+import { getCurrentWindow } from '@tauri-apps/api/window'
 import type { ChangeEventHandler, FormEventHandler } from 'react'
-import { useState } from 'react'
-import { orpc } from '@/orpc'
+import { useEffect, useState } from 'react'
+import { orpc } from '@/client/query-client'
 
-export const Route = createFileRoute('/todos')({
+export const Route = createFileRoute('/')({
   component: Todos,
   loader: async ({ context }) => {
     await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions())
@@ -19,6 +21,11 @@ function Todos() {
   const updateMutation = useMutation(orpc.todo.update.mutationOptions())
   const deleteMutation = useMutation(orpc.todo.remove.mutationOptions())
 
+  useEffect(() => {
+    if (!isTauri()) return
+    getCurrentWindow().setTitle('待办事项')
+  }, [])
+
   const handleCreateTodo: FormEventHandler<HTMLFormElement> = (e) => {
     e.preventDefault()
     if (newTodoTitle.trim()) {

apps/server/src/server/api/context.ts

@@ -0,0 +1,25 @@
+import type { DB } from '@/server/db'
+
+/**
+ * 基础 Context - 所有请求都包含的上下文
+ */
+export interface BaseContext {
+  headers: Headers
+}
+
+/**
+ * 数据库 Context - 通过 db middleware 扩展
+ */
+export interface DBContext extends BaseContext {
+  db: DB
+}
+
+/**
+ * 认证 Context - 通过 auth middleware 扩展（未来使用）
+ *
+ * @example
+ * export interface AuthContext extends DBContext {
+ *   userId: string
+ *   user: User
+ * }
+ */

apps/server/src/server/api/contracts/index.ts

@@ -0,0 +1,7 @@
+import * as todo from './todo.contract'
+
+export const contract = {
+  todo,
+}
+
+export type Contract = typeof contract

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

@@ -5,7 +5,7 @@ import {
   createUpdateSchema,
 } from 'drizzle-zod'
 import { z } from 'zod'
-import { todoTable } from '@/db/schema'
+import { todoTable } from '@/server/db/schema'
 
 const selectSchema = createSelectSchema(todoTable)
 

apps/server/src/server/api/middlewares/db.middleware.ts

@@ -0,0 +1,11 @@
+import { os } from '@orpc/server'
+import { getDB } from '@/server/db'
+
+export const db = os.middleware(async ({ context, next }) => {
+  return next({
+    context: {
+      ...context,
+      db: getDB(),
+    },
+  })
+})

apps/server/src/server/api/middlewares/index.ts

@@ -0,0 +1 @@
+export * from './db.middleware'

apps/server/src/server/api/routers/index.ts

@@ -0,0 +1,6 @@
+import { os } from '../server'
+import * as todo from './todo.router'
+
+export const router = os.router({
+  todo,
+})

apps/server/src/server/api/routers/todo.router.ts

@@ -1,12 +1,10 @@
 import { ORPCError } from '@orpc/server'
 import { eq } from 'drizzle-orm'
-import { todoTable } from '@/db/schema'
-import { dbProvider } from '@/orpc/middlewares'
-import { os } from '@/orpc/server'
+import { todoTable } from '@/server/db/schema'
+import { db } from '../middlewares'
+import { os } from '../server'
 
-export const list = os.todo.list
-  .use(dbProvider)
-  .handler(async ({ context }) => {
+export const list = os.todo.list.use(db).handler(async ({ context }) => {
   const todos = await context.db.query.todoTable.findMany({
     orderBy: (todos, { desc }) => [desc(todos.createdAt)],
   })
@@ -14,7 +12,7 @@ export const list = os.todo.list
 })
 
 export const create = os.todo.create
-  .use(dbProvider)
+  .use(db)
   .handler(async ({ context, input }) => {
     const [newTodo] = await context.db
       .insert(todoTable)
@@ -29,7 +27,7 @@ export const create = os.todo.create
   })
 
 export const update = os.todo.update
-  .use(dbProvider)
+  .use(db)
   .handler(async ({ context, input }) => {
     const [updatedTodo] = await context.db
       .update(todoTable)
@@ -45,7 +43,7 @@ export const update = os.todo.update
   })
 
 export const remove = os.todo.remove
-  .use(dbProvider)
+  .use(db)
   .handler(async ({ context, input }) => {
     await context.db.delete(todoTable).where(eq(todoTable.id, input.id))
   })

apps/server/src/server/api/server.ts

@@ -0,0 +1,5 @@
+import { implement } from '@orpc/server'
+import type { BaseContext } from './context'
+import { contract } from './contracts'
+
+export const os = implement(contract).$context<BaseContext>()

apps/server/src/server/api/types.ts

@@ -3,9 +3,8 @@ import type {
   InferContractRouterInputs,
   InferContractRouterOutputs,
 } from '@orpc/contract'
-import type { contract } from './contract'
+import type { Contract } from './contracts'
 
-export type Contract = typeof contract
 export type RouterClient = ContractRouterClient<Contract>
 export type RouterInputs = InferContractRouterInputs<Contract>
 export type RouterOutputs = InferContractRouterOutputs<Contract>

apps/server/src/server/db/index.ts

@@ -0,0 +1,27 @@
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { env } from '@/env'
+import * as schema from '@/server/db/schema'
+
+export const createDB = () =>
+  drizzle({
+    connection: {
+      url: env.DATABASE_URL,
+      prepare: true,
+    },
+    schema,
+  })
+
+export type DB = ReturnType<typeof createDB>
+
+export const getDB = (() => {
+  let db: DB | null = null
+
+  return (singleton = true): DB => {
+    if (!singleton) {
+      return createDB()
+    }
+
+    db ??= createDB()
+    return db
+  }
+})()

apps/server/src/server/db/schema/todo.ts

@@ -0,0 +1,8 @@
+import { boolean, pgTable, text } from 'drizzle-orm/pg-core'
+import { generatedFields } from './utils/field'
+
+export const todoTable = pgTable('todo', {
+  ...generatedFields,
+  title: text('title').notNull(),
+  completed: boolean('completed').notNull().default(false),
+})

apps/server/src/server/db/schema/utils/field.ts

@@ -0,0 +1,58 @@
+import { sql } from 'drizzle-orm'
+import { timestamp, uuid } from 'drizzle-orm/pg-core'
+import { v7 as uuidv7 } from 'uuid'
+
+// id
+
+export const id = (name: string) => uuid(name)
+export const pk = (name: string, strategy?: 'native' | 'extension') => {
+  switch (strategy) {
+    // PG 18+
+    case 'native':
+      return id(name).primaryKey().default(sql`uuidv7()`)
+
+    // PG 13+ with extension
+    case 'extension':
+      return id(name).primaryKey().default(sql`uuid_generate_v7()`)
+
+    // Any PG version
+    default:
+      return id(name)
+        .primaryKey()
+        .$defaultFn(() => uuidv7())
+  }
+}
+
+// timestamp
+
+export const createdAt = (name = 'created_at') =>
+  timestamp(name, { withTimezone: true }).notNull().defaultNow()
+
+export const updatedAt = (name = 'updated_at') =>
+  timestamp(name, { withTimezone: true })
+    .notNull()
+    .defaultNow()
+    .$onUpdateFn(() => new Date())
+
+// generated fields
+
+export const generatedFields = {
+  id: pk('id'),
+  createdAt: createdAt('created_at'),
+  updatedAt: updatedAt('updated_at'),
+}
+
+// Helper to create omit keys from generatedFields
+const createGeneratedFieldKeys = <T extends Record<string, unknown>>(
+  fields: T,
+): Record<keyof T, true> => {
+  return Object.keys(fields).reduce(
+    (acc, key) => {
+      acc[key as keyof T] = true
+      return acc
+    },
+    {} as Record<keyof T, true>,
+  )
+}
+
+export const generatedFieldKeys = createGeneratedFieldKeys(generatedFields)

apps/server/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@furtherverse/tsconfig/react.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}

apps/server/turbo.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../node_modules/turbo/schema.json",
+  "extends": ["//"],
+  "tasks": {
+    "compile": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    }
+  }
+}

biome.json

@@ -6,7 +6,6 @@
     "useIgnoreFile": true
   },
   "files": {
-    "includes": ["**", "!**/routeTree.gen.ts"],
     "ignoreUnknown": false
   },
   "formatter": {

bunfig.toml

@@ -0,0 +1,2 @@
+[install]
+publicHoistPattern = ["@types/*", "bun-types", "nitro*"]

mise.toml

@@ -1,4 +1,4 @@
 [tools]
-node = "24"
+node = "latest"
 bun = "1"
 rust = 'latest'

package.json

@@ -1,59 +1,65 @@
 {
-  "name": "fullstack-starter",
+  "name": "@furtherverse/monorepo",
+  "version": "1.0.0",
   "private": true,
   "type": "module",
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
   "scripts": {
-    "build": "bun run build:vite && bun run build:compile",
-    "build:compile": "bun build.ts",
-    "build:tauri": "tauri build",
-    "build:vite": "vite build",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "db:push": "drizzle-kit push",
-    "db:studio": "drizzle-kit studio",
-    "dev": "bun run dev:vite",
-    "dev:tauri": "tauri dev",
-    "dev:vite": "vite dev",
-    "fix": "biome check --write",
-    "typecheck": "tsc -b"
+    "build": "turbo run build",
+    "compile": "turbo run compile",
+    "deploy": "turbo run deploy",
+    "dev": "turbo run dev",
+    "fix": "turbo run fix",
+    "typecheck": "turbo run typecheck"
   },
-  "dependencies": {
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "turbo": "^2.7.5"
+  },
+  "catalog": {
+    "@biomejs/biome": "^2.3.11",
+    "@effect/platform": "^0.94.2",
+    "@effect/schema": "^0.75.5",
     "@orpc/client": "^1.13.4",
     "@orpc/contract": "^1.13.4",
+    "@orpc/openapi": "^1.13.4",
     "@orpc/server": "^1.13.4",
     "@orpc/tanstack-query": "^1.13.4",
     "@orpc/zod": "^1.13.4",
     "@t3-oss/env-core": "^0.13.10",
-    "@tanstack/react-query": "^5.90.18",
-    "@tanstack/react-router": "^1.151.0",
-    "@tanstack/react-router-ssr-query": "^1.151.0",
-    "@tanstack/react-start": "^1.151.0",
-    "drizzle-orm": "^0.45.1",
-    "drizzle-zod": "^0.8.3",
-    "postgres": "^3.4.8",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "zod": "^4.3.5"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.11",
-    "@effect/platform": "^0.94.1",
-    "@effect/schema": "^0.75.5",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/devtools-vite": "^0.4.1",
     "@tanstack/react-devtools": "^0.9.2",
+    "@tanstack/react-query": "^5.90.19",
     "@tanstack/react-query-devtools": "^5.91.2",
-    "@tanstack/react-router-devtools": "^1.151.0",
+    "@tanstack/react-router": "^1.154.12",
+    "@tanstack/react-router-devtools": "^1.154.12",
+    "@tanstack/react-router-ssr-query": "^1.154.12",
+    "@tanstack/react-start": "^1.154.12",
+    "@tauri-apps/api": "^2.9.1",
     "@tauri-apps/cli": "^2.9.6",
     "@types/bun": "^1.3.6",
     "@vitejs/plugin-react": "^5.1.2",
     "babel-plugin-react-compiler": "^1.0.0",
     "drizzle-kit": "^0.31.8",
-    "effect": "^3.19.14",
-    "nitro": "npm:nitro-nightly@latest",
+    "drizzle-orm": "^0.45.1",
+    "drizzle-zod": "^0.8.3",
+    "effect": "^3.19.15",
+    "nitro": "npm:nitro-nightly@3.0.1-20260122-201913-dfdff9e9",
+    "ohash": "^2.0.11",
+    "postgres": "^3.4.8",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "tailwindcss": "^4.1.18",
+    "turbo": "^2.7.5",
     "typescript": "^5.9.3",
-    "vite": "^8.0.0-beta.8",
-    "vite-tsconfig-paths": "^6.0.4"
+    "uuid": "^13.0.0",
+    "systeminformation": "^5.30.5",
+    "vite": "^8.0.0-beta.9",
+    "vite-tsconfig-paths": "^6.0.4",
+    "zod": "^4.3.6"
   }
 }

packages/tsconfig/base.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Base",
+  "compilerOptions": {
+    "target": "esnext",
+    "lib": ["ESNext"],
+    "module": "preserve",
+    "skipLibCheck": true,
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  },
+  "exclude": ["node_modules"]
+}

packages/tsconfig/bun.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Bun",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  }
+}

packages/tsconfig/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@furtherverse/tsconfig",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./base.json": "./base.json",
+    "./bun.json": "./bun.json",
+    "./react.json": "./react.json"
+  }
+}

packages/tsconfig/react.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "React",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx"
+  }
+}

packages/utils/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@furtherverse/utils",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "dependencies": {
+    "ohash": "catalog:",
+    "systeminformation": "catalog:"
+  },
+  "devDependencies": {
+    "@furtherverse/tsconfig": "workspace:*",
+    "typescript": "catalog:"
+  }
+}

packages/utils/src/fingerprint.ts

@@ -0,0 +1,29 @@
+import { hash } from 'ohash'
+import si from 'systeminformation'
+
+async function getSystemInfo() {
+  const [uuid, baseboard, bios, system, diskLayout, networkInterfaces] =
+    await Promise.all([
+      si.uuid(),
+      si.baseboard(),
+      si.bios(),
+      si.system(),
+      si.diskLayout(),
+      si.networkInterfaces(),
+    ])
+
+  return {
+    uuid,
+    baseboard,
+    bios,
+    system,
+    diskLayout,
+    networkInterfaces,
+  }
+}
+
+export async function getHardwareFingerprint() {
+  const systemInfo = await getSystemInfo()
+
+  return hash(systemInfo)
+}

packages/utils/src/index.ts

@@ -0,0 +1 @@
+export * from './fingerprint'

src/db/index.ts

@@ -1,13 +0,0 @@
-import { drizzle } from 'drizzle-orm/postgres-js'
-import * as schema from '@/db/schema'
-import { env } from '@/env'
-
-export function createDb() {
-  return drizzle({
-    connection: {
-      url: env.DATABASE_URL,
-      prepare: true,
-    },
-    schema,
-  })
-}

src/db/schema/todo.ts

@@ -1,15 +0,0 @@
-import { sql } from 'drizzle-orm'
-import { boolean, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
-
-export const todoTable = pgTable('todo', {
-  id: uuid('id').primaryKey().default(sql`uuidv7()`),
-  title: text('title').notNull(),
-  completed: boolean('completed').notNull().default(false),
-  createdAt: timestamp('created_at', { withTimezone: true })
-    .notNull()
-    .defaultNow(),
-  updatedAt: timestamp('updated_at', { withTimezone: true })
-    .notNull()
-    .defaultNow()
-    .$onUpdateFn(() => new Date()),
-})

src/integrations/tanstack-query/devtools.tsx

@@ -1,7 +0,0 @@
-import type { TanStackDevtoolsReactPlugin } from '@tanstack/react-devtools'
-import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
-
-export const devtools = {
-  name: 'TanStack Query',
-  render: <ReactQueryDevtoolsPanel />,
-} satisfies TanStackDevtoolsReactPlugin

src/integrations/tanstack-query/index.ts

@@ -1 +0,0 @@
-export * from './devtools'

src/integrations/tanstack-router/devtools.tsx

@@ -1,7 +0,0 @@
-import type { TanStackDevtoolsReactPlugin } from '@tanstack/react-devtools'
-import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
-
-export const devtools = {
-  name: 'TanStack Router',
-  render: <TanStackRouterDevtoolsPanel />,
-} satisfies TanStackDevtoolsReactPlugin

src/integrations/tanstack-router/index.ts

@@ -1 +0,0 @@
-export * from './devtools'

src/orpc/client.ts

@@ -1,53 +0,0 @@
-import { createORPCClient } from '@orpc/client'
-import { RPCLink } from '@orpc/client/fetch'
-import { createRouterClient } from '@orpc/server'
-import { createTanstackQueryUtils } from '@orpc/tanstack-query'
-import { createIsomorphicFn } from '@tanstack/react-start'
-import { getRequestHeaders } from '@tanstack/react-start/server'
-import { router } from './router'
-import type { RouterClient } from './types'
-
-const getORPCClient = createIsomorphicFn()
-  .server(() =>
-    createRouterClient(router, {
-      context: () => ({
-        headers: getRequestHeaders(),
-      }),
-    }),
-  )
-  .client(() => {
-    const link = new RPCLink({
-      url: `${window.location.origin}/api/rpc`,
-    })
-    return createORPCClient<RouterClient>(link)
-  })
-
-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() })
-          },
-        },
-      },
-    },
-  },
-})

src/orpc/contract.ts

@@ -1,5 +0,0 @@
-import * as todo from './contracts/todo'
-
-export const contract = {
-  todo,
-}

src/orpc/index.ts

@@ -1,2 +0,0 @@
-export { orpc } from './client'
-export * from './types'

src/orpc/middlewares/db.ts

@@ -1,29 +0,0 @@
-import { os } from '@orpc/server'
-import { createDb } from '@/db'
-
-const IS_SERVERLESS = false // TODO: 这里需要优化
-
-let globalDb: ReturnType<typeof createDb> | null = null
-
-function getDb() {
-  if (IS_SERVERLESS) {
-    return createDb()
-  }
-
-  if (!globalDb) {
-    globalDb = createDb()
-  }
-
-  return globalDb
-}
-
-export const dbProvider = os.middleware(async ({ context, next }) => {
-  const db = getDb()
-
-  return next({
-    context: {
-      ...context,
-      db,
-    },
-  })
-})

src/orpc/middlewares/index.ts

@@ -1 +0,0 @@
-export * from './db'

src/orpc/router.ts

@@ -1,6 +0,0 @@
-import * as todo from './handlers/todo'
-import { os } from './server'
-
-export const router = os.router({
-  todo,
-})

src/orpc/server.ts

@@ -1,7 +0,0 @@
-import { implement } from '@orpc/server'
-import { contract } from './contract'
-
-// biome-ignore lint/complexity/noBannedTypes: 暂无 context
-export type ORPCContext = {}
-
-export const os = implement(contract).$context<ORPCContext>()

src/routes/index.tsx

@@ -1,7 +0,0 @@
-import { createFileRoute } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/')({ component: App })
-
-function App() {
-  return <div>Hello, World!</div>
-}

tsconfig.json

@@ -1,34 +0,0 @@
-{
-  "compilerOptions": {
-    // Environment setup & latest features
-    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "target": "ESNext",
-    "module": "Preserve",
-    "moduleDetection": "force",
-    "jsx": "react-jsx",
-    "allowJs": true,
-
-    // Bundler mode
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "noEmit": true,
-
-    // Best practices
-    "strict": true,
-    "skipLibCheck": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-
-    // Some stricter flags (disabled by default)
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noPropertyAccessFromIndexSignature": false,
-
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  }
-}

turbo.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "./node_modules/turbo/schema.json",
+  "dangerouslyDisablePackageManagerCheck": true,
+  "globalDependencies": [
+    "package.json",
+    "bun.lock",
+    "turbo.json",
+    "biome.json"
+  ],
+  "tasks": {
+    "build": {
+      "outputs": ["dist/**", ".output/**"]
+    },
+    "compile": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "fix": {
+      "outputs": []
+    },
+    "typecheck": {
+      "dependsOn": ["^typecheck"],
+      "inputs": ["tsconfig.json", "tsconfig.*.json", "**/*.{ts,tsx}"],
+      "outputs": []
+    }
+  },
+  "ui": "tui"
+}