chore(env): 更新本地环境示例

代码 schema 用了 PG 原生 uuidv7() 函数，PG <18 会炸。在技术栈行里把
PostgreSQL 改成 PostgreSQL 18+，快速开始顶部加 callout 说明改回
Bun.randomUUIDv7() 的方式以兼容老版本。

.dockerignore

@@ -0,0 +1,13 @@
+node_modules/
+.output/
+.tanstack/
+out/
+.git/
+.env
+.env.*
+
+*.md
+*.tsbuildinfo
+*.bun-build
+
+.vscode/

.env.example

@@ -0,0 +1,6 @@
+DATABASE_URL=mysql://user:password@localhost:3306/database
+
+# Optional logging knobs (defaults are usually fine):
+# LOG_LEVEL=info       # trace|debug|info|warning|error|fatal
+# LOG_FORMAT=pretty    # pretty|json — defaults to TTY ? pretty : json
+# LOG_DB=false         # reserved for database query logging if enabled later

.gitignore

@@ -1,157 +1,23 @@
-### Custom ###
-
-# TanStack
-.tanstack/
-
-# Nitro
-.output/
-
-# Bun build
-*.bun-build
-
-# Turborepo
-.turbo/
-
-### Node ###
-
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
+# Dependencies
 node_modules/
-jspm_packages/
 
-# Snowpack dependency directory (https://snowpack.dev/)
-web_modules/
-
-# TypeScript cache
+# Build output
+.output/
+.tanstack/
+.vite/
+out/
+*.bun-build
 *.tsbuildinfo
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
 
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional stylelint cache
-.stylelintcache
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variable files
+# Env
 .env
 .env.*
 !.env.example
 
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-.parcel-cache
+# Logs
+*.log
 
-# Next.js build output
-.next
-out
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-.output
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and not Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# vuepress v2.x temp and cache directory
-.temp
-.cache
-
-# Sveltekit cache directory
-.svelte-kit/
-
-# vitepress build output
-**/.vitepress/dist
-
-# vitepress cache directory
-**/.vitepress/cache
-
-# Docusaurus cache and generated files
-.docusaurus
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# Firebase cache directory
-.firebase/
-
-# TernJS port file
-.tern-port
-
-# Stores VSCode versions used for testing VSCode extensions
-.vscode-test
-
-# yarn v3
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/sdks
-!.yarn/versions
-
-# Vite files
-vite.config.js.timestamp-*
-vite.config.ts.timestamp-*
-.vite/
+# OS
+.DS_Store

.vscode/extensions.json

@@ -1,9 +1,11 @@
 {
   "recommendations": [
     "biomejs.biome",
+    "codezombiech.gitignore",
     "hverlin.mise-vscode",
     "oven.bun-vscode",
     "redhat.vscode-yaml",
-    "tamasfe.even-better-toml"
+    "tamasfe.even-better-toml",
+    "unional.vscode-sort-package-json"
   ]
 }

.vscode/settings.json

@@ -44,6 +44,7 @@
     "**/routeTree.gen.ts": true
   },
   "js/ts.tsdk.path": "node_modules/typescript/lib",
+  "js/ts.tsdk.promptToUseWorkspaceVersion": true,
   "search.exclude": {
     "**/routeTree.gen.ts": true
   }

AGENTS.md

@@ -1,218 +1,98 @@
-# AGENTS.md - AI Coding Agent Guidelines
+# AGENTS.md
 
-Guidelines for AI agents working in this Bun monorepo.
+Repo-specific notes for AI agents.
 
-## Project Overview
+## Stack
 
-> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run <script>` for scripts. Always prefer `bun run <script>` over `bun <script>` to avoid conflicts with Bun built-in subcommands (e.g. `bun build` invokes Bun's bundler, NOT your package.json script). Never use `npm`, `npx`, or `node`.**
+- Bun-only (`mise.toml` pins `bun = 1.3.13`). Do not use `npm` / `npx` / `node` / `yarn` / `pnpm`.
+- TanStack Start + React 19 SSR + Vite + Nitro `bun` preset.
+- ORPC contract-first API, TanStack Query v5, Tailwind v4.
+- Business data source is the customer's existing **MySQL** database. This app is read-only display software.
+- There is no PostgreSQL, Drizzle schema, embedded migration flow, or local DB mutation path in this project now.
+- `scripts/seed.ts` is the only local development helper allowed to create/truncate/insert sample data. The app runtime must stay read-only.
 
-- **Monorepo**: Bun workspaces + Turborepo orchestration
-- **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js**
-- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
-- **Apps**:
-  - `apps/server` - TanStack Start fullstack web app (see `apps/server/AGENTS.md`)
-  - `apps/desktop` - Electron desktop shell, sidecar server pattern (see `apps/desktop/AGENTS.md`)
-- **Packages**: `packages/tsconfig` (shared TS configs)
+## Scripts
 
-## Build / Lint / Test Commands
-
-### Root Commands (via Turbo)
 ```bash
-bun run dev              # Start all apps in dev mode
-bun run build            # Build all apps
-bun run compile          # Compile server to standalone binary (current platform)
-bun run compile:darwin   # Compile server for macOS (arm64 + x64)
-bun run compile:linux    # Compile server for Linux (x64 + arm64)
-bun run compile:windows  # Compile server for Windows x64
-bun run dist             # Package desktop distributable (current platform)
-bun run dist:linux       # Package desktop for Linux (x64 + arm64)
-bun run dist:mac         # Package desktop for macOS (arm64 + x64)
-bun run dist:win         # Package desktop for Windows x64
-bun run fix              # Lint + format (Biome auto-fix)
-bun run typecheck        # TypeScript check across monorepo
+bun run dev
+bun run build
+bun run compile
+bun run seed
+bun run typecheck
+bun run test
+bun run fix
 ```
 
-### Server App (`apps/server`)
+Before shipping: `bun run fix && bun run typecheck && bun run test && bun run build`.
+
+## MySQL Source
+
+Environment variable:
+
 ```bash
-bun run dev                   # Vite dev server (localhost:3000)
-bun run build                 # Production build -> .output/
-bun run compile               # Compile to standalone binary (current platform)
-bun run compile:darwin        # Compile for macOS (arm64 + x64)
-bun run compile:darwin:arm64  # Compile for macOS arm64
-bun run compile:darwin:x64    # Compile for macOS x64
-bun run compile:linux         # Compile for Linux (x64 + arm64)
-bun run compile:linux:arm64   # Compile for Linux arm64
-bun run compile:linux:x64     # Compile for Linux x64
-bun run compile:windows       # Compile for Windows (default: x64)
-bun run compile:windows:x64   # Compile for Windows x64
-bun run fix                   # Biome auto-fix
-bun run typecheck             # TypeScript check
-
-# Database (Drizzle)
-bun run db:generate           # Generate migrations from schema
-bun run db:migrate            # Run migrations
-bun run db:push               # Push schema (dev only)
-bun run db:studio             # Open Drizzle Studio
+DATABASE_URL=mysql://user:password@host:3306/database
 ```
 
-### Desktop App (`apps/desktop`)
-```bash
-bun run dev                   # electron-vite dev mode (requires server dev running)
-bun run build                 # electron-vite build (main + preload)
-bun run dist                  # Build + package for current platform
-bun run dist:linux            # Build + package for Linux (x64 + arm64)
-bun run dist:linux:x64        # Build + package for Linux x64
-bun run dist:linux:arm64      # Build + package for Linux arm64
-bun run dist:mac              # Build + package for macOS (arm64 + x64)
-bun run dist:mac:arm64        # Build + package for macOS arm64
-bun run dist:mac:x64          # Build + package for macOS x64
-bun run dist:win              # Build + package for Windows x64
-bun run fix                   # Biome auto-fix
-bun run typecheck             # TypeScript check
-```
+Customer table: `ls_battery_info`.
 
-### Testing
-No test framework configured yet. When adding tests:
-```bash
-bun test path/to/test.ts              # Run single test file
-bun test -t "pattern"                 # Run tests matching pattern
-```
+| Column | Type | Meaning |
+| --- | --- | --- |
+| `id` | `int(11)` auto increment | primary key |
+| `user_id` | `int(11)` | user ID |
+| `mac` | `varchar(50)` | device MAC |
+| `dev_model` | `varchar(20)` | device model |
+| `dev_name` | `varchar(50)` | device name |
+| `is_low_power` | `varchar(10)` | `true` / `false` |
+| `power_status` | `tinyint(4)` | `0` not charging, `1` charging, `2` full |
+| `power` | `tinyint(4)` | current battery `0~100` |
+| `create_time` | `datetime` | created time |
+| `remark` | `varchar(500)` | nullable remark |
 
-## Code Style (TypeScript)
+Rules:
 
-### Formatting (Biome)
-- **Indent**: 2 spaces | **Line endings**: LF
-- **Quotes**: Single `'` | **Semicolons**: Omit (ASI)
-- **Arrow parentheses**: Always `(x) => x`
+- Only run `SELECT` queries against this table. Do not insert, update, delete, migrate, or create tables.
+- Do not add mock/fallback rows. If MySQL is unavailable, surface the error.
+- `is_low_power` is stored as a string and normalized to boolean in `src/domain/battery.ts`.
+- `power_status` is normalized to `0 | 1 | 2`.
+- Without `mac`, battery list queries return the latest record per `mac`.
+- With `mac`, battery list queries return history ordered by `create_time DESC, id DESC`, limited to 500 rows.
 
