# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 常用命令

```bash
pnpm dev          # 启动 Vite 开发服务器
pnpm build        # 生产构建
pnpm preview      # 预览生产构建
```

## 技术栈

Vue 3 (Composition API) + Vite 7 + Pinia + Vue Router + Element Plus + Less + pnpm

## 架构概览

AI 绘画/视频生成前端操作平台，通过 HTTP 接口对接算力调度后端（suanli）和第三方 AI 平台（RunningHub），提交生成任务并轮询结果。

### 关键目录

```
src/
├── main.js              # 入口：创建 Vue 应用，安装 Pinia/Router/VueVirtualScroller
├── router/index.js       # 路由定义 + token 验证守卫
├── stores/              # Pinia 状态管理
│   ├── user.js          # 用户认证、信息
│   └── display.js       # 生成历史列表、UI 状态（滚动、画布等）
├── apis/                # HTTP API 层：纯请求封装，不含业务逻辑
│   ├── auth/            # 认证相关（登录、token 校验、用户信息）
│   └── display/         # 任务创建/轮询/历史、平台模型、收藏/删除
├── components/          # 通用组件
│   ├── dialogBox/       # 生成参数输入面板（核心交互入口），含模型选择、比例、上传等子组件
│   ├── virtual-scroller/# 虚拟滚动列表组件（自定义实现，reverse 模式）
│   └── canvas/          # 图片画布编辑（圆/矩形选区，局部重绘）
├── views/               # 页面（home、login）
├── utils/
│   ├── request.js       # Axios 实例 + 拦截器：统一 Auth（不带 Bearer）+ 按前缀路由 baseURL
│   ├── websocket.js     # 任务生成入口：组装参数 → 调用 API → 20s 轮询直至完成/失败
│   ├── modelApi.js      # 模型业务层：localStorage 每日缓存 + 模型名称→UUID 查找
│   ├── createTask.js    # 调用平台适配器 Playload() 构造任务 body
│   ├── modelConfig.js   # 从远程 JSON 加载 workflow 配置，localStorage 每日缓存
│   └── auth.ts          # token 存取工具（localStorage）
├── config/
│   ├── index.js         # 平台配置入口，导出 runninghub 适配器
│   └── runninghub/      # RunningHub 平台适配器：Playload() 构造和 result() 解析
```

### API 层设计原则

- `src/apis/` 中的函数只做**纯 HTTP 调用**（`service.get/post/delete` 等），不包含缓存、localStorage、业务判断等逻辑
- 缓存、数据转换等业务逻辑放在 `src/utils/` 中，调用 apis 层的原始函数

示例：`utils/modelApi.js` 导入 `apis/display` 的原始 `fetchPlatformModels`，在其上叠加 localStorage 每日缓存和 `getModelId` 查找逻辑。

### 核心数据流

1. 用户在 `dialogBox` 中设置参数（模型、提示词、比例、上传图片等）
2. 点击生成 → `dialogBox:handleStart()` 组装 data（含 modelId、params、imgs、request）
3. 调用 `websocket.js:generate(data, generateData)`
4. `generate()` 内部先通过 `createTask(data)` → `runninghub.Playload()` 构造 RunningHub workflow payload 作为 body
5. 调用 `modelApi.getModelId(type, modelName)` 查找模型 UUID（带 localStorage 每日缓存）
6. 调用 `requestCreateTask(body, sessionId)` → POST `/suanli/v1/tasks`（`{ model_id, body, request }`，携带 `X-Session-Id` 用于预扣费）
7. 返回 task_id → `displayStore.addGeneratingItem()` 在前端列表插入"生成中"条目
8. 每 20 秒轮询 `requestTaskStatus(taskId)` → GET `/suanli/v1/tasks/{task_id}`，completed 时调用 `updateItemToSuccess()` 更新列表

### 接口速查

| 函数 | 端点 | 用途 |
|------|------|------|
| `requestCreateTask` | POST `/suanli/v1/tasks` | 创建生成任务 |
| `requestTaskStatus` | GET `/suanli/v1/tasks/:id` | 查询单个任务状态 |
| `requestTaskHistory` | GET `/suanli/v1/tasks/history` | 历史任务列表（支持 `user_id`/`platform_code`/`page`/`pageSize`） |
| `fetchPlatformModels` | GET `/suanli/v1/platforms/:code/models` | 获取平台模型列表 |
| `cancelOrCollect` | POST `/collect/toggle` | 收藏/取消收藏 |
| `deleteGenerateHistory` | DELETE `/taskRecordHistory/delete` | 删除历史记录 |

### 请求拦截器路由

拦截器统一设置 `Authorization: <token>`（不带 Bearer 前缀），根据 URL 前缀切换后端：

| URL 前缀 | 环境变量 | 示例 target |
|----------|----------|-------------|
| `/suanli` | `VITE_API_TASK_TARGET` | `http://test.xueai.art` |
| `/pay` | `VITE_API_PAY_TARGET` | `http://test.xueai.art` |
| 其他 | `VITE_API_BASE_URL`（默认） | `http://test.xueai.art/newapi/api` |

### 响应格式兼容

响应拦截器同时识别 `code === 0` 和 `status === 0` 两种成功状态。用户信息接口兼容新旧两种格式：`data.userInfo` 嵌套（新）和 `data` 扁平（旧），在 store 的 `getInfo()` 中做了 `const u = res.data.userInfo || res.data` 的兼容处理。

### 平台编码映射

| 类型 | 平台编码 |
|------|----------|
| Painting | `ai_painting_talk` |
| Video | `ai_video_talk` |

映射函数 `getPlatformCode()` 位于 `utils/modelApi.js`。

### 自动导入

- `unplugin-auto-import`：自动导入 Vue/Router/Pinia API，`.vue` 中无需手动 import
- `unplugin-vue-components`：自动注册 `src/components/` 下的组件和 Element Plus 组件
- Element Plus 图标通过 `unplugin-icons` 按需加载

### 路由守卫

`src/router/index.js` 的 `beforeEach` 守卫检查 token 存在性和有效性（调用 `POST /login/validateToken`），无效则跳转 `/login`。支持通过 URL query `?token=xxx` 传入 token。