beta冲刺

这个作业要求在哪里	https://edu.cnblogs.com/campus/gdgy/SoftwareEngineering24/homework/15658
团队名称	Nova
团队成员-学号	钟启睿3124004565 盘嵘3124005526
这个作业属于哪个课程	https://edu.cnblogs.com/campus/gdgy/SoftwareEngineering24
这个作业的目标	beta冲刺报告
FoodAdvisor-beta冲刺报告

一、继续完善项目：alpha 冲刺后的问题、探索思路与解决过程

alpha 冲刺结束后，FoodAdvisor 已经具备了基于定位、用户需求和大模型生成餐厅推荐的基本能力，但在真实使用场景中仍暴露出几个明显问题。第一，定位逻辑不够严格，部分用户在浏览器没有完成精确定位时仍可能进入推荐流程，导致系统默认到不准确的位置。第二，推荐结果存在重复和同质化，不同推荐方式可能返回相同餐厅，且过度偏向“离得最近”的候选，忽略了搜索半径内更匹配的中远距离餐厅。第三，天气推荐和场景推荐的语义匹配度不足，例如炎热天气仍推荐火锅、铜炉鸡等厚重餐型。第四，大模型容易对“招牌菜”产生幻觉，在高德数据没有明确菜品时编造或重复泛化词。第五，推荐卡只能阅读，不能直接进入导航，用户从推荐到实际到店之间仍有操作断点。

针对这些问题，beta冲刺采用“先限制错误，再提高体验”的思路推进。定位方面，系统要求浏览器必须返回高精度坐标和精度信息，否则后端接口直接拒绝服务。推荐算法方面，我们扩大了高德 POI 候选池，使用多关键词、多页召回，并把候选传给大模型前先做一次规则过滤和排序。排序不再只按距离优先，而是综合评分、距离、价格、营业信息、菜系匹配、场景匹配、天气匹配和多样性。对8公里这类较大搜索半径，系统增加近/中/远距离分层，让远处但更符合需求的餐厅也有机会进入前 5。

天气推荐方面，beta 版本明确区分炎热、寒冷、下雨等不同语境。炎热天气优先推荐日料、寿司、刺身、冰室、茶餐厅、清淡粤菜、粉面和轻食，并对火锅、铜炉、鸡煲、砂锅、麻辣烫等热重口餐型降权。招牌菜方面，我们把展示逻辑从“模型生成”改为“只展示高德候选数据里的 signature_dishes”，候选没有明确招牌菜就不显示这一项，从根源上减少幻觉。导航方面，系统从高德 POI 的 location 字段解析经纬度，生成高德 URI 导航链接，用户点击推荐卡即可打开高德地图路线规划。

二、项目特色功能展示

FoodAdvisor 的核心定位是一个轻量、直接、面向真实附近用餐场景的智能美食推荐系统。用户进入页面后必须授权精确定位，系统才会根据附近餐厅数据进行推荐。首页会先给出经过初筛的附近社会餐厅；如果用户跳过首页推荐，可以进入口味推荐、场景推荐和天气推荐三种模式。

项目的特色功能包括：

• 精确定位门槛：没有精确坐标或定位精度不足时，系统不会给出推荐，避免默认位置误导用户。
• 多模式推荐：支持口味、场景、天气三类入口，分别适配想吃什么、在什么场景吃、什么天气适合吃。
• 推荐结果多样化：后端会过滤学校饭堂、外卖柜、取餐柜、大型连锁快餐等不合适目标，并对类别和距离段做多样性控制。
• 天气语义适配：炎热天气偏清爽低负担，寒冷或下雨天气偏热汤、火锅、砂锅和粥粉面。
• 招牌菜防幻觉：只展示真实候选数据里已有的招牌菜，不让大模型凭空编造。
• 推荐卡导航：不改变原 UI，用户点击推荐卡即可跳转到高德地图导航页；手机端通常可以尝试拉起高德地图 App。