-### Imports
-Biome auto-organizes. Order: 1) External packages → 2) Internal `@/*` aliases → 3) Type imports (`import type { ... }`)
-
-```typescript
-import { createFileRoute } from '@tanstack/react-router'
-import { z } from 'zod'
-import { db } from '@/server/db'
-import type { ReactNode } from 'react'
-```
-
-### TypeScript Strictness
-- `strict: true`, `noUncheckedIndexedAccess: true`, `noImplicitOverride: true`, `verbatimModuleSyntax: true`
-- Use `@/*` path aliases (maps to `src/*`)
-
-### Naming Conventions
-| Type | Convention | Example |
-|------|------------|---------|
-| Files (utils) | kebab-case | `auth-utils.ts` |
-| Files (components) | PascalCase | `UserProfile.tsx` |
-| Components | PascalCase arrow | `const Button = () => {}` |
-| Functions | camelCase | `getUserById` |
-| Constants | UPPER_SNAKE | `MAX_RETRIES` |
-| Types/Interfaces | PascalCase | `UserProfile` |
-
-### React Patterns
-- Components: arrow functions (enforced by Biome)
-- Routes: TanStack Router file conventions (`export const Route = createFileRoute(...)`)
-- Data fetching: `useSuspenseQuery(orpc.feature.list.queryOptions())`
-
-### Error Handling
-- Use `try-catch` for async operations; throw descriptive errors
-- ORPC: Use `ORPCError` with proper codes (`NOT_FOUND`, `INPUT_VALIDATION_FAILED`)
-- Never use empty catch blocks
-
-## Database (Drizzle ORM v1 beta + postgres-js)
-
-- **ORM**: Drizzle ORM `1.0.0-beta` (RQBv2)
-- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
-- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
-- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts` (contains schema info, so `drizzle()` only needs `{ relations }`)
-- **Query style**: RQBv2 object syntax (`orderBy: { createdAt: 'desc' }`, `where: { id: 1 }`)
-
-```typescript
-export const myTable = pgTable('my_table', {
-  id: uuid().primaryKey().default(sql`uuidv7()`),
-  name: text().notNull(),
-  createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
-  updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow().$onUpdateFn(() => new Date()),
-})
-```
-
-## Environment Variables
-
-- Use `@t3-oss/env-core` with Zod validation in `src/env.ts`
-- Server vars: no prefix | Client vars: `VITE_` prefix required
-- Never commit `.env` files
-
-## Dependency Management
-
-- All versions centralized in root `package.json` `catalog` field
-- Workspace packages use `"catalog:"` — never hardcode versions
-- Internal packages use `"workspace:*"` references
-
-## Development Principles
-
-> **These principles apply to ALL code changes. Agents MUST follow them on every task.**
-
-1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks "just in case".
-2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart. This includes updating code snippets in docs when imports, APIs, or patterns change.
-3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns in the same codebase.
-
-## Critical Rules
-
-**DO:**
-- Run `bun run fix` before committing
-- Use `@/*` path aliases (not relative imports)
-- Include `createdAt`/`updatedAt` on all tables
-- Use `catalog:` for dependency versions
-- Update `AGENTS.md` and other docs whenever code patterns change
-
-**DON'T:**
-- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
-- Edit `src/routeTree.gen.ts` (auto-generated)
-- Use `as any`, `@ts-ignore`, `@ts-expect-error`
-- Commit `.env` files
-- Use empty catch blocks `catch(e) {}`
-- Hardcode dependency versions in workspace packages
-- Leave docs out of sync with code changes
-
-## Git Workflow
-
-1. Make changes following style guide
-2. `bun run fix` - auto-format and lint
-3. `bun run typecheck` - verify types
-4. `bun run dev` - test locally
-5. Commit with descriptive message
-
-## Directory Structure
+## Layout
 
 ```
-.
-├── apps/
-│   ├── server/           # TanStack Start fullstack app
-│   │   ├── src/
-│   │   │   ├── client/   # ORPC client + TanStack Query utils
-│   │   │   ├── components/
-│   │   │   ├── routes/   # File-based routing
-│   │   │   └── server/   # API layer + database
-│   │   │       ├── api/  # ORPC contracts, routers, middlewares
-│   │   │       └── db/   # Drizzle schema
-│   │   └── AGENTS.md
-│   └── desktop/          # Electron desktop shell
-│       ├── src/
-│       │   ├── main/
-│       │   │   └── index.ts       # Main process entry
-│       │   └── preload/
-│       │       └── index.ts       # Preload script
-│       ├── electron.vite.config.ts
-│       ├── electron-builder.yml   # Packaging config
-│       └── AGENTS.md
-├── packages/
-│   └── tsconfig/         # Shared TS configs
-├── biome.json            # Linting/formatting config
-├── turbo.json            # Turbo task orchestration
-└── package.json          # Workspace root + dependency catalog
+src/
+├── routes/
+│   ├── index.tsx       # SoH dashboard
+│   ├── batteries.tsx   # battery monitor page
+│   └── api/            # ORPC handlers
+├── server/
+│   ├── api/            # contracts / routers / interceptors
+│   └── battery/mysql.ts
+├── domain/battery.ts
+├── client/orpc.ts
+└── styles.css
 ```
 
-## See Also
+## ORPC
 
-- `apps/server/AGENTS.md` - Detailed TanStack Start / ORPC patterns
-- `apps/desktop/AGENTS.md` - Electron desktop development guide
+- Contracts live in `src/server/api/contracts/`.
+- Routers live in `src/server/api/routers/`.
+- Use `os` from `@/server/api/server`.
+- Current business API:
+  - `battery.dashboard`
+  - `battery.batteries`
+
+## CLI And Deploy
+
+- `src/bin.ts` must keep static imports minimal. Nitro's bun preset starts the server as a side effect when `.output/server/index.mjs` is imported.
+- `serve` is lazy-loaded via citty.
+- `bun run compile` produces `out/server-<target>`.
+- Runtime artifact is a single binary plus `DATABASE_URL` configuration.
+
+## Code Style
+
+- 2-space indentation, LF, single quotes, semicolons as-needed, 120-column line width.
+- Route components use `function Foo()` declarations below route config.
+- No `console.*` in business code; use `getLogger([...])` from `@/server/logger` if logging is needed.
+- No `as any`, `@ts-ignore`, or `@ts-expect-error`.
+- Do not edit `src/routeTree.gen.ts` manually.

Dockerfile

@@ -0,0 +1,21 @@
+FROM oven/bun:1.3.13 AS build
+
+WORKDIR /app
+
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile
+
+COPY . .
+RUN bun run build \
+    && bun run compile \
+    && mv out/server-* out/server
+
+FROM gcr.io/distroless/cc-debian13:nonroot
+
+WORKDIR /app
+COPY --from=build --chown=nonroot:nonroot /app/out/server ./server
+
+ENV HOST=0.0.0.0
+EXPOSE 3000
+
+CMD ["./server"]

README.md

@@ -0,0 +1,108 @@
+# battery-soh
+
+一个基于 **Bun + TanStack Start + ORPC** 的电池健康展示系统。应用会被打包成单个二进制文件，前端页面、SSR 服务和 ORPC API 一起发布；业务数据只读接入甲方现有 MySQL 表 `ls_battery_info`，本项目不写入、不迁移、不修改甲方数据库。
+
+## 数据源
+
+甲方提供的只读表结构：
+
+| 字段名 | 数据类型 | 说明 |
+| --- | --- | --- |
+| `id` | `int(11)` 自增 | 主键 ID |
+| `user_id` | `int(11)` | 用户 ID |
+| `mac` | `varchar(50)` | 设备 MAC |
+| `dev_model` | `varchar(20)` | 设备型号 |
+| `dev_name` | `varchar(50)` | 设备名称 |
+| `is_low_power` | `varchar(10)` | 是否低电量：`true` / `false` |
+| `power_status` | `tinyint(4)` | `0` 未充电，`1` 正在充电，`2` 充电完成 |
+| `power` | `tinyint(4)` | 当前电量 `0~100` |
+| `create_time` | `datetime` | 创建时间 |
+| `remark` | `varchar(500)` | 备注，可空 |
+
+环境变量：
+
+```bash
+DATABASE_URL=mysql://user:password@host:3306/database
+```
+
+## 快速开始
+
+```bash
+cp .env.example .env
+bun install
+bun run dev
+```
+
+如果甲方暂时没有提供数据库连接，可以用 Docker Compose 启动本地 MySQL 并填充示例数据：
+
+```bash
+docker compose up --build
+```
+
+Compose 会启动三个服务：
+
+- `db`：本地 MySQL 8.4
+- `seed`：执行 `bun run seed`，用 Drizzle MySQL schema + `drizzle-seed` 重置本地 `ls_battery_info` 并写入示例数据
+- `app`：使用同一个 `DATABASE_URL` 启动单二进制应用
+
+也可以手动 seed 本地库：
+
+```bash
+DATABASE_URL=mysql://battery:battery@localhost:3306/battery_soh bun run seed
+```
+
+`seed` 是本地开发/验收脚本，会建表并重置示例数据；应用运行时仍然只执行 `SELECT`，不会写入数据库。
+
+打开浏览器：
+
+- `http://localhost:3000/`：SoH 预测与风险洞察看板
+- `http://localhost:3000/batteries`：设备电池实时状态
+- `http://localhost:3000/api/docs`：Scalar 渲染的 ORPC OpenAPI 文档
+
+## 架构
+
+```
+src/
+├── routes/                 # TanStack Start 文件路由：页面 + API 端点
+├── server/
+│   ├── api/                # ORPC contract / router
+│   └── battery/mysql.ts    # 甲方 MySQL 只读查询
+├── domain/battery.ts       # 电池领域类型、归一化、展示聚合
+├── client/orpc.ts          # isomorphic ORPC client
+└── styles.css              # Tailwind v4 entry
+```
+
+接口保持模板里的 ORPC 模式：
+
+- `battery.dashboard`：读取每个 `mac` 的最新记录并生成看板聚合数据
+- `battery.batteries`：无 `mac` 时返回每台设备最新记录；带 `mac` 时返回该设备历史记录，按 `create_time desc` 限制 500 条
+
+所有业务查询都是 `SELECT`，没有 mutation，也没有 mock/fallback 数据。
+
+## 部署
+
+```bash
+bun run build
+bun run compile
+./out/server-<target>
+```
+
+Docker 镜像会在构建阶段产出单个 `./server` 二进制，运行阶段只需要配置 `DATABASE_URL`。
+
+## 脚本
+
+| 命令 | 作用 |
+| --- | --- |
+| `bun run dev` | Vite 开发服务器 |
+| `bun run build` | 构建到 `.output/` |
+| `bun run compile` | 生成单二进制 `out/server-<target>` |
+| `bun run seed` | 为本地 MySQL 创建甲方表并填充示例数据 |
+| `bun run typecheck` | TypeScript 类型检查 |
+| `bun run test` | 运行所有 `*.test.ts` |
+| `bun run fix` | Biome 格式化 + lint + 整理 imports |
+
+## 验证
+
+```bash
+bun run fix && bun run typecheck && bun run test && bun run build
+```

apps/desktop/.gitignore

@@ -1,3 +0,0 @@
-# electron-vite build output
-out/
-dist/

apps/desktop/AGENTS.md

@@ -1,95 +0,0 @@
-# AGENTS.md - Desktop App Guidelines
-
-Thin Electron shell hosting the fullstack server app.
-
-## Tech Stack
-
-> **⚠️ This project uses Bun as the package manager. Runtime is Electron (Node.js). Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, `yarn`, or `pnpm`.**
-
-- **Type**: Electron desktop shell
-- **Design**: Server-driven desktop (thin native window hosting web app)
-- **Runtime**: Electron (Main/Renderer) + Sidecar server binary (Bun-compiled)
-- **Build Tool**: electron-vite (Vite-based, handles main + preload builds)
-- **Packager**: electron-builder (installers, signing, auto-update)
-- **Orchestration**: Turborepo
-
-## Architecture
-
-- **Server-driven design**: The desktop app is a "thin" native shell. It does not contain UI or business logic; it opens a BrowserWindow pointing to the `apps/server` TanStack Start application.
-- **Dev mode**: Opens a BrowserWindow pointing to `localhost:3000`. Requires `apps/server` to be running separately (Turbo handles this).
-- **Production mode**: Spawns a compiled server binary (from `resources/`) as a sidecar process, waits for readiness, then loads its URL.
-
-## Commands
-
-```bash
-bun run dev                    # electron-vite dev (requires server dev running)
-bun run build                  # electron-vite build (main + preload)
-bun run dist                   # Build + package for current platform
-bun run dist:linux             # Build + package for Linux (x64 + arm64)
-bun run dist:linux:x64         # Build + package for Linux x64
-bun run dist:linux:arm64       # Build + package for Linux arm64
-bun run dist:mac               # Build + package for macOS (arm64 + x64)
-bun run dist:mac:arm64         # Build + package for macOS arm64
-bun run dist:mac:x64           # Build + package for macOS x64
-bun run dist:win               # Build + package for Windows x64
-bun run fix                    # Biome auto-fix
-bun run typecheck              # TypeScript check
-```
-
-## Directory Structure
-
-```
-.
-├── src/
-│   ├── main/
-│   │   └── index.ts       # Main process (server lifecycle + BrowserWindow)
-│   └── preload/
-│       └── index.ts       # Preload script (security isolation)
-├── resources/             # Sidecar binaries (gitignored, copied from server build)
-├── out/                   # electron-vite build output (gitignored)
-├── electron.vite.config.ts
-├── electron-builder.yml   # Packaging configuration
-├── package.json
-├── turbo.json
-└── AGENTS.md
-```
-
-## Development Workflow
-
-1. **Start server**: `bun run dev` in `apps/server` (or use root `bun run dev` via Turbo).
-2. **Start desktop**: `bun run dev` in `apps/desktop`.
-3. **Connection**: Main process polls `localhost:3000` until responsive, then opens BrowserWindow.
-
-## Production Build Workflow
-
-From monorepo root, run `bun run dist` to execute the full pipeline automatically (via Turbo task dependencies):
-
-1. **Build server**: `apps/server` → `vite build` → `.output/`
-2. **Compile server**: `apps/server` → `bun compile.ts --target ...` → `out/server-{os}-{arch}`
-3. **Package desktop**: `apps/desktop` → `electron-vite build` + `electron-builder` → distributable
-
-The `electron-builder.yml` `extraResources` config reads binaries directly from `../server/out/`, no manual copy needed.
-
-To build for a specific platform explicitly, use `bun run dist:linux` / `bun run dist:mac` / `bun run dist:win` in `apps/desktop`.
-For single-arch output, use `bun run dist:linux:x64`, `bun run dist:linux:arm64`, `bun run dist:mac:x64`, or `bun run dist:mac:arm64`.
-
-## Development Principles
-
-> **These principles apply to ALL code changes. Agents MUST follow them on every task.**
-
-1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks.
-2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart.
-3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns.
-
-## Critical Rules
-
-**DO:**
-- Use arrow functions for all utility functions.
-- Keep the desktop app as a thin shell — no UI or business logic.
-- Use `catalog:` for all dependency versions in `package.json`.
-
-**DON'T:**
-- Use `npm`, `npx`, `yarn`, or `pnpm`. Use `bun` for package management.
-- Include UI components or business logic in the desktop app.
-- Use `as any` or `@ts-ignore`.
-- Leave docs out of sync with code changes.

apps/desktop/biome.json

@@ -1,9 +0,0 @@
-{
-  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
-  "extends": "//",
-  "css": {
-    "parser": {
-      "tailwindDirectives": true
-    }
-  }
-}

apps/desktop/electron-builder.yml

@@ -1,48 +0,0 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/electron-userland/electron-builder/refs/heads/master/packages/app-builder-lib/scheme.json
-appId: com.furtherverse.desktop
-productName: Furtherverse
-executableName: furtherverse
-
-npmRebuild: false
-asarUnpack:
-  - resources/**
-
-files:
-  - "!**/.vscode/*"
-  - "!src/*"
-  - "!electron.vite.config.{js,ts,mjs,cjs}"
-  - "!{.env,.env.*,bun.lock}"
-  - "!{tsconfig.json,tsconfig.node.json}"
-  - "!{AGENTS.md,README.md,CHANGELOG.md}"
-
-# macOS
-mac:
-  target:
-    - dmg
-  category: public.app-category.productivity
-  extraResources:
-    - from: ../server/out/server-darwin-${arch}
-      to: server
-dmg:
-  artifactName: ${productName}-${version}-${os}-${arch}.${ext}
-
-# Windows
-win:
-  target:
-    - portable
-  extraResources:
-    - from: ../server/out/server-windows-${arch}.exe
-      to: server.exe
-portable:
-  artifactName: ${productName}-${version}-${os}-${arch}-Portable.${ext}
-
-# Linux
-linux:
-  target:
-    - AppImage
-  category: Utility
-  extraResources:
-    - from: ../server/out/server-linux-${arch}
-      to: server
-appImage:
-  artifactName: ${productName}-${version}-${os}-${arch}.${ext}

apps/desktop/electron.vite.config.ts

@@ -1,11 +0,0 @@
-import tailwindcss from '@tailwindcss/vite'
-import react from '@vitejs/plugin-react'
-import { defineConfig } from 'electron-vite'
-
-export default defineConfig({
-  main: {},
-  preload: {},
-  renderer: {
-    plugins: [react(), tailwindcss()],
-  },
-})

apps/desktop/package.json

@@ -1,37 +0,0 @@
-{
-  "name": "@furtherverse/desktop",
-  "version": "1.0.0",
-  "private": true,
-  "main": "out/main/index.js",
-  "scripts": {
-    "build": "electron-vite build",
-    "dev": "electron-vite dev --watch",
-    "dist": "electron-builder",
-    "dist:linux": "bun run dist:linux:x64 && bun run dist:linux:arm64",
-    "dist:linux:arm64": "electron-builder --linux --arm64",
-    "dist:linux:x64": "electron-builder --linux --x64",
-    "dist:mac": "bun run dist:mac:arm64 && bun run dist:mac:x64",
-    "dist:mac:arm64": "electron-builder --mac --arm64",
-    "dist:mac:x64": "electron-builder --mac --x64",
-    "dist:win": "electron-builder --win --x64",
-    "fix": "biome check --write",
-    "typecheck": "tsc -b"
-  },
-  "dependencies": {
-    "motion": "catalog:",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "tree-kill": "catalog:"
-  },
-  "devDependencies": {
-    "@furtherverse/tsconfig": "workspace:*",
-    "@tailwindcss/vite": "catalog:",
-    "@types/node": "catalog:",
-    "@vitejs/plugin-react": "catalog:",
-    "electron": "catalog:",
-    "electron-builder": "catalog:",
-    "electron-vite": "catalog:",
-    "tailwindcss": "catalog:",
-    "vite": "catalog:"
-  }
-}

apps/desktop/src/main/index.ts

@@ -1,198 +0,0 @@
-import { join } from 'node:path'
-import { app, BrowserWindow, dialog, session, shell } from 'electron'
-import { createSidecarRuntime } from './sidecar'
-
-const DEV_SERVER_URL = 'http://localhost:3000'
-const SAFE_EXTERNAL_PROTOCOLS = new Set(['https:', 'http:', 'mailto:'])
-
-let mainWindow: BrowserWindow | null = null
-let windowCreationPromise: Promise<void> | null = null
-let isQuitting = false
-
-const showErrorAndQuit = (title: string, detail: string) => {
-  if (isQuitting) {
-    return
-  }
-
-  dialog.showErrorBox(title, detail)
-  app.quit()
-}
-
-const sidecar = createSidecarRuntime({
-  devServerUrl: DEV_SERVER_URL,
-  isPackaged: app.isPackaged,
-  resourcesPath: process.resourcesPath,
-  isQuitting: () => isQuitting,
-  onUnexpectedStop: (detail) => {
-    showErrorAndQuit('Service Stopped', detail)
-  },
-})
-
-const toErrorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error))
-
-const canOpenExternally = (url: string): boolean => {
-  try {
-    const parsed = new URL(url)
-    return SAFE_EXTERNAL_PROTOCOLS.has(parsed.protocol)
-  } catch {
-    return false
-  }
-}
-
-const loadSplash = async (windowRef: BrowserWindow) => {
-  if (process.env.ELECTRON_RENDERER_URL) {
-    await windowRef.loadURL(process.env.ELECTRON_RENDERER_URL)
-    return
-  }
-
-  await windowRef.loadFile(join(__dirname, '../renderer/index.html'))
-}
-
-const createWindow = async () => {
-  if (mainWindow && !mainWindow.isDestroyed()) {
-    mainWindow.focus()
-    return
-  }
-
-  const windowRef = new BrowserWindow({
-    width: 1200,
-    height: 800,
-    show: false,
-    webPreferences: {
-      preload: join(__dirname, '../preload/index.js'),
-      sandbox: true,
-      contextIsolation: true,
-      nodeIntegration: false,
-    },
-  })
-  mainWindow = windowRef
-
-  windowRef.webContents.setWindowOpenHandler(({ url }) => {
-    if (!canOpenExternally(url)) {
-      if (!app.isPackaged) {
-        console.warn(`Blocked external URL: ${url}`)
-      }
-
-      return { action: 'deny' }
-    }
-
-    void shell.openExternal(url)
-    return { action: 'deny' }
-  })
-
-  windowRef.webContents.on('will-navigate', (event, url) => {
-    const allowed = [DEV_SERVER_URL, sidecar.lastResolvedUrl].filter((v): v is string => v != null)
-    const isAllowed = allowed.some((origin) => url.startsWith(origin))
-
-    if (!isAllowed) {
-      event.preventDefault()
-
-      if (canOpenExternally(url)) {
-        void shell.openExternal(url)
-      } else if (!app.isPackaged) {
-        console.warn(`Blocked navigation to: ${url}`)
-      }
-    }
-  })
-
-  windowRef.on('closed', () => {
-    if (mainWindow === windowRef) {
-      mainWindow = null
-    }
-  })
-
-  try {
-    await loadSplash(windowRef)
-  } catch (error) {
-    if (mainWindow === windowRef) {
-      mainWindow = null
-    }
-
-    if (!windowRef.isDestroyed()) {
-      windowRef.destroy()
-    }
-
-    throw error
-  }
-
-  if (!windowRef.isDestroyed()) {
-    windowRef.show()
-  }
-
-  const targetUrl = await sidecar.resolveUrl()
-  if (isQuitting || windowRef.isDestroyed()) {
-    return
-  }
-
-  try {
-    await windowRef.loadURL(targetUrl)
-  } catch (error) {
-    if (mainWindow === windowRef) {
-      mainWindow = null
-    }
-
-    if (!windowRef.isDestroyed()) {
-      windowRef.destroy()
-    }
-
-    throw error
-  }
-}
-
-const ensureWindow = async () => {
-  if (windowCreationPromise) {
-    return windowCreationPromise
-  }
-
-  windowCreationPromise = createWindow().finally(() => {
-    windowCreationPromise = null
-  })
-
-  return windowCreationPromise
-}
-
-const beginQuit = () => {
-  isQuitting = true
-  sidecar.stop()
-}
-
-const handleWindowCreationError = (error: unknown, context: string) => {
-  console.error(`${context}:`, error)
-  showErrorAndQuit(
-    "App Couldn't Start",
-    app.isPackaged
-      ? 'A required component failed to start. Please reinstall the app.'
-      : `${context}: ${toErrorMessage(error)}`,
-  )
-}
-
-app
-  .whenReady()
-  .then(() => {
-    session.defaultSession.setPermissionRequestHandler((_webContents, _permission, callback) => {
-      callback(false)
-    })
-
-    return ensureWindow()
-  })
-  .catch((error) => {
-    handleWindowCreationError(error, 'Failed to create window')
-  })
-
-app.on('window-all-closed', () => {
-  if (process.platform !== 'darwin') {
-    app.quit()
-  }
-})
-
-app.on('activate', () => {
-  if (isQuitting || BrowserWindow.getAllWindows().length > 0) {
-    return
-  }
-
-  ensureWindow().catch((error) => {
-    handleWindowCreationError(error, 'Failed to re-create window')
-  })
-})
-
-app.on('before-quit', beginQuit)

apps/desktop/src/main/sidecar.ts

@@ -1,256 +0,0 @@
-import { type ChildProcess, spawn } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { createServer } from 'node:net'
-import { join } from 'node:path'
-import killProcessTree from 'tree-kill'
-
-const SERVER_HOST = '127.0.0.1'
-const SERVER_READY_TIMEOUT_MS = 10_000
-const SERVER_REQUEST_TIMEOUT_MS = 1_500
-const SERVER_POLL_INTERVAL_MS = 250
-const SERVER_PROBE_PATHS = ['/api/health', '/']
-
-type SidecarState = {
-  process: ChildProcess | null
-  startup: Promise<string> | null
-  url: string | null
-}
-
-type SidecarRuntimeOptions = {
-  devServerUrl: string
-  isPackaged: boolean
-  resourcesPath: string
-  isQuitting: () => boolean
-  onUnexpectedStop: (detail: string) => void
-}
-
-type SidecarRuntime = {
-  resolveUrl: () => Promise<string>
-  stop: () => void
-  lastResolvedUrl: string | null
-}
-
-const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
-
-const isProcessAlive = (processToCheck: ChildProcess | null): processToCheck is ChildProcess => {
-  if (!processToCheck || !processToCheck.pid) {
-    return false
-  }
-
-  return processToCheck.exitCode === null && !processToCheck.killed
-}
-
-const getAvailablePort = (): Promise<number> =>
-  new Promise((resolve, reject) => {
-    const server = createServer()
-    server.listen(0, () => {
-      const addr = server.address()
-      if (!addr || typeof addr === 'string') {
-        server.close()
-        reject(new Error('Failed to resolve port'))
-        return
-      }
-
-      server.close(() => resolve(addr.port))
-    })
-    server.on('error', reject)
-  })
-
-const isServerReady = async (url: string): Promise<boolean> => {
-  for (const probePath of SERVER_PROBE_PATHS) {
-    try {
-      const probeUrl = new URL(probePath, `${url}/`)
-      const response = await fetch(probeUrl, {
-        method: 'GET',
-        cache: 'no-store',
-        signal: AbortSignal.timeout(SERVER_REQUEST_TIMEOUT_MS),
-      })
-
-      if (response.status < 500) {
-        if (probePath === '/api/health' && response.status === 404) {
-          continue
-        }
-
-        return true
-      }
-    } catch {
-      // Expected: probe request fails while server is still starting up
-    }
-  }
-
-  return false
-}
-
-const waitForServer = async (url: string, isQuitting: () => boolean, processRef?: ChildProcess): Promise<boolean> => {
-  const start = Date.now()
-  while (Date.now() - start < SERVER_READY_TIMEOUT_MS && !isQuitting()) {
-    if (processRef && processRef.exitCode !== null) {
-      return false
-    }
-
-    if (await isServerReady(url)) {
-      return true
-    }
-
-    await sleep(SERVER_POLL_INTERVAL_MS)
-  }
-
-  return false
-}
-
-const resolveBinaryPath = (resourcesPath: string): string => {
-  const binaryName = process.platform === 'win32' ? 'server.exe' : 'server'
-  return join(resourcesPath, binaryName)
-}
-
-const formatUnexpectedStopMessage = (
-  isPackaged: boolean,
-  code: number | null,
-  signal: NodeJS.Signals | null,
-): string => {
-  if (isPackaged) {
-    return 'The background service stopped unexpectedly. Please restart the app.'
-  }
-
-  return `Server process exited unexpectedly (code ${code ?? 'unknown'}, signal ${signal ?? 'none'}).`
-}
-
-export const createSidecarRuntime = (options: SidecarRuntimeOptions): SidecarRuntime => {
-  const state: SidecarState = {
-    process: null,
-    startup: null,
-    url: null,
-  }
-
-  const resetState = (processRef?: ChildProcess) => {
-    if (processRef && state.process !== processRef) {
-      return
-    }
-
-    state.process = null
-    state.url = null
-  }
-
-  const stop = () => {
-    const runningServer = state.process
-    resetState()
-
-    if (!runningServer?.pid || runningServer.exitCode !== null) {
-      return
-    }
-
-    killProcessTree(runningServer.pid, 'SIGTERM', (error?: Error) => {
-      if (error) {
-        console.error('Failed to stop server process:', error)
-      }
-    })
-  }
-
-  const attachLifecycleHandlers = (processRef: ChildProcess) => {
-    processRef.on('error', (error) => {
-      if (state.process !== processRef) {
-        return
-      }
-
-      const hadReadyServer = state.url !== null
-      resetState(processRef)
-
-      if (!options.isQuitting() && hadReadyServer) {
-        options.onUnexpectedStop('The background service crashed unexpectedly. Please restart the app.')
-        return
-      }
-
-      console.error('Failed to start server process:', error)
-    })
-
-    processRef.on('exit', (code, signal) => {
-      if (state.process !== processRef) {
-        return
-      }
-
-      const hadReadyServer = state.url !== null
-      resetState(processRef)
-
-      if (!options.isQuitting() && hadReadyServer) {
-        options.onUnexpectedStop(formatUnexpectedStopMessage(options.isPackaged, code, signal))
-      }
-    })
-  }
-
-  const startPackagedServer = async (): Promise<string> => {
-    if (state.url && isProcessAlive(state.process)) {
-      return state.url
-    }
-
-    if (state.startup) {
-      return state.startup
-    }
-
-    state.startup = (async () => {
-      const binaryPath = resolveBinaryPath(options.resourcesPath)
-      if (!existsSync(binaryPath)) {
-        throw new Error(`Sidecar server binary is missing: ${binaryPath}`)
-      }
-
-      if (options.isQuitting()) {
-        throw new Error('Application is shutting down.')
-      }
-
-      const port = await getAvailablePort()
-      const nextServerUrl = `http://${SERVER_HOST}:${port}`
-      const processRef = spawn(binaryPath, [], {
-        env: {
-          ...process.env,
-          HOST: SERVER_HOST,
-          PORT: String(port),
-        },
-        stdio: 'ignore',
-        windowsHide: true,
-      })
-
-      processRef.unref()
-      state.process = processRef
-      attachLifecycleHandlers(processRef)
-
-      const ready = await waitForServer(nextServerUrl, options.isQuitting, processRef)
-      if (ready && isProcessAlive(processRef)) {
-        state.url = nextServerUrl
-        return nextServerUrl
-      }
-
-      const failureReason =
-        processRef.exitCode !== null
-          ? `The service exited early (code ${processRef.exitCode}).`
-          : `The service did not respond at ${nextServerUrl} within 10 seconds.`
-
-      stop()
-      throw new Error(failureReason)
-    })().finally(() => {
-      state.startup = null
-    })
-
-    return state.startup
-  }
-
-  const resolveUrl = async (): Promise<string> => {
-    if (options.isPackaged) {
-      return startPackagedServer()
-    }
-
-    const ready = await waitForServer(options.devServerUrl, options.isQuitting)
-    if (!ready) {
-      throw new Error('Dev server not responding. Run `bun dev` in apps/server first.')
-    }
-
-    state.url = options.devServerUrl
-    return options.devServerUrl
-  }
-
-  return {
-    resolveUrl,
-    stop,
-    get lastResolvedUrl() {
-      return state.url
-    },
-  }
-}

apps/desktop/src/preload/index.ts

@@ -1 +0,0 @@
-export {}

apps/desktop/src/renderer/components/SplashApp.tsx

@@ -1,33 +0,0 @@
-import { motion } from 'motion/react'
-import logoImage from '../assets/logo.png'
-
-export const SplashApp = () => {
-  return (
-    <main className="m-0 flex h-screen w-screen cursor-default select-none items-center justify-center overflow-hidden bg-white font-sans antialiased">
-      <motion.section
-        animate={{ opacity: 1, y: 0 }}
-        className="flex flex-col items-center gap-8"
-        initial={{ opacity: 0, y: 4 }}
-        transition={{
-          duration: 1,
-          ease: [0.16, 1, 0.3, 1],
-        }}
-      >
-        <img alt="Logo" className="h-20 w-auto object-contain" draggable={false} src={logoImage} />
-
-        <div className="relative h-[4px] w-36 overflow-hidden rounded-full bg-zinc-100">
-          <motion.div
-            animate={{ x: '100%' }}
-            className="h-full w-full bg-zinc-800"
-            initial={{ x: '-100%' }}
-            transition={{
-              duration: 2,
-              ease: [0.4, 0, 0.2, 1],
-              repeat: Infinity,
-            }}
-          />
-        </div>
-      </motion.section>
-    </main>
-  )
-}

apps/desktop/src/renderer/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Furtherverse</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="./main.tsx"></script>
-  </body>
-</html>

apps/desktop/src/renderer/main.tsx

@@ -1,11 +0,0 @@
-import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
-import { SplashApp } from './components/SplashApp'
-import './styles.css'
-
-// biome-ignore lint/style/noNonNullAssertion: 一定存在
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <SplashApp />
-  </StrictMode>,
-)

apps/desktop/tsconfig.app.json

@@ -1,8 +0,0 @@
-{
-  "extends": "@furtherverse/tsconfig/react.json",
-  "compilerOptions": {
-    "composite": true,
-    "types": ["vite/client"]
-  },
-  "include": ["src/renderer/**/*"]
-}

