131 lines
3.6 KiB
Markdown
131 lines
3.6 KiB
Markdown
# 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）。
|