233 lines
6.3 KiB
Markdown
233 lines
6.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 Vue 3 的 AI 助手 Web 前端应用（Yolo），可在浏览器和 Electron 环境中运行。项目主要用于自动化私信和内容管理，支持多账号管理、轮换策略和 AI 自动回复功能。
|
||
|
||
## 核心技术栈
|
||
|
||
- **前端框架**: Vue 3（使用 Composition API）
|
||
- **构建工具**: Vite
|
||
- **样式**: Tailwind CSS
|
||
- **HTTP 请求**: Axios
|
||
- **运行环境**: 支持浏览器和 Electron 双环境
|
||
|
||
## 常用开发命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 本地开发（默认端口 5173）
|
||
npm run dev
|
||
|
||
# 生产构建
|
||
npm run build
|
||
|
||
# 预览构建产物
|
||
npm run preview
|
||
```
|
||
|
||
## 项目架构
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
src/
|
||
├── api/ # API 接口定义
|
||
├── assets/ # 静态资源（图片等）
|
||
├── components/ # Vue 组件
|
||
├── hooks/ # 可复用的组合式函数
|
||
├── layout/ # 布局组件
|
||
├── locales/ # 国际化配置
|
||
├── pages/ # 页面级组件
|
||
├── router/ # 路由配置
|
||
├── styles/ # 全局样式
|
||
├── types/ # TypeScript 类型定义
|
||
├── utils/ # 工具函数
|
||
└── views/ # 视图组件
|
||
```
|
||
|
||
### 关键架构模式
|
||
|
||
#### 双环境支持设计
|
||
|
||
项目通过 `electronBridge.js` 实现 Web 和 Electron 环境的兼容：
|
||
|
||
- 使用 `isElectron()` 检测运行环境
|
||
- 通过 `window.electronAPI` 访问 Electron 功能
|
||
- 非 Electron 环境中 API 调用会安全降级
|
||
|
||
#### 页面状态管理
|
||
|
||
应用使用三个主要页面状态：
|
||
1. `login` - 登录页面
|
||
2. `config` - 配置页面（账号、AI 设置、任务配置）
|
||
3. `browser` - 浏览器视图（9 个视图分为 A/B/C 三组）
|
||
|
||
状态存储于 `localStorage`：
|
||
- `user_data` - 用户认证信息
|
||
- `autoDm_runConfig` - 自动化运行配置
|
||
|
||
#### 视图分组系统
|
||
|
||
- 9 个视图被分为 3 组（A/B/C），每组 3 个视图
|
||
- 视图 ID 映射：Tab A (1-3), Tab B (4-5), Tab C (7-9)
|
||
- 支持账号轮换和自动切换策略
|
||
|
||
### API 请求架构
|
||
|
||
#### 请求拦截器配置
|
||
|
||
- **开发环境**: `http://192.168.2.22:8101`
|
||
- **生产环境**: `https://crawlclient.api.yolozs.com`
|
||
- **认证**: 通过 `vvtoken` header（登录和租户查询接口除外）
|
||
- **超时时间**: 60 秒
|
||
- **错误码 40400**: 强制退出登录并停止脚本
|
||
|
||
#### 关键 API 端点
|
||
|
||
```javascript
|
||
// 认证相关
|
||
/api/tenant/get-id-by-name - 根据租户名获取 ID
|
||
/api/user/doLogin - 用户登录
|
||
/api/tenant/get-expired-time - 获取账号到期时间
|
||
|
||
// 数据相关
|
||
/api/save_data/hosts_info - 保存主播信息
|
||
/api/save_data/live_host_detail - 查看直播间详情
|
||
/api/common/country_info - 获取国家信息
|
||
|
||
// 账号管理
|
||
/api/account/list - 查询员工列表
|
||
/api/account/managerhosts - 分配主播
|
||
```
|
||
|
||
### Electron 集成要点
|
||
|
||
#### 主要 IPC 通道
|
||
|
||
```javascript
|
||
// 视图控制
|
||
electronAPI.showViews() - 显示浏览器视图
|
||
electronAPI.hideViews() - 隐藏浏览器视图
|
||
electronAPI.switchTab(tabId) - 切换标签组
|
||
electronAPI.switchToView(viewId) - 切换到指定视图
|
||
|
||
// 自动化控制
|
||
electronAPI.stopTikTokAutomation(viewId) - 停止自动化任务
|
||
electronAPI.updateAutomationConfig(config) - 更新自动化配置
|
||
electronAPI.clearAllCache() - 清空所有缓存
|
||
|
||
// 状态监听
|
||
electronAPI.onRotationStatusChanged(callback) - 监听轮换状态变化
|
||
electronAPI.onGreetingStatsChanged(callback) - 监听问候统计变化
|
||
electronAPI.onAutomationLog(callback) - 监听自动化日志
|
||
|
||
// 系统功能
|
||
electronAPI.getAppVersion() - 获取应用版本
|
||
electronAPI.checkHealth() - 健康检查
|
||
```
|
||
|
||
#### 健康检查机制
|
||
|
||
每 5 秒执行一次健康检查：
|
||
- 检测到错误码 40400 时自动退出登录
|
||
- 仅在 Electron 环境且已登录状态下运行
|
||
|
||
## 样式和 UI 规范
|
||
|
||
### Tailwind 自定义配置
|
||
|
||
项目扩展了以下 Tailwind 主题：
|
||
|
||
**主色调**：
|
||
- `primary-500` (#3b82f6) 用于主要操作按钮和强调元素
|
||
- 提供完整的 50-900 梯度色阶
|
||
|
||
**自定义动画**：
|
||
- `fadeIn` - 淡入效果（0.3s）
|
||
- `slideIn` - 滑入效果（0.3s，带 Y 轴位移）
|
||
|
||
### 设计原则
|
||
|
||
- 使用渐变背景增强视觉层次：`from-slate-100 to-slate-200`
|
||
- 卡片设计使用圆角和阴影：`rounded-2xl shadow-xl`
|
||
- 状态指示器使用脉动动画：`animate-pulse`
|
||
- 过渡效果统一使用 `transition-all`
|
||
|
||
## Vite 配置要点
|
||
|
||
### 路径别名
|
||
|
||
```javascript
|
||
'@' -> src/
|
||
```
|
||
|
||
### 开发服务器
|
||
|
||
- 端口：5173
|
||
- 启用网络访问：`host: true`
|
||
|
||
### 构建配置
|
||
|
||
- 输出目录：`dist/`
|
||
- 禁用 sourcemap（生产环境）
|
||
|
||
## 重要约定
|
||
|
||
### 状态管理
|
||
|
||
不使用 Vuex/Pinia，直接使用：
|
||
- Composition API 的 `ref`/`reactive` 管理组件状态
|
||
- `localStorage` 持久化关键配置
|
||
- 事件监听器同步跨组件状态
|
||
|
||
### 组件通信
|
||
|
||
- 父子组件：通过 `props` 和 `emit` 事件
|
||
- 跨页面：通过 `storage` 事件监听 `localStorage` 变化
|
||
- Electron 通信：通过 `window.electronAPI` 的 IPC 通道
|
||
|
||
### 错误处理
|
||
|
||
- API 错误通过 Axios 拦截器统一处理
|
||
- 40400 错误码触发全局登出
|
||
- 使用 `try-catch` 保护可能失败的操作（带空 catch 块的是故意忽略错误）
|
||
|
||
### 代码风格
|
||
|
||
- 使用 ESLint 的 `eslint-disable-line no-empty` 标记故意为空的 catch 块
|
||
- 组件使用 `<script setup>` 语法
|
||
- 优先使用 `const` 和箭头函数
|
||
- 模板中使用 `:class` 动态绑定样式数组
|
||
|
||
## 调试和测试
|
||
|
||
### 环境检测
|
||
|
||
- 开发环境：`window.location.port === '5173'`
|
||
- Electron 环境：检查 `window.electronAPI` 是否存在
|
||
|
||
### 控制台日志规范
|
||
|
||
使用 `[组件名]` 前缀标识日志来源：
|
||
```javascript
|
||
console.log('[App] 收到轮换状态变化:', status)
|
||
console.error('[App] 健康检查失败:', error)
|
||
```
|
||
|
||
## 特殊注意事项
|
||
|
||
1. **更新检查**：应用启动时在 Electron 环境下会强制执行更新检查（`UpdateChecker` 组件）
|
||
|
||
2. **自动登出**：窗口关闭前（`beforeunload`）会自动清除 `localStorage` 中的用户数据
|
||
|
||
3. **并行停止任务**：停止所有任务时使用 `Promise.allSettled` 并行处理 9 个视图，避免串行等待
|
||
|
||
4. **配置持久化**：账号分组配置变化时通过 `storage` 事件跨组件同步
|
||
|
||
5. **视图映射**：视图 ID 与账号的映射关系通过 `viewAccountMap` 计算（每组 3 个账号）
|