AI 小二

Overview

AI 小二是一套面向单店包间的智能点餐顾问。顾客扫包间桌贴上的二维码进入门店专属页面，用自然语言说出人数、预算与口味，AI 从本店真实菜单中给出带推荐理由的菜品；老板在后台维护菜品、沽清状态与推荐权重，决定 AI 按什么口径推荐。

一期边界是明确的：只做推荐，不进入下单、支付与后厨；不建用户体系，扫码即用，口味偏好只在单次会话内记忆。

Problem

包间宴请场景的三个具体痛点（以自家店与同类中餐店为参照）：

• 买单人选择决策重——8 人一桌，口味不一、忌口要照顾、预算要控、菜还要「有面子」，翻菜单二十分钟定不下来；
• 顾客不好意思反复问——想知道「这个辣不辣」「量大不大」，问两三次就不再问了，凭感觉点；
• 老板想推的菜推不出去——新菜冷启动没人点、高毛利菜藏在菜单第三页，且服务员流动大，熟手会推、新手背不下菜单。

市面上的 AI 点餐几乎都在抢平台流量入口（跨店推荐、优化平台利益），没有一款是面向「这家店自己的包间」的。所以这个项目采用单点验证策略：只做包间推荐这一个场景，推荐优先级由老板直接配置；LLM 默认走云端 API 控制成本，架构上保留本地部署回退通道。

Architecture

顾客端  Taro 4 + React（H5 先行，小程序为第二编译目标）
   ↓  扫码 / 短码 / 原生小程序码
后端    FastAPI + LangGraph
   ├─ 候选集召回（在售 + 可做辣度匹配）
   ├─ LLM 网关（OpenAI 兼容：默认 DeepSeek，可切通义 / 智谱 / Kimi / vLLM / Ollama）
   └─ 输出校验与降级
   ↓
数据    MySQL 8 + Redis 7
   ↓
后台    React 18 + Vite + TDesign

部署为单台云服务器全栈形态：Nginx（静态资源 + 反向代理 + HTTPS）+ uvicorn + MySQL + Redis，业务服务器不需要 GPU。

Features

顾客端

• 扫码进店、与 AI 自然语言对话，回复以 SSE 流式逐字返回；
• 推荐卡片四种状态各有语义：可加入、已加入、今日已售完、与这桌忌口冲突（不推荐但如实说明原因）；
• 无桌码顾客有「我要打包带走」入口；收台后不再让顾客空试；弱网丢消息可重发；
• 历史推荐卡片折叠回看，会话现场持久化。

管理后台

• 菜品管理：增删改、按列排序、图片上传（服务端统一缩放重编码为 WebP）、分类管理；
• Excel 批量导入：按表头名匹配的宽容解析、逐行报错，同名即更新，另有存量一键查重合并；
• 沽清开关：置为沽清后所有会话即时停推，顾客主动问起时如实告知并给出替代；
• 推荐策略：AI 人设与菜品推荐权重批量配置；
• 包间管理：短码生成、桌贴与原生小程序码生成、一次打包下载全部桌贴；
• 会话管理：当日会话列表与详情（完整对话 + 推荐记录），支持按房间批量终止与撤销终止；
• 数据看板：概览、7 日趋势与菜品排行。

Design notes

几处经过踩坑后固化的设计：

• 防幻觉分三道闸门：推荐结果必须来自在售候选集；价格、辣度等事实字段一律取自数据库；模型输出校验不通过时降级处理，而不是把未校验的内容直接渲染给顾客；
• 会话时间阈值拆成两个参数：静默阈值（默认 30 分钟，只决定后台怎么标注）与可恢复时限（默认 180 分钟，决定顾客能否接回原会话）。最初两者共用一个值，会让超过三小时的宴请中途没跟 AI 说话就丢历史；
• 营业日切换点默认凌晨 4 点，且不硬编码：营业日切换点、静默阈值、可恢复时限均可后台配置、改完即时生效；
• 辣度拆成「默认辣度 + 可做辣度」：顾客说不吃辣时，保留「可做不辣」的菜，而不是把带辣的菜一律排除；
• LLM 配置单一来源：后台配置优先于环境变量，Key 只存服务端且后台脱敏显示；导入脚本整组排除 llm_* 配置，避免出现「配了地址与模型却没配 Key」的半套覆盖把环境变量里的有效 Key 架空；
• 测试不依赖外部服务：后端用内存 SQLite 跑 pytest，不依赖 MySQL / Redis / 网络，调用 LLM 的用例一律 mock 掉网络请求。

