docs: 添加摘要+ZIP 加密测试控制器参考

docs: 移除旧版工具箱端授权对接指南文档
refactor(server): signAndPackReport 对齐 Kotlin 参考实现的摘要与签名结构
2026-03-10 15:09:11 +08:00 · 2026-03-10 15:08:36 +08:00 · 2026-03-10 15:08:12 +08:00 · 2026-03-10 15:07:31 +08:00 · 2026-03-10 15:07:07 +08:00 · 2026-03-06 16:51:33 +08:00
121 changed files with 4419 additions and 4249 deletions
@@ -1,13 +0,0 @@
-node_modules/
-.output/
-.tanstack/
-out/
-.git/
-.env
-.env.*
-
-*.md
-*.tsbuildinfo
-*.bun-build
-
-.vscode/
@@ -1,15 +0,0 @@
-DATABASE_URL=mysql://user:password@localhost:3306/database
-
-# 默认关闭公开 OpenAPI 文档/规格；仅在受控本地或内网演示环境显式启用。
-# ENABLE_API_DOCS=false
-
-# 必填：外部 SoH 预测服务地址
-SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
-# SOH_PREDICTION_CACHE_TTL_SECONDS=86400
-# SOH_PREDICTION_NEGATIVE_CACHE_TTL_SECONDS=300
-# SOH_PREDICTION_TIMEOUT_MS=10000
-
-# 可选：日志级别与输出格式
-# 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
@@ -1,24 +1,162 @@
-# Dependencies
-node_modules/
+### Custom ###

-# Build output
-.output/
+# TanStack
 .tanstack/
-.vite/
-out/
-volumes/
-*.bun-build
-*.tsbuildinfo
-vite.config.js.timestamp-*
-vite.config.ts.timestamp-*

-# Env
+# Nitro
+.output/
+
+# Bun build
+*.bun-build
+
+# SQLite database files
+*.db
+*.db-wal
+*.db-shm
+
+# 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
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# 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.example

-# Logs
-*.log
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache

-# OS
-.DS_Store
+# 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/
@@ -1,11 +1,9 @@
 {
  "recommendations": [
    "biomejs.biome",
-    "codezombiech.gitignore",
    "hverlin.mise-vscode",
    "oven.bun-vscode",
    "redhat.vscode-yaml",
-    "tamasfe.even-better-toml",
-    "unional.vscode-sort-package-json"
+    "tamasfe.even-better-toml"
  ]
 }
@@ -43,8 +43,6 @@
  "files.watcherExclude": {
    "**/routeTree.gen.ts": true
  },
-  "js/ts.tsdk.path": "node_modules/typescript/lib",
-  "js/ts.tsdk.promptToUseWorkspaceVersion": true,
  "search.exclude": {
    "**/routeTree.gen.ts": true
  }
@@ -1,109 +1,219 @@
-# AGENTS.md
+# AGENTS.md - AI Coding Agent Guidelines

-Repo-specific notes for AI agents.
+Guidelines for AI agents working in this Bun monorepo.

-## Stack
+## Project Overview

- 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.
+> **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`.**

-## Scripts
+- **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)

+## Build / Lint / Test Commands
+
+### Root Commands (via Turbo)
 ```bash
-bun run dev
-bun run build
-bun run compile
-bun run seed
-bun run typecheck
-bun run test
-bun run fix
+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
 ```

-Before shipping: `bun run fix && bun run typecheck && bun run test && bun run build`.
-
-## MySQL Source
-
-Environment variable:
-
+### Server App (`apps/server`)
 ```bash
-DATABASE_URL=mysql://user:password@host:3306/database
+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
 ```

-Required AI prediction service:
-
+### Desktop App (`apps/desktop`)
 ```bash
-SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
-SOH_PREDICTION_CACHE_TTL_SECONDS=86400
-SOH_PREDICTION_TIMEOUT_MS=10000
+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`.
-
-| 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 |
-
-Rules:
-
- 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`.
- `battery.batteries` returns paginated latest records per `mac`; supported filters are `pageSize`, `cursor`, `search`, `lowPower`, `powerStatus`, and `sort`.
- `battery.history` takes `mac` and returns history ordered by `create_time DESC, id DESC`, limited to 500 rows.
- Dashboard requires the external prediction API via `SOH_PREDICTION_API_BASE_URL`; missing configuration must fail environment validation. Per-device prediction failures may surface as unavailable values, but must not be rendered as `0%`.
-
-## Layout
-
-```
-src/
-├── routes/
-│   ├── index.tsx       # SoH dashboard
-│   ├── batteries.tsx   # battery monitor page
-│   └── api/            # ORPC handlers
-├── server/
-│   ├── api/            # contracts / routers / interceptors
-│   ├── battery/mysql.ts
-│   └── prediction/client.ts
-├── domain/battery.ts
-├── client/orpc.ts
-└── styles.css
+### 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
 ```

-## ORPC
+## Code Style (TypeScript)

- 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`
-  - `battery.history`
+### Formatting (Biome)
+- **Indent**: 2 spaces | **Line endings**: LF
+- **Quotes**: Single `'` | **Semicolons**: Omit (ASI)
+- **Arrow parentheses**: Always `(x) => x`

-## CLI And Deploy
+### Imports
+Biome auto-organizes. Order: 1) External packages → 2) Internal `@/*` aliases → 3) Type imports (`import type { ... }`)

- `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.
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+import { db } from '@/server/db'
+import type { ReactNode } from 'react'
+```

-## Code Style
+### TypeScript Strictness
+- `strict: true`, `noUncheckedIndexedAccess: true`, `noImplicitOverride: true`, `verbatimModuleSyntax: true`
+- Use `@/*` path aliases (maps to `src/*`)

- 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.
+### 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())`
+- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)
+
+### 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
+
+```
+.
+├── 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
+```
+
+## See Also
+
+- `apps/server/AGENTS.md` - Detailed TanStack Start / ORPC patterns
+- `apps/desktop/AGENTS.md` - Electron desktop development guide
@@ -1,24 +0,0 @@
-FROM oven/bun:1.3.13 AS source
-
-WORKDIR /app
-
-COPY package.json bun.lock ./
-RUN bun install --frozen-lockfile
-
-COPY . .
-
-FROM source AS build
-
-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"]
@@ -1,143 +0,0 @@
-# battery-soh
-
-电池健康运营看板，用于接入客户现有设备数据，持续呈现电量状态、健康预测、风险分布与维护建议。系统以只读方式连接客户数据库，不改动生产数据；当健康预测暂不可用时，页面会明确显示不可用状态，避免用误导性数值替代真实结果。
-
-## 产品能力
-
- **健康总览**：聚合展示设备规模、平均健康度、30/90 天趋势与预警设备占比。
- **风险识别**：按健康度、低电量、充电状态与预测风险生成重点关注设备清单。
- **实时明细**：支持按设备名称、编号、电量与充电状态筛选设备，快速定位需要排查的对象。
- **维护建议**：基于当前可用数据给出巡检、复查与优先处理建议。
- **可信展示**：缺少预测结果时显示“预测不可用”，不会将缺失值渲染为 `0%`。
-
-## 数据接入
-
-系统接入客户现有 MySQL 数据源，业务运行时仅执行只读查询。需要配置：
-
-```bash
-DATABASE_URL=mysql://user:password@host:3306/database
-```
-
-客户设备表：`ls_battery_info`。
-
-| 字段名 | 数据类型 | 业务含义 |
-| --- | --- | --- |
-| `id` | `int(11)` auto increment | 记录 ID |
-| `user_id` | `int(11)` | 用户 ID |
-| `mac` | `varchar(50)` | 设备编号 |
-| `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)` | 备注 |
-
-## 健康预测
-
-看板需要接入外部 SoH 预测服务：
-
-```bash
-SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
-SOH_PREDICTION_CACHE_TTL_SECONDS=86400
-SOH_PREDICTION_NEGATIVE_CACHE_TTL_SECONDS=300
-SOH_PREDICTION_TIMEOUT_MS=10000
-```
-
-服务端会调用 `${SOH_PREDICTION_API_BASE_URL}/predict`，使用返回的当前健康度、30 天趋势、90 天趋势和风险评分生成看板视图。预测结果会按设备与最新采集记录缓存，默认 24 小时；单台设备预测失败或历史数据不足时会短暂缓存不可用状态，默认 5 分钟，避免反复打满预测服务，同时仅该设备显示为“预测不可用”。
-
-## 接口文档
-
-OpenAPI 文档和规格默认不公开，生产或生产类运行环境应保持默认值：
-
-```bash
-ENABLE_API_DOCS=false
-```
-
-仅在受控本地开发或内网演示环境显式设置 `ENABLE_API_DOCS=true` 后，才会开放 `http://localhost:3000/api/docs` 与 `http://localhost:3000/api/spec.json`。`/api/rpc` 不受此开关影响。
-
-## 快速开始
-
-```bash
-cp .env.example .env
-bun install
-bun run dev
-```
-
-打开浏览器：
-
- `http://localhost:3000/`：设备健康运营看板
- `http://localhost:3000/batteries`：设备状态明细
- `http://localhost:3000/api/docs`：接口文档（需设置 `ENABLE_API_DOCS=true`）
-
-## 本地演示环境
-
-如果暂时没有生产数据库连接，可以使用 Docker Compose 启动本地 MySQL 并填充演示数据：
-
-```bash
-docker compose up --build
-```
-
-Compose 会启动：
-
- `db`：本地 MySQL 8.4
- `seed`：初始化本地 `ls_battery_info` 演示数据
- `app`：启动应用服务
-
-Compose 的 `app` 服务会为本地演示显式启用 `ENABLE_API_DOCS=true`；生产部署不应沿用该设置，除非已通过网络边界或上游认证限制访问。
-
-也可以手动初始化本地数据：
-
-```bash
-DATABASE_URL=mysql://battery:battery@localhost:3306/battery_soh bun run seed
-```
-
-`seed` 仅用于本地开发和演示环境；应用运行时仍保持只读查询，不写入业务数据库。
-
-## 系统结构
-
-```text
-src/
-├── routes/                  # 页面与 API 路由
-├── server/
-│   ├── api/                 # 接口契约与路由
-│   ├── battery/mysql.ts     # 设备数据只读查询
-│   └── prediction/client.ts # 健康预测服务客户端
-├── domain/battery.ts        # 电池领域模型与看板聚合
-├── client/orpc.ts           # 前端接口客户端
-└── styles.css               # 全局样式入口
-```
-
-核心接口：
-
- `battery.dashboard`：生成健康运营看板数据。
- `battery.batteries`：分页返回每台设备的最新状态，支持搜索、筛选和排序。
- `battery.history`：返回单台设备最近 500 条历史记录。
-
-## 部署
-
-```bash
-bun run build
-bun run compile
-./out/server-<target>
-```
-
-构建产物为单个服务二进制文件，运行时需要配置 `DATABASE_URL` 与 SoH 预测服务地址。
-
-## 常用命令
-
-| 命令 | 作用 |
-| --- | --- |
-| `bun run dev` | 启动开发服务 |
-| `bun run build` | 构建应用 |
-| `bun run compile` | 生成单二进制产物 |
-| `bun run seed` | 初始化本地演示数据 |
-| `bun run typecheck` | TypeScript 类型检查 |
-| `bun run test` | 运行测试 |
-| `bun run fix` | 格式化与静态检查 |
-
-交付前验证：
-
-```bash
-bun run fix && bun run typecheck && bun run test && bun run build
-```
@@ -0,0 +1,3 @@
+# electron-vite build output
+out/
+dist/
@@ -0,0 +1,95 @@
+# 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.
@@ -0,0 +1,9 @@
+{
+  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": "//",
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  }
+}
@@ -0,0 +1,48 @@
+# 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}
@@ -0,0 +1,11 @@
+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()],
+  },
+})
@@ -0,0 +1,37 @@
+{
+  "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:"
+  }
+}
@@ -0,0 +1,198 @@
+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)
@@ -0,0 +1,256 @@
+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
+    },
+  }
+}
@@ -0,0 +1 @@
+export {}
@@ -0,0 +1,33 @@
+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>
+  )
+}
@@ -0,0 +1,12 @@
+<!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>
@@ -0,0 +1,11 @@
+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>,
+)
@@ -0,0 +1 @@
+@import "tailwindcss";
@@ -0,0 +1,8 @@
+{
+  "extends": "@furtherverse/tsconfig/react.json",
+  "compilerOptions": {
+    "composite": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/renderer/**/*"]
+}
@@ -0,0 +1,11 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.node.json"
+    }
+  ]
+}
@@ -0,0 +1,8 @@
+{
+  "extends": "@furtherverse/tsconfig/base.json",
+  "compilerOptions": {
+    "composite": true,
+    "types": ["node"]
+  },
+  "include": ["src/main/**/*", "src/preload/**/*", "electron.vite.config.ts"]
+}
@@ -0,0 +1,41 @@
+{
+  "$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/**"]
+    }
+  }
+}
@@ -0,0 +1 @@
+DATABASE_PATH=data.db
@@ -0,0 +1,279 @@
+# 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
+- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)
+
+## Environment Variables
+
+```typescript
+// src/env.ts - using @t3-oss/env-core
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const 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
@@ -0,0 +1,12 @@
+{
+  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": "//",
+  "files": {
+    "includes": ["**", "!**/routeTree.gen.ts"]
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  }
+}
@@ -1,8 +1,7 @@
 import { mkdir, rm } from 'node:fs/promises'
-import { basename } from 'node:path'
 import { parseArgs } from 'node:util'

-const ENTRYPOINT = 'src/bin.ts'
+const ENTRYPOINT = '.output/server/index.mjs'
 const OUTDIR = 'out'

 const SUPPORTED_TARGETS: readonly Bun.Build.CompileTarget[] = [
@@ -13,9 +12,8 @@ const SUPPORTED_TARGETS: readonly Bun.Build.CompileTarget[] = [
  'bun-linux-arm64',
 ]

-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 isSupportedTarget = (value: string): value is Bun.Build.CompileTarget =>
+  (SUPPORTED_TARGETS as readonly string[]).includes(value)

 const { values } = parseArgs({
  options: { target: { type: 'string' } },
@@ -50,20 +48,13 @@ const main = async () => {
  const result = await Bun.build({
    entrypoints: [ENTRYPOINT],
    outdir: OUTDIR,
-    // 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',
+    compile: { outfile, target },
  })

  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}`)
 }