apps/desktop/tsconfig.json

@@ -1,11 +0,0 @@
-{
-  "files": [],
-  "references": [
-    {
-      "path": "./tsconfig.app.json"
-    },
-    {
-      "path": "./tsconfig.node.json"
-    }
-  ]
-}

apps/desktop/tsconfig.node.json

@@ -1,8 +0,0 @@
-{
-  "extends": "@furtherverse/tsconfig/base.json",
-  "compilerOptions": {
-    "composite": true,
-    "types": ["node"]
-  },
-  "include": ["src/main/**/*", "src/preload/**/*", "electron.vite.config.ts"]
-}

apps/desktop/turbo.json

@@ -1,41 +0,0 @@
-{
-  "$schema": "../../node_modules/turbo/schema.json",
-  "extends": ["//"],
-  "tasks": {
-    "build": {
-      "outputs": ["out/**"]
-    },
-    "dist": {
-      "dependsOn": ["build", "@furtherverse/server#compile"],
-      "outputs": ["dist/**"]
-    },
-    "dist:linux": {
-      "dependsOn": ["build", "@furtherverse/server#compile:linux:arm64", "@furtherverse/server#compile:linux:x64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:linux:arm64": {
-      "dependsOn": ["build", "@furtherverse/server#compile:linux:arm64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:linux:x64": {
-      "dependsOn": ["build", "@furtherverse/server#compile:linux:x64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:mac": {
-      "dependsOn": ["build", "@furtherverse/server#compile:darwin:arm64", "@furtherverse/server#compile:darwin:x64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:mac:arm64": {
-      "dependsOn": ["build", "@furtherverse/server#compile:darwin:arm64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:mac:x64": {
-      "dependsOn": ["build", "@furtherverse/server#compile:darwin:x64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:win": {
-      "dependsOn": ["build", "@furtherverse/server#compile:windows:x64"],
-      "outputs": ["dist/**"]
-    }
-  }
-}

apps/server/.env.example

@@ -1 +0,0 @@
-DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres

apps/server/AGENTS.md

@@ -1,278 +0,0 @@
-# AGENTS.md - Server App Guidelines
-
-TanStack Start fullstack web app with ORPC (contract-first RPC).
-
-## Tech Stack
-
-> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, or `node`.**
-
-- **Framework**: TanStack Start (React 19 SSR, file-based routing)
-- **Runtime**: Bun — **NOT Node.js**
-- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
-- **Language**: TypeScript (strict mode)
-- **Styling**: Tailwind CSS v4
-- **Database**: PostgreSQL + Drizzle ORM v1 beta (`drizzle-orm/postgres-js`, RQBv2)
-- **State**: TanStack Query v5
-- **RPC**: ORPC (contract-first, type-safe)
-- **Build**: Vite + Nitro
-
-## Commands
-
-```bash
-# Development
-bun run dev                    # Vite dev server (localhost:3000)
-bun run db:studio              # Drizzle Studio GUI
-
-# Build
-bun run build                  # Production build → .output/
-bun run compile                # Compile to standalone binary (current platform, depends on build)
-bun run compile:darwin         # Compile for macOS (arm64 + x64)
-bun run compile:darwin:arm64   # Compile for macOS arm64
-bun run compile:darwin:x64     # Compile for macOS x64
-bun run compile:linux          # Compile for Linux (x64 + arm64)
-bun run compile:linux:arm64    # Compile for Linux arm64
-bun run compile:linux:x64      # Compile for Linux x64
-bun run compile:windows        # Compile for Windows (default: x64)
-bun run compile:windows:x64    # Compile for Windows x64
-
-# Code Quality
-bun run fix                    # Biome auto-fix
-bun run typecheck              # TypeScript check
-
-# Database
-bun run db:generate            # Generate migrations from schema
-bun run db:migrate             # Run migrations
-bun run db:push                # Push schema directly (dev only)
-
-# Testing (not yet configured)
-bun test path/to/test.ts       # Run single test
-bun test -t "pattern"          # Run tests matching pattern
-```
-
-## Directory Structure
-
-```
-src/
-├── client/                # Client-side code
-│   └── orpc.ts            # ORPC client + TanStack Query utils (single entry point)
-├── components/            # React components
-├── routes/                # TanStack Router file routes
-│   ├── __root.tsx         # Root layout
-│   ├── index.tsx          # Home page
-│   └── api/
-│       ├── $.ts           # OpenAPI handler + Scalar docs
-│       ├── health.ts      # Health check endpoint
-│       └── rpc.$.ts       # ORPC RPC handler
-├── server/                # Server-side code
-│   ├── api/               # ORPC layer
-│   │   ├── contracts/     # Input/output schemas (Zod)
-│   │   ├── middlewares/   # Middleware (db provider, auth)
-│   │   ├── routers/       # Handler implementations
-│   │   ├── interceptors.ts # Shared error interceptors
-│   │   ├── context.ts     # Request context
-│   │   ├── server.ts      # ORPC server instance
-│   │   └── types.ts       # Type exports
-│   └── db/
-│       ├── schema/        # Drizzle table definitions
-│       ├── fields.ts      # Shared field builders (id, createdAt, updatedAt)
-│       ├── relations.ts   # Drizzle relations (defineRelations, RQBv2)
-│       └── index.ts       # Database instance (postgres-js driver)
-├── env.ts                 # Environment variable validation
-├── router.tsx             # Router configuration
-├── routeTree.gen.ts       # Auto-generated (DO NOT EDIT)
-└── styles.css             # Tailwind entry
-```
-
-## ORPC Pattern
-
-### 1. Define Contract (`src/server/api/contracts/feature.contract.ts`)
-```typescript
-import { oc } from '@orpc/contract'
-import { createSelectSchema } from 'drizzle-orm/zod'
-import { z } from 'zod'
-import { featureTable } from '@/server/db/schema'
-
-const selectSchema = createSelectSchema(featureTable)
-
-export const list = oc.input(z.void()).output(z.array(selectSchema))
-export const create = oc.input(insertSchema).output(selectSchema)
-```
-
-### 2. Implement Router (`src/server/api/routers/feature.router.ts`)
-```typescript
-import { ORPCError } from '@orpc/server'
-import { db } from '../middlewares'
-import { os } from '../server'
-
-export const list = os.feature.list.use(db).handler(async ({ context }) => {
-  return await context.db.query.featureTable.findMany({
-    orderBy: { createdAt: 'desc' },
-  })
-})
-```
-
-### 3. Register in Index Files
-```typescript
-// src/server/api/contracts/index.ts
-import * as feature from './feature.contract'
-export const contract = { feature }
-
-// src/server/api/routers/index.ts
-import * as feature from './feature.router'
-export const router = os.router({ feature })
-```
-
-### 4. Use in Components
-```typescript
-import { useSuspenseQuery, useMutation } from '@tanstack/react-query'
-import { orpc } from '@/client/orpc'
-
-const { data } = useSuspenseQuery(orpc.feature.list.queryOptions())
-const mutation = useMutation(orpc.feature.create.mutationOptions())
-```
-
-## Database (Drizzle ORM v1 beta)
-
-- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
-- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
-- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts`
-- **Query**: RQBv2 — use `db.query.tableName.findMany()` with object-style `orderBy` and `where`
-
-### Schema Definition
-```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()),
-})
-```
-
-### Relations (RQBv2)
-```typescript
-// src/server/db/relations.ts
-import { defineRelations } from 'drizzle-orm'
-import * as schema from './schema'
-
-export const relations = defineRelations(schema, (r) => ({
-  // Define relations here using r.one / r.many / r.through
-}))
-```
-
-### DB Instance
-```typescript
-// src/server/db/index.ts
-import { drizzle } from 'drizzle-orm/postgres-js'
-import { relations } from '@/server/db/relations'
-// In RQBv2, relations already contain schema info — no separate schema import needed
-
-const db = drizzle({
-  connection: env.DATABASE_URL,
-  relations,
-})
-```
-
-### RQBv2 Query Examples
-```typescript
-// Object-style orderBy (NOT callback style)
-const todos = await db.query.todoTable.findMany({
-  orderBy: { createdAt: 'desc' },
-})
-
-// Object-style where
-const todo = await db.query.todoTable.findFirst({
-  where: { id: someId },
-})
-```
-
-## Code Style
-
-### Formatting (Biome)
-- **Indent**: 2 spaces
-- **Quotes**: Single `'`
-- **Semicolons**: Omit (ASI)
-- **Arrow parens**: Always `(x) => x`
-
-### Imports
-Biome auto-organizes:
-1. External packages
-2. Internal `@/*` aliases
-3. Type imports (`import type { ... }`)
-
-```typescript
-import { createFileRoute } from '@tanstack/react-router'
-import { z } from 'zod'
-import { db } from '@/server/db'
-import type { ReactNode } from 'react'
-```
-
-### TypeScript
-- `strict: true`
-- `noUncheckedIndexedAccess: true` - array access returns `T | undefined`
-- Use `@/*` path aliases (maps to `src/*`)
-
-### Naming
-| Type | Convention | Example |
-|------|------------|---------|
-| Files (utils) | kebab-case | `auth-utils.ts` |
-| Files (components) | PascalCase | `UserProfile.tsx` |
-| Components | PascalCase arrow | `const Button = () => {}` |
-| Functions | camelCase | `getUserById` |
-| Types | PascalCase | `UserProfile` |
-
-### React
-- Use arrow functions for components (Biome enforced)
-- Use `useSuspenseQuery` for guaranteed data
-
-## Environment Variables
-
-```typescript
-// src/env.ts - using @t3-oss/env-core
-import { createEnv } from '@t3-oss/env-core'
-import { z } from 'zod'
-
-export const env = createEnv({
-  server: {
-    DATABASE_URL: z.string().url(),
-  },
-  clientPrefix: 'VITE_',
-  client: {
-    VITE_API_URL: z.string().optional(),
-  },
-})
-```
-
-## Development Principles
-
-> **These principles apply to ALL code changes. Agents MUST follow them on every task.**
-
-1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks.
-2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart.
-3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns.
-
-## Critical Rules
-
-**DO:**
-- Run `bun run fix` before committing
-- Use `@/*` path aliases
-- Include `createdAt`/`updatedAt` on all tables
-- Use `ORPCError` with proper codes
-- Use `drizzle-orm/zod` (NOT `drizzle-zod`) for schema validation
-- Use RQBv2 object syntax for `orderBy` and `where`
-- Update `AGENTS.md` and other docs whenever code patterns change
-
-**DON'T:**
-- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
-- Edit `src/routeTree.gen.ts` (auto-generated)
-- Use `as any`, `@ts-ignore`, `@ts-expect-error`
-- Commit `.env` files
-- Use empty catch blocks
-- Import from `drizzle-zod` (use `drizzle-orm/zod` instead)
-- Use RQBv1 callback-style `orderBy` / old `relations()` API
-- Use `drizzle-orm/bun-sql` driver (use `drizzle-orm/postgres-js`)
-- Pass `schema` to `drizzle()` constructor (only `relations` is needed in RQBv2)
-- Import `os` from `@orpc/server` in middleware — use `@/server/api/server` (the local typed instance)
-- Leave docs out of sync with code changes

apps/server/biome.json

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

apps/server/drizzle.config.ts

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

apps/server/package.json

@@ -1,58 +0,0 @@
-{
-  "name": "@furtherverse/server",
-  "version": "1.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "build": "bunx --bun vite build",
-    "compile": "bun compile.ts",
-    "compile:darwin": "bun run compile:darwin:arm64 && bun run compile:darwin:x64",
-    "compile:darwin:arm64": "bun compile.ts --target bun-darwin-arm64",
-    "compile:darwin:x64": "bun compile.ts --target bun-darwin-x64",
-    "compile:linux": "bun run compile:linux:x64 && bun run compile:linux:arm64",
-    "compile:linux:arm64": "bun compile.ts --target bun-linux-arm64",
-    "compile:linux:x64": "bun compile.ts --target bun-linux-x64",
-    "compile:windows": "bun run compile:windows:x64",
-    "compile:windows:x64": "bun compile.ts --target bun-windows-x64",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "db:push": "drizzle-kit push",
-    "db:studio": "drizzle-kit studio",
-    "dev": "bunx --bun vite dev",
-    "fix": "biome check --write",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@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:",
-    "drizzle-orm": "catalog:",
-    "postgres": "catalog:",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "uuid": "catalog:",
-    "zod": "catalog:"
-  },
-  "devDependencies": {
-    "@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:",
-    "drizzle-kit": "catalog:",
-    "nitro": "catalog:",
-    "tailwindcss": "catalog:",
-    "vite": "catalog:"
-  }
-}

apps/server/public/robots.txt

@@ -1,3 +0,0 @@
-# https://www.robotstxt.org/robotstxt.html
-User-agent: *
-Disallow:

apps/server/src/components/Error.tsx

@@ -1,3 +0,0 @@
-export function ErrorComponent() {
-  return <div>An unhandled error happened!</div>
-}

apps/server/src/components/NotFound.tsx

@@ -1,3 +0,0 @@
-export function NotFoundComponent() {
-  return <div>404 - Not Found</div>
-}

apps/server/src/env.ts

@@ -1,14 +0,0 @@
-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,
-})

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

@@ -1,27 +0,0 @@
-import { createFileRoute } from '@tanstack/react-router'
-import { name, version } from '@/../package.json'
-
-const createHealthResponse = (): Response =>
-  Response.json(
-    {
-      status: 'ok',
-      service: name,
-      version,
-      timestamp: new Date().toISOString(),
-    },
-    {
-      status: 200,
-      headers: {
-        'cache-control': 'no-store',
-      },
-    },
-  )
-
-export const Route = createFileRoute('/api/health')({
-  server: {
-    handlers: {
-      GET: async () => createHealthResponse(),
-      HEAD: async () => new Response(null, { status: 200 }),
-    },
-  },
-})

apps/server/src/routes/index.tsx

@@ -1,193 +0,0 @@
-import { useMutation, useSuspenseQuery } from '@tanstack/react-query'
-import { createFileRoute } from '@tanstack/react-router'
-import type { ChangeEventHandler, SubmitEventHandler } from 'react'
-import { useState } from 'react'
-import { orpc } from '@/client/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())
-
-  const handleCreateTodo: SubmitEventHandler<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>
-  )
-}

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

@@ -1,25 +0,0 @@
-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/todo.contract.ts

@@ -1,32 +0,0 @@
-import { oc } from '@orpc/contract'
-import { createInsertSchema, createSelectSchema, createUpdateSchema } from 'drizzle-orm/zod'
-import { z } from 'zod'
-import { generatedFieldKeys } from '@/server/db/fields'
-import { todoTable } from '@/server/db/schema'
-
-const selectSchema = createSelectSchema(todoTable)
-
-const insertSchema = createInsertSchema(todoTable).omit(generatedFieldKeys)
-
-const updateSchema = createUpdateSchema(todoTable).omit(generatedFieldKeys)
-
-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())

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

@@ -1,11 +0,0 @@
-import { os } from '@/server/api/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

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

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

@@ -1,6 +0,0 @@
-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,40 +0,0 @@
-import { ORPCError } from '@orpc/server'
-import { eq } from 'drizzle-orm'
-import { todoTable } from '@/server/db/schema'
-import { db } from '../middlewares'
-import { os } from '../server'
-
-export const list = os.todo.list.use(db).handler(async ({ context }) => {
-  const todos = await context.db.query.todoTable.findMany({
-    orderBy: { createdAt: 'desc' },
-  })
-  return todos
-})
-
-export const create = os.todo.create.use(db).handler(async ({ context, input }) => {
-  const [newTodo] = await context.db.insert(todoTable).values(input).returning()
-
-  if (!newTodo) {
-    throw new ORPCError('INTERNAL_SERVER_ERROR', { message: 'Failed to create todo' })
-  }
-
-  return newTodo
-})
-
-export const update = os.todo.update.use(db).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(db).handler(async ({ context, input }) => {
-  const [deleted] = await context.db.delete(todoTable).where(eq(todoTable.id, input.id)).returning({ id: todoTable.id })
-
-  if (!deleted) {
-    throw new ORPCError('NOT_FOUND')
-  }
-})

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

@@ -1,6 +0,0 @@
-import type { ContractRouterClient, InferContractRouterInputs, InferContractRouterOutputs } from '@orpc/contract'
-import type { Contract } from './contracts'
-
-export type RouterClient = ContractRouterClient<Contract>
-export type RouterInputs = InferContractRouterInputs<Contract>
-export type RouterOutputs = InferContractRouterOutputs<Contract>

apps/server/src/server/db/fields.ts

@@ -1,55 +0,0 @@
-import { sql } from 'drizzle-orm'
-import { timestamp, uuid } from 'drizzle-orm/pg-core'
-import { v7 as uuidv7 } from 'uuid'
-
-// id
-
-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/src/server/db/index.ts

@@ -1,24 +0,0 @@
-import { drizzle } from 'drizzle-orm/postgres-js'
-import { env } from '@/env'
-import { relations } from '@/server/db/relations'
-
-export const createDB = () =>
-  drizzle({
-    connection: env.DATABASE_URL,
-    relations,
-  })
-
-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/relations.ts

@@ -1,4 +0,0 @@
-import { defineRelations } from 'drizzle-orm'
-import * as schema from './schema'
-
-export const relations = defineRelations(schema, (_r) => ({}))

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

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

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

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

apps/server/src/styles.css

@@ -1 +0,0 @@
-@import "tailwindcss";

apps/server/tsconfig.json

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

apps/server/turbo.json

@@ -1,47 +0,0 @@
-{
-  "$schema": "../../node_modules/turbo/schema.json",
-  "extends": ["//"],
-  "tasks": {
-    "build": {
-      "env": ["NODE_ENV", "VITE_*"],
-      "inputs": ["src/**", "public/**", "package.json", "tsconfig.json", "vite.config.ts"],
-      "outputs": [".output/**"]
-    },
-    "compile": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:darwin": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:darwin:arm64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:darwin:x64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:linux": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:linux:arm64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:linux:x64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:windows": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:windows:x64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    }
-  }
-}

biome.json

@@ -6,7 +6,8 @@
     "useIgnoreFile": true
   },
   "files": {
-    "ignoreUnknown": false
+    "ignoreUnknown": false,
+    "includes": ["**", "!**/routeTree.gen.ts", "!**/migrations.gen.ts"]
   },
   "formatter": {
     "enabled": true,
@@ -16,6 +17,10 @@
   },
   "linter": {
     "enabled": true,
+    "domains": {
+      "react": "recommended",
+      "types": "all"
+    },
     "rules": {
       "recommended": true,
       "complexity": {
@@ -23,6 +28,14 @@
       },
       "correctness": {
         "noReactPropAssignments": "error"
+      },
+      "style": {
+        "noNonNullAssertion": "error"
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noImportCycles": "error",
+        "noTsIgnore": "error"
       }
     }
   },
@@ -33,6 +46,11 @@
       "arrowParentheses": "always"
     }
   },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  },
   "assist": {
     "enabled": true,
     "actions": {

bunfig.toml

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

compose.yaml

@@ -0,0 +1,40 @@
+services:
+  db:
+    image: mysql:8.4
+    ports:
+      - "3306:3306"
+    volumes:
+      - ./volumes/mysql/data:/var/lib/mysql
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: battery_soh
+      MYSQL_USER: battery
+      MYSQL_PASSWORD: battery
+    healthcheck:
+      test: [ "CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-ubattery", "-pbattery" ]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  seed:
+    image: oven/bun:1.3.13
+    restart: "no"
+    depends_on:
+      db:
+        condition: service_healthy
+    volumes:
+      - .:/app
+    environment:
+      - DATABASE_URL=mysql://battery:battery@db:3306/battery_soh
+    command: [ "sh", "-lc", "bun install --frozen-lockfile && bun run seed" ]
+    working_dir: /app
+
+  app:
+    build: .
+    depends_on:
+      seed:
+        condition: service_completed_successfully
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=mysql://battery:battery@db:3306/battery_soh

mise.toml

@@ -1,3 +1,2 @@
 [tools]
-bun = "1"
-node = "24"
+bun = "1.3.13"

opencode.jsonc

@@ -1,13 +0,0 @@
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "shadcn": {
-      "type": "local",
-      "command": ["bunx", "--bun", "shadcn", "mcp"]
-    },
-    "tanstack": {
-      "type": "remote",
-      "url": "https://tanstack.com/api/mcp"
-    }
-  }
-}

