cpzs-backend/大乐透数据导入使用说明.md

# 大乐透数据导入使用说明

## 概述

本文档介绍如何使用大乐透数据导入功能，将包含D1工作表的Excel文件数据导入到`dlt_draw_record`数据库表中。

## 文件结构

### 新增文件

1. **DltDataImporter.java** - 大乐透数据导入工具类
   - 位置：`src/main/java/com/xy/xyaicpzs/util/DltDataImporter.java`
   - 功能：解析Excel文件中的D1工作表，将数据导入到数据库

2. **DltTestRunner.java** - 测试运行器
   - 位置：`src/main/java/com/xy/xyaicpzs/util/DltTestRunner.java`
   - 功能：提供手动测试导入功能

3. **DltImportController.java** - 导入控制器
   - 位置：`src/main/java/com/xy/xyaicpzs/controller/DltImportController.java`
   - 功能：提供RESTful API接口

## Excel文件格式要求

### D1工作表结构（开奖数据）

Excel文件必须包含名为"D1"的工作表，数据格式如下：

| 列 | 字段名 | 数据类型 | 描述 | 示例 |
|----|--------|----------|------|------|
| A | 开奖期号 | 字符串 | 大乐透期号 | 07001 |
| B | 开奖日期 | 日期 | 开奖日期 | 2007-05-30 |
| C | 前区1 | 整数 | 前区第1个号码 | 22 |
| D | 前区2 | 整数 | 前区第2个号码 | 24 |
| E | 前区3 | 整数 | 前区第3个号码 | 29 |
| F | 前区4 | 整数 | 前区第4个号码 | 31 |
| G | 前区5 | 整数 | 前区第5个号码 | 33 |
| H | 后区1 | 整数 | 后区第1个号码 | 4 |
| I | 后区2 | 整数 | 后区第2个号码 | 11 |

### 数据要求

- 第一行为标题行，从第二行开始为数据行
- 开奖期号必须唯一，不能为空
- 开奖日期支持多种格式：yyyy-MM-dd、yyyy/MM/dd、yyyy年MM月dd日等
- 前区号码范围：1-35
- 后区号码范围：1-12
- 所有球号字段都不能为空

### D3工作表结构（前区历史数据）

Excel文件必须包含名为"D3"的工作表，数据格式如下：

| 列 | 字段名 | 数据类型 | 描述 | 示例 |
|----|--------|----------|------|------|
| A | 球号 | 整数 | 前区球号 | 1 |
| B | 出现频次 | 整数 | 全部历史出现频次 | 410 |
| C | 出现频率% | 小数 | 出现频率百分比 | 14.84 |
| D | 平均隐现期 | 整数 | 平均隐现期次数 | 6 |
| E | 最长隐现期 | 整数 | 最长隐现期次数 | 34 |
| F | 最多连出期 | 整数 | 最多连出期次数 | 4 |
| G | 活跃系数 | 小数 | 活跃系数 | 101.47 |
| H | 出现频次 | 整数 | 最近100期出现频次 | 12 |
| I | 平均隐现期 | 小数 | 最近100期平均隐现期 | 8.33 |
| J | 当前隐现期 | 整数 | 当前隐现期 | 1 |
| K | 最多连出期 | 整数 | 最近100期最多连出期 | 1 |
| L | 活跃系数 | 小数 | 最近100期活跃系数 | 2.97 |
| M | 排位 | 整数 | 历史数据排位 | 1 |
| N | 球号 | 整数 | 排行球号 | 29 |
| O | 活跃系数 | 小数 | 排行活跃系数 | 117.56 |
| P | 排位 | 整数 | 百期数据排位 | 1 |
| Q | 球号 | 整数 | 百期排行球号 | 20 |
| R | 活跃系数 | 小数 | 百期排行活跃系数 | 5.20 |

### 数据要求（D3工作表）

- 第一行为标题行，从第二行开始为数据行
- 球号必须唯一，不能为空
- 前区球号范围：1-35
- 排位数据必须完整
- 活跃系数支持小数

### D4工作表结构（后区历史数据）

Excel文件必须包含名为"D4"的工作表，数据格式与D3相同：