@@ -0,0 +1,12 @@
+import { defineConfig } from 'drizzle-kit'
+
+const databasePath = process.env.DATABASE_PATH ?? 'data.db'
+
+export default defineConfig({
+  out: './drizzle',
+  schema: './src/server/db/schema/index.ts',
+  dialect: 'sqlite',
+  dbCredentials: {
+    url: databasePath,
+  },
+})
@@ -0,0 +1,62 @@
+{
+  "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": "bun --bun drizzle-kit generate",
+    "db:migrate": "bun --bun drizzle-kit migrate",
+    "db:push": "bun --bun drizzle-kit push",
+    "db:studio": "bun --bun drizzle-kit studio",
+    "dev": "bunx --bun vite dev",
+    "fix": "biome check --write",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@furtherverse/crypto": "workspace:*",
+    "@orpc/client": "catalog:",
+    "@orpc/contract": "catalog:",
+    "@orpc/openapi": "catalog:",
+    "@orpc/server": "catalog:",
+    "@orpc/tanstack-query": "catalog:",
+    "@orpc/zod": "catalog:",
+    "@t3-oss/env-core": "catalog:",
+    "@tanstack/react-query": "catalog:",
+    "@tanstack/react-router": "catalog:",
+    "@tanstack/react-router-ssr-query": "catalog:",
+    "@tanstack/react-start": "catalog:",
+    "drizzle-orm": "catalog:",
+    "jszip": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "systeminformation": "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:",
+    "babel-plugin-react-compiler": "catalog:",
+    "drizzle-kit": "catalog:",
+    "nitro": "catalog:",
+    "tailwindcss": "catalog:",
+    "vite": "catalog:",
+    "vite-tsconfig-paths": "catalog:"
+  }
+}
@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:
@@ -0,0 +1,3 @@
+export function ErrorComponent() {
+  return <div>An unhandled error happened!</div>
+}
@@ -0,0 +1,3 @@
+export function NotFoundComponent() {
+  return <div>404 - Not Found</div>
+}
@@ -0,0 +1,14 @@
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    DATABASE_PATH: z.string().min(1).default('data.db'),
+  },
+  clientPrefix: 'VITE_',
+  client: {
+    VITE_APP_TITLE: z.string().min(1).optional(),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+})
@@ -9,27 +9,21 @@
 // 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/$',
@@ -43,58 +37,40 @@ 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: '/' | '/batteries' | '/health' | '/api/$' | '/api/rpc/$'
+  fullPaths: '/' | '/api/$' | '/api/health' | '/api/rpc/$'
  fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/batteries' | '/health' | '/api/$' | '/api/rpc/$'
-  id: '__root__' | '/' | '/batteries' | '/health' | '/api/$' | '/api/rpc/$'
+  to: '/' | '/api/$' | '/api/health' | '/api/rpc/$'
+  id: '__root__' | '/' | '/api/$' | '/api/health' | '/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: '/'
@@ -102,6 +78,13 @@ 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/$'
@@ -121,9 +104,8 @@ declare module '@tanstack/react-router' {

 const rootRouteChildren: RootRouteChildren = {
  IndexRoute: IndexRoute,
-  BatteriesRoute: BatteriesRoute,
-  HealthRoute: HealthRoute,
  ApiSplatRoute: ApiSplatRoute,
+  ApiHealthRoute: ApiHealthRoute,
  ApiRpcSplatRoute: ApiRpcSplatRoute,
 }
 export const routeTree = rootRouteImport
@@ -4,7 +4,6 @@ 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'
@@ -24,7 +23,7 @@ export const Route = createRootRouteWithContext<RouterContext>()({
        content: 'width=device-width, initial-scale=1',
      },
      {
-        title: name,
+        title: 'Furtherverse',
      },
    ],
    links: [
@@ -35,8 +34,8 @@ export const Route = createRootRouteWithContext<RouterContext>()({
    ],
  }),
  shellComponent: RootDocument,
-  errorComponent: ErrorComponent,
-  notFoundComponent: NotFoundComponent,
+  errorComponent: () => <ErrorComponent />,
+  notFoundComponent: () => <NotFoundComponent />,
 })

 function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
@@ -3,28 +3,26 @@ 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'
-import { env } from '@/env'
+import { name, version } from '@/../package.json'
 import { handleValidationError, logError } from '@/server/api/interceptors'
 import { router } from '@/server/api/routers'

 const handler = new OpenAPIHandler(router, {
-  plugins: env.ENABLE_API_DOCS
-    ? [
-        new OpenAPIReferencePlugin({
-          docsProvider: 'scalar',
-          schemaConverters: [new ZodToJsonSchemaConverter()],
-          specGenerateOptions: {
-            info: {
-              title: name,
-              version,
-            },
-          },
-          docsPath: '/docs',
-          specPath: '/spec.json',
-        }),
-      ]
-    : [],
+  plugins: [
+    new OpenAPIReferencePlugin({
+      docsProvider: 'scalar',
+      schemaConverters: [new ZodToJsonSchemaConverter()],
+      specGenerateOptions: {
+        info: {
+          title: name,
+          version,
+          description: 'UX 授权服务 OpenAPI 文档：设备授权、任务解密、摘要加密与报告签名打包接口。',
+        },
+      },
+      docsPath: '/docs',
+      specPath: '/spec.json',
+    }),
+  ],
  interceptors: [onError(logError)],
  clientInterceptors: [onError(handleValidationError)],
 })