package.json

@@ -1,68 +1,64 @@
 {
-  "name": "@furtherverse/monorepo",
+  "name": "fullstack-starter",
   "version": "1.0.0",
   "private": true,
   "type": "module",
-  "workspaces": [
-    "apps/*",
-    "packages/*"
-  ],
+  "imports": {
+    "#package": "./package.json",
+    "#server": "./.output/server/index.mjs"
+  },
   "scripts": {
-    "build": "turbo run build",
-    "compile": "turbo run compile",
-    "compile:darwin": "turbo run compile:darwin",
-    "compile:linux": "turbo run compile:linux",
-    "compile:windows": "turbo run compile:windows",
-    "dev": "turbo run dev",
-    "dist": "turbo run dist",
-    "dist:linux": "turbo run dist:linux",
-    "dist:mac": "turbo run dist:mac",
-    "dist:win": "turbo run dist:win",
-    "fix": "turbo run fix",
-    "typecheck": "turbo run typecheck"
+    "build": "bunx --bun vite build",
+    "cli": "bun src/bin.ts",
+    "compile": "bun scripts/compile.ts",
+    "compile:darwin": "bun run compile:darwin:arm64 && bun run compile:darwin:x64",
+    "compile:darwin:arm64": "bun scripts/compile.ts --target bun-darwin-arm64",
+    "compile:darwin:x64": "bun scripts/compile.ts --target bun-darwin-x64",
+    "compile:linux": "bun run compile:linux:x64 && bun run compile:linux:arm64",
+    "compile:linux:arm64": "bun scripts/compile.ts --target bun-linux-arm64",
+    "compile:linux:x64": "bun scripts/compile.ts --target bun-linux-x64",
+    "compile:windows": "bun run compile:windows:x64",
+    "compile:windows:x64": "bun scripts/compile.ts --target bun-windows-x64",
+    "dev": "bunx --bun vite dev",
+    "fix": "biome check --write",
+    "seed": "bun scripts/seed.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
   },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.9",
-    "turbo": "^2.8.20",
-    "typescript": "^6.0.2"
-  },
-  "catalog": {
-    "@orpc/client": "^1.13.11",
-    "@orpc/contract": "^1.13.11",
-    "@orpc/openapi": "^1.13.11",
-    "@orpc/server": "^1.13.11",
-    "@orpc/tanstack-query": "^1.13.11",
-    "@orpc/zod": "^1.13.11",
+  "dependencies": {
+    "@logtape/logtape": "^2.0.5",
+    "@logtape/pretty": "^2.0.5",
+    "@orpc/client": "^1.14.0",
+    "@orpc/contract": "^1.14.0",
+    "@orpc/openapi": "^1.14.0",
+    "@orpc/server": "^1.14.0",
+    "@orpc/tanstack-query": "^1.14.0",
+    "@orpc/zod": "^1.14.0",
     "@t3-oss/env-core": "^0.13.11",
-    "@tailwindcss/vite": "^4.2.2",
-    "@tanstack/devtools-vite": "^0.6.0",
-    "@tanstack/react-devtools": "^0.10.0",
-    "@tanstack/react-query": "^5.95.2",
-    "@tanstack/react-query-devtools": "^5.95.2",
-    "@tanstack/react-router": "^1.168.3",
-    "@tanstack/react-router-devtools": "^1.166.11",
-    "@tanstack/react-router-ssr-query": "^1.166.10",
-    "@tanstack/react-start": "^1.167.6",
-    "@types/bun": "^1.3.11",
-    "@types/node": "^24.12.0",
-    "@vitejs/plugin-react": "^6.0.1",
-    "drizzle-kit": "1.0.0-beta.15-859cf75",
-    "drizzle-orm": "1.0.0-beta.15-859cf75",
-    "electron": "^34.0.0",
-    "electron-builder": "^26.8.1",
-    "electron-vite": "^5.0.0",
-    "motion": "^12.38.0",
-    "nitro": "npm:nitro-nightly@3.0.1-20260324-103046-9ce219ca",
-    "postgres": "^3.4.8",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "tailwindcss": "^4.2.2",
-    "tree-kill": "^1.2.2",
-    "uuid": "^13.0.0",
-    "vite": "^8.0.2",
+    "@tanstack/react-query": "^5.100.1",
+    "@tanstack/react-router": "^1.168.24",
+    "@tanstack/react-router-ssr-query": "^1.166.11",
+    "@tanstack/react-start": "^1.167.48",
+    "citty": "^0.2.2",
+    "drizzle-orm": "^0.45.2",
+    "mysql2": "^3.22.3",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "zod": "^4.3.6"
   },
-  "overrides": {
-    "@types/node": "catalog:"
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.13",
+    "@tailwindcss/vite": "^4.2.4",
+    "@tanstack/devtools-vite": "^0.6.0",
+    "@tanstack/react-devtools": "^0.10.2",
+    "@tanstack/react-query-devtools": "^5.100.1",
+    "@tanstack/react-router-devtools": "^1.166.13",
+    "@types/bun": "^1.3.13",
+    "@vitejs/plugin-react": "^6.0.1",
+    "drizzle-seed": "^0.3.1",
+    "nitro": "npm:nitro-nightly@3.0.1-20260424-182106-f8cf6ccc",
+    "tailwindcss": "^4.2.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10"
   }
 }

packages/tsconfig/bun.json

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

packages/tsconfig/package.json

