asset_helper/frontend/CLAUDE.md

Frontend — Claude Code 项目指南

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

项目状态

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

定位

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

• 与 backend/ 通过 HTTP/JSON 交互，遵循根目录 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，前端调用时必须遵守：

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

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. 响应包装

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

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

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

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

4. 错误响应（HTTP 非 200）

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）。