| 列 | 字段名 | 数据类型 | 描述 | 示例 |
|----|--------|----------|------|------|
| A | 球号 | 整数 | 后区球号 | 1 |
| B | 出现频次 | 整数 | 全部历史出现频次 | 150 |
| C | 出现频率% | 小数 | 出现频率百分比 | 12.50 |
| D | 平均隐现期 | 整数 | 平均隐现期次数 | 8 |
| E | 最长隐现期 | 整数 | 最长隐现期次数 | 25 |
| F | 最多连出期 | 整数 | 最多连出期次数 | 3 |
| G | 活跃系数 | 小数 | 活跃系数 | 95.20 |
| H | 出现频次 | 整数 | 最近100期出现频次 | 8 |
| I | 平均隐现期 | 小数 | 最近100期平均隐现期 | 12.50 |
| J | 当前隐现期 | 整数 | 当前隐现期 | 2 |
| K | 最多连出期 | 整数 | 最近100期最多连出期 | 2 |
| L | 活跃系数 | 小数 | 最近100期活跃系数 | 4.00 |
| M | 排位 | 整数 | 历史数据排位 | 1 |
| N | 球号 | 整数 | 排行球号 | 12 |
| O | 活跃系数 | 小数 | 排行活跃系数 | 105.50 |
| P | 排位 | 整数 | 百期数据排位 | 1 |
| Q | 球号 | 整数 | 百期排行球号 | 8 |
| R | 活跃系数 | 小数 | 百期排行活跃系数 | 4.50 |

### 数据要求（D4工作表）

- 第一行为标题行，从第二行开始为数据行
- 球号必须唯一，不能为空
- 后区球号范围：1-12
- 排位数据必须完整
- 活跃系数支持小数

## API接口

### 1. 上传文件导入开奖数据

**接口地址：** `POST /dlt/upload-draw-data`

**描述：** 上传Excel文件并导入大乐透开奖数据（D1工作表，会清空现有数据）

**参数：**
- `file`: MultipartFile类型，Excel文件（.xlsx格式）

**权限：** 需要管理员权限

**返回示例：**
```json
{
    "code": 0,
    "success": true,
    "message": "操作成功",
    "data": "大乐透开奖数据导入成功"
}
```

### 2. 上传文件导入前区历史数据

**接口地址：** `POST /dlt/upload-frontend-history`

**描述：** 上传Excel文件并导入大乐透前区历史数据（D3工作表，会清空现有数据）

**参数：**
- `file`: MultipartFile类型，Excel文件（.xlsx格式）

**权限：** 需要管理员权限

**返回示例：**
```json
{
    "code": 0,
    "success": true,
    "message": "操作成功",
    "data": "大乐透前区历史数据导入成功"
}
```

### 3. 上传文件导入后区历史数据

**接口地址：** `POST /dlt/upload-backend-history`

**描述：** 上传Excel文件并导入大乐透后区历史数据（D4工作表，会清空现有数据）

**参数：**
- `file`: MultipartFile类型，Excel文件（.xlsx格式）

**权限：** 需要管理员权限

**返回示例：**
```json
{
    "code": 0,
    "success": true,
    "message": "操作成功",
    "data": "大乐透后区历史数据导入成功"
}
```

### 4. 追加导入开奖数据

**接口地址：** `POST /dlt/upload-append-draw`

**描述：** 上传Excel文件并追加导入大乐透开奖数据（D1工作表，不清空现有数据，跳过重复记录）

**参数：**
- `file`: MultipartFile类型，Excel文件（.xlsx格式）

**权限：** 需要管理员权限

**返回示例：**
```json
{
    "code": 0,
    "success": true,
    "message": "操作成功",
    "data": "大乐透开奖数据追加导入成功"
}
```

### 5. 文件路径导入开奖数据（测试用）

**接口地址：** `POST /dlt/import-draw-by-path`

**描述：** 根据服务器上的文件路径导入开奖数据

**参数：**
- `filePath`: 字符串，服务器上的Excel文件路径

**权限：** 需要管理员权限

### 6. 文件路径导入前区历史数据（测试用）

**接口地址：** `POST /dlt/import-frontend-by-path`

**描述：** 根据服务器上的文件路径导入前区历史数据

**参数：**
- `filePath`: 字符串，服务器上的Excel文件路径

**权限：** 需要管理员权限

### 7. 文件路径导入后区历史数据（测试用）

**接口地址：** `POST /dlt/import-backend-by-path`

**描述：** 根据服务器上的文件路径导入后区历史数据

**参数：**
- `filePath`: 字符串，服务器上的Excel文件路径

**权限：** 需要管理员权限

## 使用步骤

### 1. 准备Excel文件

#### 开奖数据文件（D1工作表）
1. 创建包含D1工作表的Excel文件（.xlsx格式）
2. 按照上述D1格式要求填入大乐透开奖数据
3. 确保数据完整性和格式正确性

#### 前区历史数据文件（D3工作表）
1. 创建包含D3工作表的Excel文件（.xlsx格式）
2. 按照上述D3格式要求填入前区历史数据
3. 确保数据完整性和格式正确性

#### 后区历史数据文件（D4工作表）
1. 创建包含D4工作表的Excel文件（.xlsx格式）
2. 按照上述D4格式要求填入后区历史数据
3. 确保数据完整性和格式正确性