@@ -1,11 +0,0 @@
-{
-  "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

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

public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Disallow:

scripts/compile.ts

@@ -1,7 +1,8 @@
 import { mkdir, rm } from 'node:fs/promises'
+import { basename } from 'node:path'
 import { parseArgs } from 'node:util'
 
-const ENTRYPOINT = '.output/server/index.mjs'
+const ENTRYPOINT = 'src/bin.ts'
 const OUTDIR = 'out'
 
 const SUPPORTED_TARGETS: readonly Bun.Build.CompileTarget[] = [
@@ -12,8 +13,9 @@ const SUPPORTED_TARGETS: readonly Bun.Build.CompileTarget[] = [
   'bun-linux-arm64',
 ]
 
-const isSupportedTarget = (value: string): value is Bun.Build.CompileTarget =>
-  (SUPPORTED_TARGETS as readonly string[]).includes(value)
+const SUPPORTED_TARGET_SET: ReadonlySet<string> = new Set(SUPPORTED_TARGETS)
+
+const isSupportedTarget = (value: string): value is Bun.Build.CompileTarget => SUPPORTED_TARGET_SET.has(value)
 
 const { values } = parseArgs({
   options: { target: { type: 'string' } },
@@ -48,13 +50,20 @@ const main = async () => {
   const result = await Bun.build({
     entrypoints: [ENTRYPOINT],
     outdir: OUTDIR,
-    compile: { outfile, target },
+    // autoloadDotenv: false — produce a deterministic binary; it must not silently consume a .env from cwd.
+    compile: { outfile, target, autoloadDotenv: false },
+    minify: true,
+    bytecode: true,
+    sourcemap: 'inline',
   })
 
   if (!result.success) {
     throw new Error(result.logs.map(String).join('\n'))
   }
 
+  // Bun bundler still writes *.js.map next to the binary even with inline sourcemap.
+  await rm(`${OUTDIR}/${basename(ENTRYPOINT, '.ts')}.js.map`, { force: true })
+
   console.log(`✓ ${target} → ${OUTDIR}/${outfile}`)
 }
 

scripts/seed.ts

@@ -0,0 +1,116 @@
+import { reset } from 'drizzle-seed'
+import { drizzle } from 'drizzle-orm/mysql2'
+import { datetime, index, int, mysqlTable, tinyint, varchar } from 'drizzle-orm/mysql-core'
+import mysql from 'mysql2/promise'
+
+type SeedRow = {
+  userId: number
+  mac: string
+  devModel: string
+  devName: string
+  isLowPower: 'true' | 'false'
+  powerStatus: 0 | 1 | 2
+  power: number
+  createTime: Date
+  remark: string | null
+}
+
+const lsBatteryInfo = mysqlTable(
+  'ls_battery_info',
+  {
+    id: int('id').autoincrement().primaryKey(),
+    userId: int('user_id').notNull(),
+    mac: varchar('mac', { length: 50 }).notNull(),
+    devModel: varchar('dev_model', { length: 20 }).notNull(),
+    devName: varchar('dev_name', { length: 50 }).notNull(),
+    isLowPower: varchar('is_low_power', { length: 10 }).notNull(),
+    powerStatus: tinyint('power_status').notNull(),
+    power: tinyint('power').notNull(),
+    createTime: datetime('create_time').notNull(),
+    remark: varchar('remark', { length: 500 }),
+  },
+  (table) => [index('idx_ls_battery_info_mac_time_id').on(table.mac, table.createTime, table.id)],
+)
+
+const databaseUrl = process.env.DATABASE_URL
+
+if (!databaseUrl) {
+  throw new Error('DATABASE_URL is required, for example mysql://battery:battery@localhost:3306/battery_soh')
+}
+
+const parsedUrl = new URL(databaseUrl)
+const safeSeedHosts = new Set(['localhost', '127.0.0.1', '0.0.0.0', 'db', 'mysql'])
+
+if (!safeSeedHosts.has(parsedUrl.hostname) && process.env.SEED_ALLOW_REMOTE !== 'true') {
+  throw new Error(
+    `Refusing to seed non-local MySQL host "${parsedUrl.hostname}". Set SEED_ALLOW_REMOTE=true only for disposable test databases.`,
+  )
+}
+
+const devices = [
+  { mac: 'RING-A03', model: 'SR-01', name: '样机-A03', basePower: 96, status: 2, remark: 'v3.8.2' },
+  { mac: 'RING-B11', model: 'SR-01', name: '样机-B11', basePower: 91, status: 1, remark: 'v3.8.2' },
+  { mac: 'RING-C07', model: 'SR-02', name: '样机-C07', basePower: 88, status: 0, remark: 'v3.8.1' },
+  { mac: 'RING-D19', model: 'SR-02', name: '样机-D19', basePower: 84, status: 0, remark: 'v3.7.9' },
+  { mac: 'RING-E21', model: 'SR-03', name: '样机-E21', basePower: 79, status: 1, remark: 'v3.7.9' },
+  { mac: 'RING-F02', model: 'SR-03', name: '样机-F02', basePower: 73, status: 0, remark: null },
+  { mac: 'RING-G15', model: 'SR-04', name: '样机-G15', basePower: 93, status: 2, remark: 'v3.9.0' },
+  { mac: 'RING-H09', model: 'SR-04', name: '样机-H09', basePower: 86, status: 0, remark: 'v3.8.1' },
+] satisfies Array<{
+  mac: string
+  model: string
+  name: string
+  basePower: number
+  status: 0 | 1 | 2
+  remark: string | null
+}>
+
+function createSeedRows(now = new Date()): SeedRow[] {
+  return devices.flatMap((device, deviceIndex) =>
+    Array.from({ length: 8 }, (_, historyIndex) => {
+      const createdAt = new Date(now.getTime() - (historyIndex * 24 + deviceIndex * 2) * 60 * 60 * 1000)
+      const power = Math.max(1, Math.min(100, device.basePower - historyIndex * 2 + (deviceIndex % 3)))
+
+      return {
+        userId: 1001 + (deviceIndex % 3),
+        mac: device.mac,
+        devModel: device.model,
+        devName: device.name,
+        isLowPower: power <= 20 || device.basePower <= 80 ? 'true' : 'false',
+        powerStatus: historyIndex === 0 ? device.status : 0,
+        power,
+        createTime: createdAt,
+        remark: device.remark,
+      }
+    }),
+  )
+}
+
+const connection = await mysql.createConnection({ uri: databaseUrl })
+const db = drizzle(connection)
+
+try {
+  await db.execute(`
+    CREATE TABLE IF NOT EXISTS ls_battery_info (
+      id int(11) NOT NULL AUTO_INCREMENT,
+      user_id int(11) NOT NULL,
+      mac varchar(50) NOT NULL,
+      dev_model varchar(20) NOT NULL,
+      dev_name varchar(50) NOT NULL,
+      is_low_power varchar(10) NOT NULL,
+      power_status tinyint(4) NOT NULL,
+      power tinyint(4) NOT NULL,
+      create_time datetime NOT NULL,
+      remark varchar(500) DEFAULT NULL,
+      PRIMARY KEY (id),
+      KEY idx_ls_battery_info_mac_time_id (mac, create_time, id)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `)
+
+  await reset(db, { lsBatteryInfo })
+  await db.insert(lsBatteryInfo).values(createSeedRows())
+
+  process.stdout.write(`Seeded ${devices.length} devices into ls_battery_info.\n`)
+} finally {
+  await connection.end()
+}

src/bin.ts

@@ -0,0 +1,20 @@
+import { defineCommand, runMain } from 'citty'
+import { name, version } from '#package'
+
+// IMPORTANT: keep this file's static imports minimal. Nitro's bun preset
+// emits `.output/server/index.mjs` with a top-level `serve(...)` call, so any
+// eager (transitive) import of it would start the HTTP server even for
+// `--help`. All subcommands are lazy-loaded via citty.
+const main = defineCommand({
+  meta: {
+    name,
+    version,
+    description: 'Fullstack server binary (default subcommand: serve)',
+  },
+  default: 'serve',
+  subCommands: {
+    serve: () => import('@/cli/serve').then((m) => m.default),
+  },
+})
+
+runMain(main)

src/cli/_serve-nitro.d.mts

@@ -0,0 +1 @@
+export default function startNitroServer(): Promise<void>

src/cli/_serve-nitro.mjs

@@ -0,0 +1,3 @@
+export default async function startNitroServer() {
+  await import('#server')
+}

src/cli/serve.ts

@@ -0,0 +1,12 @@
+import { defineCommand } from 'citty'
+
+export default defineCommand({
+  meta: {
+    name: 'serve',
+    description: 'Start the HTTP server',
+  },
+  async run() {
+    const { default: startNitroServer } = await import('./_serve-nitro.mjs')
+    await startNitroServer()
+  },
+})

src/client/orpc.ts

@@ -24,30 +24,4 @@ const getORPCClient = createIsomorphicFn()
 
 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() })
-          },
-        },
-      },
-    },
-  },
-})
+export const orpc = createTanstackQueryUtils(client)

src/components/Error.tsx

@@ -0,0 +1,40 @@
+export const ErrorComponent = ({ error, reset }: { error: Error; reset: () => void }) => {
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-slate-50 px-4">
+      <div className="max-w-md w-full text-center space-y-6">
+        <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-red-100">
+          <svg
+            className="w-8 h-8 text-red-500"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={1.5}
+            aria-hidden="true"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M12 9v3.75m9-.75a9 9 0 11-18 0 9 9 0 0118 0zm-9 3.75h.008v.008H12v-.008z"
+            />
+          </svg>
+        </div>
+        <div>
+          <h1 className="text-2xl font-bold text-slate-900">出错了</h1>
+          <p className="text-slate-500 mt-2">{import.meta.env.DEV ? error.message : '请求失败，请稍后重试'}</p>
+        </div>
+        <div className="flex items-center justify-center gap-4">
+          <button
+            type="button"
+            onClick={reset}
+            className="px-6 py-2.5 bg-indigo-600 hover:bg-indigo-700 text-white rounded-xl font-medium transition-colors"
+          >
+            重试
+          </button>
+          <a href="/" className="px-6 py-2.5 text-slate-600 hover:text-slate-900 font-medium transition-colors">
+            返回首页
+          </a>
+        </div>
+      </div>
+    </div>
+  )
+}

src/components/NotFound.tsx

@@ -0,0 +1,23 @@
+import { Link } from '@tanstack/react-router'
+
+export const NotFoundComponent = () => {
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-slate-50 px-4">
+      <div className="max-w-md w-full text-center space-y-6">
+        <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-slate-100">
+          <span className="text-3xl font-bold text-slate-400">404</span>
+        </div>
+        <div>
+          <h1 className="text-2xl font-bold text-slate-900">页面不存在</h1>
+          <p className="text-slate-500 mt-2">您访问的页面可能已被移除或地址有误</p>
+        </div>
+        <Link
+          to="/"
+          className="inline-block px-6 py-2.5 bg-indigo-600 hover:bg-indigo-700 text-white rounded-xl font-medium transition-colors"
+        >
+          返回首页
+        </Link>
+      </div>
+    </div>
+  )
+}

src/domain/battery.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test'
+import { createBatteriesResponse, createDashboardSnapshot, getDeviceStatus, toBatteryInfo } from './battery'
+
+const rows = [
+  {
+    id: 1,
+    userId: 7,
+    mac: 'RING-A03',
+    devModel: '2401-A',
+    devName: 'RING-A03',
+    isLowPower: 'false',
+    powerStatus: 2,
+    power: 94,
+    createTime: new Date('2026-05-10T23:00:00.000Z'),
+    remark: 'v3.8.2',
+  },
+  {
+    id: 2,
+    userId: 7,
+    mac: 'RING-B11',
+    devModel: '2402-B',
+    devName: 'RING-B11',
+    isLowPower: 'true',
+    powerStatus: 1,
+    power: 84,
+    createTime: '2026-05-10 22:00:00',
+    remark: null,
+  },
+]
+
+describe('battery domain', () => {
+  test('preserves legacy SOH status thresholds', () => {
+    expect(getDeviceStatus(91)).toBe('健康')
+    expect(getDeviceStatus(90)).toBe('关注')
+    expect(getDeviceStatus(85)).toBe('预警')
+  })
+
+  test('builds batteries response counters from records', () => {
+    const now = new Date('2026-05-11T00:00:00.000Z')
+    const items = rows.map(toBatteryInfo)
+    const response = createBatteriesResponse(items, now)
+
+    expect(response.updatedAt).toBe('2026-05-11T00:00:00.000Z')
+    expect(response.total).toBe(items.length)
+    expect(response.lowPower).toBe(1)
+    expect(response.charging).toBe(1)
+    expect(response.items[0]?.createTime).toBe('2026-05-10T23:00:00.000Z')
+  })
+
+  test('creates old dashboard aggregate shape from deterministic records', () => {
+    const now = new Date('2026-05-11T00:00:00.000Z')
+    const snapshot = createDashboardSnapshot(rows.map(toBatteryInfo), now)
+
+    expect(snapshot.devices).toHaveLength(2)
+    expect(snapshot.soh.history).toHaveLength(12)
+    expect(snapshot.soh.forecast).toHaveLength(4)
+    expect(snapshot.summary.totalDevices).toBe(snapshot.devices.length)
+    expect(snapshot.summary.warningCount + snapshot.summary.watchCount + snapshot.summary.healthyCount).toBe(
+      snapshot.devices.length,
+    )
+  })
+})

src/domain/battery.ts

