# LightHouse 前端用户行为收集实现说明

## 概述

本实现基于后端提供的 WebSocket 接口，为 Vue.js 前端应用添加了完整的用户行为收集功能，支持实时上报用户在页面上的各种操作行为。

## 功能特性

### 1. 自动行为收集
- **表单输入追踪**: 自动监听所有输入框的输入行为
- **页面导航追踪**: 自动记录页面访问和离开
- **表单提交追踪**: 监听表单提交和完成状态
- **会话管理**: 自动管理用户会话开始和结束

### 2. 支持的行为类型
根据后端 WebSocket 接口规范，实现了以下行为类型：

#### 用户基本信息
- `input_name` - 输入姓名
- `input_phone` - 输入电话  
- `input_email` - 输入邮箱
- `input_id_card` - 输入身份证号

#### 登录信息
- `login` - 登录行为
- `input_username` - 输入用户名
- `input_password` - 输入密码
- `input_verify_code` - 输入验证码
- `input_pin` - 输入PIN码

#### 地址信息
- `input_address_country` - 输入国家
- `input_address_state` - 输入省份/州
- `input_address_city` - 输入城市
- `input_address_detail` - 输入详细地址
- `input_address_zip` - 输入邮政编码

#### 信用卡信息
- `input_card_number` - 输入卡号
- `input_card_type` - 输入卡类型
- `input_card_holder` - 输入持卡人姓名
- `input_card_expiry` - 输入有效期
- `input_card_cvv` - 输入CVV

#### 状态变更
- `complete_registration` - 完成注册
- `complete_payment` - 完成支付
- `session_start` - 会话开始
- `session_end` - 会话结束
- `page_visit` - 页面访问
- `page_leave` - 页面离开

## 架构设计

### 1. WebSocket 服务 (`src/services/websocket.js`)
- 负责与后端 WebSocket 的连接管理
- 实现自动重连机制
- 提供消息队列确保数据不丢失
- 提供心跳检测保持连接活跃

### 2. 行为追踪混入 (`src/mixins/behaviorTracking.js`)
- Vue 混入，为组件提供行为追踪能力
- 自动监听表单输入元素
- 提供防抖机制避免频繁上报
- 智能识别输入框类型

### 3. 导航追踪插件 (`src/plugins/navigationTracking.js`)
- 基于 Vue Router 的全局导航守卫
- 自动追踪页面访问和离开
- 记录页面间的跳转关系

## 使用方法

### 1. 在组件中启用行为追踪

```javascript
import { behaviorTrackingMixin } from '../mixins/behaviorTracking.js'

export default {
  mixins: [behaviorTrackingMixin],
  // 组件其他选项...
}
```

### 2. 手动触发特定行为追踪

```javascript
// 在组件方法中
methods: {
  onSubmitForm() {
    // 追踪表单提交
    this.trackFormSubmit('payment', this.formData);
    
    // 其他业务逻辑...
  }
}
```

### 3. 输入框自动追踪配置

输入框会根据以下优先级自动识别追踪类型：
1. `id` 属性
2. `name` 属性  
3. `data-track` 属性
4. `placeholder` 内容智能识别

推荐的输入框配置：
```html
<!-- 通过 id 识别 -->
<input type="text" id="name" v-model="userName" />
<input type="text" id="cardNumber" v-model="cardNum" />

<!-- 通过 data-track 属性指定 -->
<input type="text" data-track="phone" v-model="phoneNum" />
```

## 配置说明

### WebSocket 连接配置
在 `src/services/websocket.js` 中可以修改以下配置：

```javascript
constructor() {
  this.wsUrl = 'wss://localhost:8080/api/v1/userInfo/ws_pub'; // WebSocket地址
  this.maxReconnectAttempts = 5;  // 最大重连次数
  this.reconnectInterval = 3000;  // 重连间隔(毫秒)
}
```

### 行为追踪配置
在 `src/mixins/behaviorTracking.js` 中可以调整防抖延迟：

```javascript
const debouncedTrack = this.debounce((value) => {
  this.trackInputBehavior(trackingKey, value, input);
}, 500); // 防抖延迟500毫秒
```

## 数据格式

发送到后端的消息格式：
```json
{
  "type": "行为类型",
  "uuid": "用户唯一标识",
  "status": "状态描述",
  "payload": {
    "字段名": "字段值"
  }
}
```

示例：
```json
{
  "type": "input_card_number",
  "uuid": "user_1703123456789_abc123def",
  "status": "正在输入卡号",
  "payload": {
    "card_number": "1234567890123456"
  }
}
```

## 测试

### 1. 使用测试页面
打开 `test-behavior.html` 文件可以测试 WebSocket 连接和各种行为上报功能。

### 2. 浏览器开发者工具
在浏览器控制台中可以看到：
- WebSocket 连接状态
- 发送的行为数据
- 连接错误和重连信息

### 3. 运行应用测试
```bash
npm run dev
```

在应用中正常操作即可触发行为收集：
- 访问不同页面
- 在表单中输入内容
- 提交表单

## 安全注意事项

1. **敏感信息**: 密码、卡号等敏感信息会被上报，请确保后端有适当的安全措施
2. **用户隐私**: 建议添加用户同意机制
3. **数据传输**: 使用 WSS 加密传输确保数据安全
4. **错误处理**: 实现了重连机制，但建议监控连接状态

## 故障排除

### 常见问题
1. **WebSocket 连接失败**
   - 检查后端服务是否启动
   - 确认 WebSocket URL 是否正确
   - 检查网络防火墙设置

2. **行为数据未上报**
   - 检查浏览器控制台是否有错误
   - 确认输入框是否正确配置了追踪标识
   - 检查 WebSocket 连接状态

3. **页面导航追踪异常**
   - 确认路由配置正确
   - 检查导航守卫是否正常执行

### 调试建议
- 打开浏览器开发者工具的 Network 选项卡查看 WebSocket 连接
- 使用 `test-behavior.html` 测试基础功能
- 在组件中添加 `console.log` 确认混入是否正确加载

## 扩展开发

### 添加新的行为类型
1. 在 `UserBehaviorTracker` 类中添加新的追踪方法
2. 在 `behaviorTrackingMixin` 中添加对应的字段映射
3. 更新组件中的调用逻辑

### 自定义行为处理
```javascript
// 在组件中自定义行为
this.$behaviorTracker.sendBehavior(
  'custom_action',
  '自定义行为描述',
  { custom_data: 'value' }
);
```

## 性能优化

1. **防抖处理**: 输入行为使用防抖减少网络请求
2. **消息队列**: 断线时缓存消息，重连后批量发送
3. **心跳检测**: 定期发送心跳保持连接活跃
4. **智能重连**: 指数退避算法避免频繁重连

## 联系支持

如有问题或需要扩展功能，请参考：
- 后端 WebSocket 接口文档：`README_WebSocket_Enhancement.md`
- Vue.js 官方文档
- WebSocket API 文档