@@ -33,8 +31,6 @@ export const Route = createFileRoute('/api/$')({
  server: {
    handlers: {
      ANY: async ({ request }) => {
-        if (!env.ENABLE_API_DOCS) return new Response('Not Found', { status: 404 })
-
        const { response } = await handler.handle(request, {
          prefix: '/api',
          context: {
@@ -0,0 +1,27 @@
+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 }),
+    },
+  },
+})
@@ -0,0 +1,21 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/')({
+  component: Home,
+})
+
+function Home() {
+  return (
+    <div className="min-h-screen bg-slate-50 flex items-center justify-center font-sans">
+      <div className="text-center space-y-4">
+        <h1 className="text-3xl font-bold text-slate-900 tracking-tight">UX Server</h1>
+        <p className="text-slate-500">
+          API:&nbsp;
+          <a href="/api" className="text-indigo-600 hover:text-indigo-700 underline">
+            /api
+          </a>
+        </p>
+      </div>
+    </div>
+  )
+}
@@ -0,0 +1,25 @@
+import type { DB } from '@/server/db'
+
+/**
+ * 基础 Context - 所有请求都包含的上下文
+ */
+export interface BaseContext {
+  headers: Headers
+}
+
+/**
+ * 数据库 Context - 通过 db middleware 扩展
+ */
+export interface DBContext extends BaseContext {
+  db: DB
+}
+
+/**
+ * 认证 Context - 通过 auth middleware 扩展（未来使用）
+ *
+ * @example
+ * export interface AuthContext extends DBContext {
+ *   userId: string
+ *   user: User
+ * }
+ */
@@ -0,0 +1,82 @@
+import { oc } from '@orpc/contract'
+import { z } from 'zod'
+
+const configOutput = z
+  .object({
+    licence: z.string().nullable().describe('当前本地 licence，未设置时为 null'),
+    fingerprint: z.string().describe('UX 本机计算得到的设备特征码（SHA-256）'),
+    hasPgpPrivateKey: z.boolean().describe('是否已配置 OpenPGP 私钥'),
+  })
+  .meta({
+    examples: [
+      {
+        licence: 'LIC-8F2A-XXXX',
+        fingerprint: '9a3b7c1d2e4f5a6b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b',
+        hasPgpPrivateKey: true,
+      },
+      {
+        licence: null,
+        fingerprint: '9a3b7c1d2e4f5a6b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b',
+        hasPgpPrivateKey: false,
+      },
+    ],
+  })
+
+export const get = oc
+  .route({
+    method: 'POST',
+    path: '/config/get',
+    operationId: 'configGet',
+    summary: '读取本机身份配置',
+    description:
+      '返回 UX 本地持久化的 licence、本机设备特征码（fingerprint）以及 OpenPGP 私钥配置状态。工具箱端可据此判断是否已完成本地身份初始化。',
+    tags: ['Config'],
+  })
+  .input(z.object({}))
+  .output(configOutput)
+
+export const setLicence = oc
+  .route({
+    method: 'POST',
+    path: '/config/set-licence',
+    operationId: 'configSetLicence',
+    summary: '写入本地 licence',
+    description:
+      '写入或更新本机持久化的 licence。设备特征码（fingerprint）始终由 UX 本机自动计算，无需外部传入。此接口应在设备授权流程前调用。',
+    tags: ['Config'],
+  })
+  .input(
+    z
+      .object({
+        licence: z.string().min(1).describe('本地持久化的 licence'),
+      })
+      .meta({
+        examples: [{ licence: 'LIC-8F2A-XXXX' }],
+      }),
+  )
+  .output(configOutput)
+
+export const setPgpPrivateKey = oc
+  .route({
+    method: 'POST',
+    path: '/config/set-pgp-private-key',
+    operationId: 'configSetPgpPrivateKey',
+    summary: '写入本地 OpenPGP 私钥',
+    description:
+      '写入或更新本机持久化的 OpenPGP 私钥（ASCII armored 格式），用于报告签名。私钥与设备绑定，调用报告签名接口时 UX 自动读取，无需每次传入。',
+    tags: ['Config'],
+  })
+  .input(
+    z
+      .object({
+        pgpPrivateKey: z.string().min(1).describe('OpenPGP 私钥（ASCII armored 格式）'),
+      })
+      .meta({
+        examples: [
+          {
+            pgpPrivateKey: '-----BEGIN PGP PRIVATE KEY BLOCK-----\n\nxcMGBGd...\n-----END PGP PRIVATE KEY BLOCK-----',
+          },
+        ],
+      }),
+  )
+  .output(configOutput)
@@ -0,0 +1,150 @@
+import { oc } from '@orpc/contract'
+import { z } from 'zod'
+
+export const encryptDeviceInfo = oc
+  .route({
+    method: 'POST',
+    path: '/crypto/encrypt-device-info',
+    operationId: 'encryptDeviceInfo',
+    summary: '生成设备授权二维码密文',
+    description:
+      '将本机 licence 与 fingerprint 组装为 JSON，使用平台 RSA 公钥（RSA-OAEP + SHA-256）加密后返回 Base64 密文，供工具箱生成设备授权二维码。参见《工具箱端 - 设备授权二维码生成指南》。',
+    tags: ['Crypto'],
+  })
+  .input(
+    z
+      .object({
+        platformPublicKey: z.string().min(1).describe('平台公钥（Base64，SPKI DER）'),
+      })
+      .meta({
+        examples: [
+          {
+            platformPublicKey:
+              'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzDlZvMDVaL+fjl05Hi182JOAUAaN4gh9rOF+1NhKfO4J6e0HLy8lBuylp3A4xoTiyUejNm22h0dqAgDSPnY/xZR76POFTD1soHr2LaFCN8JAbQ96P8gE7wC9qpoTssVvIVRH7QbVd260J6eD0Szwcx9cg591RSN69pMpe5IVRi8T99Hhql6/wnZHORPr18eESLOY93jRskLzc0q18r68RRoTJiQf+9YC8ub5iKp7rCjVnPi1UbIYmXmL08tk5mksYA0NqWQAa1ofKxx/9tQtB9uTjhTxuTu94XU9jlGU87qaHZs+kpqa8CAbYYJFbSP1xHwoZzpU2jpw2aF22HBYxwIDAQAB',
+          },
+        ],
+      }),
+  )
+  .output(
+    z
+      .object({
+        encrypted: z.string().describe('Base64 密文（用于设备授权二维码）'),
+      })
+      .meta({
+        examples: [
+          {
+            encrypted: 'dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIFJTQS1PQUVQIGVuY3J5cHRlZCBkZXZpY2UgaW5mby4uLg==',
+          },
+        ],
+      }),
+  )
+
+export const decryptTask = oc
+  .route({
+    method: 'POST',
+    path: '/crypto/decrypt-task',
+    operationId: 'decryptTask',
+    summary: '解密任务二维码数据',
+    description:
+      '使用本机 licence 与 fingerprint 派生 AES-256-GCM 密钥（SHA-256），解密 App 任务二维码中的 Base64 密文，返回任务信息明文。参见《工具箱端 - 任务二维码解密指南》。',
+    tags: ['Crypto'],
+  })
+  .input(
+    z
+      .object({
+        encryptedData: z.string().min(1).describe('Base64 编码的 AES-256-GCM 密文（来自任务二维码扫描结果）'),
+      })
+      .meta({
+        examples: [
+          {
+            encryptedData: 'uWUcAmp6UQd0w3G3crdsd4613QCxGLoEgslgXJ4G2hQhpQdjtghtQjCBUZwB/JO+NRgH1vSTr8dqBJRq7Qh4nug==',
+          },
+        ],
+      }),
+  )
+  .output(
+    z
+      .object({
+        decrypted: z.string().describe('解密后的任务信息 JSON 字符串'),
+      })
+      .meta({
+        examples: [
+          {
+            decrypted:
+              '{"taskId":"TASK-20260115-4875","enterpriseId":"1173040813421105152","orgName":"超艺科技有限公司","inspectionId":"702286470691215417","inspectionPerson":"警务通","issuedAt":1734571234567}',
+          },
+        ],
+      }),
+  )
+
+export const encryptSummary = oc
+  .route({
+    method: 'POST',
+    path: '/crypto/encrypt-summary',
+    operationId: 'encryptSummary',
+    summary: '加密摘要信息',
+    description:
+      '使用本机 licence 与 fingerprint 通过 HKDF-SHA256 派生密钥，以 AES-256-GCM 加密检查摘要明文并返回 Base64 密文，供工具箱生成摘要信息二维码。参见《工具箱端 - 摘要信息二维码生成指南》。',
+    tags: ['Crypto'],
+  })
+  .input(
+    z
+      .object({
+        salt: z.string().min(1).describe('HKDF salt（即 taskId，从任务二维码中获取）'),
+        plaintext: z.string().min(1).describe('待加密的摘要信息 JSON 明文'),
+      })
+      .meta({
+        examples: [
+          {
+            salt: 'TASK-20260115-4875',
+            plaintext:
+              '{"enterpriseId":"1173040813421105152","inspectionId":"702286470691215417","summary":"检查摘要信息：发现3个高危漏洞，5个中危漏洞","timestamp":1734571234567}',
+          },
+        ],
+      }),
+  )
+  .output(
+    z
+      .object({
+        encrypted: z.string().describe('Base64 密文（用于摘要信息二维码）'),
+      })
+      .meta({
+        examples: [
+          {
+            encrypted: 'uWUcAmp6UQd0w3G3crdsd4613QCxGLoEgslgXJ4G2hQhpQdjtghtQjCBUZwB/JO+NRgH1vSTr8dqBJRq7Qh4nug==',
+          },
+        ],
+      }),
+  )
+
+export const signAndPackReport = oc
+  .route({
+    method: 'POST',
+    path: '/crypto/sign-and-pack-report',
+    operationId: 'signAndPackReport',
+    summary: '签名并打包检查报告',
+    description:
+      '上传包含 summary.json 的原始报告 ZIP，UX 自动从 ZIP 中提取 summary.json，使用本地存储的 licence/fingerprint 计算设备签名（HKDF + HMAC-SHA256），并使用本地 OpenPGP 私钥生成分离式签名。返回包含 summary.json（含 deviceSignature）、META-INF/manifest.json、META-INF/signature.asc 的签名报告 ZIP。参见《工具箱端 - 报告加密与签名生成指南》。',
+    tags: ['Crypto', 'Report'],
+  })
+  .input(
+    z.object({
+      rawZip: z
+        .file()
+        .mime(['application/zip', 'application/x-zip-compressed'])
+        .describe(
+          '原始报告 ZIP 文件（必须包含 summary.json，以及 assets.json、vulnerabilities.json、weakPasswords.json、漏洞评估报告.html 等报告文件）',
+        ),
+      outputFileName: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('返回 ZIP 文件名（可选，默认 signed-report.zip）')
+        .meta({ examples: ['signed-report.zip'] }),
+    }),
+  )
+  .output(
+    z
+      .file()
+      .describe('签名后报告 ZIP 文件（二进制响应，包含 summary.json、META-INF/manifest.json、META-INF/signature.asc）'),
+  )
@@ -0,0 +1,9 @@
+import * as config from './config.contract'
+import * as crypto from './crypto.contract'
+
+export const contract = {
+  config,
+  crypto,
+}
+
+export type Contract = typeof contract
@@ -1,19 +1,13 @@
 import { ORPCError, ValidationError } from '@orpc/server'
 import { z } from 'zod'
-import { getLogger } from '@/server/logger'
-
-const logger = getLogger(['api'])

 export const logError = (error: unknown) => {
-  logger.error('Unhandled error in ORPC handler', { error })
+  console.error(error)
 }

 export const handleValidationError = (error: unknown) => {
-  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.
+  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)
    const zodError = new z.ZodError(error.cause.issues as z.core.$ZodIssue[])

    throw new ORPCError('INPUT_VALIDATION_FAILED', {
@@ -24,7 +18,7 @@ export const handleValidationError = (error: unknown) => {
    })
  }