@@ -0,0 +1,354 @@
+import { z } from 'zod'
+
+export const powerStatusSchema = z.union([z.literal(0), z.literal(1), z.literal(2)])
+export type PowerStatus = z.infer<typeof powerStatusSchema>
+
+export const deviceStatusSchema = z.union([z.literal('健康'), z.literal('关注'), z.literal('预警')])
+export type DeviceStatus = z.infer<typeof deviceStatusSchema>
+
+export const batteryInfoSchema = z.object({
+  id: z.number().int(),
+  userId: z.number().int(),
+  mac: z.string(),
+  devModel: z.string(),
+  devName: z.string(),
+  isLowPower: z.boolean(),
+  powerStatus: powerStatusSchema,
+  power: z.number().int().min(0).max(100),
+  createTime: z.string(),
+  remark: z.string().nullable(),
+})
+export type BatteryInfo = z.infer<typeof batteryInfoSchema>
+
+export const fleetUnitSchema = z.object({
+  id: z.string(),
+  batch: z.string(),
+  firmware: z.string(),
+  cycles: z.number().int(),
+  soh: z.number(),
+  soh30d: z.number(),
+  soh60d: z.number(),
+  soh90d: z.number(),
+  temperature: z.number(),
+  riskScore: z.number().int(),
+  chargeEfficiency: z.number(),
+  status: deviceStatusSchema,
+  riskFactors: z.array(z.string()),
+})
+export type FleetUnit = z.infer<typeof fleetUnitSchema>
+
+export const sohPointSchema = z.object({ month: z.string(), value: z.number() })
+export const sohResponseSchema = z.object({
+  history: z.array(sohPointSchema),
+  forecast: z.array(sohPointSchema),
+})
+
+export const eventItemSchema = z.object({
+  time: z.string(),
+  title: z.string(),
+  detail: z.string(),
+  severity: z.union([z.literal('高'), z.literal('中'), z.literal('低')]),
+})
+
+export const strategyItemSchema = z.object({
+  name: z.string(),
+  impact: z.string(),
+  scope: z.string(),
+  eta: z.string(),
+})
+
+export const summaryResponseSchema = z.object({
+  totalDevices: z.number().int(),
+  avgSoh: z.number(),
+  avgSoh30d: z.number(),
+  avgSoh90d: z.number(),
+  warningCount: z.number().int(),
+  watchCount: z.number().int(),
+  healthyCount: z.number().int(),
+  batchPerformance: z.array(z.object({ batch: z.string(), avgSoh: z.number() })),
+  riskFactorCounts: z.array(z.object({ factor: z.string(), count: z.number().int() })),
+  firmwareHealth: z.array(z.object({ firmware: z.string(), avgSoh: z.number(), count: z.number().int() })),
+  updatedAt: z.string(),
+  executiveSummary: z.string(),
+})
+
+export const dashboardSnapshotSchema = z.object({
+  devices: z.array(fleetUnitSchema),
+  soh: sohResponseSchema,
+  events: z.array(eventItemSchema),
+  strategies: z.array(strategyItemSchema),
+  summary: summaryResponseSchema,
+})
+export type DashboardSnapshot = z.infer<typeof dashboardSnapshotSchema>
+
+export const batteriesResponseSchema = z.object({
+  updatedAt: z.string(),
+  total: z.number().int(),
+  lowPower: z.number().int(),
+  charging: z.number().int(),
+  items: z.array(batteryInfoSchema),
+})
+export type BatteriesResponse = z.infer<typeof batteriesResponseSchema>
+
+const round1 = (value: number) => Math.round(value * 10) / 10
+
+const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value))
+
+const pad2 = (value: number) => value.toString().padStart(2, '0')
+
+const addMonths = (date: Date, months: number) =>
+  new Date(date.getFullYear(), date.getMonth() + months, date.getDate(), date.getHours(), 0, 0, 0)
+
+const addHours = (date: Date, hours: number) => new Date(date.getTime() + hours * 60 * 60 * 1000)
+
+const formatMonthLabel = (date: Date) => `${date.getFullYear().toString().slice(-2)}.${pad2(date.getMonth() + 1)}`
+
+const formatDateTime = (date: Date) =>
+  `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())} ${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`
+
+const formatEventTime = (date: Date) =>
+  `${pad2(date.getMonth() + 1)}-${pad2(date.getDate())} ${pad2(date.getHours())}:${pad2(date.getMinutes())}`
+
+export function getDeviceStatus(soh: number): DeviceStatus {
+  if (soh <= 85) return '预警'
+  if (soh <= 90) return '关注'
+  return '健康'
+}
+
+export function normalizePowerStatus(value: number): PowerStatus {
+  if (value === 1 || value === 2) return value
+  return 0
+}
+
+export function normalizeLowPower(value: string | boolean): boolean {
+  if (typeof value === 'boolean') return value
+  return value.toLowerCase() === 'true'
+}
+
+export type BatteryInfoSourceRow = {
+  id: number
+  userId: number
+  mac: string
+  devModel: string
+  devName: string
+  isLowPower: string | boolean
+  powerStatus: number
+  power: number
+  createTime: Date | string
+  remark: string | null
+}
+
+export function toBatteryInfo(row: BatteryInfoSourceRow): BatteryInfo {
+  return {
+    id: row.id,
+    userId: row.userId,
+    mac: row.mac,
+    devModel: row.devModel,
+    devName: row.devName,
+    isLowPower: normalizeLowPower(row.isLowPower),
+    powerStatus: normalizePowerStatus(row.powerStatus),
+    power: row.power,
+    createTime: row.createTime instanceof Date ? row.createTime.toISOString() : String(row.createTime),
+    remark: row.remark,
+  }
+}
+
+export function createBatteriesResponse(items: BatteryInfo[], now = new Date()): BatteriesResponse {
+  return {
+    updatedAt: now.toISOString(),
+    total: items.length,
+    lowPower: items.filter((item) => item.isLowPower).length,
+    charging: items.filter((item) => item.powerStatus === 1).length,
+    items,
+  }
+}
+
+function toFleetUnit(item: BatteryInfo, index: number): FleetUnit {
+  const soh = item.power
+  const status = getDeviceStatus(soh)
+  const riskFactors: string[] = []
+
+  if (item.isLowPower || item.power <= 20) riskFactors.push('低电量')
+  if (item.powerStatus === 1) riskFactors.push('充电中')
+  if (status === '预警') riskFactors.push('衰减加速')
+  if (item.remark?.includes('v3.7')) riskFactors.push('旧固件')
+
+  const thermalPressure = index % 3
+  const soh30d = round1(clamp(soh - 0.8 - thermalPressure * 0.25, 0, 100))
+  const soh60d = round1(clamp(soh - 1.7 - thermalPressure * 0.35, 0, 100))
+  const soh90d = round1(clamp(soh - 2.8 - thermalPressure * 0.45, 0, 100))
+  const temperature = round1(29.5 + thermalPressure * 2.1 + (item.isLowPower ? 1.4 : 0))
+  const chargeEfficiency = round1(clamp(91 + item.power / 12 - riskFactors.length * 1.8, 80, 98))
+  const riskScore = Math.round(clamp(12 + (100 - soh) * 1.45 + riskFactors.length * 8 + thermalPressure * 4, 8, 96))
+
+  return {
+    id: item.devName || item.mac,
+    batch: item.devModel,
+    firmware: item.remark ?? 'unknown',
+    cycles: 120 + index * 17 + Math.round((100 - soh) * 2.2),
+    soh,
+    soh30d,
+    soh60d,
+    soh90d,
+    temperature,
+    riskScore,
+    chargeEfficiency,
+    status,
+    riskFactors,
+  }
+}
+
+function createSohResponse(devices: FleetUnit[], now: Date) {
+  if (devices.length === 0) return { history: [], forecast: [] }
+
+  const avgSoh = devices.reduce((sum, unit) => sum + unit.soh, 0) / devices.length
+  const monthlyDrop = 0.45 + devices.reduce((sum, unit) => sum + unit.riskScore, 0) / devices.length / 160
+
+  const history = Array.from({ length: 12 }, (_, index) => {
+    const monthOffset = index - 11
+    return {
+      month: formatMonthLabel(addMonths(now, monthOffset)),
+      value: round1(clamp(avgSoh + Math.abs(monthOffset) * monthlyDrop, avgSoh, 100)),
+    }
+  })
+  const currentValue = history.at(-1)?.value ?? round1(avgSoh)
+  const forecast = Array.from({ length: 4 }, (_, index) => ({
+    month: formatMonthLabel(addMonths(now, index)),
+    value: index === 0 ? currentValue : round1(clamp(avgSoh - monthlyDrop * index, 0, 100)),
+  }))
+
+  return { history, forecast }
+}
+
+function summarizeBy<T extends string>(items: FleetUnit[], getKey: (item: FleetUnit) => T) {
+  return Object.entries(
+    items.reduce<Record<string, { sum: number; count: number }>>((acc, item) => {
+      const key = getKey(item)
+      const entry = acc[key] ?? { sum: 0, count: 0 }
+      entry.sum += item.soh
+      entry.count += 1
+      acc[key] = entry
+      return acc
+    }, {}),
+  )
+}
+
+function createSummary(devices: FleetUnit[], now: Date) {
+  const totalDevices = devices.length
+
+  if (totalDevices === 0) {
+    return {
+      totalDevices,
+      avgSoh: 0,
+      avgSoh30d: 0,
+      avgSoh90d: 0,
+      warningCount: 0,
+      watchCount: 0,
+      healthyCount: 0,
+      batchPerformance: [],
+      riskFactorCounts: [],
+      firmwareHealth: [],
+      updatedAt: formatDateTime(now),
+      executiveSummary: '当前没有可用于电池健康分析的真实设备记录。',
+    }
+  }
+
+  const avgSoh = devices.reduce((sum, unit) => sum + unit.soh, 0) / totalDevices
+  const avgSoh30d = devices.reduce((sum, unit) => sum + unit.soh30d, 0) / totalDevices
+  const avgSoh90d = devices.reduce((sum, unit) => sum + unit.soh90d, 0) / totalDevices
+  const warningCount = devices.filter((unit) => unit.status === '预警').length
+  const watchCount = devices.filter((unit) => unit.status === '关注').length
+  const healthyCount = devices.filter((unit) => unit.status === '健康').length
+  const batchPerformance = summarizeBy(devices, (unit) => unit.batch)
+    .map(([batch, data]) => ({ batch, avgSoh: round1(data.sum / data.count) }))
+    .sort((a, b) => b.avgSoh - a.avgSoh)
+  const firmwareHealth = summarizeBy(devices, (unit) => unit.firmware)
+    .map(([firmware, data]) => ({ firmware, avgSoh: round1(data.sum / data.count), count: data.count }))
+    .sort((a, b) => b.avgSoh - a.avgSoh)
+  const riskFactorCounts = Object.entries(
+    devices.reduce<Record<string, number>>((acc, unit) => {
+      for (const factor of unit.riskFactors) {
+        acc[factor] = (acc[factor] ?? 0) + 1
+      }
+      return acc
+    }, {}),
+  )
+    .map(([factor, count]) => ({ factor, count }))
+    .sort((a, b) => b.count - a.count)
+  const weakestBatch = batchPerformance.at(-1)?.batch ?? '当前设备'
+  const weakestFirmware = firmwareHealth.at(-1)?.firmware ?? 'unknown'
+
+  return {
+    totalDevices,
+    avgSoh: round1(avgSoh),
+    avgSoh30d: round1(avgSoh30d),
+    avgSoh90d: round1(avgSoh90d),
+    warningCount,
+    watchCount,
+    healthyCount,
+    batchPerformance,
+    riskFactorCounts,
+    firmwareHealth,
+    updatedAt: formatDateTime(now),
+    executiveSummary: `当前电池健康度总体可控，重点风险集中在 ${weakestBatch} 批次与 ${weakestFirmware} 固件设备。建议优先跟踪低电量、充电状态与未来 90 天 SoH 变化。`,
+  }
+}
+
+function createEvents(devices: FleetUnit[], now: Date) {
+  const sortedDevices = devices.slice().sort((a, b) => b.riskScore - a.riskScore)
+  const first = sortedDevices[0]
+
+  if (!first) return []
+
+  const second = sortedDevices[1] ?? first
+
+  return [
+    {
+      time: formatEventTime(addHours(now, -2)),
+      title: `${first.id} 进入重点观察队列`,
+      detail: `${first.id} 当前 SoH 为 ${first.soh.toFixed(1)}%，综合风险评分 ${first.riskScore}。`,
+      severity: first.status === '预警' ? '高' : '中',
+    },
+    {
+      time: formatEventTime(addHours(now, -5)),
+      title: `${second.batch} 批次健康度趋势更新`,
+      detail: `${second.batch} 批次未来 90 天预测 SoH 为 ${second.soh90d.toFixed(1)}%。`,
+      severity: second.status === '健康' ? '低' : '中',
+    },
+  ] satisfies DashboardSnapshot['events']
+}
+
+function createStrategies(devices: FleetUnit[]) {
+  if (devices.length === 0) return []
+
+  const warningDevices = devices.filter((unit) => unit.status === '预警')
+  const chargingDevices = devices.filter((unit) => unit.riskFactors.includes('充电中'))
+  const first = devices.slice().sort((a, b) => b.riskScore - a.riskScore)[0]
+
+  return [
+    {
+      name: '预警设备优先维护',
+      impact: `预计高风险设备减少 ${Math.max(10, warningDevices.length * 12)}%`,
+      scope: first ? `${first.id} 等 ${Math.max(1, warningDevices.length)} 台设备` : '当前设备',
+      eta: '48 小时内完成',
+    },
+    {
+      name: '充电策略复核',
+      impact: `覆盖 ${Math.max(1, chargingDevices.length)} 台充电中设备`,
+      scope: '充电中与低电量设备',
+      eta: '本周完成首轮验证',
+    },
+  ] satisfies DashboardSnapshot['strategies']
+}
+
+export function createDashboardSnapshot(items: BatteryInfo[], now = new Date()): DashboardSnapshot {
+  const devices = items.map(toFleetUnit)
+
+  return {
+    devices,
+    soh: createSohResponse(devices, now),
+    events: createEvents(devices, now),
+    strategies: createStrategies(devices),
+    summary: createSummary(devices, now),
+  }
+}

src/env.ts

@@ -0,0 +1,15 @@
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.url({ protocol: /^mysql$/ }),
+    LOG_DB: z.stringbool().default(false),
+    LOG_FORMAT: z.enum(['pretty', 'json']).optional(),
+    LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warning', 'error', 'fatal']).default('info'),
+  },
+  clientPrefix: 'VITE_',
+  client: {},
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+})

src/routeTree.gen.ts

@@ -9,21 +9,27 @@
 // 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 HealthRouteImport } from './routes/health'
+import { Route as BatteriesRouteImport } from './routes/batteries'
 import { Route as IndexRouteImport } from './routes/index'
-import { Route as ApiHealthRouteImport } from './routes/api/health'
 import { Route as ApiSplatRouteImport } from './routes/api/$'
 import { Route as ApiRpcSplatRouteImport } from './routes/api/rpc.$'
 
+const HealthRoute = HealthRouteImport.update({
+  id: '/health',
+  path: '/health',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const BatteriesRoute = BatteriesRouteImport.update({
+  id: '/batteries',
+  path: '/batteries',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiHealthRoute = ApiHealthRouteImport.update({
-  id: '/api/health',
-  path: '/api/health',
-  getParentRoute: () => rootRouteImport,
-} as any)
 const ApiSplatRoute = ApiSplatRouteImport.update({
   id: '/api/$',
   path: '/api/$',
@@ -37,40 +43,58 @@ const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/batteries': typeof BatteriesRoute
+  '/health': typeof HealthRoute
   '/api/$': typeof ApiSplatRoute
-  '/api/health': typeof ApiHealthRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/batteries': typeof BatteriesRoute
+  '/health': typeof HealthRoute
   '/api/$': typeof ApiSplatRoute
-  '/api/health': typeof ApiHealthRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/batteries': typeof BatteriesRoute
+  '/health': typeof HealthRoute
   '/api/$': typeof ApiSplatRoute
-  '/api/health': typeof ApiHealthRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/api/$' | '/api/health' | '/api/rpc/$'
+  fullPaths: '/' | '/batteries' | '/health' | '/api/$' | '/api/rpc/$'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/api/$' | '/api/health' | '/api/rpc/$'
-  id: '__root__' | '/' | '/api/$' | '/api/health' | '/api/rpc/$'
+  to: '/' | '/batteries' | '/health' | '/api/$' | '/api/rpc/$'
+  id: '__root__' | '/' | '/batteries' | '/health' | '/api/$' | '/api/rpc/$'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  BatteriesRoute: typeof BatteriesRoute
+  HealthRoute: typeof HealthRoute
   ApiSplatRoute: typeof ApiSplatRoute
-  ApiHealthRoute: typeof ApiHealthRoute
   ApiRpcSplatRoute: typeof ApiRpcSplatRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/health': {
+      id: '/health'
+      path: '/health'
+      fullPath: '/health'
+      preLoaderRoute: typeof HealthRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/batteries': {
+      id: '/batteries'
+      path: '/batteries'
+      fullPath: '/batteries'
+      preLoaderRoute: typeof BatteriesRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -78,13 +102,6 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/health': {
-      id: '/api/health'
-      path: '/api/health'
-      fullPath: '/api/health'
-      preLoaderRoute: typeof ApiHealthRouteImport
-      parentRoute: typeof rootRouteImport
-    }
     '/api/$': {
       id: '/api/$'
       path: '/api/$'
@@ -104,8 +121,9 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  BatteriesRoute: BatteriesRoute,
+  HealthRoute: HealthRoute,
   ApiSplatRoute: ApiSplatRoute,
-  ApiHealthRoute: ApiHealthRoute,
   ApiRpcSplatRoute: ApiRpcSplatRoute,
 }
 export const routeTree = rootRouteImport

src/routes/__root.tsx

@@ -4,6 +4,7 @@ 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 { name } from '#package'
 import { ErrorComponent } from '@/components/Error'
 import { NotFoundComponent } from '@/components/NotFound'
 import appCss from '@/styles.css?url'
@@ -23,7 +24,7 @@ export const Route = createRootRouteWithContext<RouterContext>()({
         content: 'width=device-width, initial-scale=1',
       },
       {
-        title: 'Furtherverse',
+        title: name,
       },
     ],
     links: [
@@ -34,8 +35,8 @@ export const Route = createRootRouteWithContext<RouterContext>()({
     ],
   }),
   shellComponent: RootDocument,
-  errorComponent: () => <ErrorComponent />,
-  notFoundComponent: () => <NotFoundComponent />,
+  errorComponent: ErrorComponent,
+  notFoundComponent: NotFoundComponent,
 })
 
 function RootDocument({ children }: Readonly<{ children: ReactNode }>) {

src/routes/api/$.ts

@@ -3,7 +3,7 @@ import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
 import { onError } from '@orpc/server'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
 import { createFileRoute } from '@tanstack/react-router'
-import { name, version } from '@/../package.json'
+import { name, version } from '#package'
 import { handleValidationError, logError } from '@/server/api/interceptors'
 import { router } from '@/server/api/routers'
 

src/routes/batteries.tsx

@@ -0,0 +1,119 @@
+import { useSuspenseQuery } from '@tanstack/react-query'
+import { createFileRoute, Link } from '@tanstack/react-router'
+import { orpc } from '@/client/orpc'
+import type { BatteryInfo } from '@/domain/battery'
+
+export const Route = createFileRoute('/batteries')({
+  component: BatteriesPage,
+  loader: async ({ context }) => {
+    await context.queryClient.ensureQueryData(orpc.battery.batteries.queryOptions({ input: {} }))
+  },
+  errorComponent: ({ error }) => (
+    <main className="flex min-h-screen items-center justify-center bg-[#09090B]">
+      <div className="text-center">
+        <p className="text-lg text-red-400">数据加载失败</p>
+        <p className="mt-2 text-sm text-zinc-500">{error.message}</p>
+      </div>
+    </main>
+  ),
+})
+
+const powerStatusLabel: Record<0 | 1 | 2, string> = {
+  0: '未充电',
+  1: '充电中',
+  2: '已充满',
+}
+
+const powerStatusColor: Record<0 | 1 | 2, string> = {
+  0: 'text-zinc-400',
+  1: 'text-teal-400',
+  2: 'text-emerald-400',
+}
+
+function powerBarColor(power: number, isLowPower: boolean): string {
+  if (isLowPower || power <= 20) return 'bg-red-500'
+  if (power <= 50) return 'bg-amber-500'
+  return 'bg-teal-500'
+}
+
+function DeviceCard({ item }: { item: BatteryInfo }) {
+  return (
+    <article className="rounded-lg border border-zinc-800 bg-zinc-950 p-4">
+      <header className="flex items-start justify-between">
+        <div>
+          <h3 className="font-medium text-zinc-100">{item.devName}</h3>
+          <p className="mt-0.5 text-xs text-zinc-500">{item.mac}</p>
+        </div>
+        <span className="rounded bg-zinc-900 px-2 py-0.5 text-xs text-zinc-400">{item.devModel}</span>
+      </header>
+
+      <div className="mt-4">
+        <div className="flex items-baseline justify-between">
+          <span className="font-semibold text-2xl text-zinc-100">
+            {item.power}
+            <span className="ml-0.5 font-normal text-sm text-zinc-500">%</span>
+          </span>
+          <span className={`text-xs ${powerStatusColor[item.powerStatus]}`}>{powerStatusLabel[item.powerStatus]}</span>
+        </div>
+        <div className="mt-2 h-1.5 overflow-hidden rounded-full bg-zinc-800">
+          <div className={`h-full ${powerBarColor(item.power, item.isLowPower)}`} style={{ width: `${item.power}%` }} />
+        </div>
+      </div>
+
+      <footer className="mt-4 flex items-center justify-between text-xs text-zinc-500">
+        <span>更新 {new Date(item.createTime).toLocaleString('zh-CN')}</span>
+        {item.isLowPower && <span className="rounded bg-red-950 px-1.5 py-0.5 text-red-400">低电量</span>}
+      </footer>
+    </article>
+  )
+}
+
+function BatteriesPage() {
+  const { data } = useSuspenseQuery(
+    orpc.battery.batteries.queryOptions({
+      input: {},
+      refetchInterval: 30_000,
+    }),
+  )
+
+  return (
+    <main className="min-h-screen bg-[#09090B] px-6 py-8 text-zinc-100">
+      <header className="mx-auto max-w-7xl">
+        <div className="flex items-end justify-between">
+          <div>
+            <h1 className="font-semibold text-2xl">设备电池实时状态</h1>
+            <p className="mt-1 text-sm text-zinc-500">更新 {new Date(data.updatedAt).toLocaleString('zh-CN')}</p>
+          </div>
+          <nav className="text-xs">
+            <Link to="/" className="text-zinc-500 hover:text-zinc-300">
+              ← 返回 SoH 看板
+            </Link>
+          </nav>
+        </div>
+
+        <dl className="mt-6 grid grid-cols-3 gap-4">
+          <div className="rounded-lg border border-zinc-800 bg-zinc-950 p-4">
+            <dt className="text-xs text-zinc-500">设备总数</dt>
+            <dd className="mt-1 font-semibold text-2xl">{data.total}</dd>
+          </div>
+          <div className="rounded-lg border border-zinc-800 bg-zinc-950 p-4">
+            <dt className="text-xs text-zinc-500">低电量</dt>
+            <dd className="mt-1 font-semibold text-2xl text-red-400">{data.lowPower}</dd>
+          </div>
+          <div className="rounded-lg border border-zinc-800 bg-zinc-950 p-4">
+            <dt className="text-xs text-zinc-500">充电中</dt>
+            <dd className="mt-1 font-semibold text-2xl text-teal-400">{data.charging}</dd>
+          </div>
+        </dl>
+      </header>
+
+      <section className="mx-auto mt-8 grid max-w-7xl grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+        {data.items.length > 0 ? (
+          data.items.map((item) => <DeviceCard key={item.id} item={item} />)
+        ) : (
+          <div className="col-span-full py-12 text-center text-zinc-500">暂无设备数据</div>
+        )}
+      </section>
+    </main>
+  )
+}

src/routes/health.ts

@@ -0,0 +1,9 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/health')({
+  server: {
+    handlers: {
+      GET: () => new Response('ok', { status: 200, headers: { 'content-type': 'text/plain' } }),
+    },
+  },
+})

src/routes/index.tsx

