# 蓝狐代理 (Lanhu Proxy) - AI 开发助手指南

## 项目概述

Next.js 15+ 代理服务平台，包含公开营销站点与用户管理后台。使用 Bun 运行时，React 19 Server Components，shadcn/ui 组件库。

**核心业务**: IP 代理购买、提取、白名单管理、实名认证、充值计费

## 架构模式

### 三层数据流架构

1. **Server Actions** (`src/actions/*.ts`) - 所有 API 调用统一入口
   - 每个文件对应一个业务域 (auth, bill, ip, resource 等)
   - 通过 `base.ts` 的三种调用模式访问后端:
     - `callPublic()` - 无需认证的公开接口
     - `callByDevice()` - 使用 CLIENT_ID/CLIENT_SECRET 的设备级认证
     - `callByUser()` - 使用用户会话 token 的用户级认证
   - 所有调用都用 `cache()` 包装以支持 React 缓存
   - 返回统一的 `ApiResponse<T>` 类型

2. **Zustand Store** (`src/components/stores/*.tsx`) - 客户端状态管理
   - 异步初始化模式: 通过 Promise 传递服务端数据到客户端
   - `ProfileStoreProvider` 在根布局初始化用户资料
   - 每个 store 导出: `createXxxStore()`, `XxxStoreProvider`, `useXxxStore()`
   - 示例: `profile.tsx` 使用 `profile: Promise<User | null>` 实现服务端到客户端水合

3. **认证流程** - Token 刷新在 middleware 自动处理
   - `src/proxy.ts` (middleware) 检测 `auth_token` 过期时自动调用 `refreshAuth()`
   - 访问 `/admin` 路径无 token 时重定向到 `/login?redirect=`
   - Cookies: `auth_token` (访问令牌), `auth_refresh` (刷新令牌)

### 路由组织

- **(home)** - 公开营销站点，包含产品介绍、文档中心、定制服务
- **(auth)** - 登录、实名认证、隐私协议、兑换码
- **admin** - 用户后台，包含仪表盘、账单、资源管理、白名单、提取功能
- **(api)/proxies** - API 端点路由

括号路由 `(group)` 不影响 URL 路径，仅用于组织布局层级。

### 验证码集成 (Cap.js)

- `src/lib/cap/index.ts` 自定义存储实现，使用 HMAC 签名的 Cookie 而非文件系统
- `getCap()` 返回配置好的 Cap 实例
- Challenge 和 token 都存储在 httpOnly cookies 中
- `sign()` / `verify()` 基于 CLIENT_SECRET 的签名验证

## 开发工作流

### 命令速查

```bash
bun install              # 安装依赖
bun dev                  # 开发服务器 (0.0.0.0:3000 + Turbopack)
bun run build            # 生产构建 (Turbopack)
bun start                # 启动生产服务器
bun run lint             # ESLint 自动修复
bun run check            # TypeScript 类型检查
```

### 组件开发模式

**shadcn/ui 组件** (`src/components/ui/*.tsx`)
- 使用 `components.json` 配置，New York 风格
- 通过 CLI 添加: `bunx shadcn@latest add <component>`
- 所有组件使用 `merge()` (twMerge 别名) 合并类名

**业务组件** (`src/components/composites/*`)
- 复杂表单、对话框、支付组件等放在此目录
- 标记 `'use client'` 的客户端组件
- 示例: `purchase/index.tsx` 使用 URL 查询参数控制 Tab 状态

**工具函数**
- `merge(...inputs)` - 合并 Tailwind 类名 (来自 `@/lib/utils`)
- `Children` 类型 - 标准 `{children: ReactNode}` 类型别名

### MDX 文档系统

- 文档源文件: `src/docs/*.mdx`
- 配置: `next.config.ts` 集成 `@next/mdx`, `remark-gfm`, `rehype-highlight`
- 页面扩展名: `.md`, `.mdx`, `.js`, `.jsx`, `.ts`, `.tsx`
- 布局: `src/app/(home)/docs/layout.tsx` 提供面包屑和侧边栏

## 项目特定约定

### 类型定义模式

```typescript
// 从 server action 推断请求/响应类型
type ExtraReq<T> = T extends (...args: infer P) => unknown ? P[0] : never
type ExtraResp<T> = Awaited<ReturnType<T>> extends ApiResponse<infer D> ? D : never

// 使用示例
type LoginRequest = ExtraReq<typeof login>
type UserProfile = ExtraResp<typeof getProfile>
```

### 错误处理

- Server actions 返回 `ApiResponse<T>`:
  - 成功: `{success: true, data: T}`
  - 失败: `{success: false, status: number, message: string}`
- 使用 `sonner` (Toaster) 显示用户提示
- 预定义错误: `UnauthorizedError` (401 场景)

### 样式规范

- 主色系: `primary-*`, `card`, `primary-muted`
- 响应式断点: 使用 Tailwind 默认 (`sm:`, `md:`, `lg:`)
- 布局: 首页使用 `bg-blue-50` 背景，后台使用 `bg-card` 和圆角遮罩 (见 `admin/layout.tsx`)

## 关键文件参考

- [src/actions/base.ts](src/actions/base.ts) - API 调用核心抽象
- [src/proxy.ts](src/proxy.ts) - 认证 middleware 和 token 刷新逻辑
- [src/components/stores/profile.tsx](src/components/stores/profile.tsx) - 异步 store 初始化模式
- [src/lib/cap/index.ts](src/lib/cap/index.ts) - Cap.js 自定义存储实现
- [src/app/layout.tsx](src/app/layout.tsx) - Store providers 和异步初始化
- [next.config.ts](next.config.ts) - MDX、React Compiler、Turbopack 配置

## 环境变量

需要配置:
- `API_BASE_URL` - 后端 API 地址
- `CLIENT_ID`, `CLIENT_SECRET` - OAuth2 设备认证凭据

## 部署

- 使用 `output: 'standalone'` 模式
- Dockerfile 多阶段构建 (Bun 1.2.19 Alpine)
- 生产端口: 3000

## 待改进事项 (来自 README)

- 考虑使用 SWR/React Query 替代当前的 server cache + zustand 混合方案
- 手机端优化: 购买和提取页面需一页展示全部内容
- IP 管理按长短效分页
- 后台导航结构重组 (当前过于分散)