-  if (error.code === 'INTERNAL_SERVER_ERROR') {
+  if (error instanceof ORPCError && error.code === 'INTERNAL_SERVER_ERROR' && error.cause instanceof ValidationError) {
    throw new ORPCError('OUTPUT_VALIDATION_FAILED', {
      cause: error.cause,
    })
@@ -0,0 +1,11 @@
+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(),
+    },
+  })
+})
@@ -0,0 +1 @@
+export * from './db.middleware'
@@ -0,0 +1,32 @@
+import { validatePgpPrivateKey } from '@furtherverse/crypto'
+import { ORPCError } from '@orpc/server'
+import { ensureUxConfig, setUxLicence, setUxPgpPrivateKey } from '@/server/ux-config'
+import { db } from '../middlewares'
+import { os } from '../server'
+
+const toConfigOutput = (config: { licence: string | null; fingerprint: string; pgpPrivateKey: string | null }) => ({
+  licence: config.licence,
+  fingerprint: config.fingerprint,
+  hasPgpPrivateKey: config.pgpPrivateKey != null,
+})
+
+export const get = os.config.get.use(db).handler(async ({ context }) => {
+  const config = await ensureUxConfig(context.db)
+  return toConfigOutput(config)
+})
+
+export const setLicence = os.config.setLicence.use(db).handler(async ({ context, input }) => {
+  const config = await setUxLicence(context.db, input.licence)
+  return toConfigOutput(config)
+})
+
+export const setPgpPrivateKey = os.config.setPgpPrivateKey.use(db).handler(async ({ context, input }) => {
+  await validatePgpPrivateKey(input.pgpPrivateKey).catch((error) => {
+    throw new ORPCError('BAD_REQUEST', {
+      message: `Invalid PGP private key: ${error instanceof Error ? error.message : 'unable to parse'}`,
+    })
+  })
+
+  const config = await setUxPgpPrivateKey(context.db, input.pgpPrivateKey)
+  return toConfigOutput(config)
+})
@@ -0,0 +1,183 @@
+import {
+  aesGcmDecrypt,
+  aesGcmEncrypt,
+  hkdfSha256,
+  hmacSha256Base64,
+  pgpSignDetached,
+  rsaOaepEncrypt,
+  sha256,
+  sha256Hex,
+} from '@furtherverse/crypto'
+import { ORPCError } from '@orpc/server'
+import JSZip from 'jszip'
+import { z } from 'zod'
+import { extractSafeZipFiles, ZipValidationError } from '@/server/safe-zip'
+import { getUxConfig } from '@/server/ux-config'
+import { db } from '../middlewares'
+import { os } from '../server'
+
+const summaryPayloadSchema = z
+  .object({
+    taskId: z.string().min(1, 'summary.json must contain a non-empty taskId'),
+    checkId: z.union([z.string(), z.number()]).optional(),
+    inspectionId: z.union([z.string(), z.number()]).optional(),
+    orgId: z.union([z.string(), z.number()]).optional(),
+    enterpriseId: z.union([z.string(), z.number()]).optional(),
+    summary: z.string().optional(),
+  })
+  .loose()
+
+const requireIdentity = async (dbInstance: Parameters<typeof getUxConfig>[0]) => {
+  const config = await getUxConfig(dbInstance)
+  if (!config || !config.licence) {
+    throw new ORPCError('PRECONDITION_FAILED', {
+      message: 'Local identity is not initialized. Call config.get and then config.setLicence first.',
+    })
+  }
+  return config as typeof config & { licence: string }
+}
+
+export const encryptDeviceInfo = os.crypto.encryptDeviceInfo.use(db).handler(async ({ context, input }) => {
+  const config = await requireIdentity(context.db)
+
+  const deviceInfoJson = JSON.stringify({
+    licence: config.licence,
+    fingerprint: config.fingerprint,
+  })
+
+  const encrypted = rsaOaepEncrypt(deviceInfoJson, input.platformPublicKey)
+  return { encrypted }
+})
+
+export const decryptTask = os.crypto.decryptTask.use(db).handler(async ({ context, input }) => {
+  const config = await requireIdentity(context.db)
+
+  const key = sha256(config.licence + config.fingerprint)
+  const decrypted = aesGcmDecrypt(input.encryptedData, key)
+  return { decrypted }
+})
+
+export const encryptSummary = os.crypto.encryptSummary.use(db).handler(async ({ context, input }) => {
+  const config = await requireIdentity(context.db)
+
+  const ikm = config.licence + config.fingerprint
+  const aesKey = hkdfSha256(ikm, input.salt, 'inspection_report_encryption')
+  const encrypted = aesGcmEncrypt(input.plaintext, aesKey)
+  return { encrypted }
+})
+
+export const signAndPackReport = os.crypto.signAndPackReport.use(db).handler(async ({ context, input }) => {
+  const config = await requireIdentity(context.db)
+
+  if (!config.pgpPrivateKey) {
+    throw new ORPCError('PRECONDITION_FAILED', {
+      message: 'PGP private key is not configured. Call config.setPgpPrivateKey first.',
+    })
+  }
+
+  const rawZipBytes = Buffer.from(await input.rawZip.arrayBuffer())
+
+  const zipFiles = await extractSafeZipFiles(rawZipBytes).catch((error) => {
+    if (error instanceof ZipValidationError) {
+      throw new ORPCError('BAD_REQUEST', { message: error.message })
+    }
+    throw error
+  })
+
+  // Extract and validate summary.json from the ZIP
+  const summaryFile = zipFiles.find((f) => f.name === 'summary.json')
+  if (!summaryFile) {
+    throw new ORPCError('BAD_REQUEST', {
+      message: 'rawZip must contain a summary.json file',
+    })
+  }
+
+  let rawJson: unknown
+  try {
+    rawJson = JSON.parse(Buffer.from(summaryFile.bytes).toString('utf-8'))
+  } catch {
+    throw new ORPCError('BAD_REQUEST', {
+      message: 'summary.json in the ZIP is not valid JSON',
+    })
+  }
+
+  const parsed = summaryPayloadSchema.safeParse(rawJson)
+  if (!parsed.success) {
+    throw new ORPCError('BAD_REQUEST', {
+      message: `Invalid summary.json: ${z.prettifyError(parsed.error)}`,
+    })
+  }
+
+  const summaryPayload = parsed.data
+  const checkId = String(summaryPayload.checkId ?? summaryPayload.inspectionId ?? '')
+  const orgId = summaryPayload.orgId ?? summaryPayload.enterpriseId ?? ''
+
+  // Helper: find file in ZIP and compute its SHA256 hash
+  const requireFileHash = (name: string): string => {
+    const file = zipFiles.find((f) => f.name === name)
+    if (!file) {
+      throw new ORPCError('BAD_REQUEST', { message: `rawZip must contain ${name}` })
+    }
+    return sha256Hex(Buffer.from(file.bytes))
+  }
+
+  // Compute SHA256 of each content file (fixed order, matching Kotlin reference)
+  const assetsSha256 = requireFileHash('assets.json')
+  const vulnerabilitiesSha256 = requireFileHash('vulnerabilities.json')
+  const weakPasswordsSha256 = requireFileHash('weakPasswords.json')
+  const reportHtmlSha256 = requireFileHash('漏洞评估报告.html')
+
+  // Compute device signature
+  // signPayload = taskId + inspectionId + assetsSha256 + vulnerabilitiesSha256 + weakPasswordsSha256 + reportHtmlSha256
+  // (plain concatenation, no separators, fixed order — matching Kotlin reference)
+  const ikm = config.licence + config.fingerprint
+  const signingKey = hkdfSha256(ikm, 'AUTH_V3_SALT', 'device_report_signature')
+
+  const signPayload = `${summaryPayload.taskId}${checkId}${assetsSha256}${vulnerabilitiesSha256}${weakPasswordsSha256}${reportHtmlSha256}`
+  const deviceSignature = hmacSha256Base64(signingKey, signPayload)
+
+  // Build final summary.json with flat structure (matching Kotlin reference)
+  const finalSummary = {
+    orgId,
+    checkId,
+    taskId: summaryPayload.taskId,
+    licence: config.licence,
+    fingerprint: config.fingerprint,
+    deviceSignature,
+    summary: summaryPayload.summary ?? '',
+  }
+  const summaryBytes = Buffer.from(JSON.stringify(finalSummary), 'utf-8')
+
+  // Build manifest.json (fixed file list, matching Kotlin reference)
+  const manifestFiles: Record<string, string> = {
+    'summary.json': sha256Hex(summaryBytes),
+    'assets.json': assetsSha256,
+    'vulnerabilities.json': vulnerabilitiesSha256,
+    'weakPasswords.json': weakPasswordsSha256,
+    '漏洞评估报告.html': reportHtmlSha256,
+  }
+
+  const manifestBytes = Buffer.from(JSON.stringify({ files: manifestFiles }, null, 2), 'utf-8')
+  const signatureAsc = await pgpSignDetached(manifestBytes, config.pgpPrivateKey)
+
+  // Pack signed ZIP
+  const signedZip = new JSZip()
+  signedZip.file('summary.json', summaryBytes)
+  for (const item of zipFiles) {
+    if (item.name !== 'summary.json') {
+      signedZip.file(item.name, item.bytes)
+    }
+  }
+  signedZip.file('META-INF/manifest.json', manifestBytes)
+  signedZip.file('META-INF/signature.asc', signatureAsc)
+
+  const signedZipBytes = await signedZip.generateAsync({
+    type: 'uint8array',
+    compression: 'DEFLATE',
+    compressionOptions: { level: 9 },
+  })
+
+  return new File([Buffer.from(signedZipBytes)], input.outputFileName ?? 'signed-report.zip', {
+    type: 'application/zip',
+  })
+})
@@ -0,0 +1,8 @@
+import { os } from '../server'
+import * as config from './config.router'
+import * as crypto from './crypto.router'
+
+export const router = os.router({
+  config,
+  crypto,
+})
@@ -0,0 +1,6 @@
+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>
@@ -0,0 +1,36 @@
+import { integer, text } from 'drizzle-orm/sqlite-core'
+import { v7 as uuidv7 } from 'uuid'
+
+export const pk = (name = 'id') =>
+  text(name)
+    .primaryKey()
+    .$defaultFn(() => uuidv7())
+
+export const createdAt = (name = 'created_at') =>
+  integer(name, { mode: 'timestamp_ms' })
+    .notNull()
+    .$defaultFn(() => new Date())
+
+export const updatedAt = (name = 'updated_at') =>
+  integer(name, { mode: 'timestamp_ms' })
+    .notNull()
+    .$defaultFn(() => new Date())
+    .$onUpdateFn(() => new Date())
+
+export const generatedFields = {
+  id: pk('id'),
+  createdAt: createdAt('created_at'),
+  updatedAt: updatedAt('updated_at'),
+}
+
+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)
@@ -0,0 +1,26 @@
+import { Database } from 'bun:sqlite'
+import { drizzle } from 'drizzle-orm/bun-sqlite'
+import { env } from '@/env'
+import { relations } from '@/server/db/relations'
+
+export const createDB = () => {
+  const sqlite = new Database(env.DATABASE_PATH)
+  sqlite.exec('PRAGMA journal_mode = WAL')
+  sqlite.exec('PRAGMA foreign_keys = ON')
+  return drizzle({ client: sqlite, 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
+  }
+})()
@@ -0,0 +1,4 @@
+import { defineRelations } from 'drizzle-orm'
+import * as schema from './schema'
+
+export const relations = defineRelations(schema, () => ({}))
@@ -0,0 +1 @@
+export * from './ux-config'
@@ -0,0 +1,10 @@
+import { sqliteTable, text } from 'drizzle-orm/sqlite-core'
+import { generatedFields } from '../fields'
+
+export const uxConfigTable = sqliteTable('ux_config', {
+  ...generatedFields,
+  singletonKey: text('singleton_key').notNull().unique().default('default'),
+  licence: text('licence'),
+  fingerprint: text('fingerprint').notNull(),
+  pgpPrivateKey: text('pgp_private_key'),
+})
@@ -0,0 +1,10 @@
+import { sha256Hex } from '@furtherverse/crypto'
+import { system } from 'systeminformation'
+
+export const computeDeviceFingerprint = async (): Promise<string> => {
+  const { uuid, serial, model, manufacturer } = await system()
+  const source = [uuid, serial, model, manufacturer].join('|')
+  const hash = sha256Hex(source)
+
+  return hash
+}
@@ -0,0 +1,96 @@
+import type { JSZipObject } from 'jszip'
+import JSZip from 'jszip'
+
+export class ZipValidationError extends Error {
+  override name = 'ZipValidationError'
+}
+
+export interface ZipFileItem {
+  name: string
+  bytes: Uint8Array
+}
+
+export interface SafeZipOptions {
+  maxRawBytes?: number
+  maxEntries?: number
+  maxSingleFileBytes?: number
+  maxTotalUncompressedBytes?: number
+}
+
+const DEFAULTS = {
+  maxRawBytes: 50 * 1024 * 1024,
+  maxEntries: 64,
+  maxSingleFileBytes: 20 * 1024 * 1024,
+  maxTotalUncompressedBytes: 60 * 1024 * 1024,
+} satisfies Required<SafeZipOptions>
+
+const normalizePath = (name: string): string => name.replaceAll('\\', '/')
+
+const isUnsafePath = (name: string): boolean => {
+  const normalized = normalizePath(name)
+  const segments = normalized.split('/')
+
+  return (
+    normalized.startsWith('/') ||
+    normalized.includes('\0') ||
+    segments.some((segment) => segment === '..' || segment.trim().length === 0)
+  )
+}
+
+export const extractSafeZipFiles = async (
+  rawBytes: Uint8Array | Buffer,
+  options?: SafeZipOptions,
+): Promise<ZipFileItem[]> => {
+  const opts = { ...DEFAULTS, ...options }
+
+  if (rawBytes.byteLength === 0 || rawBytes.byteLength > opts.maxRawBytes) {
+    throw new ZipValidationError('ZIP is empty or exceeds max size limit')
+  }
+
+  const zip = await JSZip.loadAsync(rawBytes, { checkCRC32: true }).catch(() => {
+    throw new ZipValidationError('Not a valid ZIP file')
+  })
+
+  const entries = Object.values(zip.files) as JSZipObject[]
+  if (entries.length > opts.maxEntries) {
+    throw new ZipValidationError(`ZIP contains too many entries: ${entries.length}`)
+  }
+
+  let totalUncompressedBytes = 0
+  const files: ZipFileItem[] = []
+  const seen = new Set<string>()
+
+  for (const entry of entries) {
+    if (entry.dir) {
+      continue
+    }
+
+    if (isUnsafePath(entry.name)) {
+      throw new ZipValidationError(`ZIP contains unsafe entry path: ${entry.name}`)
+    }
+
+    const normalizedName = normalizePath(entry.name)
+    if (seen.has(normalizedName)) {
+      throw new ZipValidationError(`ZIP contains duplicate entry: ${normalizedName}`)
+    }
+    seen.add(normalizedName)
+
+    const content = await entry.async('uint8array')
+    if (content.byteLength > opts.maxSingleFileBytes) {
+      throw new ZipValidationError(`ZIP entry too large: ${normalizedName}`)
+    }
+
+    totalUncompressedBytes += content.byteLength
+    if (totalUncompressedBytes > opts.maxTotalUncompressedBytes) {
+      throw new ZipValidationError('ZIP total uncompressed content exceeds max size limit')
+    }
+
+    files.push({ name: normalizedName, bytes: content })
+  }
+
+  if (files.length === 0) {
+    throw new ZipValidationError('ZIP has no file entries')
+  }
+
+  return files
+}
@@ -0,0 +1,56 @@
+import { eq } from 'drizzle-orm'
+import type { DB } from '@/server/db'
+import { uxConfigTable } from '@/server/db/schema'
+import { computeDeviceFingerprint } from './device-fingerprint'
+
+const UX_CONFIG_KEY = 'default'
+
+export const getUxConfig = async (db: DB) => {
+  return await db.query.uxConfigTable.findFirst({
+    where: { singletonKey: UX_CONFIG_KEY },
+  })
+}
+
+export const ensureUxConfig = async (db: DB) => {
+  const fingerprint = await computeDeviceFingerprint()
+  const existing = await getUxConfig(db)
+
+  if (existing) {
+    if (existing.fingerprint !== fingerprint) {
+      const rows = await db
+        .update(uxConfigTable)
+        .set({ fingerprint })
+        .where(eq(uxConfigTable.id, existing.id))
+        .returning()
+      return rows[0] as (typeof rows)[number]
+    }
+    return existing
+  }
+
+  const rows = await db
+    .insert(uxConfigTable)
+    .values({
+      singletonKey: UX_CONFIG_KEY,
+      fingerprint,
+      licence: null,
+    })
+    .returning()
+
+  return rows[0] as (typeof rows)[number]
+}
+
+export const setUxLicence = async (db: DB, licence: string) => {
+  const config = await ensureUxConfig(db)
+
+  const rows = await db.update(uxConfigTable).set({ licence }).where(eq(uxConfigTable.id, config.id)).returning()
+
+  return rows[0] as (typeof rows)[number]
+}
+
+export const setUxPgpPrivateKey = async (db: DB, pgpPrivateKey: string) => {
+  const config = await ensureUxConfig(db)
+
+  const rows = await db.update(uxConfigTable).set({ pgpPrivateKey }).where(eq(uxConfigTable.id, config.id)).returning()
+
+  return rows[0] as (typeof rows)[number]
+}
@@ -0,0 +1 @@
+@import "tailwindcss";
@@ -0,0 +1,9 @@
+{
+  "extends": "@furtherverse/tsconfig/react.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
@@ -0,0 +1,47 @@
+{
+  "$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/**"]
+    }
+  }
+}
@@ -4,21 +4,27 @@ import { tanstackStart } from '@tanstack/react-start/plugin/vite'
 import react from '@vitejs/plugin-react'
 import { nitro } from 'nitro/vite'
 import { defineConfig } from 'vite'