@@ -0,0 +1,632 @@
+import { useSuspenseQuery } from '@tanstack/react-query'
+import { createFileRoute, Link } from '@tanstack/react-router'
+import { orpc } from '@/client/orpc'
+import type { DashboardSnapshot, DeviceStatus } from '@/domain/battery'
+
+export const Route = createFileRoute('/')({
+  component: Dashboard,
+  loader: async ({ context }) => {
+    await context.queryClient.ensureQueryData(orpc.battery.dashboard.queryOptions())
+  },
+  errorComponent: ({ error }) => (
+    <main className="flex min-h-screen items-center justify-center bg-[#09090B]">
+      <div className="text-center">
+        <p className="text-lg text-red-400">数据加载失败</p>
+        <p className="mt-2 text-sm text-[#71717A]">{error.message}</p>
+      </div>
+    </main>
+  ),
+})
+
+function buildChartData(soh: DashboardSnapshot['soh']) {
+  const chartData: { month: string; history?: number; forecast?: number }[] = soh.history.map((h) => ({
+    month: h.month,
+    history: h.value,
+    forecast: undefined,
+  }))
+
+  if (chartData.length > 0 && soh.forecast.length > 0) {
+    // Overlap: last history point is also first forecast point
+    const last = chartData[chartData.length - 1]
+    if (last) {
+      last.forecast = soh.forecast[0]?.value
+    }
+  }
+
+  for (let i = 1; i < soh.forecast.length; i++) {
+    const f = soh.forecast[i]
+    if (f) {
+      chartData.push({
+        month: f.month,
+        history: undefined,
+        forecast: f.value,
+      })
+    }
+  }
+
+  return chartData
+}
+
+const statusColorMap: Record<DeviceStatus, string> = {
+  健康: 'text-emerald-400',
+  关注: 'text-amber-400',
+  预警: 'text-red-400',
+}
+
+const severityColorMap: Record<DashboardSnapshot['events'][number]['severity'], string> = {
+  高: 'text-red-400',
+  中: 'text-amber-400',
+  低: 'text-zinc-400',
+}
+
+function SimpleChart({ data }: { data: ReturnType<typeof buildChartData> }) {
+  if (data.length === 0) {
+    return <div className="flex h-full items-center justify-center text-[#71717A]">暂无数据</div>
+  }
+
+  const minVal = Math.floor(Math.min(...data.map((d) => Math.min(d.history ?? 100, d.forecast ?? 100)))) - 2
+  const maxVal = Math.ceil(Math.max(...data.map((d) => Math.max(d.history ?? 0, d.forecast ?? 0)))) + 2
+  const range = maxVal - minVal
+
+  const width = 1000
+  const height = 280
+  const padding = { top: 20, right: 20, bottom: 30, left: 40 }
+  const innerWidth = width - padding.left - padding.right
+  const innerHeight = height - padding.top - padding.bottom
+
+  const getX = (index: number) => padding.left + (index / (data.length - 1)) * innerWidth
+  const getY = (val: number) => padding.top + innerHeight - ((val - minVal) / range) * innerHeight
+
+  const historyPoints = data
+    .map((d, i) => (d.history !== undefined ? `${getX(i)},${getY(d.history)}` : null))
+    .filter(Boolean)
+    .join(' ')
+
+  const forecastPoints = data
+    .map((d, i) => (d.forecast !== undefined ? `${getX(i)},${getY(d.forecast)}` : null))
+    .filter(Boolean)
+    .join(' ')
+
+  const lastHistoryIndex = data.findLastIndex((d) => d.history !== undefined)
+  const historyArea = historyPoints
+    ? `${historyPoints} ${getX(lastHistoryIndex)},${padding.top + innerHeight} ${getX(0)},${padding.top + innerHeight}`
+    : ''
+
+  const forecastStartIndex = data.findIndex((d) => d.forecast !== undefined)
+  const forecastArea = forecastPoints
+    ? `${forecastPoints} ${getX(data.length - 1)},${padding.top + innerHeight} ${getX(forecastStartIndex)},${padding.top + innerHeight}`
+    : ''
+
+  return (
+    <svg
+      viewBox={`0 0 ${width} ${height}`}
+      className="w-full h-full overflow-visible"
+      role="img"
+      aria-label="SoH Trend Chart"
+    >
+      <title>SoH Trend Chart</title>
+      <defs>
+        <linearGradient id="historyFill" x1="0" y1="0" x2="0" y2="1">
+          <stop offset="0%" stopColor="#2DD4BF" stopOpacity={0.15} />
+          <stop offset="100%" stopColor="#2DD4BF" stopOpacity={0} />
+        </linearGradient>
+        <linearGradient id="forecastFill" x1="0" y1="0" x2="0" y2="1">
+          <stop offset="0%" stopColor="#818CF8" stopOpacity={0.15} />
+          <stop offset="100%" stopColor="#818CF8" stopOpacity={0} />
+        </linearGradient>
+      </defs>
+
+      {/* Grid */}
+      {[0, 0.25, 0.5, 0.75, 1].map((ratio) => {
+        const y = padding.top + innerHeight * ratio
+        const val = maxVal - range * ratio
+        return (
+          <g key={ratio}>
+            <line x1={padding.left} y1={y} x2={width - padding.right} y2={y} stroke="#ffffff" strokeOpacity={0.05} />
+            <text x={padding.left - 10} y={y + 4} fill="#71717A" fontSize="11" textAnchor="end">
+              {val.toFixed(0)}%
+            </text>
+          </g>
+        )
+      })}
+
+      {/* 85% Reference Line */}
+      {85 >= minVal && 85 <= maxVal && (
+        <g>
+          <line
+            x1={padding.left}
+            y1={getY(85)}
+            x2={width - padding.right}
+            y2={getY(85)}
+            stroke="#F87171"
+            strokeOpacity={0.4}
+            strokeDasharray="4 4"
+          />
+          <text x={width - padding.right + 10} y={getY(85) + 4} fill="#F87171" fontSize="11">
+            85% 预警线
+          </text>
+        </g>
+      )}
+
+      {/* X Axis */}
+      {data.map((d, i) => (
+        <text key={d.month} x={getX(i)} y={height - 5} fill="#71717A" fontSize="11" textAnchor="middle">
+          {d.month}
+        </text>
+      ))}
+
+      {/* Areas */}
+      {historyArea && <polygon points={historyArea} fill="url(#historyFill)" />}
+      {forecastArea && <polygon points={forecastArea} fill="url(#forecastFill)" />}
+
+      {/* Lines */}
+      {historyPoints && <polyline points={historyPoints} fill="none" stroke="#2DD4BF" strokeWidth="2.5" />}
+      {forecastPoints && (
+        <polyline points={forecastPoints} fill="none" stroke="#818CF8" strokeWidth="2.5" strokeDasharray="4 4" />
+      )}
+
+      {/* Dots */}
+      {data.map((d, i) => {
+        const dots = []
+        if (d.history !== undefined) {
+          dots.push(
+            <circle
+              key={`h-${d.month}`}
+              cx={getX(i)}
+              cy={getY(d.history)}
+              r="3"
+              fill="#09090B"
+              stroke="#2DD4BF"
+              strokeWidth="2"
+            />,
+          )
+        }
+        if (d.forecast !== undefined) {
+          dots.push(
+            <circle
+              key={`f-${d.month}`}
+              cx={getX(i)}
+              cy={getY(d.forecast)}
+              r="3"
+              fill="#09090B"
+              stroke="#818CF8"
+              strokeWidth="2"
+            />,
+          )
+        }
+        return dots
+      })}
+    </svg>
+  )
+}
+
+function Dashboard() {
+  const { data } = useSuspenseQuery(orpc.battery.dashboard.queryOptions())
+
+  const { devices, soh, events, strategies, summary } = data
+  const {
+    totalDevices,
+    avgSoh,
+    avgSoh30d,
+    avgSoh90d,
+    warningCount,
+    watchCount,
+    healthyCount,
+    batchPerformance,
+    riskFactorCounts,
+    firmwareHealth,
+    updatedAt,
+    executiveSummary,
+  } = summary
+  const chartData = buildChartData(soh)
+
+  return (
+    <main className="min-h-screen w-full bg-[#09090B] font-sans text-[#F4F4F5]">
+      {/* Background gradient */}
+      <div className="pointer-events-none fixed inset-0 z-0 flex justify-center">
+        <div className="h-[800px] w-[1200px] -translate-y-1/2 rounded-full bg-teal-900/10 blur-[120px]" />
+      </div>
+
+      <div className="relative z-10 mx-auto max-w-[1400px] px-6 pb-24 pt-12 lg:px-12">
+        {/* Header */}
+        <header className="animate-fade-up mb-12 flex flex-col gap-6 lg:flex-row lg:items-end lg:justify-between">
+          <div className="max-w-3xl">
+            <div className="mb-4 inline-flex items-center gap-2 rounded-md border border-white/10 bg-white/5 px-2.5 py-1 text-xs font-medium text-teal-400">
+              智能戒指电池健康预测模型 (v2.4)
+            </div>
+            <h1 className="text-4xl font-light tracking-tight text-white sm:text-5xl">SoH 预测与风险洞察</h1>
+          </div>
+          <div className="flex flex-col items-end gap-3 text-right">
+            <div className="flex items-center gap-6 text-sm">
+              <div>
+                <span className="text-[#71717A]">模型回测准确率 (MAE)</span>
+                <span className="ml-2 font-medium tabular-nums text-teal-400">1.2%</span>
+              </div>
+              <div className="h-4 w-px bg-white/10" />
+              <div>
+                <span className="text-[#71717A]">预测命中率</span>
+                <span className="ml-2 font-medium tabular-nums text-teal-400">94.5%</span>
+              </div>
+            </div>
+            <p className="text-xs tabular-nums text-[#71717A]">数据更新时间: {updatedAt}</p>
+            <Link to="/batteries" className="text-xs text-teal-400 hover:text-teal-300">
+              设备电池实时状态 →
+            </Link>
+          </div>
+        </header>
+
+        {/* Executive Summary */}
+        <section className="animate-fade-up delay-100 mb-12 rounded-xl border border-teal-900/30 bg-teal-950/10 p-6">
+          <h2 className="mb-3 text-sm font-medium text-teal-400">执行摘要</h2>
+          <p className="text-base leading-relaxed text-[#A1A1AA]">{executiveSummary}</p>
+        </section>
+
+        {/* Primary KPI Row */}
+        <section className="animate-fade-up delay-200 mb-12 grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-5">
+          {/* Hero KPI */}
+          <article className="relative overflow-hidden rounded-2xl border border-white/10 bg-white/[0.03] p-8 lg:col-span-2">
+            <div className="absolute inset-x-0 top-0 h-1 bg-gradient-to-r from-teal-500/50 to-transparent" />
+            <p className="text-sm font-medium text-[#A1A1AA]">当前平均 SoH</p>
+            <div className="mt-4 flex items-baseline gap-2">
+              <h2 className="text-6xl font-light tabular-nums text-white">{avgSoh.toFixed(1)}</h2>
+              <span className="text-2xl text-[#71717A]">%</span>
+            </div>
+            <div className="mt-6 flex items-center gap-3 text-sm">
+              <span className="inline-flex items-center gap-1.5 text-emerald-400">
+                <span className="h-1.5 w-1.5 rounded-full bg-emerald-400" />
+                基线健康
+              </span>
+              <span className="text-[#71717A]">|</span>
+              <span className="text-[#A1A1AA]">共 {totalDevices} 台设备</span>
+            </div>
+          </article>
+
+          {/* Regular KPIs */}
+          <article className="rounded-2xl border border-white/[0.06] bg-white/[0.02] p-6 transition-colors hover:border-white/10">
+            <p className="text-sm text-[#A1A1AA]">30 天预测均值</p>
+            <div className="mt-3 flex items-baseline gap-1">
+              <h2 className="text-4xl font-light tabular-nums text-white">{avgSoh30d.toFixed(1)}</h2>
+              <span className="text-lg text-[#71717A]">%</span>
+            </div>
+            <div className="mt-4 flex items-center gap-1.5 text-sm">
+              <span className="text-red-400">↘</span>
+              <span className="tabular-nums text-[#A1A1AA]">{(avgSoh - avgSoh30d).toFixed(1)}% 衰减</span>
+            </div>
+          </article>
+
+          <article className="rounded-2xl border border-white/[0.06] bg-white/[0.02] p-6 transition-colors hover:border-white/10">
+            <p className="text-sm text-[#A1A1AA]">90 天预测均值</p>
+            <div className="mt-3 flex items-baseline gap-1">
+              <h2 className="text-4xl font-light tabular-nums text-white">{avgSoh90d.toFixed(1)}</h2>
+              <span className="text-lg text-[#71717A]">%</span>
+            </div>
+            <div className="mt-4 flex items-center gap-1.5 text-sm">
+              <span className="text-red-400">↘</span>
+              <span className="tabular-nums text-[#A1A1AA]">{(avgSoh - avgSoh90d).toFixed(1)}% 衰减</span>
+            </div>
+          </article>
+
+          <article className="rounded-2xl border border-white/[0.06] bg-white/[0.02] p-6 transition-colors hover:border-white/10">
+            <p className="text-sm text-[#A1A1AA]">高风险设备</p>
+            <div className="mt-3 flex items-baseline gap-1">
+              <h2 className="text-4xl font-light tabular-nums text-white">{warningCount}</h2>
+              <span className="text-lg text-[#71717A]">台</span>
+            </div>
+            <div className="mt-4 flex items-center gap-1.5 text-sm">
+              <span className="text-amber-400">↗</span>
+              <span className="tabular-nums text-[#A1A1AA]">
+                占比 {totalDevices > 0 ? ((warningCount / totalDevices) * 100).toFixed(1) : 0}%
+              </span>
+            </div>
+          </article>
+        </section>
+
+        {/* Divider */}
+        <hr className="my-12 border-white/5" />
+
+        {/* SoH Trend Chart */}
+        <section className="animate-fade-up delay-300 mb-12">
+          <article className="rounded-2xl border border-white/[0.06] bg-white/[0.03] p-8">
+            <header className="mb-8 flex flex-wrap items-end justify-between gap-4">
+              <div>
+                <h3 className="text-xl font-medium text-white">SoH 衰减趋势与 90 天预测</h3>
+                <p className="mt-1 text-sm text-[#A1A1AA]">基于历史 12 个月真实数据与未来 3 个月模型预测区间</p>
+              </div>
+              <div className="flex items-center gap-6 text-sm text-[#A1A1AA]">
+                <span className="inline-flex items-center gap-2">
+                  <span className="h-2 w-4 rounded-full bg-teal-400" />
+                  历史观测值
+                </span>
+                <span className="inline-flex items-center gap-2">
+                  <span className="h-2 w-4 rounded-full bg-indigo-400" />
+                  模型预测值
+                </span>
+              </div>
+            </header>
+
+            <div className="w-full h-[320px]">
+              <SimpleChart data={chartData} />
+            </div>
+          </article>
+        </section>
+
+        {/* Two-column grid */}
+        <section className="animate-fade-up delay-400 mb-12 grid grid-cols-1 gap-8 lg:grid-cols-2">
+          {/* Left Column */}
+          <div className="space-y-8">
+            {/* Risk Distribution */}
+            <div>
+              <h3 className="mb-6 text-lg font-medium text-white">风险分层与结构</h3>
+              <div className="space-y-5">
+                <div>
+                  <div className="mb-2 flex justify-between text-sm">
+                    <span className="text-[#A1A1AA]">健康 (SoH &gt; 90%)</span>
+                    <span className="tabular-nums text-white">
+                      {healthyCount} 台{' '}
+                      <span className="text-[#71717A]">
+                        / {totalDevices > 0 ? ((healthyCount / totalDevices) * 100).toFixed(1) : 0}%
+                      </span>
+                    </span>
+                  </div>
+                  <div className="h-1.5 overflow-hidden rounded-full bg-white/5">
+                    <div
+                      className="h-full rounded-full bg-emerald-400"
+                      style={{ width: `${totalDevices > 0 ? (healthyCount / totalDevices) * 100 : 0}%` }}
+                    />
+                  </div>
+                </div>
+                <div>
+                  <div className="mb-2 flex justify-between text-sm">
+                    <span className="text-[#A1A1AA]">关注 (85% &lt; SoH &le; 90%)</span>
+                    <span className="tabular-nums text-white">
+                      {watchCount} 台{' '}
+                      <span className="text-[#71717A]">
+                        / {totalDevices > 0 ? ((watchCount / totalDevices) * 100).toFixed(1) : 0}%
+                      </span>
+                    </span>
+                  </div>
+                  <div className="h-1.5 overflow-hidden rounded-full bg-white/5">
+                    <div
+                      className="h-full rounded-full bg-amber-400"
+                      style={{ width: `${totalDevices > 0 ? (watchCount / totalDevices) * 100 : 0}%` }}
+                    />
+                  </div>
+                </div>
+                <div>
+                  <div className="mb-2 flex justify-between text-sm">
+                    <span className="text-[#A1A1AA]">预警 (SoH &le; 85%)</span>
+                    <span className="tabular-nums text-white">
+                      {warningCount} 台{' '}
+                      <span className="text-[#71717A]">
+                        / {totalDevices > 0 ? ((warningCount / totalDevices) * 100).toFixed(1) : 0}%
+                      </span>
+                    </span>
+                  </div>
+                  <div className="h-1.5 overflow-hidden rounded-full bg-white/5">
+                    <div
+                      className="h-full rounded-full bg-red-400"
+                      style={{ width: `${totalDevices > 0 ? (warningCount / totalDevices) * 100 : 0}%` }}
+                    />
+                  </div>
+                </div>
+              </div>
+            </div>
+
+            {/* Regional Performance */}
+            <div>
+              <h3 className="mb-6 text-lg font-medium text-white">批次健康度概览</h3>
+              <div className="space-y-4">
+                {batchPerformance.length > 0 ? (
+                  batchPerformance.map((item) => (
+                    <div key={item.batch} className="flex items-center gap-4">
+                      <span className="w-20 text-sm text-[#A1A1AA]">{item.batch}</span>
+                      <div className="flex-1">
+                        <div className="h-1.5 overflow-hidden rounded-full bg-white/5">
+                          <div className="h-full rounded-full bg-white/20" style={{ width: `${item.avgSoh}%` }} />
+                        </div>
+                      </div>
+                      <span className="w-12 text-right text-sm tabular-nums text-white">{item.avgSoh.toFixed(1)}%</span>
+                    </div>
+                  ))
+                ) : (
+                  <div className="text-sm text-[#71717A]">暂无数据</div>
+                )}
+              </div>
+            </div>
+          </div>
+
+          {/* Right Column */}
+          <div className="space-y-8">
+            {/* Event Timeline */}
+            <div>
+              <h3 className="mb-6 text-lg font-medium text-white">异常特征时间轴</h3>
+              <div className="relative border-l border-white/10 pl-5">
+                {events.length > 0 ? (
+                  events.map((event) => (
+                    <div key={event.time + event.title} className="mb-6 last:mb-0">
+                      <div
+                        className={`absolute -left-[4px] mt-1.5 h-2 w-2 rounded-full ${
+                          event.severity === '高' ? 'bg-red-400' : 'bg-amber-400'
+                        }`}
+                      />
+                      <div className="mb-1 flex items-center gap-3">
+                        <span className="text-xs font-medium tabular-nums text-[#71717A]">{event.time}</span>
+                        <span className={`text-xs ${severityColorMap[event.severity]}`}>{event.severity}风险</span>
+                      </div>
+                      <h4 className="text-sm font-medium text-[#F4F4F5]">{event.title}</h4>
+                      <p className="mt-1 text-sm leading-relaxed text-[#A1A1AA]">{event.detail}</p>
+                    </div>
+                  ))
+                ) : (
+                  <div className="text-sm text-[#71717A]">暂无数据</div>
+                )}
+              </div>
+            </div>
+
+            {/* Risk Factor Frequency */}
+            <div>
+              <h3 className="mb-6 text-lg font-medium text-white">主要风险因子分布</h3>
+              <div className="flex flex-wrap gap-2">
+                {riskFactorCounts.length > 0 ? (
+                  riskFactorCounts.map((item) => (
+                    <div
+                      key={item.factor}
+                      className="flex items-center gap-2 rounded-md border border-white/5 bg-white/[0.02] px-3 py-1.5 text-sm"
+                    >
+                      <span className="text-[#A1A1AA]">{item.factor}</span>
+                      <span className="rounded bg-white/10 px-1.5 py-0.5 text-xs tabular-nums text-white">
+                        {item.count}
+                      </span>
+                    </div>
+                  ))
+                ) : (
+                  <div className="text-sm text-[#71717A]">暂无数据</div>
+                )}
+              </div>
+            </div>
+          </div>
+        </section>
+
+        {/* Divider */}
+        <hr className="my-12 border-white/5" />
+
+        {/* Device Table */}
+        <section className="animate-fade-up delay-500 mb-12">
+          <div className="mb-6 flex items-end justify-between">
+            <div>
+              <h3 className="text-xl font-medium text-white">高风险设备清单与预测明细</h3>
+              <p className="mt-1 text-sm text-[#A1A1AA]">按综合风险评分排序，展示未来 30/60/90 天衰减预测</p>
+            </div>
+          </div>
+          <div className="overflow-x-auto rounded-xl border border-white/[0.06] bg-white/[0.02]">
+            <table className="w-full min-w-[1000px] border-collapse text-left text-sm">
+              <thead>
+                <tr className="border-b border-white/10 bg-white/[0.02] text-[#A1A1AA]">
+                  <th className="px-6 py-4 font-medium">设备标识</th>
+                  <th className="px-6 py-4 font-medium">生产批次</th>
+                  <th className="px-6 py-4 font-medium">当前 SoH</th>
+                  <th className="px-6 py-4 font-medium">30天预测</th>
+                  <th className="px-6 py-4 font-medium">90天预测</th>
+                  <th className="px-6 py-4 font-medium">风险评分</th>
+                  <th className="px-6 py-4 font-medium">状态</th>
+                  <th className="px-6 py-4 font-medium">主要风险因子</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-white/5">
+                {devices.length > 0 ? (
+                  devices
+                    .slice()
+                    .sort((a, b) => b.riskScore - a.riskScore)
+                    .map((unit) => (
+                      <tr key={unit.id} className="transition-colors hover:bg-white/[0.04]">
+                        <td className="px-6 py-4 font-medium text-white">{unit.id}</td>
+                        <td className="px-6 py-4 text-[#A1A1AA]">{unit.batch}</td>
+                        <td className="px-6 py-4 tabular-nums text-white">{unit.soh.toFixed(1)}%</td>
+                        <td className="px-6 py-4 tabular-nums text-[#A1A1AA]">{unit.soh30d.toFixed(1)}%</td>
+                        <td className="px-6 py-4 tabular-nums text-[#A1A1AA]">{unit.soh90d.toFixed(1)}%</td>
+                        <td className="px-6 py-4">
+                          <div className="flex items-center gap-2">
+                            <div className="h-1.5 w-12 overflow-hidden rounded-full bg-white/5">
+                              <div
+                                className={`h-full rounded-full ${
+                                  unit.riskScore >= 75
+                                    ? 'bg-red-400'
+                                    : unit.riskScore >= 45
+                                      ? 'bg-amber-400'
+                                      : 'bg-emerald-400'
+                                }`}
+                                style={{ width: `${unit.riskScore}%` }}
+                              />
+                            </div>
+                            <span className="tabular-nums text-white">{unit.riskScore}</span>
+                          </div>
+                        </td>
+                        <td className="px-6 py-4">
+                          <span className={statusColorMap[unit.status]}>{unit.status}</span>
+                        </td>
+                        <td className="px-6 py-4">
+                          <div className="flex flex-wrap gap-1.5">
+                            {unit.riskFactors.length > 0 ? (
+                              unit.riskFactors.map((factor) => (
+                                <span key={factor} className="text-[#A1A1AA]">
+                                  {factor}
+                                  {factor !== unit.riskFactors[unit.riskFactors.length - 1] && '、'}
+                                </span>
+                              ))
+                            ) : (
+                              <span className="text-[#71717A]">-</span>
+                            )}
+                          </div>
+                        </td>
+                      </tr>
+                    ))
+                ) : (
+                  <tr>
+                    <td colSpan={8} className="px-6 py-8 text-center text-[#71717A]">
+                      暂无设备数据
+                    </td>
+                  </tr>
+                )}
+              </tbody>
+            </table>
+          </div>
+        </section>
+
+        {/* Bottom Row */}
+        <section className="animate-fade-up delay-500 grid grid-cols-1 gap-8 lg:grid-cols-3">
+          {/* Strategy Cards */}
+          <div className="lg:col-span-2">
+            <h3 className="mb-6 text-lg font-medium text-white">模型驱动的维护策略建议</h3>
+            <div className="grid gap-4 sm:grid-cols-2">
+              {strategies.length > 0 ? (
+                strategies.map((item, index) => (
+                  <div
+                    key={item.name}
+                    className="relative overflow-hidden rounded-xl border border-white/[0.06] bg-white/[0.02] p-5"
+                  >
+                    <div
+                      className={`absolute bottom-0 left-0 top-0 w-1 ${index === 0 ? 'bg-red-400' : index === 1 ? 'bg-amber-400' : 'bg-teal-400'}`}
+                    />
+                    <h4 className="font-medium text-white">{item.name}</h4>
+                    <p className="mt-2 text-sm text-[#A1A1AA]">{item.impact}</p>
+                    <div className="mt-4 flex flex-wrap gap-4 text-xs text-[#71717A]">
+                      <span>范围: {item.scope}</span>
+                      <span>时效: {item.eta}</span>
+                    </div>
+                  </div>
+                ))
+              ) : (
+                <div className="text-sm text-[#71717A] col-span-2">暂无策略建议</div>
+              )}
+            </div>
+          </div>
+
+          {/* Firmware Comparison */}
+          <div>
+            <h3 className="mb-6 text-lg font-medium text-white">固件版本健康度对比</h3>
+            <div className="rounded-xl border border-white/[0.06] bg-white/[0.02] p-5">
+              <div className="space-y-4">
+                {firmwareHealth.length > 0 ? (
+                  firmwareHealth.map((item) => (
+                    <div key={item.firmware} className="flex items-center justify-between">
+                      <div>
+                        <div className="text-sm font-medium text-white">{item.firmware}</div>
+                        <div className="text-xs text-[#71717A]">{item.count} 台设备</div>
+                      </div>
+                      <div className="text-right">
+                        <div className="text-sm tabular-nums text-white">{item.avgSoh.toFixed(1)}%</div>
+                        <div className="text-xs text-[#71717A]">平均 SoH</div>
+                      </div>
+                    </div>
+                  ))
+                ) : (
+                  <div className="text-sm text-[#71717A]">暂无数据</div>
+                )}
+              </div>
+            </div>
+          </div>
+        </section>
+      </div>
+    </main>
+  )
+}