### 2. 通过API导入

#### 方式一：文件上传导入开奖数据
```bash
curl -X POST \
  http://localhost:8080/dlt/upload-draw-data \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/your/dlt_draw_data.xlsx'
```

#### 方式二：文件上传导入前区历史数据
```bash
curl -X POST \
  http://localhost:8080/dlt/upload-frontend-history \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/your/dlt_frontend_data.xlsx'
```

#### 方式三：文件上传导入后区历史数据
```bash
curl -X POST \
  http://localhost:8080/dlt/upload-backend-history \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/your/dlt_backend_data.xlsx'
```

#### 方式四：服务器文件路径导入
```bash
# 导入开奖数据
curl -X POST \
  'http://localhost:8080/dlt/import-draw-by-path?filePath=/path/to/server/file.xlsx'

# 导入前区历史数据
curl -X POST \
  'http://localhost:8080/dlt/import-frontend-by-path?filePath=/path/to/server/file.xlsx'

# 导入后区历史数据
curl -X POST \
  'http://localhost:8080/dlt/import-backend-by-path?filePath=/path/to/server/file.xlsx'
```

### 3. 查看导入结果

- 开奖数据导入成功后，数据将保存到`dlt_draw_record`表中
- 前区历史数据导入成功后，数据将保存到四个前区历史相关表中
- 后区历史数据导入成功后，数据将保存到四个后区历史相关表中
- 系统会记录操作历史，可通过操作历史接口查看详细信息
- 查看应用日志了解详细的导入过程和统计信息

## 数据库表结构

### 1. dlt_draw_record表（开奖数据）

```sql
CREATE TABLE IF NOT EXISTS `dlt_draw_record` (
    `id` BIGINT AUTO_INCREMENT COMMENT '唯一标识符' PRIMARY KEY,
    `drawId` VARCHAR(50) NOT NULL COMMENT '开奖期号',
    `drawDate` DATE NOT NULL COMMENT '开奖日期',
    `frontBall1` INT NOT NULL COMMENT '前区1',
    `frontBall2` INT NOT NULL COMMENT '前区2',
    `frontBall3` INT NOT NULL COMMENT '前区3',
    `frontBall4` INT NOT NULL COMMENT '前区4',
    `frontBall5` INT NOT NULL COMMENT '前区5',
    `backBall1` INT NOT NULL COMMENT '后区1',
    `backBall2` INT NOT NULL COMMENT '后区2',
    `createTime` datetime DEFAULT CURRENT_TIMESTAMP NOT NULL COMMENT '记录创建时间',
    `updateTime` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP NOT NULL COMMENT '记录更新时间'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '大乐透开奖信息表';
```

### 2. dlt_frontend_history_all表（前区全部历史数据）

```sql
CREATE TABLE IF NOT EXISTS `dlt_frontend_history_all` (
    id BIGINT AUTO_INCREMENT COMMENT '唯一标识符' PRIMARY KEY,
    ballNumber INT NOT NULL COMMENT '球号',
    frequencyCount INT NULL COMMENT '出现频次',
    frequencyPercentage FLOAT NULL COMMENT '出现频率%',
    averageHiddenAppear INT NULL COMMENT '平均隐现期(次)',
    maxHiddenInterval INT NULL COMMENT '最长隐现期(次)',
    maxConsecutive INT NULL COMMENT '最多连出期(次)',
    activeCoefficient FLOAT NULL COMMENT '活跃系数'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '大乐透前区全部历史数据表';
```

### 3. dlt_frontend_history_100表（前区最近100期数据）

```sql
CREATE TABLE IF NOT EXISTS `dlt_frontend_history_100` (
    id BIGINT AUTO_INCREMENT COMMENT '唯一标识符' PRIMARY KEY,
    ballNumber INT NOT NULL COMMENT '球号',
    frequencyCount INT NULL COMMENT '出现频次',
    averageHiddenAppear FLOAT NULL COMMENT '平均隐现期(次)',
    currentHiddenInterval INT NULL COMMENT '当前隐现期',
    maxConsecutive INT NULL COMMENT '最多连出期(次)',
    activeCoefficient FLOAT NULL COMMENT '活跃系数'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '大乐透前区最近100期数据表';
```

### 4. dlt_frontend_history_top表（前区历史数据排行）

```sql
CREATE TABLE IF NOT EXISTS `dlt_frontend_history_top` (
    id BIGINT AUTO_INCREMENT COMMENT '唯一标识符' PRIMARY KEY,
    ranking INT NULL COMMENT '排位',
    ballNumber INT NULL COMMENT '球号',
    activeCoefficient FLOAT NULL COMMENT '活跃系数'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '大乐透前区历史数据排行表';
```