+import tsconfigPaths from 'vite-tsconfig-paths'

 export default defineConfig({
  clearScreen: false,
  plugins: [
    tanstackDevtools(),
    tailwindcss(),
+    tsconfigPaths(),
    tanstackStart(),
-    react(),
+    react({
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
    nitro({
      preset: 'bun',
      serveStatic: 'inline',
-      plugins: ['./src/server/plugins/shutdown.ts'],
    }),
  ],
-  resolve: {
-    tsconfigPaths: true,
+  server: {
+    port: 3000,
+    strictPort: true,
  },
 })
@@ -6,8 +6,7 @@
    "useIgnoreFile": true
  },
  "files": {
-    "ignoreUnknown": false,
-    "includes": ["**", "!**/routeTree.gen.ts", "!**/migrations.gen.ts", "!volumes"]
+    "ignoreUnknown": false
  },
  "formatter": {
    "enabled": true,
@@ -17,10 +16,6 @@
  },
  "linter": {
    "enabled": true,
-    "domains": {
-      "react": "recommended",
-      "types": "all"
-    },
    "rules": {
      "recommended": true,
      "complexity": {
@@ -28,14 +23,6 @@
      },
      "correctness": {
        "noReactPropAssignments": "error"
-      },
-      "style": {
-        "noNonNullAssertion": "error"
-      },
-      "suspicious": {
-        "noExplicitAny": "error",
-        "noImportCycles": "error",
-        "noTsIgnore": "error"
      }
    }
  },
@@ -46,11 +33,6 @@
      "arrowParentheses": "always"
    }
  },
