dataservice-yy/VAA_SYNC_README.md

# VAA录音盒HTTP同步服务

## 📋 概述

基于合肥实现方案，通过HTTP API从VAA录音盒设备定时拉取录音数据并上传到OSS。

## 🔧 核心特性

1. **HTTP API通信** - 使用录音盒提供的RESTful API
2. **定时同步** - 每2小时自动执行一次同步任务
3. **增量同步** - 根据上次同步时间，只拉取新增录音
4. **自动登录** - 每次同步前自动认证
5. **通道状态更新** - 同步时更新设备通道状态
6. **OSS上传** - 录音文件自动上传到对象存储
7. **完整日志** - 记录每次同步的结果

## 📊 数据流程

```
┌──────────────┐
│ 定时触发      │ (每2小时)
└──────┬───────┘
       ↓
┌──────────────┐
│ 查询设备列表  │ (YYDC_YYSB表)
└──────┬───────┘
       ↓
┌──────────────┐
│ HTTP登录认证  │ (/authorize)
└──────┬───────┘
       ↓
┌──────────────┐
│ 获取通道状态  │ (/service/running/channel)
└──────┬───────┘
       ↓
┌──────────────┐
│ 获取录音列表  │ (/service/record/~/time[开始,结束])
└──────┬───────┘
       ↓
┌──────────────┐
│ 下载录音文件  │ (HTTP下载)
└──────┬───────┘
       ↓
┌──────────────┐
│ 上传到OSS     │ (FileUploadUtil)
└──────┬───────┘
       ↓
┌──────────────┐
│ 保存到数据库  │ (YYDC_YYTH表)
└──────┬───────┘
       ↓
┌──────────────┐
│ 记录同步日志  │ (YYDC_TBRZ表)
└──────────────┘
```

## 🗄️ 数据库表要求

### YYDC_YYSB (语音设备表)

必需字段：
- `ID` - 设备ID
- `UUID` - 设备UUID
- `ORGAN_NAME` - 机构名称
- `ORGAN_ID` - 机构ID
- `IP` - 设备IP地址
- `PORT` - 设备端口（默认80）
- `SBYH` - 设备用户名
- `SBMM` - 设备密码
- `SFYX_ST` - 是否有效（'1':有效）

### YYDC_SBTD (设备通道表)

必需字段：
- `ID` - 通道ID
- `UUID` - 关联设备UUID
- `TDHM` - 通道号码
- `PHONE` - 电话号码
- `TDZT` - 通道状态
- `SFYX_ST` - 是否有效

### YYDC_YYTH (通话记录表)

必需字段：
- `ID` - 通话ID（格式：设备ID_录音ID_开始时间戳）
- `ORGAN_NAME`, `ORGAN_ID` - 机构信息
- `YYSB_ID` - 语音设备ID
- `SBTD_ID` - 设备通道ID
- `THFX` - 通话方向（'1':呼出, '0':呼入）
- `PHONE`, `ZJHM`, `BJHM` - 号码信息
- `THSC` - 通话时长（秒）
- `KSSJ`, `JSSJ` - 开始/结束时间
- `LYDZ` - 录音地址（OSS URL）
- `LYMC` - 录音文件名

### YYDC_TBRZ (同步日志表)

必需字段：
- `CODE` - 同步代码（格式：YYDC.AUDIO(设备ID)）
- `KSSJ` - 开始时间
- `JSSJ` - 结束时间
- `GXSJ` - 更新时间
- `TBBZ` - 同步标志（'1':成功, '0':失败）
- `TBSM` - 同步说明

## ⚙️ 配置说明

### application.yml

```yaml
# 本地IP（用于生成录音访问URL）
server:
  local-ip: 127.0.0.1

# VAA同步配置
vaa-sync:
  download-path: /tmp/vaa-recordings  # 临时下载目录
  sync-interval-cron: "0 0 0/2 * * ?" # 每2小时同步
```

## 🚀 使用方法

### 1. 配置设备信息

在数据库中插入设备信息：

```sql
INSERT INTO YYDC_YYSB (ID, UUID, ORGAN_NAME, ORGAN_ID, IP, PORT, SBYH, SBMM, SFYX_ST)
VALUES ('device-001', 'uuid-001', '黄山市局', 1001, '192.168.1.100', 80, 'admin', 'admin123', '1');
```

### 2. 配置通道信息

```sql
INSERT INTO YYDC_SBTD (ID, UUID, TDHM, PHONE, SFYX_ST)
VALUES ('channel-001', 'uuid-001', '1', '13800138000', '1');
```

### 3. 启动应用

```bash
mvn spring-boot:run
```

应用启动后，定时任务会自动执行。

### 4. 手动触发（可选）

可以通过注入 `VaaSyncService` 并调用 `executeSync()` 方法手动触发同步。

## 📝 VAA录音盒API说明

### 1. 登录认证

```
GET http://{IP}/authorize?username={用户}&password={密码}
```

### 2. 获取通道状态

```
GET http://{IP}/service/running/channel
```

返回示例：
```json
[
  {"ch": "1", "state": "1"},
  {"ch": "2", "state": "0"}
]
```

### 3. 获取录音列表

```
GET http://{IP}/service/record/~/time[开始时间戳,结束时间戳]
```

返回示例：
```json
[
  {
    "id": "12345",
    "channel": "1",
    "phone": "13800138000",
    "file": "/recordings/20260520/xxx.wav",
    "begtime": 1716192000,
    "endtime": 1716192120,
    "state": "1"
  }
]
```

### 4. 下载录音文件

```
GET http://{IP}{文件路径}
```

## 🔍 日志说明

同步过程会输出详细日志：

```
========== 定时任务触发: VAA录音盒同步 ==========
开始同步设备: ID=device-001, 机构=黄山市局, IP=192.168.1.100:80
正在登录设备...
登录成功
获取录音列表: http://192.168.1.100/service/record/~/time[1716105600,1716192000]
获取到 5 条录音记录
开始下载录音: /recordings/20260520/xxx.wav
录音下载完成: /tmp/vaa-recordings/20260520/uuid-001/xxx.wav
录音上传OSS: https://oss.example.com/voice/黄山市局/20260520/xxx.wav
插入通话记录: device-001_12345_1716192000
设备同步完成: ID=device-001, 成功5条
========== VAA录音盒同步任务完成 ==========
```

## ⚠️ 注意事项

1. **网络连接** - 确保服务器能访问录音盒设备的IP和端口
2. **存储空间** - 确保 `/tmp/vaa-recordings` 有足够的空间
3. **时间同步** - 确保服务器时间与录音盒时间一致
4. **并发控制** - 每个设备独立执行，不会相互阻塞
5. **错误处理** - 单个设备失败不影响其他设备

## 🔄 与FTP方式的对比

| 特性 | HTTP API方式 | FTP方式 |
|------|-------------|---------|
| 连接方式 | HTTP RESTful API | FTP协议 |
| 认证方式 | URL参数认证 | 用户名密码 |
| 数据获取 | JSON API | 解析.txt索引文件 |
| 文件下载 | HTTP GET | FTP RETR |
| 实时性 | 更好（API直接查询） | 依赖文件生成 |
| 复杂度 | 较低 | 较高 |

## 📞 技术支持

如有问题，请检查：
1. 设备IP、端口、用户名、密码是否正确
2. 网络是否能访问设备
3. 数据库表结构是否正确
4. 日志中的错误信息