# AGENTS.md - AI Coding Agent Guidelines

本文档为 AI 编程助手提供此 TanStack Start 全栈项目的开发规范和指南。

## 项目概览

- **框架**: TanStack Start (React SSR 框架，文件路由)
- **运行时**: Bun
- **语言**: TypeScript (strict mode, ESNext)
- **样式**: Tailwind CSS v4
- **数据库**: SQLite + Drizzle ORM
- **状态管理**: TanStack Query
- **路由**: TanStack Router (文件路由)
- **RPC**: ORPC (类型安全 RPC，契约优先)
- **构建工具**: Vite + Turbo
- **代码质量**: Biome (格式化 + Lint)

## 依赖管理

### Bun Catalog 系统

项目使用 **Bun Catalog** 统一管理依赖版本（定义在根目录 `package.json` 的 `catalog` 字段）。

**安装依赖的正确方式**：
```bash
# ✅ 正确：使用 catalog: 前缀
bun add <package-name>@catalog:

# ❌ 错误：直接安装会绕过版本统一管理
bun add <package-name>@latest
```

**示例**：
```bash
# 添加 systeminformation 依赖到 packages/utils
cd packages/utils
bun add systeminformation@catalog:

# 添加 react 依赖到 apps/server
cd apps/server
bun add react@catalog:
```

**为什么使用 Catalog**：
- 确保 monorepo 中所有包使用相同版本
- 集中管理依赖版本，避免版本冲突
- 简化依赖升级（只需修改根 package.json）

**添加新依赖的步骤**：
1. 在根目录 `package.json` 的 `catalog` 字段添加依赖及版本
2. 在目标包中使用 `bun add <package>@catalog:` 安装

## 构建、Lint 和测试命令

### 开发
```bash
bun dev                    # 启动 Vite 开发服务器
bun db:studio              # 打开 Drizzle Studio 数据库管理界面
```

### 构建
```bash
bun build                  # 构建 Vite 应用 (输出到 .output/)
bun compile                # 编译为独立可执行文件 (使用 build.ts)
```

### 代码质量
```bash
bun typecheck              # 运行 TypeScript 类型检查
bun fix                    # 运行 Biome 自动修复格式和 Lint 问题
biome check .              # 检查但不自动修复
biome format --write .     # 仅格式化代码
```

### 数据库
```bash
bun db:generate            # 从 schema 生成迁移文件
bun db:migrate             # 执行数据库迁移
bun db:push                # 直接推送 schema 变更 (仅开发环境)
```

### 测试
**注意**: 当前未配置测试框架。添加测试时:
- 使用 Vitest 或 Bun 内置测试运行器
- 运行单个测试文件: `bun test path/to/test.ts`
- 运行特定测试: `bun test -t "测试名称模式"`

## 代码风格指南

### 格式化 (Biome)

**缩进**: 2 空格 (不使用 tab)
**换行符**: LF (Unix 风格)
**引号**: 单引号 `'string'`
**分号**: 按需 (ASI - 自动分号插入)
**箭头函数括号**: 始终使用 `(x) => x`

示例:
```typescript
const myFunc = (value: string) => {
  return value.toUpperCase()
}
```

### 导入组织

Biome 自动组织导入。顺序:
1. 外部依赖
2. 内部导入 (使用 `@/*` 别名)
3. 类型导入 (仅导入类型时使用 `type` 关键字)

示例:
```typescript
import { createFileRoute } from '@tanstack/react-router'
import { oc } from '@orpc/contract'
import { z } from 'zod'
import { db } from '@/db'
import { todoTable } from '@/db/schema'
import type { ReactNode } from 'react'
```

### TypeScript

**严格模式**: 启用了额外的严格检查
- `strict: true`
- `noUncheckedIndexedAccess: true` - 数组/对象索引返回 `T | undefined`
- `noImplicitOverride: true`
- `noFallthroughCasesInSwitch: true`

**模块解析**: `bundler` 模式 + `verbatimModuleSyntax`
- 导入时始终使用 `.ts`/`.tsx` 扩展名
- 使用 `@/*` 路径别名指向 `src/*`

**类型注解**:
- 公共 API 的函数参数和返回类型必须注解
- 优先使用显式类型而非 `any`
- 对象形状用 `type`，可扩展契约用 `interface`
- 不可变 props 使用 `Readonly<T>`

### 命名规范

- **文件**: 工具函数用 kebab-case，组件用 PascalCase
  - `utils.ts`, `todo.tsx`, `NotFound.tsx`
- **路由**: 遵循 TanStack Router 约定
  - `routes/index.tsx` → `/`
  - `routes/__root.tsx` → 根布局
- **组件**: PascalCase 箭头函数 (Biome 规则 `useArrowFunction` 强制)
- **函数**: camelCase
- **常量**: 真常量用 UPPER_SNAKE_CASE，配置对象用 camelCase
- **类型/接口**: PascalCase

### React 模式

**组件**: 使用箭头函数
```typescript
const MyComponent = ({ title }: { title: string }) => {
  return <div>{title}</div>
}
```