-  "css": {
-    "parser": {
-      "tailwindDirectives": true
-    }
-  },
  "assist": {
    "enabled": true,
    "actions": {
@@ -0,0 +1,2 @@
+[install]
+publicHoistPattern = ["@types/*", "bun-types", "nitro*"]
@@ -1,47 +0,0 @@
-services:
-  db:
-    image: mysql:8.4
-    ports:
-      - "3306:3306"
-    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:
-    build:
-      context: .
-      target: source
-    restart: "no"
-    depends_on:
-      db:
-        condition: service_healthy
-    environment:
-      - DATABASE_URL=mysql://battery:battery@db:3306/battery_soh
-      - SOH_PREDICTION_API_BASE_URL=http://host.docker.internal:8000
-    command: [ "bun", "run", "seed" ]
-
-  app:
-    build: .
-    depends_on:
-      seed:
-        condition: service_completed_successfully
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
-    ports:
-      - "3000:3000"
-    environment:
-      - DATABASE_URL=mysql://battery:battery@db:3306/battery_soh
-      - SOH_PREDICTION_API_BASE_URL=http://host.docker.internal:8000
-      - ENABLE_API_DOCS=true
-
-volumes:
-  mysql_data:
@@ -0,0 +1,432 @@
+package top.tangyh.lamp.filing.controller.compress
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import io.swagger.annotations.Api
+import io.swagger.annotations.ApiOperation
+import io.swagger.annotations.ApiParam
+import org.springframework.validation.annotation.Validated
+import org.springframework.web.bind.annotation.*
+import top.tangyh.basic.annotation.log.WebLog
+import top.tangyh.basic.base.R
+import top.tangyh.lamp.filing.dto.management.UploadInspectionFileV2Request
+import top.tangyh.lamp.filing.utils.AesGcmUtil
+import top.tangyh.lamp.filing.utils.HkdfUtil
+import top.tangyh.lamp.filing.utils.PgpSignatureUtil
+import java.util.*
+
+/**
+ * 加密测试工具类
+ * 
+ * 用于生成加密后的 encrypted 数据，测试 uploadInspectionFileV2Encrypted 接口
+ * 
+ * 使用说明：
+ * 1. 调用 /compression/test/generateEncrypted 接口
+ * 2. 传入 licence、fingerprint、taskId 和明文数据
+ * 3. 获取加密后的 Base64 字符串
+ * 4. 使用返回的 encrypted 数据测试 uploadInspectionFileV2Encrypted 接口
+ */
+@Validated
+@RestController
+@RequestMapping("/compression/test")
+@Api(value = "EncryptionTest", tags = ["加密测试工具"])
+class EncryptionTestController {
+
+    private val objectMapper = ObjectMapper()
+    
+    companion object {
+        private const val DEFAULT_PGP_PRIVATE_KEY = """-----BEGIN PGP PRIVATE KEY BLOCK-----
+
+lFgEaSZqXBYJKwYBBAHaRw8BAQdARzZ5JXreuTeTgMFwYcw0Ju7aCWmXuUMmQyff
+5vmN8RQAAP4nli0R/MTNtgx9+g5ZPyAj8XSAnjHaW9u2UJQxYhMIYw8XtBZpdHRj
+PGl0dGNAaXR0Yy5zaC5jbj6IkwQTFgoAOxYhBG8IkI1kmkNpEu8iuqWu91t6SEzN
+BQJpJmpcAhsDBQsJCAcCAiICBhUKCQgLAgQWAgMBAh4HAheAAAoJEKWu91t6SEzN
+dSQBAPM5llVG0X6SBa4YM90Iqyb2jWvlNjstoF8jjPVny1CiAP4hIOUvb686oSA0
+OrS3AuICi7X/r+JnSo1Z7pngUA3VC5xdBGkmalwSCisGAQQBl1UBBQEBB0BouQlG
+hIL0bq7EbaB55s+ygLVFOfhjFA8E4fwFBFJGVAMBCAcAAP98ZXRGgzld1XUa5ZGx
+cTE+1qGZY4E4BVIeqkVxdg5tqA64iHgEGBYKACAWIQRvCJCNZJpDaRLvIrqlrvdb
+ekhMzQUCaSZqXAIbDAAKCRClrvdbekhMzcaSAQDB/4pvDuc7SploQg1fBYobFm5P
+vxguByr8I+PrYWKKOQEAnaeXT4ipi1nICXFiigztsIl2xTth3D77XG6pZUU/Zw8=
+=/k1H
+-----END PGP PRIVATE KEY BLOCK-----"""
+        
+        private const val DEFAULT_PGP_PASSPHRASE = ""
+    }
+
+    /**
+     * 生成加密数据请求 DTO
+     */
+    data class GenerateEncryptedRequest(
+        @ApiParam(value = "授权码", required = true)
+        val licence: String,
+        
+        @ApiParam(value = "硬件指纹", required = true)
+        val fingerprint: String,
+        
+        @ApiParam(value = "任务ID", required = true)
+        val taskId: String,
+        
+        @ApiParam(value = "企业ID", required = true)
+        val enterpriseId: Long,
+        
+        @ApiParam(value = "检查ID", required = true)
+        val inspectionId: Long,
+        
+        @ApiParam(value = "摘要信息", required = true)
+        val summary: String
+    )
+
+    /**
+     * 生成加密数据响应 DTO
+     */
+    data class GenerateEncryptedResponse(
+        val encrypted: String,
+        val requestBody: UploadInspectionFileV2Request,
+        val plaintext: String,
+        val keyDerivationInfo: KeyDerivationInfo
+    )
+
+    /**
+     * 密钥派生信息
+     */
+    data class KeyDerivationInfo(
+        val ikm: String,
+        val salt: String,
+        val info: String,
+        val keyLength: Int,
+        val keyHex: String
+    )
+
+    /**
+     * 生成加密数据
+     * 
+     * 模拟工具箱端的加密逻辑：
+     * 1. 使用 HKDF-SHA256 派生 AES 密钥
+     *    - ikm = licence + fingerprint
+     *    - salt = taskId
+     *    - info = "inspection_report_encryption"
+     *    - length = 32 bytes
+     * 
+     * 2. 使用 AES-256-GCM 加密数据
+     *    - 格式：IV (12字节) + Ciphertext + Tag (16字节)
+     *    - Base64 编码返回
+     * 
+     * @param request 生成加密数据请求
+     * @return 加密后的数据和完整的请求体
+     */
+    @ApiOperation(value = "生成加密数据", notes = "生成加密后的 encrypted 数据，用于测试 uploadInspectionFileV2Encrypted 接口")
+    @PostMapping("/generateEncrypted")
+    @WebLog(value = "'生成加密数据:'", request = false)
+    fun generateEncrypted(
+        @RequestBody request: GenerateEncryptedRequest
+    ): R<GenerateEncryptedResponse> {
+        return try {
+            // 1. 组装明文数据（JSON格式）
+            val timestamp = System.currentTimeMillis()
+            val plaintextMap = mapOf(
+                "enterpriseId" to request.enterpriseId.toString(),
+                "inspectionId" to request.inspectionId.toString(),
+                "summary" to request.summary,
+                "timestamp" to timestamp
+            )
+            val plaintext = objectMapper.writeValueAsString(plaintextMap)
+
+            // 2. 使用 HKDF-SHA256 派生 AES 密钥
+            // ikm = licence + fingerprint
+            // salt = taskId（工具箱从二维码获取，平台从请求获取）
+            // info = "inspection_report_encryption"（固定值）
+            // length = 32 bytes
+            val ikm = "${request.licence}${request.fingerprint}"
+            val salt = request.taskId.toString()
+            val info = "inspection_report_encryption"
+            val keyLength = 32
+
+            val aesKey = HkdfUtil.deriveKey(ikm, salt, info, keyLength)
+
+            // 3. 使用 AES-256-GCM 加密数据
+            val encrypted = AesGcmUtil.encrypt(plaintext, aesKey)
+
+            // 4. 组装完整的请求体（appid 需要前端自己赋值）
+            val requestBody = UploadInspectionFileV2Request().apply {
+                this.appid = "test-appid" // 测试用的 appid，实际使用时前端会赋值
+                this.taskId = request.taskId
+                this.encrypted = encrypted
+            }
+
+            // 5. 返回加密数据和密钥派生信息
+            val response = GenerateEncryptedResponse(
+                encrypted = encrypted,
+                requestBody = requestBody,
+                plaintext = plaintext,
+                keyDerivationInfo = KeyDerivationInfo(
+                    ikm = ikm,
+                    salt = salt,
+                    info = info,
+                    keyLength = keyLength,
+                    keyHex = aesKey.joinToString("") { "%02x".format(it) }
+                )
+            )
+
+            R.success(response, "加密数据生成成功")
+        } catch (e: Exception) {
+            R.fail("生成加密数据失败: ${e.message}")
+        }
+    }
+
+    /**
+     * 快速生成测试数据（使用默认值）
+     * 
+     * @return 加密后的数据和完整的请求体
+     */
+    @ApiOperation(value = "快速生成测试数据", notes = "使用默认值快速生成加密数据，用于快速测试")
+    @GetMapping("/generateTestData")
+    @WebLog(value = "'快速生成测试数据:'", request = false)
+    fun generateTestData(): R<GenerateEncryptedResponse> {
+        return try {
+            // 使用默认测试数据
+            val request = GenerateEncryptedRequest(
+                licence = "TEST-LICENCE-001",
+                fingerprint = "TEST-FINGERPRINT-001",
+                taskId = "TASK-20260115-4875",
+                enterpriseId = 1173040813421105152L,
+                inspectionId = 702286470691215417L,
+                summary = "测试摘要信息"
+            )
+
+            generateEncrypted(request).data?.let {
+                R.success(it, "测试数据生成成功")
+            } ?: R.fail("生成测试数据失败")
+        } catch (e: Exception) {
+            R.fail("生成测试数据失败: ${e.message}")
+        }
+    }
+
+    /**
+     * 验证加密数据（解密测试）
+     * 
+     * 用于验证生成的加密数据是否能正确解密
+     * 
+     * @param encrypted 加密后的 Base64 字符串
+     * @param licence 授权码
+     * @param fingerprint 硬件指纹
+     * @param taskId 任务ID
+     * @return 解密后的明文数据
+     */
+    @ApiOperation(value = "验证加密数据", notes = "解密加密数据，验证加密是否正确")
+    @PostMapping("/verifyEncrypted")
+    @WebLog(value = "'验证加密数据:'", request = false)
+    fun verifyEncrypted(
+        @ApiParam(value = "加密后的 Base64 字符串", required = true)
+        @RequestParam encrypted: String,
+        
+        @ApiParam(value = "授权码", required = true)
+        @RequestParam licence: String,
+        
+        @ApiParam(value = "硬件指纹", required = true)
+        @RequestParam fingerprint: String,
+        
+        @ApiParam(value = "任务ID", required = true)
+        @RequestParam taskId: String
+    ): R<Map<String, Any>> {
+        return try {
+            // 1. 使用相同的密钥派生规则派生密钥
+            val ikm = "$licence$fingerprint"
+            val salt = taskId.toString()
+            val info = "inspection_report_encryption"
+            val aesKey = HkdfUtil.deriveKey(ikm, salt, info, 32)
+
+            // 2. 解密数据
+            val decrypted = AesGcmUtil.decrypt(encrypted, aesKey)
+
+            // 3. 解析 JSON
+            @Suppress("UNCHECKED_CAST")
+            val dataMap = objectMapper.readValue(decrypted, Map::class.java) as Map<String, Any>
+
+            R.success(dataMap, "解密成功")
+        } catch (e: Exception) {
+            R.fail("解密失败: ${e.message}")
+        }
+    }
+
+    /**
+     * 生成加密报告 ZIP 文件请求 DTO
+     */
+    data class GenerateEncryptedZipRequest(
+        @ApiParam(value = "授权码", required = true)
+        val licence: String,
+        
+        @ApiParam(value = "硬件指纹", required = true)
+        val fingerprint: String,
+        
+        @ApiParam(value = "任务ID", required = true)
+        val taskId: String,
+        
+        @ApiParam(value = "企业ID", required = true)
+        val enterpriseId: Long,
+        
+        @ApiParam(value = "检查ID", required = true)
+        val inspectionId: Long,
+        
+        @ApiParam(value = "摘要信息", required = true)
+        val summary: String,
+        
+        @ApiParam(value = "资产信息 JSON", required = true)
+        val assetsJson: String,
+        
+        @ApiParam(value = "漏洞信息 JSON", required = true)
+        val vulnerabilitiesJson: String,
+        
+        @ApiParam(value = "弱密码信息 JSON", required = true)
+        val weakPasswordsJson: String,
+        
+        @ApiParam(value = "漏洞评估报告 HTML", required = true)
+        val reportHtml: String,
+        
+        @ApiParam(value = "PGP 私钥（可选，不提供则跳过 PGP 签名）", required = false)
+        val pgpPrivateKey: String? = null,
+        
+        @ApiParam(value = "PGP 私钥密码（可选）", required = false)
+        val pgpPassphrase: String? = null
+    )
+
+    /**
+     * 生成加密报告 ZIP 文件
+     * 
+     * 按照文档《工具箱端-报告加密与签名生成指南.md》生成加密报告 ZIP 文件
+     * 
+     * @param request 生成请求
+     * @return ZIP 文件（二进制流）
+     */
+    @ApiOperation(value = "生成加密报告 ZIP", notes = "生成带设备签名的加密报告 ZIP 文件，可被 uploadInspectionFileV2 接口解密")
+    @PostMapping("/generateEncryptedZip")
+    @WebLog(value = "'生成加密报告 ZIP:'", request = false)
+    fun generateEncryptedZip(
+        @RequestBody request: GenerateEncryptedZipRequest,
+        response: javax.servlet.http.HttpServletResponse
+    ) {
+        try {
+            // 1. 准备文件内容
+            val assetsContent = request.assetsJson.toByteArray(Charsets.UTF_8)
+            val vulnerabilitiesContent = request.vulnerabilitiesJson.toByteArray(Charsets.UTF_8)
+            val weakPasswordsContent = request.weakPasswordsJson.toByteArray(Charsets.UTF_8)
+            val reportHtmlContent = request.reportHtml.toByteArray(Charsets.UTF_8)
+
+            // 2. 生成设备签名
+            // 2.1 密钥派生
+            val ikm = "${request.licence}${request.fingerprint}"
+            val salt = "AUTH_V3_SALT"
+            val info = "device_report_signature"
+            val derivedKey = HkdfUtil.deriveKey(ikm, salt, info, 32)
+
+            // 2.2 计算文件 SHA256
+            fun sha256Hex(content: ByteArray): String {
+                val digest = java.security.MessageDigest.getInstance("SHA-256")
+                return digest.digest(content).joinToString("") { "%02x".format(it) }
+            }
+
+            val assetsSha256 = sha256Hex(assetsContent)
+            val vulnerabilitiesSha256 = sha256Hex(vulnerabilitiesContent)
+            val weakPasswordsSha256 = sha256Hex(weakPasswordsContent)
+            val reportHtmlSha256 = sha256Hex(reportHtmlContent)
+
+            // 2.3 组装签名数据（严格顺序）
+            val signPayload = buildString {
+                append(request.taskId)
+                append(request.inspectionId)
+                append(assetsSha256)
+                append(vulnerabilitiesSha256)
+                append(weakPasswordsSha256)
+                append(reportHtmlSha256)
+            }
+
+            // 2.4 计算 HMAC-SHA256
+            val mac = javax.crypto.Mac.getInstance("HmacSHA256")
+            val secretKey = javax.crypto.spec.SecretKeySpec(derivedKey, "HmacSHA256")
+            mac.init(secretKey)
+            val signatureBytes = mac.doFinal(signPayload.toByteArray(Charsets.UTF_8))
+            val deviceSignature = Base64.getEncoder().encodeToString(signatureBytes)
+
+            // 2.5 生成 summary.json
+            val summaryMap = mapOf(
+                "orgId" to request.enterpriseId,
+                "checkId" to request.inspectionId,
+                "taskId" to request.taskId,
+                "licence" to request.licence,
+                "fingerprint" to request.fingerprint,
+                "deviceSignature" to deviceSignature,
+                "summary" to request.summary
+            )
+            val summaryContent = objectMapper.writeValueAsString(summaryMap).toByteArray(Charsets.UTF_8)
+
+            // 3. 生成 manifest.json
+            val filesHashes = mapOf(
+                "summary.json" to sha256Hex(summaryContent),
+                "assets.json" to assetsSha256,
+                "vulnerabilities.json" to vulnerabilitiesSha256,
+                "weakPasswords.json" to weakPasswordsSha256,
+                "漏洞评估报告.html" to reportHtmlSha256
+            )
+            val manifest = mapOf("files" to filesHashes)
+            val manifestContent = objectMapper.writeValueAsString(manifest).toByteArray(Charsets.UTF_8)
+
+            // 4. 生成 signature.asc
+            val privateKey = request.pgpPrivateKey?.takeIf { it.isNotBlank() } ?: DEFAULT_PGP_PRIVATE_KEY
+            val passphrase = request.pgpPassphrase ?: DEFAULT_PGP_PASSPHRASE
+            
+            val signatureAsc = try {
+                PgpSignatureUtil.generateDetachedSignature(
+                    manifestContent,
+                    privateKey,
+                    passphrase
+                )
+            } catch (e: Exception) {
+                throw RuntimeException("生成 PGP 签名失败: ${e.message}", e)
+            }
+
+            // 5. 打包 ZIP 文件到内存
+            val baos = java.io.ByteArrayOutputStream()
+            java.util.zip.ZipOutputStream(baos).use { zipOut ->
+                zipOut.putNextEntry(java.util.zip.ZipEntry("summary.json"))
+                zipOut.write(summaryContent)
+                zipOut.closeEntry()
+
+                zipOut.putNextEntry(java.util.zip.ZipEntry("assets.json"))
+                zipOut.write(assetsContent)
+                zipOut.closeEntry()
+
+                zipOut.putNextEntry(java.util.zip.ZipEntry("vulnerabilities.json"))
+                zipOut.write(vulnerabilitiesContent)
+                zipOut.closeEntry()
+
+                zipOut.putNextEntry(java.util.zip.ZipEntry("weakPasswords.json"))
+                zipOut.write(weakPasswordsContent)
+                zipOut.closeEntry()
+
+                zipOut.putNextEntry(java.util.zip.ZipEntry("漏洞评估报告.html"))
+                zipOut.write(reportHtmlContent)
+                zipOut.closeEntry()
+
+                zipOut.putNextEntry(java.util.zip.ZipEntry("META-INF/manifest.json"))
+                zipOut.write(manifestContent)
+                zipOut.closeEntry()
+
+                zipOut.putNextEntry(java.util.zip.ZipEntry("META-INF/signature.asc"))
+                zipOut.write(signatureAsc)
+                zipOut.closeEntry()
+            }
+
+            val zipBytes = baos.toByteArray()
+
+            // 6. 设置响应头并输出
+            response.contentType = "application/octet-stream"
+            response.setHeader("Content-Disposition", "attachment; filename=\"report_${request.taskId}.zip\"")
+            response.setHeader("Content-Length", zipBytes.size.toString())
+            response.outputStream.write(zipBytes)
+            response.outputStream.flush()
+        } catch (e: Exception) {
+            response.reset()
+            response.contentType = "application/json; charset=UTF-8"
+            response.writer.write("{\"code\": 500, \"msg\": \"生成 ZIP 文件失败: ${e.message}\"}")
+        }
+    }
+}
+
@@ -1,2 +1,3 @@
 [tools]
-bun = "1.3.13"
+bun = "1"
+node = "24"
@@ -0,0 +1,13 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "shadcn": {
+      "type": "local",
+      "command": ["bunx", "--bun", "shadcn", "mcp"]
+    },
+    "tanstack": {
+      "type": "remote",
+      "url": "https://tanstack.com/api/mcp"
+    }
+  }
+}
@@ -1,71 +1,72 @@
 {
-  "name": "battery-soh",
+  "name": "@furtherverse/monorepo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
-  "imports": {
-    "#package": "./package.json",
-    "#server": "./.output/server/index.mjs"
-  },
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
  "scripts": {
-    "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"
-  },
-  "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",
-    "@radix-ui/react-select": "^2.2.6",
-    "@t3-oss/env-core": "^0.13.11",
-    "@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",
-    "@tanstack/react-table": "^8.21.3",
-    "@tanstack/react-virtual": "^3.13.24",
-    "citty": "^0.2.2",
-    "lru-cache": "^11.3.6",
-    "lucide-react": "^1.14.0",
-    "motion": "^12.38.0",
-    "mysql2": "^3.22.3",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
-    "recharts": "^3.8.1",
-    "zod": "^4.3.6"
+    "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"
  },
  "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-orm": "^0.45.2",