Status

2026-09-11 至 2026-09-24 共 9 个开发日、176 次提交，已完成顾客端对话闭环、管理后台六个页面与线上部署；数据库每日逻辑备份与隔离恢复演练已在服务器验收通过。

Roadmap

• 多人共享会话（一间房一个会话，共享清单与忌口）；
• 微信授权登录与长期口味偏好档案；
• 结构化忌口硬过滤、已点菜品联动与时段策略；
• 外包存储的异地备份，解掉单机磁盘故障风险。

单店私有部署，实例运行在自有服务器上；顾客端以包间桌贴二维码分发，不对外开放入口。

更新日志

1. 2026.09.11
   • 仓库初始化，部署形态定为「全云单机」，顾客端确定 Taro H5 先行、小程序为第二编译目标
   • 产品方案升级至 v0.3：新增后台会话管理，明确会话生命周期与恢复规则
   • 落地后端骨架与顾客端建会话链路，接入 LLM 网关（Provider 抽象 + DeepSeek 实现，可切本地 vLLM）
   • 推荐链核心打通：菜品候选召回与打分 → 组装 → 输出校验与降级
   • 顾客端对话闭环跑通：意图路由 + 约束抽取 + 发消息 SSE 接口
2. 2026.09.12
   • 后台接口齐备：菜品 / 包间 / 推荐策略 / 会话管理 / 系统设置
   • 菜品 Excel 批量导入与模板下载上线，导入采用同名即更新，另提供一键清理重复
   • 菜品辣度拆为「默认辣度 + 可做辣度」，召回按「这道菜能不能做成顾客要的辣度」判断去留
   • 管理后台骨架搭建完成（Vite + React + TDesign）并接入登录鉴权
3. 2026.09.14
   • 后台五个页面成型：菜品 / 包间 / 推荐策略 / 会话管理 / 系统设置，列表统一改为卡片布局
   • 接入营业日自动归档定时任务与 Alembic 数据库迁移
   • 顾客端接入真实后端、替换全部 mock 数据；修掉「回复不流式、卡片不显示」的同一个根因
   • 历史推荐卡片折叠展示，会话现场（卡片与清单）落库持久化
4. 2026.09.15
   • 接入数据埋点，顾客端补 card_click / summary_view 事件上报
   • 菜品图上传与统一重编码为 WebP（顺带剥离 EXIF），卡片改为左图右文
   • 修复会话记忆丢失：多轮对话里的人数与忌口不再被丢掉
   • 加长对话性能基准：30 轮消息的开销主要在卡片而非文本
   • 阿里云单机部署脚本成型，后台改挂 /admin/
5. 2026.09.21
   • 桌贴改版，支持范围推荐与独立的老板提示词
   • 每日数据库备份与隔离恢复演练落地
   • 发布门禁加固：依赖安装、数据库迁移或健康检查失败即中止
6. 2026.09.22
   • 生产备份安装与隔离恢复演练验收通过
   • 顾客端增加店内定位门禁，服务范围由后台配置
   • 支持带图片的菜单包一次性导入
7. 2026.09.23
   • 启用域名 HTTPS，完善发布门禁（未登录接口须返回 401）
   • 完成小程序端适配：请求、流式对话、图片、定位与扫码
   • 桌贴二维码改为原生小程序码，顾客微信扫一扫直进小程序；后台支持一次打包下载全部桌贴
   • 新增「我要打包带走」入口，外带顾客不必先找桌码
8. 2026.09.24
   • 全链路统一 GCJ-02 坐标系，修掉店内被判「已离店」
   • 服务范围从单点改为多地点，后台卡片式编辑与地图核对
   • 顾客「已加入清单」落库，后台可复盘推荐有没有被真正使用
   • 补统计地基（埋点可索引、动作语义、统一口径），后台新增数据看板：概览 + 7 日趋势 + 菜品排行
   • 制作小程序头像，包间桌贴底部展示店内 WiFi 信息