src/server/api/context.ts

@@ -0,0 +1,3 @@
+export interface BaseContext {
+  headers: Headers
+}

src/server/api/contracts/battery.contract.ts

@@ -0,0 +1,13 @@
+import { oc } from '@orpc/contract'
+import { z } from 'zod'
+import { batteriesResponseSchema, dashboardSnapshotSchema } from '@/domain/battery'
+
+export const dashboard = oc.input(z.void()).output(dashboardSnapshotSchema)
+
+export const batteries = oc
+  .input(
+    z.object({
+      mac: z.string().min(1).optional(),
+    }),
+  )
+  .output(batteriesResponseSchema)

src/server/api/contracts/index.ts

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

src/server/api/interceptors.ts

@@ -1,13 +1,19 @@
 import { ORPCError, ValidationError } from '@orpc/server'
 import { z } from 'zod'
+import { getLogger } from '@/server/logger'
+
+const logger = getLogger(['api'])
 
 export const logError = (error: unknown) => {
-  console.error(error)
+  logger.error('Unhandled error in ORPC handler', { error })
 }
 
 export const handleValidationError = (error: unknown) => {
-  if (error instanceof ORPCError && error.code === 'BAD_REQUEST' && error.cause instanceof ValidationError) {
-    // If you only use Zod you can safely cast to ZodIssue[] (per ORPC official docs)
+  if (!(error instanceof ORPCError) || !(error.cause instanceof ValidationError)) return
+
+  if (error.code === 'BAD_REQUEST') {
+    // ORPC widens issues to the Standard Schema shape; contracts here are built from Zod.
+    // Rehydrate to reuse z.prettifyError / z.flattenError.
     const zodError = new z.ZodError(error.cause.issues as z.core.$ZodIssue[])
 
     throw new ORPCError('INPUT_VALIDATION_FAILED', {
@@ -18,7 +24,7 @@ export const handleValidationError = (error: unknown) => {
     })
   }
 
-  if (error instanceof ORPCError && error.code === 'INTERNAL_SERVER_ERROR' && error.cause instanceof ValidationError) {
+  if (error.code === 'INTERNAL_SERVER_ERROR') {
     throw new ORPCError('OUTPUT_VALIDATION_FAILED', {
       cause: error.cause,
     })

src/server/api/routers/battery.router.ts

@@ -0,0 +1,15 @@
+import { createBatteriesResponse, createDashboardSnapshot } from '@/domain/battery'
+import { os } from '@/server/api/server'
+import { getBatteryHistory, getLatestBatteryPerDevice } from '@/server/battery/mysql'
+
+export const dashboard = os.battery.dashboard.handler(async () => {
+  const items = await getLatestBatteryPerDevice()
+
+  return createDashboardSnapshot(items)
+})
+
+export const batteries = os.battery.batteries.handler(async ({ input }) => {
+  const items = input.mac ? await getBatteryHistory(input.mac) : await getLatestBatteryPerDevice()
+
+  return createBatteriesResponse(items)
+})

src/server/api/routers/index.ts

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

src/server/api/types.ts

@@ -0,0 +1,5 @@
+import type { ContractRouterClient, InferContractRouterOutputs } from '@orpc/contract'
+import type { Contract } from './contracts'
+
+export type RouterClient = ContractRouterClient<Contract>
+export type RouterOutputs = InferContractRouterOutputs<Contract>

src/server/battery/mysql.ts

@@ -0,0 +1,75 @@
+import mysql, { type Pool, type RowDataPacket } from 'mysql2/promise'
+
+import { type BatteryInfo, type BatteryInfoSourceRow, toBatteryInfo } from '@/domain/battery'
+import { env } from '@/env'
+
+const historyLimit = 500
+
+type BatteryInfoMysqlRow = RowDataPacket & BatteryInfoSourceRow
+
+let pool: Pool | undefined
+
+function getBatteryPool() {
+  pool ??= mysql.createPool({
+    uri: env.DATABASE_URL,
+    waitForConnections: true,
+    connectionLimit: 5,
+    namedPlaceholders: true,
+  })
+
+  return pool
+}
+
+export async function closeBatteryPool() {
+  if (!pool) return
+
+  await pool.end()
+  pool = undefined
+}
+
+const sourceColumns = `
+  id,
+  user_id AS userId,
+  mac,
+  dev_model AS devModel,
+  dev_name AS devName,
+  is_low_power AS isLowPower,
+  power_status AS powerStatus,
+  power,
+  create_time AS createTime,
+  remark
+`
+
+export async function getBatteryHistory(mac: string): Promise<BatteryInfo[]> {
+  const [rows] = await getBatteryPool().query<BatteryInfoMysqlRow[]>(
+    `
+      SELECT ${sourceColumns}
+      FROM ls_battery_info
+      WHERE mac = :mac
+      ORDER BY create_time DESC, id DESC
+      LIMIT :limit
+    `,
+    { mac, limit: historyLimit },
+  )
+
+  return rows.map(toBatteryInfo)
+}
+
+export async function getLatestBatteryPerDevice(): Promise<BatteryInfo[]> {
+  const [rows] = await getBatteryPool().query<BatteryInfoMysqlRow[]>(`
+    SELECT ${sourceColumns}
+    FROM ls_battery_info AS current_record
+    WHERE NOT EXISTS (
+      SELECT 1
+      FROM ls_battery_info AS newer_record
+      WHERE newer_record.mac = current_record.mac
+        AND (
+          newer_record.create_time > current_record.create_time
+          OR (newer_record.create_time = current_record.create_time AND newer_record.id > current_record.id)
+        )
+    )
+    ORDER BY current_record.create_time DESC, current_record.id DESC
+  `)
+
+  return rows.map(toBatteryInfo)
+}

src/server/logger.ts

@@ -0,0 +1,19 @@
+import { configureSync, getConfig, getConsoleSink, getJsonLinesFormatter } from '@logtape/logtape'
+import { prettyFormatter } from '@logtape/pretty'
+import { env } from '@/env'
+
+if (getConfig() === null) {
+  const format = env.LOG_FORMAT ?? (process.stdout.isTTY ? 'pretty' : 'json')
+
+  configureSync({
+    sinks: {
+      console: getConsoleSink({ formatter: format === 'pretty' ? prettyFormatter : getJsonLinesFormatter() }),
+    },
+    loggers: [
+      { category: [], lowestLevel: env.LOG_LEVEL, sinks: ['console'] },
+      { category: ['logtape', 'meta'], lowestLevel: 'warning', sinks: ['console'], parentSinks: 'override' },
+    ],
+  })
+}
+
+export { getLogger } from '@logtape/logtape'

src/server/plugins/shutdown.ts

@@ -0,0 +1,30 @@
+import { closeBatteryPool } from '@/server/battery/mysql'
+import { getLogger } from '@/server/logger'
+
+export default () => {
+  if (import.meta.dev) return
+
+  const logger = getLogger(['shutdown'])
+  let exiting = false
+
+  const shutdown = async (signal: NodeJS.Signals) => {
+    if (exiting) {
+      logger.warn('Forcing exit on repeated signal', { signal })
+      process.exit(0)
+    }
+    exiting = true
+    logger.info('Draining for shutdown', { signal, graceMs: 500 })
+
+    await Bun.sleep(500)
+    try {
+      await closeBatteryPool()
+      logger.info('Battery MySQL pool closed, exiting')
+    } catch (error) {
+      logger.error('DB pool close failed during shutdown', { error })
+    }
+    process.exit(0)
+  }
+
+  process.on('SIGINT', () => void shutdown('SIGINT'))
+  process.on('SIGTERM', () => void shutdown('SIGTERM'))
+}

tsconfig.json

@@ -1,9 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/tsconfig",
-  "display": "Base",
   "compilerOptions": {
     "target": "esnext",
-    "lib": ["ESNext"],
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
     "module": "preserve",
     "skipLibCheck": true,
 
@@ -22,7 +21,12 @@
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true,
 
-    "types": ["bun"]
+    "jsx": "react-jsx",
+    "types": ["bun"],
+
+    "paths": {
+      "@/*": ["./src/*"]
+    }
   },
-  "exclude": ["node_modules"]
+  "exclude": ["node_modules", ".output", "out"]
 }

turbo.json

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

vite.config.ts

@@ -15,13 +15,10 @@ export default defineConfig({
     nitro({
       preset: 'bun',
       serveStatic: 'inline',
+      plugins: ['./src/server/plugins/shutdown.ts'],
     }),
   ],
   resolve: {
     tsconfigPaths: true,
   },
-  server: {
-    port: 3000,
-    strictPort: true,
-  },
 })