-    "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"
+    "@biomejs/biome": "^2.4.5",
+    "turbo": "^2.8.13",
+    "typescript": "^5.9.3"
+  },
+  "catalog": {
+    "@orpc/client": "^1.13.6",
+    "@orpc/contract": "^1.13.6",
+    "@orpc/openapi": "^1.13.6",
+    "@orpc/server": "^1.13.6",
+    "@orpc/tanstack-query": "^1.13.6",
+    "@orpc/zod": "^1.13.6",
+    "@t3-oss/env-core": "^0.13.10",
+    "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/devtools-vite": "^0.5.3",
+    "@tanstack/react-devtools": "^0.9.9",
+    "@tanstack/react-query": "^5.90.21",
+    "@tanstack/react-query-devtools": "^5.91.3",
+    "@tanstack/react-router": "^1.166.2",
+    "@tanstack/react-router-devtools": "^1.166.2",
+    "@tanstack/react-router-ssr-query": "^1.166.2",
+    "@tanstack/react-start": "^1.166.2",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^24.11.0",
+    "@vitejs/plugin-react": "^5.1.4",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "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",
+    "jszip": "^3.10.1",
+    "motion": "^12.35.0",
+    "nitro": "npm:nitro-nightly@3.0.1-20260227-181935-bfbb207c",
+    "openpgp": "^6.0.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwindcss": "^4.2.1",
+    "tree-kill": "^1.2.2",
+    "uuid": "^13.0.0",
+    "vite": "^8.0.0-beta.16",
+    "vite-tsconfig-paths": "^6.1.1",
+    "systeminformation": "^5.31.3",
+    "zod": "^4.3.6"
+  },
+  "overrides": {
+    "@types/node": "catalog:"
  }
 }