### 5. dlt_frontend_history_top_100表（前区百期数据排行）

```sql
CREATE TABLE IF NOT EXISTS `dlt_frontend_history_top_100` (
    id BIGINT AUTO_INCREMENT COMMENT '唯一标识符' PRIMARY KEY,
    ranking INT NULL COMMENT '排位',
    ballNumber INT NULL COMMENT '球号',
    activeCoefficient FLOAT NULL COMMENT '活跃系数'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '大乐透前区百期数据排行表';
```

### 6. dlt_backend_history_all表（后区全部历史数据）

```sql
CREATE TABLE IF NOT EXISTS `dlt_backend_history_all` (
    id BIGINT AUTO_INCREMENT COMMENT '唯一标识符' PRIMARY KEY,
    ballNumber INT NOT NULL COMMENT '球号',
    frequencyCount INT NULL COMMENT '出现频次',
    frequencyPercentage FLOAT NULL COMMENT '出现频率%',
    averageHiddenAppear INT NULL COMMENT '平均隐现期(次)',
    maxHiddenInterval INT NULL COMMENT '最长隐现期(次)',
    maxConsecutive INT NULL COMMENT '最多连出期(次)',
    activeCoefficient FLOAT NULL COMMENT '活跃系数'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '大乐透后区全部历史数据表';
```

### 7. dlt_backend_history_100表（后区最近100期数据）

```sql
CREATE TABLE IF NOT EXISTS `dlt_backend_history_100` (
    id BIGINT AUTO_INCREMENT COMMENT '唯一标识符' PRIMARY KEY,
    ballNumber INT NOT NULL COMMENT '球号',
    frequencyCount INT NULL COMMENT '出现频次',
    averageHiddenAppear FLOAT NULL COMMENT '平均隐现期(次)',
    currentHiddenInterval INT NULL COMMENT '当前隐现期',
    maxConsecutive INT NULL COMMENT '最多连出期(次)',
    activeCoefficient FLOAT NULL COMMENT '活跃系数'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '大乐透后区最近100期数据表';
```

### 8. dlt_backend_history_top表（后区历史数据排行）

```sql
CREATE TABLE IF NOT EXISTS `dlt_backend_history_top` (
    id BIGINT AUTO_INCREMENT COMMENT '唯一标识符' PRIMARY KEY,
    ranking INT NULL COMMENT '排位',
    ballNumber INT NULL COMMENT '球号',
    activeCoefficient FLOAT NULL COMMENT '活跃系数'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '大乐透后区历史数据排行表';
```

### 9. dlt_backend_history_top_100表（后区百期数据排行）

```sql
CREATE TABLE IF NOT EXISTS `dlt_backend_history_top_100` (
    id BIGINT AUTO_INCREMENT COMMENT '唯一标识符' PRIMARY KEY,
    ranking INT NULL COMMENT '排位',
    ballNumber INT NULL COMMENT '球号',
    activeCoefficient FLOAT NULL COMMENT '活跃系数'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '大乐透后区百期数据排行表';
```

## 错误处理

### 常见错误及解决方案

1. **文件格式错误**
   - 错误：`只支持.xlsx格式的Excel文件`
   - 解决：确保上传的是.xlsx格式的Excel文件

2. **工作表不存在**
   - 错误：`未找到D1工作表`
   - 解决：确保Excel文件包含名为"D1"的工作表

3. **数据不完整**
   - 错误：`第X行数据不完整，跳过`
   - 解决：检查对应行的数据，确保所有必需字段都有值

4. **日期格式错误**
   - 错误：`第X行开奖日期为空，跳过`
   - 解决：检查日期格式，支持yyyy-MM-dd、yyyy/MM/dd等格式

5. **权限不足**
   - 错误：`无权限`
   - 解决：确保使用管理员账号登录

## 日志信息

导入过程中会产生详细的日志信息：

- **INFO级别**：导入进度、成功统计
- **WARN级别**：跳过的无效数据行
- **ERROR级别**：导入失败的错误信息
- **DEBUG级别**：每条记录的详细信息（需开启DEBUG日志）

## 性能说明

- 支持批量导入，使用MyBatis-Plus的`saveBatch`方法
- 追加导入时会检查重复记录，避免数据重复
- 大文件导入建议分批处理，避免内存溢出

## 注意事项

1. **数据备份**：导入前建议备份现有数据
2. **权限控制**：所有导入接口都需要管理员权限
3. **文件大小**：注意服务器文件上传大小限制
4. **并发控制**：避免同时进行多个导入操作
5. **操作记录**：所有导入操作都会记录到操作历史表中