# 数据采集 (Data Acquisition)

[![Java](https://img.shields.io/badge/Java-21-orange.svg)](https://www.oracle.com/java/)
[![Maven](https://img.shields.io/badge/Maven-3.6+-blue.svg)](https://maven.apache.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

从托育机构信息平台 (tuoyu.cpdrc.org.cn) 爬取数据并导出为 Excel 文件的 Java 爬虫工具。

## 快速开始

```bash
# 编译
mvn compile

# 运行
mvn exec:java -Dexec.mainClass=space.anyi.app.Application
```

运行后会在项目根目录生成 `data.xlsx` 文件。

## 环境要求

| 依赖 | 版本 |
|------|------|
| JDK | 21+ |
| Maven | 3.6+ |

## 运行效果

```
数据已成功保存到Excel文件: data.xlsx
共保存 XXX 条记录
```

## 工作原理

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  启动程序    │────▶│  请求第1页   │────▶│  获取总页数   │────▶│  遍历所有页  │
│  (pageSize= │     │  获取总数     │     │  解析响应     │     │  100ms 间隔  │
│   10,page=1)│     │  解析响应     │     │  决定循环次数  │     │  累积数据     │
└─────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘
                                                                   │
                                                              ┌────▼─────┐
                                                              │ 生成 Excel │
                                                              │ data.xlsx │
                                                              └──────────┘
```

## API 数据源

| 项 | 值 |
|---|---|
| 目标网站 | https://tuoyu.cpdrc.org.cn/ |
| API 地址 | `https://tuoyu.cpdrc.org.cn/bapfopm/pub/search/action/queryInfo?pageSize={n}&pageNum={n}` |
| 请求方式 | GET |
| 分页策略 | 首次请求获取总页数，然后逐页遍历 |
| 请求间隔 | 100ms（防止请求过快） |

### API 响应示例

```json
{
  "code": 200,
  "message": "success",
  "responseData": {
    "dataList": [
      {
        "institution_name": "XX托育中心",
        "institution_other_name": "XX早教",
        "institution_type": "全日制",
        "credit_code": "91XXXXXXXXXXXXXXXX",
        "address": "XX省XX市XX区XX路XX号",
        "zoning_name": "XX区",
        "zoning_code": "110101",
        "finished_time": "2024-01-01"
      }
    ],
    "totalPage": 50,
    "totalRecord": 500,
    "pageSize": 10,
    "pageIndex": 1,
    "offset": 0
  }
}
```

## 输出字段

| 列名 | 说明 | JSON 键 |
|------|------|---------|
| 机构名称 | 托育机构正式名称 | `institution_name` |
| 机构别名 | 机构其他名称 | `institution_other_name` |
| 机构类型 | 机构所属分类 | `institution_type` |
| 信用代码 | 统一社会信用代码 | `credit_code` |
| 地址 | 机构详细地址 | `address`（直接匹配） |
| 所在区域 | 行政区划名称 | `zoning_name` |
| 区域代码 | 行政区划代码 | `zoning_code` |
| 完成时间 | 数据录入/完成时间 | `finished_time` |

## 项目结构

```
src/main/java/space/anyi/app/
├── Application.java          # 入口：发起请求 → 解析 → 导出 Excel
└── model/
    ├── Institution.java      # DTO：机构数据实体，使用 @JsonProperty 映射
    ├── Response.java         # API 响应信封：code, message, responseData
    └── ResponseData.java     # 分页数据包装：dataList, totalPage, totalRecord 等
```

## 数据模型关系

```
Response
├── code (int)
├── message (String)
└── responseData (ResponseData)
    ├── dataList (List<Institution>)
    ├── totalPage (Integer)
    ├── totalRecord (Integer)
    ├── pageSize (Integer)
    ├── pageIndex (Integer)
    └── offset (Integer)
```

## 技术栈

| 组件 | 版本 | 用途 |
|------|------|------|
| Jackson Databind | 2.21.2 | JSON 反序列化 |
| Apache POI | 5.5.1 | Excel 文件生成 |
| Java HttpClient | JDK 内置 | HTTP 请求 |

## 常用命令

| 命令 | 说明 |
|------|------|
| `mvn compile` | 编译项目 |
| `mvn exec:java -Dexec.mainClass=space.anyi.app.Application` | 运行爬虫 |
| `mvn clean` | 清理构建产物 |

## 注意事项

- **输出文件**: `data.xlsx` 不在 `.gitignore` 中，请勿提交
- **Excel 格式**: 使用 `HSSFWorkbook` 生成的是旧版 `.xls` 二进制格式，扩展名虽为 `.xlsx`，实际需用 Excel 兼容模式打开
- **格式升级**: 如需真正的 `.xlsx` 格式，需替换为 `XSSFWorkbook` 并添加 `poi-ooxml` 依赖
- **执行插件**: `mvn exec:java` 依赖 Maven 默认插件解析，`pom.xml` 中未显式配置 `exec-maven-plugin`
- **运行时间**: 数据量较大时请耐心等待，程序会自动处理所有页面

## 常见问题

### Q: 运行时报错 "无法解析依赖"？

确保已正确安装 Maven 并能访问中央仓库。可尝试：

```bash
mvn clean install
```

### Q: 生成的 Excel 文件打不开？

程序使用 HSSF 格式生成的是 `.xls` 格式文件。用 Excel 打开时可能会提示格式不匹配，点击"是"即可正常打开。如需真正的 `.xlsx` 格式，请参考 [格式升级](#注意事项) 说明。

### Q: 如何调整每页数据量？

修改 `Application.java` 中的 `pageSize` 变量即可：

```java
int pageSize = 20; // 改为每页20条
```

注意：过大的 pageSize 可能导致请求超时。