# 项目开发思路与步骤文档 (DEVELOPMENT.md)

本文档详细记录了“电影评分网站影片数据抓取与分析项目”的完整开发思路、每一个步骤以及遇到的关键技术点。

---

## 一、 开发思路 (Development Philosophy)

### 1. 目标设定
开发一个基于 Java 的自动化工具，能够从豆瓣电影 Top 250 这种评分网站上自动化获取结构化的电影信息，并对其进行多维度的统计分析，最终将抽象的数据转化为直观的报告和可视化图表。

### 2. 技术选型
- **核心语言**: Java 11 (利用其成熟的生态和强类型支持)。
- **构建管理**: Maven (自动管理依赖和构建生命周期)。
- **网页爬虫**: Jsoup (轻量级、强大的 HTML 解析库，支持 CSS 选择器)。
- **数据分析**: Java 8+ Stream API (声明式的数据处理方式，高效且易于阅读)。
- **数据序列化**: Jackson (工业级的 JSON 处理库)。
- **可视化**: JFreeChart (老牌稳定的 Java 图表库)。
- **代码简化**: Lombok (通过注解减少冗余的 Getter/Setter)。

### 3. 系统架构 (已升级为 Spring Boot 架构)
采用典型的 MVC 模式进行解耦，并引入 Web 层：
- **Model**: `Movie.java` (JPA 实体), `DirectorStats.java` (统计 DTO)
- **Repository**: `MovieRepository.java` (数据持久化层，支持 H2 数据库)
- **Service**: `MovieService.java` (业务逻辑与 Caffeine 缓存层)
- **Controller**: `DirectorController.java` (Web 接口与路由)
- **View**: Thymeleaf 模板 (响应式前端页面)
- **Crawler**: `MovieCrawler.java` (数据采集组件)

---

## 二、 详细开发步骤 (Step-by-Step Guide)

### 第 1 步：项目初始化与架构升级
- 在 `pom.xml` 中引入 `spring-boot-starter-web`, `spring-boot-starter-data-jpa`, `spring-boot-starter-thymeleaf` 等。
- 配置 H2 内存数据库和 Caffeine 缓存，确保接口响应时间在 500ms 以内。

### 第 2 步：定义数据实体与统计模型
- 将 `Movie.java` 重构为 JPA 实体，增加 `id`, `type` (作品类型), `posterUrl` (海报链接) 等字段。
- 创建 `DirectorStats.java` 用于承载导演作品数量、平均评分、总票房等聚合统计数据。

### 第 3 步：实现数据访问与业务逻辑
- **Repository 层**: 使用 Spring Data JPA 的 `@Query` 编写复杂的聚合查询，支持按导演姓名搜索、作品类型过滤及分页统计。
- **Service 层**: 
    - 集成 Spring Cache (@Cacheable)，对耗时的排行榜查询进行 10 分钟缓存。
    - 实现 `refreshData` 方法，支持在爬虫抓取后自动更新数据库并清空缓存。

### 第 4 步：增强爬虫功能
- 更新 `MovieCrawler.java`，利用 Jsoup 提取电影海报 URL 和作品类型。
- 实现 `DataInitializer` (CommandLineRunner)，在应用启动时自动触发爬取任务并将数据持久化到 H2 数据库。

### 第 5 步：开发响应式 Web 前端
- 使用 **Bootstrap 5** 结合 **Thymeleaf** 开发导演排行榜页面 (`director_rankings.html`)。
- **功能点**:
    - **分页显示**: 默认每页 20 位导演。
    - **搜索与过滤**: 支持导演名模糊搜索和作品类型下拉过滤。
    - **交互设计**: 点击导演姓名可跳转至该导演的作品详情页 (`director_movies.html`)。
    - **加载状态**: 添加 Spinner 加载动画和响应时间监测。

### 第 6 步：性能优化与验证
- 配置 Caffeine 缓存规格，平衡内存占用与响应速度。
- 在 Controller 层记录请求耗时，确保在大数据量下依然满足 <500ms 的性能要求。

---

## 三、 遇到的挑战与解决方案
1. **JPA 聚合查询复杂性**: 导演排行榜涉及 `COUNT`, `AVG`, `SUM` 等多个聚合函数。通过 `new com.movieratings.model.DirectorStats(...)` 构造器投影解决了 JPA 返回原始 Object 数组难以处理的问题。
2. **响应式图片展示**: 海报图片大小不一。通过 CSS `object-fit: cover` 确保在排行榜缩略图和详情页大图显示中均保持比例协调。
3. **缓存一致性**: 爬虫更新数据后，排行榜可能显示旧数据。通过 `@CacheEvict` 在保存数据时自动失效相关缓存。

---

## 四、 后续改进方向
- 实现多线程爬虫以提高抓取速度。
- 引入数据库（如 MySQL 或 SQLite）进行更长期的存储。
- 开发一个简单的 GUI 界面（如 JavaFX）实时展示抓取过程。