refactor: 重构演示应用目录结构与配置文件路径

- 重命名构建配置文件至指定应用目录 - 重命名 drizzle.config.ts 文件至 apps/demo-app/ 目录下 - 添加演示应用的完整包配置，包含构建、开发、数据库管理及依赖项，支持 Tauri 桌面应用开发。 - 重命名 robots.txt 文件至 demo-app 应用目录下 - 重命名 src-tauri/.gitignore 文件为 apps/demo-app/src-tauri/.gitignore - 重命名 AGENTS.md 文件至指定目录路径 - 重命名构建脚本文件以匹配新项目路径结构 - 重命名默认能力配置文件以匹配新项目路径 - 重命名 Cargo.lock 文件以匹配新的项目路径结构 - 重命名 Cargo.toml 文件以正确反映其在项目中的路径位置 - 重命名图标文件以正确匹配新项目路径 - 重命名128x128.png图标文件至demo-app应用目录下 - 重命名图标文件以正确匹配新项目路径 - 重命名图标文件以匹配新项目路径 - 重命名图标文件以正确匹配新项目路径 - 重命名图标文件以匹配新项目路径 - 重命名图标文件以正确反映其在项目中的路径位置 - 重命名图标文件以匹配新项目路径结构 - 重命名图标文件以正确匹配新项目路径 - 重命名图标文件以正确匹配新项目路径 - 重命名图标文件以正确匹配新项目路径 - 重命名图标文件以正确匹配新项目路径 - 重命名图标文件以匹配新项目路径结构 - 重命名图标文件以正确放置在演示应用的资源目录中 - 重命名图标文件以正确匹配新项目路径 - 重命名图标文件以正确匹配新项目路径 - 重命名命令模块文件路径以匹配项目结构 - 重命名文件以正确反映其在项目中的位置 - 重命名主程序文件路径以匹配项目结构 - 重命名 sidecar.rs 文件至 demo-app 项目路径下 - 重命名 tauri.conf.json 文件至指定目录路径 - 重命名错误组件文件以正确反映其在项目中的位置 - 重命名文件 NotFount.tsx 到指定目录路径 - 重命名数据库入口文件路径以适应项目结构调整 - 重命名数据 schema 文件路径以匹配项目结构 - 重命名文件以正确反映其在项目中的位置路径 - 重命名环境配置文件以正确反映其在项目中的位置。 - 重命名文件以正确反映其在项目中的路径位置 - 重命名文件以正确反映其在项目中的位置 - 重命名文件以正确反映其在项目中的路径位置 - 重命名文件以正确反映其在项目中的路径位置 - 重命名工具函数文件以正确反映其在项目中的位置 - 重命名客户端文件以正确反映其在项目中的位置 - 重命名文件以正确反映其在项目中的位置 - 重命名文件路径以正确组织项目结构中的契约文件 - 重命名文件路径以正确反映其在项目中的位置 - 重命名文件以正确反映其在项目中的位置 - 重命名数据库中间件文件以正确反映其在项目中的位置 - 重命名中间件文件路径以匹配项目结构 - 重命名路由文件以正确反映其在项目中的位置 - 重命名文件以正确反映其在项目中的位置。 - 重命名类型文件以正确反映其在项目中的路径位置 - 重命名路由配置文件以匹配项目目录结构 - 重命名根路由文件以正确反映其在项目中的位置 - 重命名RPC路由文件至demo-app应用目录下 - 重命名路由文件路径以匹配项目结构调整 - 重命名路由树生成文件至 demo-app 应用目录下 - 重命名样式文件以正确反映其在项目中的位置 - 添加 TypeScript 配置以扩展 React 项目模板并设置路径别名。 - 重命名 vite.config.ts 文件至 apps/demo-app/ 目录下 - 移除 biome.json 中对 routeTree.gen.ts 文件的排除规则 - 更新依赖版本以统一使用 catalog 依赖管理，提升项目依赖一致性并升级关键包至最新稳定版本。 - 配置安装时的公共提升模式，包含类型包和特定命名空间的包。 - 删除空的 drizzle 目录占位文件 - 将 node 版本更新为最新版本，同时将 bun 和 rust 版本设置为最新。 - 将项目名称更新为 monorepo 并重构脚本与依赖配置以支持工作区结构和统一的 turbo 管理。 - 添加基础 TypeScript 配置文件，启用严格模式并配置模块解析与编译选项以支持现代 JavaScript 特性。 - 添加 Bun 专用的 TypeScript 配置，继承基础配置并引入 Bun 类型定义。 - 添加 tsconfig 包的配置文件并定义基础、Bun 和 React 的配置导出，同时引入 Bun 类型定义作为开发依赖。 - 添加React项目专用的TypeScript配置，指定JSX处理方式并扩展基础配置。 - 删除旧的 TypeScript 配置文件以移除过时的编译选项和路径别名设置。
2026-01-21 14:31:12 +08:00
parent 5513979ebc
commit a6125718f5
71 changed files with 309 additions and 152 deletions
--- a/apps/demo-app/build.ts
+++ b/apps/demo-app/build.ts
@@ -0,0 +1,289 @@
+import { Schema } from '@effect/schema'
+import { $ } from 'bun'
+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',
+  'bun-darwin-x64',
+  'bun-linux-x64',
+  'bun-linux-arm64',
+)
+
+type BunTarget = Schema.Schema.Type<typeof BunTargetSchema>
+
+const BuildConfigSchema = Schema.Struct({
+  entrypoint: Schema.String.pipe(Schema.nonEmptyString()),
+  outputDir: Schema.String.pipe(Schema.nonEmptyString()),
+  targets: Schema.Array(BunTargetSchema).pipe(Schema.minItems(1)),
+})
+
+type BuildConfig = Schema.Schema.Type<typeof BuildConfigSchema>
+
+const BuildResultSchema = Schema.Struct({
+  target: BunTargetSchema,
+  outputs: Schema.Array(Schema.String),
+})
+
+type BuildResult = Schema.Schema.Type<typeof BuildResultSchema>
+
+// ============================================================================
+// Error Models (使用 Data.TaggedError)
+// ============================================================================
+
+class CleanError extends Data.TaggedError('CleanError')<{
+  readonly dir: string
+  readonly cause: unknown
+}> {}
+
+class BuildError extends Data.TaggedError('BuildError')<{
+  readonly target: BunTarget
+  readonly cause: unknown
+}> {}
+
+class ConfigError extends Data.TaggedError('ConfigError')<{
+  readonly message: string
+  readonly cause: unknown
+}> {}
+
+// ============================================================================
+// Services
+// ============================================================================
+
+/**
+ * 配置服务
+ */
+class BuildConfigService extends Context.Tag('BuildConfigService')<
+  BuildConfigService,
+  BuildConfig
+>() {
+  /**
+   * 从原始数据创建并验证配置
+   */
+  static fromRaw = (raw: unknown) =>
+    Effect.gen(function* () {
+      const decoded = yield* Schema.decodeUnknown(BuildConfigSchema)(raw)
+      return decoded
+    }).pipe(
+      Effect.catchAll((error) =>
+        Effect.fail(
+          new ConfigError({
+            message: '配置验证失败',
+            cause: error,
+          }),
+        ),
+      ),
+    )
+
+  /**
+   * 默认配置 Layer
+   */
+  static readonly Live = Layer.effect(
+    BuildConfigService,
+    BuildConfigService.fromRaw({
+      entrypoint: '.output/server/index.mjs',
+      // outputDir: 'out',
+      outputDir: 'src-tauri/binaries',
+      targets: ['bun-windows-x64', 'bun-darwin-arm64', 'bun-linux-x64'],
+    }),
+  )
+}
+
+/**
+ * 文件系统服务
+ */
+class FileSystemService extends Context.Tag('FileSystemService')<
+  FileSystemService,
+  {
+    readonly cleanDir: (dir: string) => Effect.Effect<void, CleanError>
+  }
+>() {
+  static readonly Live = Layer.succeed(FileSystemService, {
+    cleanDir: (dir: string) =>
+      Effect.tryPromise({
+        try: async () => {
+          await $`rm -rf ${dir}`
+        },
+        catch: (cause: unknown) =>
+          new CleanError({
+            dir,
+            cause,
+          }),
+      }),
+  })
+}
+
+/**
+ * 构建服务
+ */
+class BuildService extends Context.Tag('BuildService')<
+  BuildService,
+  {
+    readonly buildForTarget: (
+      config: BuildConfig,
+      target: BunTarget,
+    ) => Effect.Effect<BuildResult, BuildError>
+    readonly buildAll: (
+      config: BuildConfig,
+    ) => Effect.Effect<ReadonlyArray<BuildResult>, BuildError>
+  }
+>() {
+  static readonly Live = Layer.succeed(BuildService, {
+    buildForTarget: (config: BuildConfig, target: BunTarget) =>
+      Effect.gen(function* () {
+        yield* Console.log(`🔨 开始构建: ${target}`)
+
+        const output = yield* Effect.tryPromise({
+          try: () =>
+            Bun.build({
+              entrypoints: [config.entrypoint],
+              compile: {
+                outfile: `app-${targetMap[target]}`,
+                target: target,
+              },
+              outdir: config.outputDir,
+            }),
+          catch: (cause: unknown) =>
+            new BuildError({
+              target,
+              cause,
+            }),
+        })
+
+        const paths = output.outputs.map((item: { path: string }) => item.path)
+
+        return {
+          target,
+          outputs: paths,
+        } satisfies BuildResult
+      }),
+
+    buildAll: (config: BuildConfig) =>
+      Effect.gen(function* () {
+        const effects = config.targets.map((target) =>
+          Effect.gen(function* () {
+            yield* Console.log(`🔨 开始构建: ${target}`)
+
+            const output = yield* Effect.tryPromise({
+              try: () =>
+                Bun.build({
+                  entrypoints: [config.entrypoint],
+                  compile: {
+                    outfile: `app-${targetMap[target]}`,
+                    target: target,
+                  },
+                  outdir: config.outputDir,
+                }),
+              catch: (cause: unknown) =>
+                new BuildError({
+                  target,
+                  cause,
+                }),
+            })
+
+            const paths = output.outputs.map(
+              (item: { path: string }) => item.path,
+            )
+
+            return {
+              target,
+              outputs: paths,
+            } satisfies BuildResult
+          }),
+        )
+        return yield* Effect.all(effects, { concurrency: 'unbounded' })
+      }),
+  })
+}
+
+/**
+ * 报告服务
+ */
+class ReporterService extends Context.Tag('ReporterService')<
+  ReporterService,
+  {
+    readonly printSummary: (
+      results: ReadonlyArray<BuildResult>,
+    ) => Effect.Effect<void>
+  }
+>() {
+  static readonly Live = Layer.succeed(ReporterService, {
+    printSummary: (results: ReadonlyArray<BuildResult>) =>
+      Effect.gen(function* () {
+        yield* Console.log('\n📦 构建完成:')
+        for (const result of results) {
+          yield* Console.log(`  ${result.target}:`)
+          for (const path of result.outputs) {
+            yield* Console.log(`    - ${path}`)
+          }
+        }
+      }),
+  })
+}
+
+// ============================================================================
+// Main Program
+// ============================================================================
+
+const program = Effect.gen(function* () {
+  const config = yield* BuildConfigService
+  const fs = yield* FileSystemService
+  const builder = yield* BuildService
+  const reporter = yield* ReporterService
+
+  // 1. 清理输出目录
+  yield* fs.cleanDir(config.outputDir)
+  yield* Console.log(`✓ 已清理输出目录: ${config.outputDir}`)
+
+  // 2. 并行构建所有目标
+  const results = yield* builder.buildAll(config)
+
+  // 3. 输出构建摘要
+  yield* reporter.printSummary(results)
+
+  return results
+})
+
+// ============================================================================
+// Layer Composition
+// ============================================================================
+
+const MainLayer = Layer.mergeAll(
+  BuildConfigService.Live,
+  FileSystemService.Live,
+  BuildService.Live,
+  ReporterService.Live,
+)
+
+// ============================================================================
+// Runner
+// ============================================================================
+
+const runnable = program.pipe(
+  Effect.provide(MainLayer),
+  Effect.catchTags({
+    CleanError: (error) =>
+      Console.error(`❌ 清理目录失败: ${error.dir}`, error.cause),
+    BuildError: (error) =>
+      Console.error(`❌ 构建失败 [${error.target}]:`, error.cause),
+    ConfigError: (error) =>
+      Console.error(`❌ 配置错误: ${error.message}`, error.cause),
+  }),
+  Effect.tapErrorCause((cause) => Console.error('❌ 未预期的错误:', cause)),
+)
+
+Effect.runPromise(runnable).catch(() => {
+  process.exit(1)
+})
--- a/apps/demo-app/drizzle.config.ts
+++ b/apps/demo-app/drizzle.config.ts
@@ -0,0 +1,11 @@
+import { defineConfig } from 'drizzle-kit'
+import { env } from '@/env'
+
+export default defineConfig({
+  out: './drizzle',
+  schema: './src/db/schema/index.ts',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: env.DATABASE_URL,
+  },
+})
--- a/apps/demo-app/package.json
+++ b/apps/demo-app/package.json
@@ -0,0 +1,61 @@
+{
+  "name": "@furtherverse/demo-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "turbo build:tauri",
+    "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": "turbo dev:tauri",
+    "dev:tauri": "tauri dev",
+    "dev:vite": "vite dev",
+    "fix": "biome check --write",
+    "typecheck": "tsc -b"
+  },
+  "dependencies": {
+    "@orpc/client": "catalog:",
+    "@orpc/contract": "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:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "catalog:",
+    "@effect/platform": "catalog:",
+    "@effect/schema": "catalog:",
+    "@tailwindcss/vite": "catalog:",
+    "@tanstack/devtools-vite": "catalog:",
+    "@tanstack/react-devtools": "catalog:",
+    "@tanstack/react-query-devtools": "catalog:",
+    "@tanstack/react-router-devtools": "catalog:",
+    "@tauri-apps/cli": "catalog:",
+    "@types/bun": "catalog:",
+    "@vitejs/plugin-react": "catalog:",
+    "babel-plugin-react-compiler": "catalog:",
+    "drizzle-kit": "catalog:",
+    "effect": "catalog:",
+    "nitro": "catalog:",
+    "tailwindcss": "catalog:",
+    "turbo": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-tsconfig-paths": "catalog:"
+  }
+}
--- a/apps/demo-app/public/robots.txt
+++ b/apps/demo-app/public/robots.txt
@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:
--- a/apps/demo-app/src-tauri/.gitignore
+++ b/apps/demo-app/src-tauri/.gitignore
@@ -0,0 +1,10 @@
+# Generated by Cargo
+# will have compiled files and executables
+/target/
+
+# Generated by Tauri
+# will have schema files for capabilities auto-completion
+/gen/schemas
+
+# Tauri Sidecar
+binaries/
--- a/apps/demo-app/src-tauri/AGENTS.md
+++ b/apps/demo-app/src-tauri/AGENTS.md
@@ -0,0 +1,357 @@
+# AGENTS.md - Tauri Shell 项目开发指南
+
+本文档为 AI 编程助手和开发者提供项目规范、构建命令和代码风格指南。
+
+## 项目概览
+
+- **项目类型**: Tauri v2 桌面应用（轻量级壳子）
+- **后端**: Rust (Edition 2021)
+- **架构**: Sidecar 模式 - Sidecar App 承载主要业务逻辑
+- **设计理念**: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Sidecar App 处理
+- **开发模式**: 使用 localhost:3000（需手动启动开发服务器）
+- **生产模式**: 自动启动 Sidecar 二进制
+- **异步运行时**: Tokio
+- **Rust 版本**: 1.92.0+
+- **工具管理**: 使用 mise 管理 Rust 和 Tauri CLI 版本（见 `mise.toml`）
+
+## 构建、测试、运行命令
+
+### 开发运行
+```bash
+# 开发模式运行 (需要先启动开发服务器)
+# 终端 1: 启动前端开发服务器
+bun run dev
+
+# 终端 2: 启动 Tauri 应用
+tauri dev
+
+# 或者使用单命令并行启动（需要配置 package.json）
+bun run dev:tauri
+```
+
+**开发模式说明**：
+- 开发模式下，Tauri 直接连接到 `localhost:3000`（不启动 sidecar 二进制）
+- 需要手动运行 `bun run dev` 来启动开发服务器
+- 支持热重载（HMR），无需重启 Tauri 应用
+
+### 构建
+```bash
+# 开发构建 (debug mode)
+cargo build
+
+# 生产构建
+cargo build --release
+
+# Tauri 应用打包 (生成安装程序)
+tauri build
+```
+
+### 代码检查
+```bash
+# 编译检查 (不生成二进制)
+cargo check
+
+# Clippy 代码质量检查
+cargo clippy
+
+# Clippy 严格模式 (所有警告视为错误)
+cargo clippy -- -D warnings
+
+# 代码格式化检查
+cargo fmt -- --check
+
+# 自动格式化代码
+cargo fmt
+```
+
+### 测试
+```bash
+# 运行所有测试
+cargo test
+
+# 运行单个测试 (按名称过滤)
+cargo test test_function_name
+
+# 运行特定模块的测试
+cargo test module_name::
+
+# 显示测试输出 (包括 println!)
+cargo test -- --nocapture
+
+# 运行单个测试并显示输出
+cargo test test_name -- --nocapture
+```
+
+### 清理
+```bash
+# 清理构建产物
+cargo clean
+```
+
+## 项目结构
+
+```
+app-desktop/
+├── src/
+│   ├── main.rs          # 入口文件 (仅调用 lib::run)
+│   ├── lib.rs           # 核心应用逻辑 (注册插件、命令、状态)
+│   ├── commands/
+│   │   └── mod.rs       # 原生桌面功能命令 (文件对话框、通知等)
+│   └── sidecar.rs       # Sidecar 进程管理 (启动、端口扫描、清理)
+├── binaries/            # Sidecar 二进制文件
+│   └── app-*   # Sidecar App 可执行文件 (示例: app)
+├── capabilities/        # Tauri v2 权限配置
+│   └── default.json
+├── icons/               # 应用图标资源
+├── gen/schemas/         # 自动生成的 Schema (不要手动编辑)
+├── Cargo.toml          # Rust 项目配置
+├── tauri.conf.json     # Tauri 应用配置
+├── build.rs            # Rust 构建脚本
+└── mise.toml           # 开发工具版本管理
+```
+
+## Rust 代码风格指南
+
+### 导入 (Imports)
+
+- 使用标准库、外部 crate、当前 crate 的顺序，用空行分隔
+- 按字母顺序排列
+- 优先使用具体导入而非通配符 `*`
+
+```rust
+// ✅ 推荐
+use std::sync::Mutex;
+use std::time::Duration;
+
+use tauri::Manager;
+use tauri_plugin_shell::ShellExt;
+use tauri_plugin_shell::process::{CommandEvent, CommandChild};
+
+// ❌ 避免
+use tauri::*;
+```
+
+### 命名规范
+
+- **函数和变量**: `snake_case`
+- **类型、结构体、枚举、Trait**: `PascalCase`
+- **常量和静态变量**: `SCREAMING_SNAKE_CASE`
+- **生命周期参数**: 简短小写字母，如 `'a`, `'b`
+
+```rust
+// ✅ 推荐
+struct SidecarProcess(Mutex<Option<CommandChild>>);
+const DEFAULT_PORT: u16 = 3000;
+async fn find_available_port(start: u16) -> u16 { }
+
+// ❌ 避免
+struct sidecar_process { }
+const defaultPort: u16 = 3000;
+```
+
+### 类型注解
+
+- 函数参数必须有类型注解
+- 函数返回值必须明确声明 (除非返回 `()`)
+- 优先使用具体类型而非 `impl Trait` (除非必要)
+- 使用 `&str` 而非 `String` 作为只读字符串参数
+
+```rust
+// ✅ 推荐
+#[tauri::command]
+fn greet(name: &str) -> String {
+    format!("Hello, {}!", name)
+}
+
+async fn is_port_available(port: u16) -> bool {
+    tokio::net::TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .is_ok()
+}
+```
+
+### 错误处理
+
+- 使用 `Result<T, E>` 返回可能失败的操作
+- 使用 `expect()` 时提供有意义的错误消息 (中文)
+- 避免 `unwrap()` 在生产代码中，除非逻辑上保证不会 panic
+- 使用 `?` 操作符传播错误
+- 记录关键错误信息到控制台
+
+```rust
+// ✅ 推荐
+let sidecar = app_handle
+    .shell()
+    .sidecar("app")
+    .expect("无法找到 app sidecar");
+
+let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
+
+// 日志记录
+eprintln!("✗ Sidecar App 启动失败");
+println!("✓ Sidecar App 启动成功！");
+
+// ❌ 避免
+let data = read_file().unwrap();  // 无上下文信息
+```
+
+### 异步代码
+
+- 使用 `async/await` 而非手动创建 Future
+- Tauri 内部使用 `tauri::async_runtime::spawn` 启动异步任务
+- 使用 Tokio 的异步 API (如 `tokio::net::TcpListener`)
+- 避免阻塞异步运行时 (使用 `tokio::task::spawn_blocking`)
+
+```rust
+// ✅ 推荐
+tauri::async_runtime::spawn(async move {
+    let port = find_available_port(3000).await;
+    // ...
+});
+```
+
+### 格式化
+
+- 使用 `cargo fmt` 自动格式化
+- 缩进: 4 空格
+- 行宽: 100 字符 (rustfmt 默认)
+- 结构体和枚举的字段每行一个 (如果超过一定长度)
+- 链式调用适当换行提高可读性
+
+### 注释
+
+- 使用中文注释说明复杂逻辑
+- 代码块前添加简短说明注释
+- 避免显而易见的注释
+
+```rust
+// ✅ 推荐
+// 全局状态：存储 Sidecar App 进程句柄
+struct SidecarProcess(Mutex<Option<CommandChild>>);
+
+// 检查端口是否可用
+async fn is_port_available(port: u16) -> bool { }
+```
+
+## Tauri 特定规范
+
+### 模块组织
+
+- **`lib.rs`**: 主入口，负责注册插件、命令、状态管理
+- **`commands/mod.rs`**: 所有 Tauri 命令集中定义，命令必须是 `pub fn`
+- **`sidecar.rs`**: Sidecar 进程管理逻辑，导出公共 API（`spawn_sidecar`, `cleanup_sidecar_process`）
+
+```rust
+// lib.rs - 模块声明
+mod commands;
+mod sidecar;
+
+use sidecar::SidecarProcess;
+
+// 注册命令时使用模块路径
+.invoke_handler(tauri::generate_handler![commands::greet])
+```
+
+### 命令定义
+
+- 使用 `#[tauri::command]` 宏标记命令
+- 命令函数必须是公开的或在 `invoke_handler` 中注册
+- 参数类型必须实现 `serde::Deserialize`
+- 返回类型必须实现 `serde::Serialize`
+
+```rust
+#[tauri::command]
+fn greet(name: &str) -> String {
+    format!("Hello, {}!", name)
+}
+
+// 在 Builder 中注册
+.invoke_handler(tauri::generate_handler![greet])
+```
+
+### 状态管理
+
+- 使用 `app.manage()` 注册全局状态
+- 状态必须实现 `Send + Sync`
+- 使用 `Mutex` 或 `RwLock` 保证线程安全
+
+```rust
+struct SidecarProcess(Mutex<Option<CommandChild>>);
+
+// 注册状态
+app.manage(SidecarProcess(Mutex::new(None)));
+
+// 访问状态
+if let Some(state) = app_handle.try_state::<SidecarProcess>() {
+    *state.0.lock().unwrap() = Some(child);
+}
+```
+
+### Sidecar 进程管理
+
+- Sidecar 二进制必须在 `tauri.conf.json` 的 `bundle.externalBin` 中声明
+- 使用 `app.shell().sidecar()` 启动 sidecar
+- 在应用退出时清理子进程 (监听 `RunEvent::ExitRequested`)
+
+```rust
+// 启动 sidecar
+let sidecar = app_handle
+    .shell()
+    .sidecar("app")
+    .expect("无法找到 app sidecar")
+    .env("PORT", port.to_string());
+
+// 清理进程
+match event {
+    tauri::RunEvent::ExitRequested { .. } | tauri::RunEvent::Exit => {
+        if let Some(child) = process.take() {
+            let _ = child.kill();
+        }
+    }
+    _ => {}
+}
+```
+
+## 依赖管理
+
+- 在 `Cargo.toml` 中明确声明依赖版本
+- 使用语义化版本 (如 `"2"` 表示兼容 2.x.x)
+- 仅启用需要的 feature 以减少编译时间和二进制大小
+
+```toml
+tauri = { version = "2", features = [] }
+tauri-plugin-opener = "2"
+tauri-plugin-shell = "2"
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["net"] }
+```
+
+## 开发工具
+
+推荐安装以下 VSCode 扩展:
+- `tauri-apps.tauri-vscode` - Tauri 官方支持
+- `rust-lang.rust-analyzer` - Rust 语言服务器
+
+## 最佳实践
+
+1. **开发环境配置**: 
+   - 开发模式下需先启动前端开发服务器（`bun run dev`），再启动 Tauri（`tauri dev`）
+   - 生产构建自动打包 sidecar 二进制，无需额外配置
+2. **进程生命周期**: 始终在应用退出时清理子进程和资源
+3. **端口管理**: 
+   - 开发模式固定使用 3000 端口（与开发服务器匹配）
+   - 生产模式使用端口扫描避免硬编码端口冲突
+4. **超时处理**: 异步操作设置合理的超时时间 (如 5 秒)
+5. **日志**: 使用表情符号 (✓/✗/🔧/🚀) 和中文消息提供清晰的状态反馈
+6. **错误退出**: 关键错误时调用 `std::process::exit(1)`
+7. **窗口配置**: 使用 `WebviewWindowBuilder` 动态创建窗口
+
+## 提交代码前检查清单
+
+- [ ] `cargo fmt` 格式化通过
+- [ ] `cargo clippy` 无警告
+- [ ] `cargo check` 编译通过
+- [ ] `cargo test` 测试通过
+- [ ] 更新相关注释和文档
+- [ ] 检查是否有 `unwrap()` 需要替换为 `expect()`
+- [ ] 验证 Tauri 应用正常启动和退出
--- a/apps/demo-app/src-tauri/Cargo.lock
+++ b/apps/demo-app/src-tauri/Cargo.lock
--- a/apps/demo-app/src-tauri/Cargo.toml
+++ b/apps/demo-app/src-tauri/Cargo.toml
@@ -0,0 +1,24 @@
+[package]
+name = "app-desktop"
+version = "0.1.0"
+description = "A Tauri App"
+authors = ["imbytecat"]
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[lib]
+# 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 = "app_desktop_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+tauri-plugin-shell = "2"
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["net"] }
--- a/apps/demo-app/src-tauri/build.rs
+++ b/apps/demo-app/src-tauri/build.rs
@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}
--- a/apps/demo-app/src-tauri/capabilities/default.json
+++ b/apps/demo-app/src-tauri/capabilities/default.json
@@ -0,0 +1,27 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "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/app",
+          "sidecar": true
+        }
+      ]
+    }
+  ]
+}
--- a/apps/demo-app/src-tauri/icons/128x128.png
+++ b/apps/demo-app/src-tauri/icons/128x128.png
--- a/apps/demo-app/src-tauri/icons/128x128@2x.png
+++ b/apps/demo-app/src-tauri/icons/128x128@2x.png
--- a/apps/demo-app/src-tauri/icons/32x32.png
+++ b/apps/demo-app/src-tauri/icons/32x32.png
--- a/apps/demo-app/src-tauri/icons/Square107x107Logo.png
+++ b/apps/demo-app/src-tauri/icons/Square107x107Logo.png
--- a/apps/demo-app/src-tauri/icons/Square142x142Logo.png
+++ b/apps/demo-app/src-tauri/icons/Square142x142Logo.png
--- a/apps/demo-app/src-tauri/icons/Square150x150Logo.png
+++ b/apps/demo-app/src-tauri/icons/Square150x150Logo.png
--- a/apps/demo-app/src-tauri/icons/Square284x284Logo.png
+++ b/apps/demo-app/src-tauri/icons/Square284x284Logo.png
--- a/apps/demo-app/src-tauri/icons/Square30x30Logo.png
+++ b/apps/demo-app/src-tauri/icons/Square30x30Logo.png
--- a/apps/demo-app/src-tauri/icons/Square310x310Logo.png
+++ b/apps/demo-app/src-tauri/icons/Square310x310Logo.png
--- a/apps/demo-app/src-tauri/icons/Square44x44Logo.png
+++ b/apps/demo-app/src-tauri/icons/Square44x44Logo.png
--- a/apps/demo-app/src-tauri/icons/Square71x71Logo.png
+++ b/apps/demo-app/src-tauri/icons/Square71x71Logo.png
--- a/apps/demo-app/src-tauri/icons/Square89x89Logo.png
+++ b/apps/demo-app/src-tauri/icons/Square89x89Logo.png
--- a/apps/demo-app/src-tauri/icons/StoreLogo.png
+++ b/apps/demo-app/src-tauri/icons/StoreLogo.png
--- a/apps/demo-app/src-tauri/icons/icon.icns
+++ b/apps/demo-app/src-tauri/icons/icon.icns
--- a/apps/demo-app/src-tauri/icons/icon.ico
+++ b/apps/demo-app/src-tauri/icons/icon.ico
--- a/apps/demo-app/src-tauri/icons/icon.png
+++ b/apps/demo-app/src-tauri/icons/icon.png
--- a/apps/demo-app/src-tauri/src/commands/mod.rs
+++ b/apps/demo-app/src-tauri/src/commands/mod.rs
@@ -0,0 +1,8 @@
+// 原生桌面功能命令
+// 未来可能包含: 文件对话框、系统通知、剪贴板等
+
+// 示例命令 (可根据需要删除或替换)
+#[tauri::command]
+pub fn greet(name: &str) -> String {
+    format!("Hello, {}! You've been greeted from Rust!", name)
+}
--- a/apps/demo-app/src-tauri/src/lib.rs
+++ b/apps/demo-app/src-tauri/src/lib.rs
@@ -0,0 +1,33 @@
+use tauri::Manager;
+
+// 模块声明
+mod commands;
+mod sidecar;
+
+use sidecar::SidecarProcess;
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_shell::init())
+        .setup(|app| {
+            // 注册全局状态
+            app.manage(SidecarProcess(std::sync::Mutex::new(None)));
+
+            // 启动 Sidecar 进程
+            let app_handle = app.handle().clone();
+            sidecar::spawn_sidecar(app_handle);
+
+            Ok(())
+        })
+        .invoke_handler(tauri::generate_handler![commands::greet])
+        .build(tauri::generate_context!())
+        .expect("error while building tauri application")
+        .run(|app_handle, event| {
+            // 监听应用退出事件，清理 Sidecar 进程
+            if let tauri::RunEvent::Exit = event {
+                // 只在 Exit 事件时清理，避免重复执行
+                sidecar::cleanup_sidecar_process(app_handle);
+            }
+        });
+}
--- a/apps/demo-app/src-tauri/src/main.rs
+++ b/apps/demo-app/src-tauri/src/main.rs
@@ -0,0 +1,6 @@
+// Prevents additional console window on Windows in release, DO NOT REMOVE!!
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    app_desktop_lib::run()
+}
--- a/apps/demo-app/src-tauri/src/sidecar.rs
+++ b/apps/demo-app/src-tauri/src/sidecar.rs
@@ -0,0 +1,166 @@
+use std::sync::Mutex;
+use std::time::Duration;
+
+use tauri::Manager;
+use tauri_plugin_shell::process::{CommandChild, CommandEvent};
+use tauri_plugin_shell::ShellExt;
+
+// ===== 配置常量 =====
+
+/// Sidecar App 启动超时时间（秒）
+const STARTUP_TIMEOUT_SECS: u64 = 5;
+
+/// 默认起始端口
+const DEFAULT_PORT: u16 = 3000;
+
+/// 端口扫描范围（从起始端口开始扫描的端口数量）
+const PORT_SCAN_RANGE: u16 = 100;
+
+/// 窗口默认宽度
+const DEFAULT_WINDOW_WIDTH: f64 = 1200.0;
+
+/// 窗口默认高度
+const DEFAULT_WINDOW_HEIGHT: f64 = 800.0;
+
+/// 窗口标题
+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
+        .is_ok()
+}
+
+// 查找可用端口
+async fn find_available_port(start: u16) -> u16 {
+    for port in start..start + PORT_SCAN_RANGE {
+        if is_port_available(port).await {
+            return port;
+        }
+    }
+    start // 回退到起始端口
+}
+
+/// 启动 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);
+
+        // 启动 sidecar
+        let sidecar = app_handle
+            .shell()
+            .sidecar("app")
+            .expect("无法找到 app")
+            .env("PORT", port.to_string());
+
+        let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
+
+        // 保存进程句柄到全局状态
+        if let Some(state) = app_handle.try_state::<SidecarProcess>() {
+            *state.0.lock().unwrap() = Some(child);
+        }
+
+        // 监听 stdout，等待服务器就绪信号
+        let start_time = std::time::Instant::now();
+        let timeout = Duration::from_secs(STARTUP_TIMEOUT_SECS);
+        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!("App: {}", output);
+
+                // 检测 App 启动成功的标志
+                if output.contains("Listening on:") || output.contains("localhost") {
+                    app_ready = true;
+                    println!("✓ App 启动成功！");
+
+                    // 创建主窗口
+                    let url = format!("http://localhost:{}", port);
+                    tauri::WebviewWindowBuilder::new(
+                        &app_handle,
+                        "main",
+                        tauri::WebviewUrl::External(url.parse().unwrap()),
+                    )
+                    .title(WINDOW_TITLE)
+                    .inner_size(DEFAULT_WINDOW_WIDTH, DEFAULT_WINDOW_HEIGHT)
+                    .center()
+                    .build()
+                    .expect("创建窗口失败");
+
+                    break;
+                }
+            }
+
+            // 超时检查
+            if start_time.elapsed() > timeout {
+                eprintln!("✗ 启动超时: App 未能在 {} 秒内启动", STARTUP_TIMEOUT_SECS);
+                break;
+            }
+        }
+
+        if !app_ready {
+            eprintln!("✗ App 启动失败");
+            std::process::exit(1);
+        }
+    });
+}
+
+/// 清理 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() {
+            if let Some(child) = process.take() {
+                let _ = child.kill();
+                println!("✓ Sidecar 进程已终止");
+            }
+        }
+    }
+}
--- a/apps/demo-app/src-tauri/tauri.conf.json
+++ b/apps/demo-app/src-tauri/tauri.conf.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "app-desktop",
+  "version": "0.1.0",
+  "identifier": "com.imbytecat.app-desktop",
+  "app": {
+    "withGlobalTauri": true,
+    "windows": [],
+    "security": {
+      "csp": null
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": "all",
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/128x128@2x.png",
+      "icons/icon.icns",
+      "icons/icon.ico"
+    ],
+    "externalBin": ["binaries/app"]
+  }
+}
--- a/apps/demo-app/src/components/Error.tsx
+++ b/apps/demo-app/src/components/Error.tsx
@@ -0,0 +1,3 @@
+export function ErrorComponent() {
+  return <div>An unhandled error happened!</div>
+}
--- a/apps/demo-app/src/components/NotFount.tsx
+++ b/apps/demo-app/src/components/NotFount.tsx
@@ -0,0 +1,3 @@
+export function NotFoundComponent() {
+  return <div>404 - Not Found</div>
+}
--- a/apps/demo-app/src/db/index.ts
+++ b/apps/demo-app/src/db/index.ts
@@ -0,0 +1,13 @@
+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,
+  })
+}
--- a/apps/demo-app/src/db/schema/index.ts
+++ b/apps/demo-app/src/db/schema/index.ts
@@ -0,0 +1 @@
+export * from './todo'
--- a/apps/demo-app/src/db/schema/todo.ts
+++ b/apps/demo-app/src/db/schema/todo.ts
@@ -0,0 +1,15 @@
+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()),
+})
--- a/apps/demo-app/src/env.ts
+++ b/apps/demo-app/src/env.ts
@@ -0,0 +1,14 @@
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.url(),
+  },
+  clientPrefix: 'VITE_',
+  client: {
+    VITE_APP_TITLE: z.string().min(1).optional(),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+})
--- a/apps/demo-app/src/integrations/tanstack-query/devtools.tsx
+++ b/apps/demo-app/src/integrations/tanstack-query/devtools.tsx
@@ -0,0 +1,7 @@
+import type { TanStackDevtoolsReactPlugin } from '@tanstack/react-devtools'
+import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
+
+export const devtools = {
+  name: 'TanStack Query',
+  render: <ReactQueryDevtoolsPanel />,
+} satisfies TanStackDevtoolsReactPlugin
--- a/apps/demo-app/src/integrations/tanstack-query/index.ts
+++ b/apps/demo-app/src/integrations/tanstack-query/index.ts
@@ -0,0 +1 @@
+export * from './devtools'
--- a/apps/demo-app/src/integrations/tanstack-router/devtools.tsx
+++ b/apps/demo-app/src/integrations/tanstack-router/devtools.tsx
@@ -0,0 +1,7 @@
+import type { TanStackDevtoolsReactPlugin } from '@tanstack/react-devtools'
+import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
+
+export const devtools = {
+  name: 'TanStack Router',
+  render: <TanStackRouterDevtoolsPanel />,
+} satisfies TanStackDevtoolsReactPlugin
--- a/apps/demo-app/src/integrations/tanstack-router/index.ts
+++ b/apps/demo-app/src/integrations/tanstack-router/index.ts
@@ -0,0 +1 @@
+export * from './devtools'
--- a/apps/demo-app/src/lib/utils.ts
+++ b/apps/demo-app/src/lib/utils.ts
--- a/apps/demo-app/src/orpc/client.ts
+++ b/apps/demo-app/src/orpc/client.ts
@@ -0,0 +1,53 @@
+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() })
+          },
+        },
+      },
+    },
+  },
+})
--- a/apps/demo-app/src/orpc/contract.ts
+++ b/apps/demo-app/src/orpc/contract.ts
@@ -0,0 +1,5 @@
+import * as todo from './contracts/todo'
+
+export const contract = {
+  todo,
+}
--- a/apps/demo-app/src/orpc/contracts/todo.ts
+++ b/apps/demo-app/src/orpc/contracts/todo.ts
@@ -0,0 +1,43 @@
+import { oc } from '@orpc/contract'
+import {
+  createInsertSchema,
+  createSelectSchema,
+  createUpdateSchema,
+} from 'drizzle-zod'
+import { z } from 'zod'
+import { todoTable } from '@/db/schema'
+
+const selectSchema = createSelectSchema(todoTable)
+
+const insertSchema = createInsertSchema(todoTable).omit({
+  id: true,
+  createdAt: true,
+  updatedAt: true,
+})
+
+const updateSchema = createUpdateSchema(todoTable).omit({
+  id: true,
+  createdAt: true,
+  updatedAt: true,
+})
+
+export const list = oc.input(z.void()).output(z.array(selectSchema))
+
+export const create = oc.input(insertSchema).output(selectSchema)
+
+export const update = oc
+  .input(
+    z.object({
+      id: z.uuid(),
+      data: updateSchema,
+    }),
+  )
+  .output(selectSchema)
+
+export const remove = oc
+  .input(
+    z.object({
+      id: z.uuid(),
+    }),
+  )
+  .output(z.void())
--- a/apps/demo-app/src/orpc/handlers/todo.ts
+++ b/apps/demo-app/src/orpc/handlers/todo.ts
@@ -0,0 +1,51 @@
+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'
+
+export const list = os.todo.list
+  .use(dbProvider)
+  .handler(async ({ context }) => {
+    const todos = await context.db.query.todoTable.findMany({
+      orderBy: (todos, { desc }) => [desc(todos.createdAt)],
+    })
+    return todos
+  })
+
+export const create = os.todo.create
+  .use(dbProvider)
+  .handler(async ({ context, input }) => {
+    const [newTodo] = await context.db
+      .insert(todoTable)
+      .values(input)
+      .returning()
+
+    if (!newTodo) {
+      throw new ORPCError('NOT_FOUND')
+    }
+
+    return newTodo
+  })
+
+export const update = os.todo.update
+  .use(dbProvider)
+  .handler(async ({ context, input }) => {
+    const [updatedTodo] = await context.db
+      .update(todoTable)
+      .set(input.data)
+      .where(eq(todoTable.id, input.id))
+      .returning()
+
+    if (!updatedTodo) {
+      throw new ORPCError('NOT_FOUND')
+    }
+
+    return updatedTodo
+  })
+
+export const remove = os.todo.remove
+  .use(dbProvider)
+  .handler(async ({ context, input }) => {
+    await context.db.delete(todoTable).where(eq(todoTable.id, input.id))
+  })
--- a/apps/demo-app/src/orpc/index.ts
+++ b/apps/demo-app/src/orpc/index.ts
@@ -0,0 +1,2 @@
+export { orpc } from './client'
+export * from './types'
--- a/apps/demo-app/src/orpc/middlewares/db.ts
+++ b/apps/demo-app/src/orpc/middlewares/db.ts
@@ -0,0 +1,29 @@
+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,
+    },
+  })
+})
--- a/apps/demo-app/src/orpc/middlewares/index.ts
+++ b/apps/demo-app/src/orpc/middlewares/index.ts
@@ -0,0 +1 @@
+export * from './db'
--- a/apps/demo-app/src/orpc/router.ts
+++ b/apps/demo-app/src/orpc/router.ts
@@ -0,0 +1,6 @@
+import * as todo from './handlers/todo'
+import { os } from './server'
+
+export const router = os.router({
+  todo,
+})
--- a/apps/demo-app/src/orpc/server.ts
+++ b/apps/demo-app/src/orpc/server.ts
@@ -0,0 +1,7 @@
+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>()
--- a/apps/demo-app/src/orpc/types.ts
+++ b/apps/demo-app/src/orpc/types.ts
@@ -0,0 +1,11 @@
+import type {
+  ContractRouterClient,
+  InferContractRouterInputs,
+  InferContractRouterOutputs,
+} from '@orpc/contract'
+import type { contract } from './contract'
+
+export type Contract = typeof contract
+export type RouterClient = ContractRouterClient<Contract>
+export type RouterInputs = InferContractRouterInputs<Contract>
+export type RouterOutputs = InferContractRouterOutputs<Contract>
--- a/apps/demo-app/src/routeTree.gen.ts
+++ b/apps/demo-app/src/routeTree.gen.ts
@@ -0,0 +1,86 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// 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 IndexRouteImport } from './routes/index'
+import { Route as ApiRpcSplatRouteImport } from './routes/api/rpc.$'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
+  id: '/api/rpc/$',
+  path: '/api/rpc/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/api/rpc/$': typeof ApiRpcSplatRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/api/rpc/$': typeof ApiRpcSplatRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/api/rpc/$': typeof ApiRpcSplatRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/api/rpc/$'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/api/rpc/$'
+  id: '__root__' | '/' | '/api/rpc/$'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  ApiRpcSplatRoute: typeof ApiRpcSplatRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/rpc/$': {
+      id: '/api/rpc/$'
+      path: '/api/rpc/$'
+      fullPath: '/api/rpc/$'
+      preLoaderRoute: typeof ApiRpcSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  ApiRpcSplatRoute: ApiRpcSplatRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}
--- a/apps/demo-app/src/router.tsx
+++ b/apps/demo-app/src/router.tsx
@@ -0,0 +1,26 @@
+import { QueryClient } from '@tanstack/react-query'
+import { createRouter } from '@tanstack/react-router'
+import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query'
+import type { RouterContext } from './routes/__root'
+import { routeTree } from './routeTree.gen'
+
+export const getRouter = () => {
+  const queryClient = new QueryClient()
+
+  const router = createRouter({
+    routeTree,
+    context: {
+      queryClient,
+    } satisfies RouterContext,
+
+    scrollRestoration: true,
+    defaultPreloadStaleTime: 0,
+  })
+
+  setupRouterSsrQueryIntegration({
+    router,
+    queryClient,
+  })
+
+  return router
+}
--- a/apps/demo-app/src/routes/__root.tsx
+++ b/apps/demo-app/src/routes/__root.tsx
@@ -0,0 +1,63 @@
+import { TanStackDevtools } from '@tanstack/react-devtools'
+import type { QueryClient } from '@tanstack/react-query'
+import {
+  createRootRouteWithContext,
+  HeadContent,
+  Scripts,
+} from '@tanstack/react-router'
+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 {
+  queryClient: QueryClient
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  head: () => ({
+    meta: [
+      {
+        charSet: 'utf-8',
+      },
+      {
+        name: 'viewport',
+        content: 'width=device-width, initial-scale=1',
+      },
+      {
+        title: 'Fullstack Starter',
+      },
+    ],
+    links: [
+      {
+        rel: 'stylesheet',
+        href: appCss,
+      },
+    ],
+  }),
+  shellComponent: RootDocument,
+  errorComponent: () => <ErrorComponent />,
+  notFoundComponent: () => <NotFoundComponent />,
+})
+
+function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
+  return (
+    <html lang="zh-Hans">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <TanStackDevtools
+          config={{
+            position: 'bottom-right',
+          }}
+          plugins={[routerDevtools, queryDevtools]}
+        />
+        <Scripts />
+      </body>
+    </html>
+  )
+}
--- a/apps/demo-app/src/routes/api/rpc.$.ts
+++ b/apps/demo-app/src/routes/api/rpc.$.ts
@@ -0,0 +1,59 @@
+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'
+
+const handler = new RPCHandler(router, {
+  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/rpc/$')({
+  server: {
+    handlers: {
+      ANY: async ({ request }) => {
+        const { response } = await handler.handle(request, {
+          prefix: '/api/rpc',
+          context: {},
+        })
+
+        return response ?? new Response('Not Found', { status: 404 })
+      },
+    },
+  },
+})
--- a/apps/demo-app/src/routes/index.tsx
+++ b/apps/demo-app/src/routes/index.tsx
@@ -0,0 +1,215 @@
+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 { useEffect, useState } from 'react'
+import { orpc } from '@/orpc'
+
+export const Route = createFileRoute('/')({
+  component: Todos,
+  loader: async ({ context }) => {
+    await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions())
+  },
+})
+
+function Todos() {
+  const [newTodoTitle, setNewTodoTitle] = useState('')
+
+  const listQuery = useSuspenseQuery(orpc.todo.list.queryOptions())
+  const createMutation = useMutation(orpc.todo.create.mutationOptions())
+  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()) {
+      createMutation.mutate({ title: newTodoTitle.trim() })
+      setNewTodoTitle('')
+    }
+  }
+
+  const handleInputChange: ChangeEventHandler<HTMLInputElement> = (e) => {
+    setNewTodoTitle(e.target.value)
+  }
+
+  const handleToggleTodo = (id: string, currentCompleted: boolean) => {
+    updateMutation.mutate({
+      id,
+      data: { completed: !currentCompleted },
+    })
+  }
+
+  const handleDeleteTodo = (id: string) => {
+    deleteMutation.mutate({ id })
+  }
+
+  const todos = listQuery.data
+  const completedCount = todos.filter((todo) => todo.completed).length
+  const totalCount = todos.length
+  const progress = totalCount > 0 ? (completedCount / totalCount) * 100 : 0
+
+  return (
+    <div className="min-h-screen bg-slate-50 py-12 px-4 sm:px-6 font-sans">
+      <div className="max-w-2xl mx-auto space-y-8">
+        {/* Header */}
+        <div className="flex items-end justify-between">
+          <div>
+            <h1 className="text-3xl font-bold text-slate-900 tracking-tight">
+              我的待办
+            </h1>
+            <p className="text-slate-500 mt-1">保持专注，逐个击破</p>
+          </div>
+          <div className="text-right">
+            <div className="text-2xl font-semibold text-slate-900">
+              {completedCount}
+              <span className="text-slate-400 text-lg">/{totalCount}</span>
+            </div>
+            <div className="text-xs font-medium text-slate-400 uppercase tracking-wider">
+              已完成
+            </div>
+          </div>
+        </div>
+
+        {/* Add Todo Form */}
+        <form onSubmit={handleCreateTodo} className="relative group z-10">
+          <div className="relative transform transition-all duration-200 focus-within:-translate-y-1">
+            <input
+              type="text"
+              value={newTodoTitle}
+              onChange={handleInputChange}
+              placeholder="添加新任务..."
+              className="w-full pl-6 pr-32 py-5 bg-white rounded-2xl shadow-[0_8px_30px_rgb(0,0,0,0.04)] border-0 ring-1 ring-slate-100 focus:ring-2 focus:ring-indigo-500/50 outline-none transition-all placeholder:text-slate-400 text-lg text-slate-700"
+              disabled={createMutation.isPending}
+            />
+            <button
+              type="submit"
+              disabled={createMutation.isPending || !newTodoTitle.trim()}
+              className="absolute right-3 top-3 bottom-3 px-6 bg-indigo-600 hover:bg-indigo-700 text-white rounded-xl font-medium transition-all shadow-md shadow-indigo-200 disabled:opacity-50 disabled:shadow-none hover:shadow-lg hover:shadow-indigo-300 active:scale-95"
+            >
+              {createMutation.isPending ? '添加中' : '添加'}
+            </button>
+          </div>
+        </form>
+
+        {/* Progress Bar (Only visible when there are tasks) */}
+        {totalCount > 0 && (
+          <div className="h-1.5 w-full bg-slate-200 rounded-full overflow-hidden">
+            <div
+              className="h-full bg-indigo-500 transition-all duration-500 ease-out rounded-full"
+              style={{ width: `${progress}%` }}
+            />
+          </div>
+        )}
+
+        {/* Todo List */}
+        <div className="space-y-3">
+          {todos.length === 0 ? (
+            <div className="py-20 text-center">
+              <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-slate-100 mb-4">
+                <svg
+                  className="w-8 h-8 text-slate-400"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  stroke="currentColor"
+                  aria-hidden="true"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={1.5}
+                    d="M12 6v6m0 0v6m0-6h6m-6 0H6"
+                  />
+                </svg>
+              </div>
+              <p className="text-slate-500 text-lg font-medium">没有待办事项</p>
+              <p className="text-slate-400 text-sm mt-1">
+                输入上方内容添加您的第一个任务
+              </p>
+            </div>
+          ) : (
+            todos.map((todo) => (
+              <div
+                key={todo.id}
+                className={`group relative flex items-center p-4 bg-white rounded-xl border border-slate-100 shadow-sm transition-all duration-200 hover:shadow-md hover:border-slate-200 ${
+                  todo.completed ? 'bg-slate-50/50' : ''
+                }`}
+              >
+                <button
+                  type="button"
+                  onClick={() => handleToggleTodo(todo.id, todo.completed)}
+                  className={`flex-shrink-0 w-6 h-6 rounded-full border-2 transition-all duration-200 flex items-center justify-center mr-4 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 ${
+                    todo.completed
+                      ? 'bg-indigo-500 border-indigo-500'
+                      : 'border-slate-300 hover:border-indigo-500 bg-white'
+                  }`}
+                >
+                  {todo.completed && (
+                    <svg
+                      className="w-3.5 h-3.5 text-white"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      stroke="currentColor"
+                      strokeWidth={3}
+                      aria-hidden="true"
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        d="M5 13l4 4L19 7"
+                      />
+                    </svg>
+                  )}
+                </button>
+
+                <div className="flex-1 min-w-0">
+                  <p
+                    className={`text-lg transition-all duration-200 truncate ${
+                      todo.completed
+                        ? 'text-slate-400 line-through decoration-slate-300 decoration-2'
+                        : 'text-slate-700'
+                    }`}
+                  >
+                    {todo.title}
+                  </p>
+                </div>
+
+                <div className="flex items-center opacity-0 group-hover:opacity-100 transition-opacity duration-200 absolute right-4 pl-4 bg-gradient-to-l from-white via-white to-transparent sm:static sm:bg-none">
+                  <span className="text-xs text-slate-400 mr-3 hidden sm:inline-block">
+                    {new Date(todo.createdAt).toLocaleDateString('zh-CN')}
+                  </span>
+                  <button
+                    type="button"
+                    onClick={() => handleDeleteTodo(todo.id)}
+                    className="p-2 text-slate-400 hover:text-red-500 hover:bg-red-50 rounded-lg transition-colors focus:outline-none"
+                    title="删除"
+                  >
+                    <svg
+                      className="w-5 h-5"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      stroke="currentColor"
+                      strokeWidth={1.5}
+                      aria-hidden="true"
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
+                      />
+                    </svg>
+                  </button>
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
--- a/apps/demo-app/src/styles.css
+++ b/apps/demo-app/src/styles.css
@@ -0,0 +1 @@
+@import "tailwindcss";
--- a/apps/demo-app/tsconfig.json
+++ b/apps/demo-app/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "@furtherverse/tsconfig/react.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
--- a/apps/demo-app/vite.config.ts
+++ b/apps/demo-app/vite.config.ts
@@ -0,0 +1,33 @@
+import tailwindcss from '@tailwindcss/vite'
+import { devtools as tanstackDevtools } from '@tanstack/devtools-vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import react from '@vitejs/plugin-react'
+import { nitro } from 'nitro/vite'
+import { defineConfig } from 'vite'
+import tsconfigPaths from 'vite-tsconfig-paths'
+
+export default defineConfig({
+  clearScreen: false,
+  plugins: [
+    tanstackDevtools(),
+    nitro({
+      preset: 'bun',
+      serveStatic: 'inline',
+    }),
+    tsconfigPaths(),
+    tailwindcss(),
+    tanstackStart(),
+    react({
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
+  ],
+  server: {
+    port: 3000,
+    strictPort: true,
+    watch: {
+      ignored: ['**/src-tauri/**'],
+    },
+  },
+})