@@ -0,0 +1,18 @@
+{
+  "name": "@furtherverse/crypto",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "node-forge": "^1.3.3",
+    "openpgp": "catalog:"
+  },
+  "devDependencies": {
+    "@furtherverse/tsconfig": "workspace:*",
+    "@types/bun": "catalog:",
+    "@types/node-forge": "^1.3.14"
+  }
+}
@@ -0,0 +1,53 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+
+const GCM_IV_LENGTH = 12 // 96 bits
+const GCM_TAG_LENGTH = 16 // 128 bits
+const ALGORITHM = 'aes-256-gcm'
+
+/**
+ * AES-256-GCM encrypt.
+ *
+ * Output format (before Base64): [IV (12 bytes)] + [ciphertext] + [auth tag (16 bytes)]
+ *
+ * @param plaintext - UTF-8 string to encrypt
+ * @param key - 32-byte AES key
+ * @returns Base64-encoded encrypted data
+ */
+export const aesGcmEncrypt = (plaintext: string, key: Buffer): string => {
+  const iv = randomBytes(GCM_IV_LENGTH)
+  const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: GCM_TAG_LENGTH })
+
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+
+  // Layout: IV + ciphertext + tag
+  const combined = Buffer.concat([iv, encrypted, tag])
+  return combined.toString('base64')
+}
+
+/**
+ * AES-256-GCM decrypt.
+ *
+ * Input format (after Base64 decode): [IV (12 bytes)] + [ciphertext] + [auth tag (16 bytes)]
+ *
+ * @param encryptedBase64 - Base64-encoded encrypted data
+ * @param key - 32-byte AES key
+ * @returns Decrypted UTF-8 string
+ */
+export const aesGcmDecrypt = (encryptedBase64: string, key: Buffer): string => {
+  const data = Buffer.from(encryptedBase64, 'base64')
+
+  if (data.length < GCM_IV_LENGTH + GCM_TAG_LENGTH) {
+    throw new Error('Encrypted data too short: must contain IV + tag at minimum')
+  }
+
+  const iv = data.subarray(0, GCM_IV_LENGTH)
+  const tag = data.subarray(data.length - GCM_TAG_LENGTH)
+  const ciphertext = data.subarray(GCM_IV_LENGTH, data.length - GCM_TAG_LENGTH)
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: GCM_TAG_LENGTH })
+  decipher.setAuthTag(tag)
+
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()])
+  return decrypted.toString('utf-8')
+}
@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * Compute SHA-256 hash and return raw Buffer.
+ */
+export const sha256 = (data: string | Buffer): Buffer => {
+  return createHash('sha256').update(data).digest()
+}
+
+/**
+ * Compute SHA-256 hash and return lowercase hex string.
+ */
+export const sha256Hex = (data: string | Buffer): string => {
+  return createHash('sha256').update(data).digest('hex')
+}
@@ -0,0 +1,15 @@
+import { hkdfSync } from 'node:crypto'
+
+/**
+ * Derive a key using HKDF-SHA256.
+ *
+ * @param ikm - Input keying material (string, will be UTF-8 encoded)
+ * @param salt - Salt value (string, will be UTF-8 encoded)
+ * @param info - Info/context string (will be UTF-8 encoded)
+ * @param length - Output key length in bytes (default: 32 for AES-256)
+ * @returns Derived key as Buffer
+ */
+export const hkdfSha256 = (ikm: string, salt: string, info: string, length = 32): Buffer => {
+  const derived = hkdfSync('sha256', ikm, salt, info, length)
+  return Buffer.from(derived)
+}
@@ -0,0 +1,23 @@
+import { createHmac } from 'node:crypto'
+
+/**
+ * Compute HMAC-SHA256 and return Base64-encoded signature.
+ *
+ * @param key - HMAC key (Buffer)
+ * @param data - Data to sign (UTF-8 string)
+ * @returns Base64-encoded HMAC-SHA256 signature
+ */
+export const hmacSha256Base64 = (key: Buffer, data: string): string => {
+  return createHmac('sha256', key).update(data, 'utf-8').digest('base64')
+}
+
+/**
+ * Compute HMAC-SHA256 and return raw Buffer.
+ *
+ * @param key - HMAC key (Buffer)
+ * @param data - Data to sign (UTF-8 string)
+ * @returns HMAC-SHA256 digest as Buffer
+ */
+export const hmacSha256 = (key: Buffer, data: string): Buffer => {
+  return createHmac('sha256', key).update(data, 'utf-8').digest()
+}
@@ -0,0 +1,6 @@
+export { aesGcmDecrypt, aesGcmEncrypt } from './aes-gcm'
+export { sha256, sha256Hex } from './hash'
+export { hkdfSha256 } from './hkdf'
+export { hmacSha256, hmacSha256Base64 } from './hmac'
+export { generatePgpKeyPair, pgpSignDetached, pgpVerifyDetached, validatePgpPrivateKey } from './pgp'
+export { rsaOaepEncrypt } from './rsa-oaep'
@@ -0,0 +1,79 @@
+import * as openpgp from 'openpgp'
+
+/**
+ * Generate an OpenPGP RSA key pair.
+ *
+ * @param name - User name for the key
+ * @param email - User email for the key
+ * @returns ASCII-armored private and public keys
+ */
+export const generatePgpKeyPair = async (
+  name: string,
+  email: string,
+): Promise<{ privateKey: string; publicKey: string }> => {
+  const { privateKey, publicKey } = await openpgp.generateKey({
+    type: 'rsa',
+    rsaBits: 2048,
+    userIDs: [{ name, email }],
+    format: 'armored',
+  })
+
+  return { privateKey, publicKey }
+}
+
+/**
+ * Create a detached OpenPGP signature for the given data.
+ *
+ * @param data - Raw data to sign (Buffer or Uint8Array)
+ * @param armoredPrivateKey - ASCII-armored private key
+ * @returns ASCII-armored detached signature (signature.asc content)
+ */
+export const validatePgpPrivateKey = async (armoredKey: string): Promise<void> => {
+  await openpgp.readPrivateKey({ armoredKey })
+}
+
+export const pgpSignDetached = async (data: Uint8Array, armoredPrivateKey: string): Promise<string> => {
+  const privateKey = await openpgp.readPrivateKey({ armoredKey: armoredPrivateKey })
+  const message = await openpgp.createMessage({ binary: data })
+
+  const signature = await openpgp.sign({
+    message,
+    signingKeys: privateKey,
+    detached: true,
+    format: 'armored',
+  })
+
+  return signature as string
+}
+
+/**
+ * Verify a detached OpenPGP signature.
+ *
+ * @param data - Original data (Buffer or Uint8Array)
+ * @param armoredSignature - ASCII-armored detached signature
+ * @param armoredPublicKey - ASCII-armored public key
+ * @returns true if signature is valid
+ */
+export const pgpVerifyDetached = async (
+  data: Uint8Array,
+  armoredSignature: string,
+  armoredPublicKey: string,
+): Promise<boolean> => {
+  const publicKey = await openpgp.readKey({ armoredKey: armoredPublicKey })
+  const signature = await openpgp.readSignature({ armoredSignature })
+  const message = await openpgp.createMessage({ binary: data })
+
+  const verificationResult = await openpgp.verify({
+    message,
+    signature,
+    verificationKeys: publicKey,
+  })
+
+  const { verified } = verificationResult.signatures[0]!
+  try {
+    await verified
+    return true
+  } catch {
+    return false
+  }
+}
@@ -0,0 +1,32 @@
+import forge from 'node-forge'
+
+/**
+ * RSA-OAEP encrypt with platform public key.
+ *
+ * Matches Java's {@code Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding")}
+ * with **default SunJCE parameters**:
+ *
+ * | Parameter | Value  |
+ * |-----------|--------|
+ * | OAEP hash | SHA-256|
+ * | MGF1 hash | SHA-1  |
+ *
+ * Node.js `crypto.publicEncrypt({ oaepHash })` ties both hashes together,
+ * so we use `node-forge` which allows independent configuration.
+ *
+ * @param plaintext - UTF-8 string to encrypt
+ * @param publicKeyBase64 - Platform RSA public key (X.509 / SPKI DER, Base64)
+ * @returns Base64-encoded ciphertext
+ */
+export const rsaOaepEncrypt = (plaintext: string, publicKeyBase64: string): string => {
+  const derBytes = forge.util.decode64(publicKeyBase64)
+  const asn1 = forge.asn1.fromDer(derBytes)
+  const publicKey = forge.pki.publicKeyFromAsn1(asn1) as forge.pki.rsa.PublicKey
+
+  const encrypted = publicKey.encrypt(plaintext, 'RSA-OAEP', {
+    md: forge.md.sha256.create(),
+    mgf1: { md: forge.md.sha1.create() },
+  })
+
+  return forge.util.encode64(encrypted)
+}
@@ -0,0 +1,7 @@
+{
+  "extends": "@furtherverse/tsconfig/bun.json",
+  "compilerOptions": {
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
@@ -1,8 +1,9 @@
 {
  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Base",
  "compilerOptions": {
    "target": "esnext",
-    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "lib": ["ESNext"],
    "module": "preserve",
    "skipLibCheck": true,

@@ -19,14 +20,7 @@
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true,
    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-
-    "jsx": "react-jsx",
-    "types": ["bun"],
-
-    "paths": {
-      "@/*": ["./src/*"]
-    }
+    "noImplicitOverride": true
  },
-  "exclude": ["node_modules", ".output", "out"]
+  "exclude": ["node_modules"]
 }
@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Bun",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  }
+}
@@ -0,0 +1,11 @@
+{
+  "name": "@furtherverse/tsconfig",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./base.json": "./base.json",
+    "./bun.json": "./bun.json",
+    "./react.json": "./react.json"
+  }
+}
@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "React",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx"
+  }
+}
@@ -1,2 +0,0 @@
-User-agent: *
-Disallow:
@@ -1,138 +0,0 @@
-import { datetime, index, int, mysqlTable, tinyint, varchar } from 'drizzle-orm/mysql-core'
-import { drizzle } from 'drizzle-orm/mysql2'
-import { reset } from 'drizzle-seed'
-import mysql from 'mysql2/promise'
-import { type MYSQL_BOOLEAN, POWER_STATUS, type PowerStatus, toMysqlBoolean } from '@/domain/battery'
-
-type SeedRow = {
-  userId: number
-  mac: string
-  devModel: string
-  devName: string
-  isLowPower: (typeof MYSQL_BOOLEAN)[keyof typeof MYSQL_BOOLEAN]
-  powerStatus: PowerStatus
-  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: POWER_STATUS.FULL, remark: 'v3.8.2' },
-  { mac: 'RING-B11', model: 'SR-01', name: '样机-B11', basePower: 91, status: POWER_STATUS.CHARGING, remark: 'v3.8.2' },
-  {
-    mac: 'RING-C07',
-    model: 'SR-02',
-    name: '样机-C07',
-    basePower: 88,
-    status: POWER_STATUS.NOT_CHARGING,
-    remark: 'v3.8.1',
-  },
-  {
-    mac: 'RING-D19',
-    model: 'SR-02',
-    name: '样机-D19',
-    basePower: 84,
-    status: POWER_STATUS.NOT_CHARGING,
-    remark: 'v3.7.9',
-  },
-  { mac: 'RING-E21', model: 'SR-03', name: '样机-E21', basePower: 79, status: POWER_STATUS.CHARGING, remark: 'v3.7.9' },
-  { mac: 'RING-F02', model: 'SR-03', name: '样机-F02', basePower: 73, status: POWER_STATUS.NOT_CHARGING, remark: null },
-  { mac: 'RING-G15', model: 'SR-04', name: '样机-G15', basePower: 93, status: POWER_STATUS.FULL, remark: 'v3.9.0' },
-  {
-    mac: 'RING-H09',
-    model: 'SR-04',
-    name: '样机-H09',
-    basePower: 86,
-    status: POWER_STATUS.NOT_CHARGING,
-    remark: 'v3.8.1',
-  },
-] satisfies Array<{
-  mac: string
-  model: string
-  name: string
-  basePower: number
-  status: PowerStatus
-  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: toMysqlBoolean(power <= 20 || device.basePower <= 80),
-        powerStatus: historyIndex === 0 ? device.status : POWER_STATUS.NOT_CHARGING,
-        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()
-}
@@ -1,20 +0,0 @@
-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)
@@ -1 +0,0 @@
-export default function startNitroServer(): Promise<void>
@@ -1,3 +0,0 @@
-export default async function startNitroServer() {
-  await import('#server')
-}
@@ -1,12 +0,0 @@
-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()
-  },
-})
@@ -1,40 +0,0 @@
-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>
-  )
-}
@@ -1,23 +0,0 @@
-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>
-  )
-}
@@ -1,128 +0,0 @@
-import { motion, useReducedMotion } from 'motion/react'
-import type { ComponentPropsWithoutRef, ReactNode } from 'react'
-
-export function useMotionConfig() {
-  const shouldReduceMotion = useReducedMotion()
-  return { shouldReduceMotion }
-}
-
-export function MotionHeader({
-  children,
-  delay = 0,
-  className,
-  ...props
-}: { children: ReactNode; delay?: number } & ComponentPropsWithoutRef<typeof motion.header>) {
-  const { shouldReduceMotion } = useMotionConfig()
-
-  return (
-    <motion.header
-      initial={shouldReduceMotion ? false : { opacity: 0, y: 10 }}
-      animate={{ opacity: 1, y: 0 }}
-      transition={{ duration: 0.5, delay, ease: [0.25, 0.1, 0.25, 1] }}
-      className={className}
-      {...props}
-    >
-      {children}
-    </motion.header>
-  )
-}
-
-export function MotionSection({
-  children,
-  delay = 0,
-  className,
-  ...props
-}: { children: ReactNode; delay?: number } & ComponentPropsWithoutRef<typeof motion.section>) {
-  const { shouldReduceMotion } = useMotionConfig()
-
-  return (
-    <motion.section
-      initial={shouldReduceMotion ? false : { opacity: 0, y: 10 }}
-      animate={{ opacity: 1, y: 0 }}
-      transition={{ duration: 0.5, delay, ease: [0.25, 0.1, 0.25, 1] }}
-      className={className}
-      {...props}
-    >
-      {children}
-    </motion.section>
-  )
-}
-
-export function MotionDiv({
-  children,
-  delay = 0,
-  className,
-  ...props
-}: { children: ReactNode; delay?: number } & ComponentPropsWithoutRef<typeof motion.div>) {
-  const { shouldReduceMotion } = useMotionConfig()
-
-  return (
-    <motion.div
-      initial={shouldReduceMotion ? false : { opacity: 0, y: 10 }}
-      animate={{ opacity: 1, y: 0 }}
-      transition={{ duration: 0.5, delay, ease: [0.25, 0.1, 0.25, 1] }}
-      className={className}
-      {...props}
-    >
-      {children}
-    </motion.div>
-  )
-}
-
-export function MotionCardArticle({
-  children,
-  className,
-  ...props
-}: { children: ReactNode } & ComponentPropsWithoutRef<typeof motion.article>) {
-  const { shouldReduceMotion } = useMotionConfig()
-
-  return (
-    <motion.article
-      whileHover={shouldReduceMotion ? {} : { y: -2 }}
-      transition={{ duration: 0.2, ease: 'easeOut' }}
-      className={className}
-      {...props}
-    >
-      {children}
-    </motion.article>
-  )
-}
-
-export function MotionCardDiv({
-  children,
-  className,
-  ...props
-}: { children: ReactNode } & ComponentPropsWithoutRef<typeof motion.div>) {
-  const { shouldReduceMotion } = useMotionConfig()
-
-  return (
-    <motion.div
-      whileHover={shouldReduceMotion ? {} : { y: -2 }}
-      transition={{ duration: 0.2, ease: 'easeOut' }}
-      className={className}
-      {...props}
-    >
-      {children}
-    </motion.div>
-  )
-}
-
-export function MotionTableRow({
-  children,
-  className,
-  ...props
-}: { children: ReactNode } & ComponentPropsWithoutRef<typeof motion.tr>) {
-  const { shouldReduceMotion } = useMotionConfig()
-
-  return (
-    <motion.tr
-      initial={shouldReduceMotion ? false : { opacity: 0 }}
-      animate={{ opacity: 1 }}
-      transition={{ duration: 0.3 }}
-      className={className}
-      {...props}
-    >
-      {children}
-    </motion.tr>
-  )
-}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
imbytecat	42bc8605b4	docs: 添加摘要+ZIP 加密测试控制器参考	2026-03-10 15:09:11 +08:00
imbytecat	04ff718f47	docs: 移除旧版工具箱端授权对接指南文档	2026-03-10 15:08:36 +08:00
imbytecat	da82403f7f	refactor(server): signAndPackReport 对齐 Kotlin 参考实现的摘要与签名结构	2026-03-10 15:08:12 +08:00
imbytecat	4a5dd437fa	fix(server): setPgpPrivateKey 接口增加私钥格式校验	2026-03-10 15:07:31 +08:00
imbytecat	1945417f28	feat(crypto): 新增 validatePgpPrivateKey 校验函数	2026-03-10 15:07:07 +08:00
imbytecat	8be32bf15b	refactor(server): extract ZIP security checks into reusable safe-zip module	2026-03-06 16:51:33 +08:00
imbytecat	1110edc974	docs: remove outdated UX API docs (superseded by OpenAPI /api/docs)	2026-03-06 16:41:15 +08:00
imbytecat	a5fd9c1833	fix(crypto): replace deprecated .passthrough() with .loose() (Zod 4)	2026-03-06 16:40:46 +08:00
imbytecat	3d27f8ccfa	refactor(crypto): use Zod safeParse for summary.json validation instead of manual checks	2026-03-06 16:39:38 +08:00
imbytecat	4d64cfb93d	docs: 添加管理平台标准加密算法 Kotlin 参考实现	2026-03-06 15:34:04 +08:00
imbytecat	2651ec0835	fix(crypto): 修复 RSA-OAEP 加密与 Java SunJCE 的 MGF1 哈希不兼容问题 Node.js publicEncrypt({ oaepHash }) 会将 OAEP hash 和 MGF1 hash 绑定为同一算法，而 Java OAEPWithSHA-256AndMGF1Padding 默认使用 SHA-256(OAEP) + SHA-1(MGF1)。改用 node-forge 独立配置两个哈希，确保密文可被管理平台正确解密。	2026-03-06 15:33:07 +08:00
imbytecat	122dead202	refactor(server): 简化 signAndPackReport 接口，PGP 私钥本地存储、summary.json 从 ZIP 提取 - DB schema 新增 pgpPrivateKey 字段 - 新增 config.setPgpPrivateKey 接口，私钥与设备绑定 - signAndPackReport 只需传 rawZip，signingContext 自动从 summary.json 派生 - configOutput 新增 hasPgpPrivateKey 字段 - 抽取 requireIdentity 减少重复校验代码	2026-03-06 14:55:12 +08:00
imbytecat	ec41a4cfc7	docs(contract): 为所有 API 的 input/output 添加 OpenAPI examples，便于厂商测试	2026-03-06 14:37:50 +08:00
imbytecat	86754f73c1	docs(contract): 优化 API summary/description，对齐工具箱端对接指南文档	2026-03-06 14:30:09 +08:00
imbytecat	9296ab31e4	fix(server): 每次启动重新计算设备特征码，环境变化时自动更新	2026-03-06 11:28:14 +08:00
imbytecat	72d1727eb6	refactor(server): 设备特征码直接使用完整 SHA-256，移除 FP- 前缀和截断	2026-03-06 11:23:52 +08:00
imbytecat	aabd60e619	refactor(server): 使用 systeminformation 替代手动采集生成设备特征码硬件级 SMBIOS 标识（uuid/serial/model/manufacturer）跨平台稳定，不再依赖 Linux 独有的 machine-id 和易变的 OS release/内存/MAC 地址。	2026-03-06 11:16:17 +08:00
imbytecat	cdb3298f6d	refactor(db): 删除去业务化后残留的 device/task 表定义	2026-03-06 10:39:09 +08:00
imbytecat	060ddd8e12	docs: 更新 UX 本地身份配置流程与对接说明	2026-03-06 10:02:56 +08:00
imbytecat	b50d2eaf10	refactor(server): 重构为本地身份配置 + 底层 crypto 能力接口	2026-03-06 10:02:26 +08:00
imbytecat	46e2c94faf	fix(db): 修正 drizzle-kit 在 Bun SQLite 下的配置与脚本	2026-03-05 16:59:25 +08:00
imbytecat	b1062a5aed	refactor(api): signAndPackReport 直接返回签名 ZIP 文件	2026-03-05 16:58:59 +08:00
imbytecat	b193759e90	docs: 新增第三方 OpenAPI 对接指南	2026-03-05 16:44:01 +08:00
imbytecat	eb941c06c0	docs(api): 补全 OpenAPI 元数据与字段描述	2026-03-05 16:43:53 +08:00
imbytecat	eb2f6554b2	docs: 更新 signAndPackReport 为 multipart 文件上传说明	2026-03-05 16:32:49 +08:00
imbytecat	58d57fa148	refactor(server): 使用 multipart File 替代报告 ZIP 的 base64 上传	2026-03-05 16:32:41 +08:00
imbytecat	509860bba8	docs: 补充 UX 集成模式与授权对接说明	2026-03-05 16:24:21 +08:00
imbytecat	4e7c4e1aa5	feat(server): 实现设备授权与报告 ZIP 签名打包接口	2026-03-05 16:24:10 +08:00
imbytecat	8261409d7d	refactor(server): 切换 SQLite 并重建设备/任务表结构	2026-03-05 16:23:30 +08:00
imbytecat	d2eb98d612	feat: 新增共享加密包并引入 ZIP/PGP 依赖	2026-03-05 16:23:13 +08:00
				`@@ -1 +0,0 @@`
				`export default function startNitroServer(): Promise<void>`