全栈项目初始化各端 CLAUDE.md 项目指南

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

frontend/CLAUDE.md

@@ -0,0 +1,130 @@
+# 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）。