第三次软工作业

作业所属课程	https://edu.cnblogs.com/campus/gdgy/SoftwareEngineering24/
作业要求	https://edu.cnblogs.com/campus/gdgy/SoftwareEngineering24/homework/15655
作业的目标	完成基于AI智能体的大学生兴趣培养与成长规划平台的需求分析、团队组建、项目规划、技术落地，实现可运行WEB
团队名称	Nova
团队成员学号-名字	3124004565钟启睿3124005526盘嵘

智能美食推荐系统 - 需求分析文档
一、迭代计划表格

版本号	日期	修订内容	作者
V1.0	2026-04-20	初始版本：完成Web端基础功能（定位、高德搜索、DeepSeek推荐、三种交互模式）	开发团队
V2.0	计划2026-05	封装为Flutter App，增加一键导航、离线缓存	开发团队
V2.5	计划2026-06	引入加权排序算法、营业中筛选	开发团队
V3.0	计划2026-07	协同过滤推荐、用户行为分析	开发团队

三、思维导图
智能美食推荐系统
├─ 前端
│ ├─ 定位模块（浏览器Geolocation / App原生定位）
│ ├─ 页面交互（首页推荐、常规推荐、场景推荐、天气推荐）
│ └─ 结果展示（餐厅列表 + 推荐文案）
├─ 后端
│ ├─ API服务（FastAPI）
│ ├─ 高德地图集成（周边搜索、IP定位）
│ ├─ DeepSeek大模型推荐
│ ├─ 缓存机制（内存缓存10分钟）
│ └─ 安全控制（环境变量、CORS）
├─ 数据
│ ├─ 用户位置（经纬度）
│ ├─ 餐厅信息（名称、地址、距离、评分）
│ └─ 推荐结果（大模型生成文本）
└─ 部署
├─ Render云端部署
└─ 环境变量注入

四、类图
FastAPI应用类 app：包含路由方法 home_recommend()、chat()、ip_location()。
请求模型类 ChatRequest：属性 latitude、longitude、radius、demand、scene、cuisine。
高德接口类 AmapService（在 amap_api.py 中）：方法 ip_location(ip)。
推荐服务类 RecommendService（在 llm_api.py 中）：方法 search_nearby_restaurants(lat, lng, radius, keywords)、chat_with_llm(demand, restaurants, scene)。
缓存类 Cache（在 app.py 中）：字典 restaurants，过期时间 expire。

类关系：app 依赖 ChatRequest，并调用 RecommendService 和 AmapService；RecommendService 独立调用高德API和DeepSeek API。

五、功能描述

5.1 前端功能
自动定位：进入页面后请求浏览器位置权限，成功获取经纬度，失败则降级为广州默认坐标。
首页推荐：自动展示附近3家餐厅（名称、地址、距离、评分）。
常规推荐：用户选择菜系（火锅、日料等）、搜索距离（1-50公里）、输入预算，系统生成个性化推荐。
场景推荐：用户输入场景描述（如“约会，安静”），系统结合场景生成推荐。
天气推荐：用户输入当前天气（下雨、寒冷等），系统推荐适合的餐厅类型。
一键导航（计划V2.0）：每个餐厅旁增加导航按钮，调起手机地图App。

5.2 后端功能
IP定位备用：提供 /api/ip_location 接口，通过高德API获取客户端公网IP对应位置。
周边餐厅搜索：调用高德 /v3/place/around，支持关键词、半径、类型筛选，返回POI数据。
大模型推荐生成：拼接餐厅信息和用户需求，调用DeepSeek API，返回自然语言推荐语。
缓存管理：以“经纬度_菜系”为键缓存搜索结果10分钟，减少高德调用。
环境变量安全：所有API Key通过 os.getenv() 读取，不在代码中硬编码。

六、验收标准

测试项	验收标准
前端定位	首次访问提示权限请求，获取真实坐标；超时或拒绝后3秒内降级为默认坐标，页面不崩溃。
首页展示	自动加载至少3家周边餐厅，显示名称、地址、距离（公里）、评分。若无结果，显示友好提示。
常规推荐	选择菜系和距离后，5秒内返回推荐文案，文案中提及至少2家餐厅且符合菜系要求。
场景推荐	输入“约会”类描述，推荐结果包含“环境好”“适合情侣”等关键词。
天气推荐	输入“寒冷”，推荐结果包含“火锅”“热汤”等关键词。
缓存生效	10分钟内重复相同坐标/菜系请求，后端不重复调用高德API（日志可验证）。
安全检验	GitHub仓库中无 .env 文件，无硬编码API Key；部署至Render后通过环境变量正常调用接口。
云端访问	通过公网域名可访问完整功能，电脑关机后服务依然可用。
一键导航（V2.0）	点击导航按钮，自动调起手机地图App并规划路线。