diff --git a/README.md b/README.md index 3b2c9b9..0355971 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,240 @@ -# java +# FilmFinder - 智能电影推荐系统 -FilmFinder - 智能电影推荐系统 -

FilmFinder Logo
基于Flask与AI的个性化电影发现平台

项目简介 • 核心特性 • 技术栈 • 系统架构 • 快速开始 • 项目文档

-🎬 项目简介 -FilmFinder 是一个基于Web的智能电影推荐系统，旨在解决用户在影视内容爆炸式增长时代面临的"选择困难"问题。系统通过多维度筛选、AI智能搜索和个性化推荐算法，帮助用户快速发现符合个人喜好的电影。 +FilmFinder 是一个基于 Flask 开发的智能电影推荐系统，集成了协同过滤推荐算法、AI 台词搜索、TMDB 电影数据导入等先进功能，为用户提供个性化的电影推荐服务。 -目标用户：电影爱好者、有观影需求但缺乏明确目标的普通用户、希望探索冷门佳片的观众。 +## ✨ 主要特性 -✨ 核心特性 -🎯 智能搜索 -传统搜索：支持按电影名称关键词快速检索 +### 🎬 核心功能 +- **个性化推荐**：基于用户标签和协同过滤算法的智能推荐 +- **电影搜索**：支持按电影名称、类型搜索，以及 AI 台词搜索 +- **用户系统**：完整的用户注册、登录、标签选择功能 +- **收藏与评分**：用户可以收藏喜欢的电影并为其评分 +- **电影详情**：详细的电影信息展示，包括封面、简介、评分等 -AI台词搜索：集成DeepSeek大模型，支持通过经典台词、角色名、电影描述进行智能语义匹配 +### 🤖 AI 功能 +- **AI 台词搜索**：通过输入经典台词或角色名称，AI 智能识别并推荐相关电影 -🤖 个性化推荐 -基于内容的推荐：分析用户收藏、评分行为，构建用户兴趣向量 +### 🎯 管理员功能 +- **电影管理**：添加、删除电影，支持批量导入 +- **TMDB 导入**：从 The Movie Database (TMDB) API 导入电影数据 +- **数据统计**：用户行为分析、电影热度统计、数据可视化 -余弦相似度算法：计算用户兴趣与电影特征的匹配度，实现精准推荐 +### 🎨 界面设计 +- **现代化 UI**：使用 Tailwind CSS 构建的响应式界面 +- **数据可视化**：使用 ECharts 和 Chart.js 展示统计数据 +- **用户体验优化**：流畅的交互体验和友好的错误提示 -冷启动处理：新用户通过兴趣标签选择（5-10个）获得初始推荐 +## 🛠️ 技术栈 -🎨 用户体验 -多维度筛选：支持按类型、评分、地区等多条件组合筛选 +### 后端 +- **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，完美适配手机和电脑屏幕 +### 前端 +- **Tailwind CSS** - 实用优先的 CSS 框架 +- **ECharts** - 数据可视化图表库 +- **Chart.js** - 另一个图表库 +- **Iconify** - 图标库 -交互式操作：收藏电影、1-5星评分、个人中心管理 +### 外部 API +- **TMDB API** - 电影数据库 API +- **DashScope API** - 阿里云 AI 服务（用于台词搜索） -👨‍💼 管理员功能 -电影库管理：手动添加/删除电影 +## 📋 系统要求 -批量导入：通过TMDB API实现电影数据批量导入 +- Python 3.7+ +- pip（Python 包管理器） -数据统计：查看用户行为数据、电影热度排行 +## 🚀 快速开始 -🛠 技术栈 -后端技术 -框架：Flask (Python) +### 1. 克隆项目 -ORM：SQLAlchemy +```bash +git clone +cd FilmFinder +``` -数据库：SQLite +### 2. 安装依赖 -算法库：NumPy (余弦相似度计算) +```bash +pip install -r requirements.txt +``` -AI集成：DeepSeek API (智能搜索) +### 3. 配置环境变量（可选） -前端技术 -基础技术：HTML5, CSS3, JavaScript +如果需要使用 AI 台词搜索功能，需要设置 DashScope API 密钥： -样式框架：Tailwind CSS +```bash +# Windows +set DASHSCOPE_API_KEY=your_api_key_here -模板引擎：Jinja2 +# Linux/Mac +export DASHSCOPE_API_KEY=your_api_key_here +``` + +> **注意**：如果不设置 API 密钥，系统会自动切换到演示模式，仍可使用部分功能。 + +### 4. 初始化数据库 + +数据库会在首次运行时自动创建。如果需要重置数据库，可以运行： + +```bash +python reset_db.py +``` + +### 5. 启动应用 + +```bash +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： + +```python +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)](https://www.themoviedb.org/) - 提供电影数据 API +- [DashScope](https://dashscope.aliyun.com/) - 提供 AI 服务 +- Flask 社区 - 优秀的 Python Web 框架 + +## 📞 联系方式 + +如有问题或建议，欢迎提交 Issue 或 Pull Request。 + +--- + +**FilmFinder** - 发现你的下一部好电影 🎬 -数据可视化：ECharts (管理员统计) \ No newline at end of file