FilmFinder - 智能电影推荐系统

FilmFinder 是一个基于 Flask 开发的智能电影推荐系统，集成了协同过滤推荐算法、AI 台词搜索、TMDB 电影数据导入等先进功能，为用户提供个性化的电影推荐服务。

✨ 主要特性

🎬 核心功能

• 个性化推荐：基于用户标签和协同过滤算法的智能推荐
• 电影搜索：支持按电影名称、类型搜索，以及 AI 台词搜索
• 用户系统：完整的用户注册、登录、标签选择功能
• 收藏与评分：用户可以收藏喜欢的电影并为其评分
• 电影详情：详细的电影信息展示，包括封面、简介、评分等

🤖 AI 功能

• AI 台词搜索：通过输入经典台词或角色名称，AI 智能识别并推荐相关电影

🎯 管理员功能

• 电影管理：添加、删除电影，支持批量导入
• TMDB 导入：从 The Movie Database (TMDB) API 导入电影数据
• 数据统计：用户行为分析、电影热度统计、数据可视化

🎨 界面设计

• 现代化 UI：使用 Tailwind CSS 构建的响应式界面
• 数据可视化：使用 ECharts 和 Chart.js 展示统计数据
• 用户体验优化：流畅的交互体验和友好的错误提示

🛠️ 技术栈

后端

• Flask 2.3.3 - Python Web 框架
• SQLAlchemy 3.0.5 - ORM 数据库操作
• SQLite - 轻量级数据库
• NumPy 1.24.3 - 数值计算（用于推荐算法）
• OpenAI API - AI 台词搜索功能
• Requests 2.31.0 - HTTP 请求库

前端

• Tailwind CSS - 实用优先的 CSS 框架
• ECharts - 数据可视化图表库
• Chart.js - 另一个图表库
• Iconify - 图标库

外部 API

• TMDB API - 电影数据库 API
• DashScope API - 阿里云 AI 服务（用于台词搜索）

📋 系统要求

• Python 3.7+
• pip（Python 包管理器）

🚀 快速开始

1. 克隆项目

git clone <repository-url>
cd FilmFinder

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量（可选）

如果需要使用 AI 台词搜索功能，需要设置 DashScope API 密钥：

# Windows
set DASHSCOPE_API_KEY=your_api_key_here

# Linux/Mac
export DASHSCOPE_API_KEY=your_api_key_here

注意：如果不设置 API 密钥，系统会自动切换到演示模式，仍可使用部分功能。

4. 初始化数据库

数据库会在首次运行时自动创建。如果需要重置数据库，可以运行：

python reset_db.py

5. 启动应用

python app.py

应用将在 http://127.0.0.1:5000 启动。

6. 访问系统

• 打开浏览器访问 http://127.0.0.1:5000
• 默认管理员账户：
  • 用户名：admin
  • 密码：123456

📖 使用指南

普通用户

1. 注册账户

   • 访问注册页面，创建新账户
   • 首次登录需要选择至少 3 个电影标签（最多 10 个）

2. 浏览电影

   • 首页会显示基于您选择的标签的推荐电影
   • 点击"推荐"页面查看个性化推荐

3. 搜索电影

   • 使用搜索框按电影名称搜索
   • 使用 AI 台词搜索功能，输入经典台词或角色名称

4. 收藏与评分

   • 在电影详情页可以收藏电影
   • 可以为电影评分（1-5 星）

管理员

1. 登录管理员账户

   • 使用默认管理员账户登录

2. 添加电影

   • 访问"管理员" -> "添加电影"
   • 填写电影信息（标题、类型、年份、简介、封面等）

3. 从 TMDB 导入

   • 访问"管理员" -> "TMDB 导入"
   • 搜索电影并一键导入

4. 查看统计

   • 访问"管理员" -> "数据统计"
   • 查看用户行为、电影热度等数据可视化

5. 删除电影

   • 在电影详情页或管理后台删除电影
   • 系统会自动清理相关的用户行为数据

📁 项目结构

FilmFinder/
├── app.py                 # Flask 主应用文件
├── models.py              # 数据库模型定义
├── requirements.txt       # Python 依赖包列表
├── reset_db.py           # 数据库重置脚本
├── auto-add-script.py     # 自动添加电影脚本
├── clearup.py            # 清理脚本
├── movies.json           # 电影数据 JSON 文件
├── instance/             # Flask 实例文件夹（数据库文件）
├── static/               # 静态资源文件夹
│   ├── covers/          # 电影封面图片
│   └── vendor/          # 第三方前端库
└── templates/            # HTML 模板文件夹
    ├── index.html       # 首页
    ├── login.html       # 登录页
    ├── register.html    # 注册页
    ├── detail.html      # 电影详情页
    ├── recommend.html   # 推荐页
    ├── admin_dashboard.html  # 管理员后台
    └── ...

🔧 配置说明

数据库配置

默认使用 SQLite 数据库，数据库文件位于 instance/movie_recommend.db。

如需修改数据库配置，编辑 app.py 中的数据库 URI：

app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///movie_recommend.db'

TMDB API 配置

系统已内置 TMDB API 密钥，支持多个镜像地址，自动回退机制确保在网络不稳定时仍可使用本地数据。

推荐算法

系统使用基于协同过滤的推荐算法：

• 基于用户选择的标签进行初始推荐
• 根据用户行为（评分、收藏）动态调整推荐
• 使用余弦相似度计算电影相似性

🐛 常见问题

Q: 启动时提示数据库错误？

A: 删除 instance/movie_recommend.db 文件，重新运行应用会自动创建数据库。

Q: AI 台词搜索不工作？

A: 检查是否设置了 DASHSCOPE_API_KEY 环境变量。未设置时会自动切换到演示模式。

Q: TMDB 导入失败？

A: 系统支持多个 TMDB 镜像，会自动尝试连接。如果所有镜像都失败，会使用本地电影数据库。

Q: 如何重置管理员密码？

A: 运行 reset_db.py 重置数据库，或直接在数据库中修改密码哈希值。

📝 开发说明

添加新功能

1. 在 app.py 中添加路由和业务逻辑
2. 如需新数据模型，在 models.py 中定义
3. 在 templates/ 中添加对应的 HTML 模板

数据库迁移

当前使用 SQLite，如需迁移到其他数据库：

1. 修改 app.py 中的数据库 URI
2. 运行应用，SQLAlchemy 会自动创建表结构

📄 许可证

本项目为课程设计项目，仅供学习使用。

🙏 致谢

• The Movie Database (TMDB) - 提供电影数据 API
• DashScope - 提供 AI 服务
• Flask 社区 - 优秀的 Python Web 框架

📞 联系方式

如有问题或建议，欢迎提交 Issue 或 Pull Request。

---

FilmFinder - 发现你的下一部好电影 🎬