asset_helper/frontend/CLAUDE.md

Frontend — Claude Code 项目指南

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

项目状态

技术栈已确定，项目已初始化。

维度	选型
框架	React 18 + TypeScript 5
构建	Vite 6
UI 库	Ant Design 5 + @ant-design/icons
路由	React Router 6
状态管理	Zustand（客户端状态）
HTTP 客户端	Axios（API 封装在 src/api/）

定位

frontend/ 是 asset_helper 的 Web 管理后台，调用后端 API（通过 Nginx 网关暴露）。

• 与 backend/ 通过 HTTP/JSON 交互，遵循根目录 CLAUDE.md 中定义的跨端契约
• 与 app/（移动/桌面端）共享后端，但 UI 实现独立
• 当前为后台管理系统，后续可扩展为面向用户的 Web 端

Docker 开发与部署

开发环境（热更新，不污染物理机）

cd frontend
docker-compose -f docker-compose.dev.yml up --build

• 访问：http://localhost:3000
• 源码通过 volume 挂载，修改后自动热更新
• API 请求通过 Vite proxy 转发到后端网关（默认 http://host.docker.internal:80）

如需修改后端地址：

VITE_API_BASE_URL=http://your-backend:80 docker-compose -f docker-compose.dev.yml up

生产构建与部署

cd frontend
docker-compose up --build

• 访问：http://localhost:20080（端口可通过 ADMIN_WEB_PORT 环境变量修改）
• 多阶段构建：Node 构建 → Nginx 提供静态文件
• Nginx 代理 /api/* 到后端网关容器

与后端的协作约定

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

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

interface ApiRequest<T> {
  device: number;    // 前端固定使用 Device.Web = 3
  language: number;  // 默认 Language.SimplifiedChinese = 1
  data: T;           // 业务字段
}

device 编码：

• 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 存储策略：存于 Zustand 内存中（页面刷新丢失，需重新登录）。如需持久化，可改为 localStorage，但需注意 XSS 风险。

4. 错误响应（HTTP 非 200）

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

目录结构

frontend/
├── docker/
│   ├── Dockerfile          # 生产多阶段构建
│   ├── Dockerfile.dev      # 开发环境（volume 挂载源码）
│   └── nginx.conf          # 生产 Nginx SPA 配置
├── src/
│   ├── api/
│   │   ├── client.ts       # Axios 封装（device/language 注入、JWT、错误处理）
│   │   └── auth.ts         # 认证相关 API
│   ├── components/         # 可复用 UI 组件（待扩展）
│   ├── hooks/              # 自定义 Hooks（待扩展）
│   ├── layouts/
│   │   └── MainLayout.tsx  # 后台主布局（侧边栏 + 头部 + 内容区）
│   ├── pages/
│   │   ├── LoginPage.tsx   # 登录页（账号/邮箱切换）
│   │   ├── DashboardPage.tsx  # 仪表盘首页
│   │   └── NotFoundPage.tsx   # 404
│   ├── router/
│   │   └── index.tsx       # 路由配置（登录守卫 + 受保护路由）
│   ├── stores/
│   │   └── auth.ts         # Zustand 认证状态（token + login/logout）
│   ├── types/
│   │   ├── api.ts          # 通用 API 类型（device/language 枚举、包装类型）
│   │   └── auth.ts         # 认证相关类型
│   ├── utils/
│   │   └── storage.ts      # localStorage 封装（带前缀隔离）
│   ├── App.tsx             # 根组件（ConfigProvider + RouterProvider）
│   └── main.tsx            # 入口
├── docker-compose.dev.yml  # 开发编排（热更新）
├── docker-compose.yml      # 生产编排
├── index.html
├── package.json
├── tsconfig.json / tsconfig.app.json / tsconfig.node.json
└── vite.config.ts

API 调用规范

必须使用封装函数，禁止直接 fetch/axios：

// ✅ 业务接口（自动注入 device/language）
import { apiPost, apiGet } from '@/api/client'
const data = await apiPost<RequestType, ResponseType>('/api/v1/users/xxx', payload)

// ✅ 认证接口（扁平格式，不包装）
import { loginAccount } from '@/api/auth'
const result = await loginAccount({ account: 'xxx', password: 'xxx' })

代码风格

• 注释使用中文（与后端保持一致）
• TypeScript 类型与后端 Rust 结构体一一对齐，禁止 any
• API 调用集中在 src/api/，不在组件中直接写 axios
• 路由守卫在 src/router/index.tsx 中统一配置

常用命令

命令	说明
npm install	安装依赖（开发容器内自动执行）
npm run dev	启动开发服务器（容器内）
npm run build	生产构建
npm run preview	预览生产构建

开发环境

• 后端网关默认通过 Docker 网络或 host.docker.internal 访问
• 开发容器内 Vite 监听 0.0.0.0:5173，映射到宿主机 3000
• 如需后端使用 HTTPS 自签名证书，Vite proxy 已配置 secure: false

扩展指南

新增页面/功能时：

1. 先在 types/ 定义与后端对齐的类型
2. 在 api/ 添加调用封装（务必通过统一封装注入 device/language）
3. 在 pages/ 创建页面组件
4. 在 router/index.tsx 添加路由
5. 如需加入侧边栏菜单，在 layouts/MainLayout.tsx 的 menuItems 中配置

发现重复逻辑时优先抽到 utils/ 或自定义 Hook。