**路由**: 使用 `createFileRoute` 定义路由
```typescript
export const Route = createFileRoute('/')({
  component: Home,
})
```

**数据获取**: 使用 TanStack Query hooks
- `useSuspenseQuery` - 保证有数据
- `useQuery` - 数据可能为空

**Props**: 禁止直接修改 props (Biome 规则 `noReactPropAssignments`)

### 数据库 Schema (Drizzle)

- 在 `src/server/db/schema/*.ts` 定义 schema
- 从 `src/server/db/schema/index.ts` 导出
- 使用 `drizzle-orm/sqlite-core` 的 SQLite 类型
- 主键使用 `uuidv7()` (TEXT 存储)
- 时间戳使用 `integer({ mode: 'timestamp_ms' })` (Unix 毫秒时间戳)
- 始终包含 `createdAt` 和 `updatedAt` 时间戳

示例:
```typescript
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
import { v7 as uuidv7 } from 'uuid'

export const myTable = sqliteTable('my_table', {
  id: text('id').primaryKey().$defaultFn(() => uuidv7()),
  name: text('name').notNull(),
  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date()),
  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date()).$onUpdateFn(() => new Date()),
})
```

### 环境变量

- 使用 `@t3-oss/env-core` 进行类型安全的环境变量验证
- 在 `src/env.ts` 定义 schema
- 服务端变量: 无前缀
- 客户端变量: 必须有 `VITE_` 前缀
- 使用 Zod schema 验证

### 错误处理

- 异步操作使用 try-catch
- 抛出带有描述性消息的错误
- 用户界面错误优先使用 Result 类型或错误边界
- 适当记录错误 (避免记录敏感数据)

### 样式 (Tailwind CSS)

- 使用 Tailwind v4 工具类
- 通过 `@/styles.css?url` 导入样式
- 优先使用组合而非自定义 CSS
- 响应式修饰符: `sm:`, `md:`, `lg:`
- UI 文本适当使用中文

## 目录结构

```
src/
├── components/            # 可复用 React 组件
├── db/
│   ├── schema/           # Drizzle schema 定义
│   └── index.ts          # 数据库实例
├── integrations/         # 第三方集成 (TanStack Query/Router)
├── lib/                  # 工具函数
├── orpc/                 # ORPC (RPC 层)
│   ├── contracts/        # 契约定义 (input/output schemas)
│   ├── handlers/         # 服务端过程实现
│   ├── middlewares/      # 中间件 (如 DB provider)
│   ├── contract.ts       # 契约聚合
│   ├── router.ts         # 路由组合
│   ├── server.ts         # 服务端实例
│   └── client.ts         # 同构客户端
├── routes/               # TanStack Router 文件路由
│   ├── __root.tsx        # 根布局
│   ├── index.tsx         # 首页
│   └── api/rpc.$.ts      # ORPC HTTP 端点
├── env.ts                # 环境变量验证
└── router.tsx            # 路由配置
```

## 重要提示

- **禁止** 编辑 `src/routeTree.gen.ts` - 自动生成
- **禁止** 提交 `.env` 文件 - 使用 `.env.example` 作为模板
- **必须** 在提交前运行 `bun fix`
- **必须** 使用 `@/*` 路径别名而非相对导入
- **必须** 利用 React Compiler (babel-plugin-react-compiler) - 避免手动 memoization

## Git 工作流

1. 按照上述风格指南进行修改
2. 运行 `bun fix` 自动格式化和 lint
3. 运行 `bun typecheck` 确保类型安全
4. 使用 `bun dev` 本地测试变更
5. 使用清晰的描述性消息提交

## 常见模式

### 创建 ORPC 过程

**步骤 1: 定义契约** (`src/orpc/contracts/my-feature.ts`)
```typescript
import { oc } from '@orpc/contract'
import { z } from 'zod'

export const myContract = {
  get: oc.input(z.object({ id: z.uuid() })).output(mySchema),
  create: oc.input(createSchema).output(mySchema),
}
```

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

export const get = os.myFeature.get
  .use(dbProvider)
  .handler(async ({ context, input }) => {
    return await context.db.query.myTable.findFirst(...)
  })
```

**步骤 3: 注册到契约和路由**
```typescript
// src/orpc/contract.ts
export const contract = { myFeature: myContract }

// src/orpc/router.ts
import * as myFeature from './handlers/my-feature'
export const router = os.router({ myFeature })
```

**步骤 4: 在组件中使用**
```typescript
import { orpc } from '@/orpc'
const query = useSuspenseQuery(orpc.myFeature.get.queryOptions({ id }))
const mutation = useMutation(orpc.myFeature.create.mutationOptions())
```

---

## 已知问题与解决方案

### 构建问题

**已解决**: Vite 8.0.0-beta.10 已修复与 Nitro 插件的兼容性问题
- **当前版本**: Vite 8.0.0-beta.10 + nitro-nightly@3.0.1-20260125
- **状态**: 构建稳定，开发和生产环境均正常工作

### 依赖选择经验

**ohash vs crypto.createHash**

在实现硬件指纹功能时，曾误判 `ohash` 不适合用于硬件指纹识别。经深入研究发现：

**事实**：
- `ohash` 内部使用**完整的 SHA-256** 算法（256 位）
- 输出 43 字符 Base64URL 编码（等价于 64 字符 Hex）
- 碰撞概率与 `crypto.createHash('sha256')` **完全相同**（2^128）
- 自动处理对象序列化，代码更简洁

**对比**：
```typescript
// ohash - 推荐用于对象哈希
import { hash } from 'ohash'
const fingerprint = hash(systemInfo) // 一行搞定