三、关键模块与自动化单元测试
beta 冲刺中重点完善了三个关键模块。
第一个模块是后端候选餐厅召回与排序模块。llm_api.py 中的 search_nearby_restaurants 负责调用高德周边搜索，按不同推荐模式扩展关键词，并合并多页、多关键词召回结果。_filter_and_rank_restaurants 负责过滤不适合的 POI，_restaurant_score 负责综合评分、距离、菜系、天气、场景等因素计算分数，_diversify_restaurants 负责控制前排推荐的类别和距离段多样性。
第二个模块是大模型推荐渲染模块。chat_with_llm 将候选餐厅和用户需求发送给 DeepSeek，让模型负责推荐理由和适配解释；但页面最终展示的餐厅名、距离、评分、人均和招牌菜由后端真实候选数据回填，避免模型在关键事实字段上产生幻觉。
第三个模块是推荐卡导航模块。_normalize_poi 从高德 POI 的 location 字段解析经纬度，并生成 navigation_url。前端 getNavigationUrl、openNavigation 和全局点击监听负责在用户点击推荐卡时打开高德地图导航。
本次 beta 冲刺做了以下自动化或半自动化验证：
测试覆盖点包括：

• Python 语法检查：python -m py_compile app.py llm_api.py amap_api.py。
• 导航 URL 生成测试：确认 POI 经纬度解析正确，生成的链接以 https://uri.amap.com/navigation 开头，并包含编码后的餐厅名。
• 推荐 HTML 渲染测试：确认大模型推荐卡会带 data-nav-url 和 role="link"。
• 本地服务测试：启动 FastAPI 后访问首页，确认返回 200。
• 定位拦截测试：无定位调用推荐接口时返回错误码，证明“未精确定位不服务”的规则仍然有效。

四、团队协作记录与成员收获
本次 beta 冲刺的协作过程按“问题复盘、方案拆解、代码实现、验证部署”的节奏推进。需求侧先从真实用户反馈中整理出问题：推荐数量少、距离过近、天气匹配不合理、招牌菜幻觉、推荐后不能直接导航。开发侧再把这些反馈拆解成可落地的技术任务，包括扩大候选池、改排序公式、约束模型输出、增加高德 URI 导航和保持 UI 不变的交互改造。

每个成员在这次 beta 冲刺中的体会和收获如下：

钟启睿：这次最大的收获是认识到“能推荐”不等于“推荐得合理”。餐厅推荐要结合真实场景，不能只用距离最近作为主要依据，也不能让模型随意编造看似合理的信息。后续做学校食堂推荐时，也需要先设计数据结构和评价体系。这次还重点学习了如何在不改变视觉设计的前提下增强交互。推荐卡仍保持原来的样式，但通过 data-nav-url、role="link" 和键盘事件支持，使卡片具备导航能力，同时兼顾可访问性。
盘嵘：这次主要收获是推荐系统不能只依赖大模型。大模型适合生成自然语言理由，但候选召回、过滤、排序和事实字段展示必须由后端掌控，尤其是定位、距离、评分、招牌菜这类关键信息。另外，还强化了上线前验证意识。每次修改后都需要跑语法检查、本地服务检查和关键函数检查，并确保 .env、缓存文件、报告材料等不被提交到 GitHub。

五、GitHub 仓库与后续计划

团队项目 GitHub 仓库链接：

https://github.com/dave66688/software-engeneering

beta 冲刺完成后，最新代码已准备更新到团队仓库。后续计划包括：

• 增加用户反馈入口，让用户对推荐结果进行“满意/不满意/已到店”评价。
• 建立学校食堂独立推荐线，设计学校、食堂、窗口、菜品、评分和招牌菜的数据表。
• 增加历史推荐去重，避免用户短时间内多次看到同一批餐厅。
• 对推荐公式进行参数化管理，便于后续根据真实反馈调整评分权重。
• 如果未来转向微信生态，再考虑小程序版本；当前网页版已能满足定位、推荐和高德导航闭环。