# Frontend — Claude Code 项目指南

本文件为 Claude Code（及其它 AI Agent）提供前端项目的背景、结构说明和开发规范。

## 项目状态

> **当前状态：尚未初始化代码。** 技术栈待定，目录除本文件外为空。
> 在选定技术栈后，请补全本文件中标记为「⚠️ 待补充」的章节。

## 定位

`frontend/` 是 asset_helper 的 **Web 前端**，调用后端 API（默认通过 Nginx 网关 `https://api.example.com` 暴露）。

- 与 `backend/` 通过 HTTP/JSON 交互，遵循根目录 [CLAUDE.md](../CLAUDE.md) 中定义的跨端契约
- 与 `app/`（移动/桌面端）共享后端，但 UI 实现独立

## 技术栈

> ⚠️ 待补充：选定后请填写。建议候选：
>
> | 维度 | 候选 |
> |------|------|
> | 框架 | React 18 / Vue 3 / Next.js |
> | 语言 | TypeScript（推荐，与 Rust 后端类型对齐更顺） |
> | 构建 | Vite / Next.js |
> | 状态管理 | Zustand / Pinia / React Query |
> | UI 库 | Ant Design / Element Plus / shadcn-ui |
> | HTTP 客户端 | axios / ky / fetch 封装 |

## 与后端的协作约定

以下约定来自 [backend/CLAUDE.md](../backend/CLAUDE.md)，前端调用时**必须遵守**：

### 1. 请求包装（注册/业务类接口）

```ts
interface ApiRequest<T> {
  device: number;    // 见下方 device 编码
  language: number;  // 见下方 language 编码
  data: T;           // 业务字段
}
```

**device 编码（必须与 backend 保持一致）：**
- `1` = iOS
- `2` = Android
- `3` = Web ← **前端使用此值**
- `4` = iPad
- `5` = macOS
- `6` = Windows
- `7` = Linux

**language 编码：**
- `1` = 简体中文
- `2` = 繁体中文
- `3` = 英文

### 2. 响应包装

```ts
interface ApiResponse<T> {
  success: boolean;
  message: string;
  data: T | null;  // 失败时为 null
}
```

### 3. 登录/认证类接口（扁平响应）

```ts
interface LoginResponse {
  success: boolean;
  token: string | null;  // JWT
  message: string;
}
```

JWT 存储建议：HttpOnly Cookie（CSRF 防护）或 localStorage（注意 XSS 风险），后续根据安全策略统一。

### 4. 错误响应（HTTP 非 200）

```ts
interface ErrorResponse {
  error: string;
  message: string;
  code: number;
}
```

## 代码风格

- 注释使用**中文**（与后端保持一致）
- TypeScript 类型与后端 Rust 结构体一一对齐，避免 `any`
- API 客户端集中封装在一处（如 `src/api/`），不要在组件中直接 fetch

## 目录结构

> ⚠️ 待补充：技术栈选定后填写。常见骨架：
>
> ```
> frontend/
> ├── src/
> │   ├── api/          # API 客户端封装（device/language 注入、错误统一处理）
> │   ├── components/   # 可复用 UI 组件
> │   ├── pages/        # 路由页面
> │   ├── stores/       # 状态管理
> │   ├── types/        # 与后端对齐的类型定义
> │   └── utils/
> ├── public/
> ├── package.json
> └── vite.config.ts (或对应配置)
> ```

## 常用命令

> ⚠️ 待补充：技术栈选定后填写（如 `pnpm dev` / `pnpm build` / `pnpm test`）。

## 开发环境

- 后端网关默认监听 `localhost:80`/`443`，本地需配置 hosts 或直连 `localhost`
- 后端开发证书为自签名，浏览器需信任或开发环境关闭 HTTPS

## 扩展指南

新增页面/功能时：
1. 先在 `types/` 定义与后端对齐的类型
2. 在 `api/` 添加调用封装（务必通过统一封装注入 `device`/`language`）
3. 再开发组件/页面

发现重复逻辑时优先抽到 `utils/` 或自定义 Hook（React）/ Composable（Vue）。