// crypto - 需要手动序列化
import { createHash } from 'node:crypto'
const fingerprint = createHash('sha256')
  .update(JSON.stringify(systemInfo))
  .digest('base64url')
```

**结论**：
- ✅ `ohash` 完全适合硬件指纹场景（数据来自系统 API，非用户输入）
- ✅ 两者安全性等价，选择取决于代码风格偏好
- ⚠️ ohash 文档警告的"序列化安全性"仅针对**用户输入**场景

**经验教训**：
- 不要仅凭名称（"短哈希"）判断库的实现
- 深入研究文档和源码再做技术决策
- 区分"用户输入场景"和"系统数据场景"的安全要求

### 缓存库选择：@isaacs/ttlcache

**决策时间**: 2026-01-26

**背景**：
硬件指纹功能最初使用手动实现的 TTL 缓存（module-level 变量 + 手动过期检查）。为提高代码可维护性，迁移到专业缓存库。

**选型**：
- **选择**: `@isaacs/ttlcache` v2.1.4
- **理由**:
  - 专为 TTL 场景优化，无需 LRU 追踪开销
  - 零依赖，6M+ 周下载量
  - 内置 TypeScript 类型
  - 自动过期管理，无需手动定时器
  - API 简洁: `new TTLCache({ ttl, max })`

**实现细节**：
- 保留 `inFlight` Promise 模式用于并发请求去重（TTLCache 不提供此功能）
- 使用单一缓存键 `'fingerprint'`（单服务器场景，opts 不影响输出）
- 默认 TTL: 10 分钟（可通过 `cacheTtlMs` 参数覆盖）

**对比手动实现**：
- ✅ 更少自定义代码
- ✅ 更清晰的 TTL 语义
- ✅ 经过充分测试的库
- ⚠️ 仍需手动处理并发去重

**经验教训**：
- 专业库不一定解决所有问题（如并发去重）
- 对于简单场景，手动实现 vs 库的选择主要取决于可维护性而非功能

### SQLite 数据库使用说明

**技术栈**:
- **驱动**: `better-sqlite3` v11.8.1 (原生模块，跨平台)
- **类型定义**: `@types/better-sqlite3` v7.6.12
- **数据库文件**: `./data/app.db`

**数据类型策略**:
- **主键**: TEXT 存储 UUIDv7 (36 字符字符串，全局唯一)
- **时间戳**: INTEGER 存储 Unix 毫秒时间戳 (`integer({ mode: 'timestamp_ms' })`)
  - Drizzle 自动转换 `Date` ↔ `number`
- **布尔值**: INTEGER 存储 0/1 (`integer({ mode: 'boolean' })`)
  - Drizzle 自动转换 `boolean` ↔ `0/1`

**数据库连接**:
```typescript
import { drizzle } from 'drizzle-orm/better-sqlite3'
import Database from 'better-sqlite3'
import { mkdirSync } from 'node:fs'
import { dirname } from 'node:path'

export const createDB = () => {
  const dbPath = env.DATABASE_URL
  if (dbPath !== ':memory:') {
    mkdirSync(dirname(dbPath), { recursive: true })
  }
  const sqlite = new Database(dbPath)
  return drizzle(sqlite, { schema })
}
```

**注意事项**:
- SQLite 是文件数据库，适合嵌入环境和单实例应用
- 不支持多进程并发写入
- 数据库文件和 WAL 文件 (`.db-shm`, `.db-wal`) 已添加到 `.gitignore`
- `better-sqlite3` 是原生模块，构建时需匹配生产环境 OS 和架构

### AGENTS.md 文档维护原则

**核心原则**：AGENTS.md 只记录当前项目状态，不记录重构历史

1. **当前状态优先**：只描述项目当前使用的技术栈、架构和最佳实践
2. **无需向后兼容**：不保留旧技术栈的文档，重构后直接更新为新状态
3. **避免历史记录**：不记录"从 X 迁移到 Y"的过程，只记录"当前使用 Y"
4. **保持简洁**：删除过时信息，避免上下文过长影响 AI 理解
5. **及时同步**：架构变更后立即更新文档，确保文档与代码一致

**何时更新 AGENTS.md**：
- 更换技术栈（如数据库、框架）
- 修改项目架构或目录结构
- 添加/移除重要依赖
- 发现重要的最佳实践或经验教训

**何时不更新 AGENTS.md**：
- 日常功能开发
- Bug 修复
- 代码重构（不涉及架构变更）
- 临时实验或 POC

---

**最后更新**: 2026-01-26
**项目版本**: 基于 package.json 依赖版本