餐饮 · AI 智能经营分析平台

全栈餐饮系统：Java 后端负责完整外卖业务， AI 助手（CrewAI + FastAPI）作为全新能力层，为管理端提供自然语言经营分析、为用户端提供 智能客服。系统以 Docker Compose 一键编排，开箱即跑。

---

目录

• 项目简介
• 演示效果
• 核心特征
  • AI 助手：革新点与技术点
  • Java 后端：相对传统的改变
• 系统整体架构
• 技术栈与依赖
• 目录结构
• 快速开始
• 数据库设计
• 接口与集成
• 安全事项
• 常见问题
• TODO

---

项目简介

项目代号 take_out（店铺名「天涯客栈」），由三个子系统组成：

1. Java 后端（take_out/）：基于传统餐饮后端二次开发，负责完整的 C 端外卖与 B 端运营业务， 包括菜品/套餐、购物车、订单、支付（Mock）、报表统计、营业状态、WebSocket 接单提醒等。
2. AI 助手（ai_assistant/）：基于 CrewAI 多智能体 + FastAPI 的全新能力层。管理端输入中文 问题即得结构化经营分析报告；用户端提供带个人订单/地址查询能力的智能客服，全部通过 SSE 流式输出。
3. 前端（Front_end/）：管理后台（Vue 2 版沿自苍穹 + Vue 3 重写版）、用户端 H5 网页版 （替代/补充小程序），均接入 AI 对话页面。

数据库直接复用同一套 take_out 库：AI 助手通过只读 SQL 与 Java 业务接口两种通道访问数据， 不复制、不同步，保证口径一致。

---

演示效果

场景一：管理端 AI 经营分析

登录管理后台（admin_source）进入「AI 智能分析助手」页面，输入：

• “这个月营业额怎么样？” → 返回营业总额、订单量、客单价等指标
• “最近一周哪个菜卖得最好？” → 热销排行 + 搭配建议
• “本周订单有没有异常？” → 取消率、履约超时、区域分布

回答以打字机效果流式输出，结束后自动渲染为结构化卡片：总结、指标网格、洞察、建议； 每条指标都带有数据来源工具名，方便核对。支持快捷问题、历史记录恢复与清空。

场景二：用户端 AI 智能客服

用户端 H5（sky_web）内置「AI 客服」页面，可以问：

• “推荐几个招牌菜” → 客服调用热销排行工具，用真实数据推荐
• “现在营业吗” → 实时查询 Java 后端的营业状态（Redis）
• “我的订单到哪了 / 我的地址” → 识别 JWT 用户身份后查询本人订单/地址；未登录则引导登录
• “营业时间 / 配送范围” → FAQ 直达，不消耗 LLM

场景三：传统业务闭环

用户端完成“选菜 → 购物车 → 下单 → 支付（Mock）→ 确认收货”，管理端实时收到 WebSocket 新订单提醒， 接单/派送，工作台与数据统计页面查看营业额、用户、订单、销量图表，并支持导出 Excel 报表。

---

核心特征

AI 助手：革新点与技术点

AI 助手不是简单地把 LLM 接到数据库上，而是围绕可控、可审计、口径一致、可评估四个目标设计：

1. 受控编排替代黑盒调度（core/orchestrator.py） 放弃 CrewAI hierarchical Manager 的不可控自动委派，改为代码路由：
   • 意图路由：FAQ、营业状态、未登录的个人查询直接短路，不启动 LLM；
   • 维度路由：销售 / 菜品 / 订单 / 用户 / 综合五类问题分别路由到单一 Agent， 综合问题才使用全量工具 Agent，一次回答只跑一个 Crew，成本与延迟可控；
   • 日期注入：每个任务注入“今天日期”，禁止 LLM 在用户未指定日期时凭记忆猜日期；
   • 营业状态强制查工具：实时状态类问题直接调用 query_shop_status，不依赖模型记忆。
2. 统一工具治理层（tools/decorators.py 的 @analysis_tool） 全部 20 个分析工具经过统一装饰器包装，自动提供：
   • 日期校验（格式、顺序、区间跨度上限 366 天）、limit 参数收拢；
   • 结果行数保护（超限截断并打 _truncated 标记，防止大结果集撑爆上下文）；
   • 进程内 TTL 缓存（营业额 120s、排行 300s 等，按工具名+参数隔离）；
   • 审计日志（logs/tool_audit.jsonl：时间、参数、耗时、行数、错误），供评估与排障；
   • 数据库连接/读超时（默认 5s / 15s）。
3. 语义层防口径混用（metrics_definitions.yaml） 营业额、客单价、订单完成率等所有统计口径集中维护为“度量词典”，工具与 LLM 提示词均以其为准， 从源头防止 Agent 把“营业额”和“销售额”等口径混为一谈。
4. 结构化输出契约 + 容错解析（core/structured.py） 管理端报告统一为 {summary, metrics[], insights[], suggestions[]} JSON；解析器对模型常见的 漏花括号、漏引号、Markdown 代码块包裹等问题做自动修复，失败时降级为纯文本； SSE 新增 result 事件下发完整报告，前端按卡片渲染。
5. 流式输出（SSE 打字机） CrewAI 1.x 流式块按类型过滤（只透传 TEXT，丢弃工具调用碎片），并兼容浏览器 fetch 的 LF 分隔协议（EventSourceResponse(sep="\n")）；nginx 层关闭缓冲保证长回答实时到达。
6. 跨系统身份互通（security/jwt_auth.py） Python 端用与 Java 相同的 HS256 密钥解密 JWT：用户端 authentication 头 → userId， 管理端 token 头 → empId，因此 AI 能安全查询当前用户本人的订单/地址，管理端接口可鉴权。
7. 数据双通道设计
   • 业务统计：Python 直连 MySQL（PyMySQL，短连接 + 上下文管理器，规避多线程连接不安全）只读查询；
   • 实时营业状态：调用 Java 已放行的 GET /user/shop/status（Java 内部读 Redis）， 规避 Python 直读 Redis 的序列化差异，同时保持 Java 为状态唯一权威源。
8. 用户点单统计（mysql/migration_user_order_stats.sql） 通过 MySQL 触发器自动维护 user_order_stats（新用户注册自动插行、订单支付成功自动累加）， AI 工具 query_user_usage_stats 直接读取，可回答注册用户数、下单转化率、复购率等运营问题， 统计逻辑沉淀在数据库层，不依赖 AI 记忆。
9. 可评估、有基线（ai_assistant/evals/） 工具层离线评估 20/20；Agent 层用例 6/6 全部通过结构化校验（改造前 3/6）， 6 例总耗时从 189s 降至 94s，营业额问题工具调用数从 11 个降到 4 个。 评估依据来自统一装饰器的审计日志，可观测、可复跑。

Java 后端：相对的改变

1. 技术栈升级：JDK 17；fastjson → fastjson2（2.0.53）；commons-lang → commons-lang3； jjwt 拆分 api/impl/jackson；引入 Testcontainers（MySQL 集成测试）； 新增 RedisCacheManager（默认 30 分钟 TTL）。
2. Redis 序列化修复：RedisTemplate value 改用 GenericJackson2JsonRedisSerializer （原先只有 key 是 String 序列化，value 是 JDK 二进制），营业状态改用 StringRedisTemplate 存取，为 Python 侧通过 HTTP 读取 Redis 状态铺路。
3. 支付解耦：新增 PaymentService 接口 + MockPaymentService 实现，订单业务不再直接依赖 微信支付 SDK；后续接入真实支付只需新增实现类并切换配置。
4. 登录方式扩展：新增手机号验证码登录 /user/user/sendCode、/user/user/login/phone （开发阶段验证码固定 000000），不再局限于微信登录。
5. 订单流程完善：新增“确认收货”（PUT /user/order/confirm/{id}）；取消规则细化—— 已接单/派送中的订单需超过预计送达时间才能取消；退款判断从“订单状态”改为“已支付状态”。
6. 越权防护：订单详情/取消/再来一单、地址簿增删改查均增加归属校验 （ORDER_PERMISSION_ERROR / ADDRESS_BOOK_PERMISSION_ERROR），修复原项目可越权操作他人数据的问题。
7. 报表性能优化：营业额/用户/订单统计从“逐日 N+1 查询”改为单条 GROUP BY + 内存累计， 用户总数由每日重算改为区间累计；订单列表明细改为批量加载（消除 N+1）。
8. 鉴权白名单调整：放行 /user/shop/status、手机号登录/验证码接口，其中营业状态接口 同时作为 AI 助手的数据通道。
9. 前端配套：管理后台新增 Vue 3 + Vite + Element Plus ； 用户端新增 Vue 3 H5 网页版（sky_web，含 AI 客服页），替代对小程序编译产物的直接依赖。

---

系统整体架构

flowchart TB
    subgraph Clients["客户端"]
        A2["管理后台 Vue2（admin_source）"]
        A3["管理后台 Vue3（admin_v3）"]
        W["用户端 H5（sky_web）"]
    end

    NG["Nginx 1.20 反向代理"]

    subgraph BE["Java 后端（Spring Boot 2.7 / JDK17）"]
        J["Controller / Service / Mapper"]
        WS["WebSocket 新订单提醒"]
    end

    subgraph AI["AI 助手（FastAPI + CrewAI）"]
        OR["受控编排 orchestrator"]
        AG["5 个 Agent + Crew 工厂"]
        TL["20 个分析工具（统一装饰器）"]
        SE["结构化输出 / SSE 流式"]
    end

    LLM["LLM（DeepSeek / OpenAI 兼容）"]
    MYSQL[("MySQL 8（take_out 库）")]
    REDIS[("Redis 7（营业状态/缓存）")]

    A2 --> NG
    A3 --> NG
    W --> NG

    NG -->|"/api/ /user/ /ws/"| BE
    NG -->|"/ai/ SSE 不缓冲"| AI

    J -->|"MyBatis + Druid"| MYSQL
    J -->|"StringRedis / RedisCache"| REDIS
    J <--> WS

    OR --> AG
    AG --> TL
    TL -->|"只读 SQL（PyMySQL 短连接）"| MYSQL
    TL -->|"GET /user/shop/status"| J
    AG --> LLM
    SE --> OR

---

技术栈与依赖

| 模块 | 技术 | | --- | --- | | 管理后台（沿自苍穹） | Vue 2.6 + Element UI + TypeScript + Vuex + ECharts（admin_source） | | 用户端 H5 | Vue 3.5 + Vite 5 + Element Plus + Pinia（sky_web） | | Java 后端 | Spring Boot 2.7.3 / JDK 17、MyBatis、Druid、Redis、WebSocket、Knife4j、POI 5、fastjson2 | | AI 助手 | Python 3.11、FastAPI、CrewAI ≥ 1.15、sse-starlette、PyMySQL、PyJWT | | LLM | DeepSeek（OpenAI 兼容接口，LLM_MODEL / LLM_BASE_URL 可换） | | 数据库 | MySQL 8.0（utf8mb4）、Redis 7 | | 部署 | Docker Compose、Nginx 1.20、多阶段镜像构建（Maven / Python） |

---

目录结构

.
├── docker-compose.yml            # 一键编排：MySQL / Redis / Java / AI / Nginx
├── .env.example                  # 环境变量模板（复制为 .env 后填写）
├── .gitignore
├── README.md
├── mysql/                        # 数据库初始化脚本与设计文档
│   ├── take_out.sql              # 基础库表（含演示数据）
│   ├── migration_user_order_stats.sql  # 用户点单统计表 + 触发器
│   └── 数据库设计文档.md
├── take_out/                     # Java 后端（改造自苍穹外卖）
│   ├── sky-common/               # 公共模块：工具类 / 常量 / 异常 / 结果封装
│   ├── sky-pojo/                 # 实体 / DTO / VO
│   └── sky-server/               # 启动模块：Controller / Service / Mapper / 配置
├── ai_assistant/                 # AI 助手（FastAPI + CrewAI）
│   ├── main.py                   # FastAPI 入口（uvicorn）
│   ├── config.py                 # 全部环境配置
│   ├── api/                      # SSE 聊天接口 + 历史接口
│   ├── core/                     # 受控编排 / 流式封装 / 结构化输出
│   ├── tools/                    # 20 个分析工具（统一 @analysis_tool 装饰器）
│   ├── agents/                   # 5 个 Agent 定义
│   ├── crews/                    # Analyst / CustomerService Crew 工厂
│   ├── db/                       # MySQL 连接管理、聊天历史持久化
│   ├── security/                 # JWT 校验（与 Java 令牌互通）
│   ├── evals/                    # 工具层 / Agent 层评估体系
│   └── metrics_definitions.yaml  # 语义层：统计口径词典
└── Front_end/
    ├── admin_source/             # 管理后台 Vue2（含 AI 分析页）
    ├── sky_web/                  # 用户端 H5（含 AI 客服页）
    ├── docker/nginx/default.conf # Nginx 反向代理配置（入库）
    └── nginx-1.20.2/             # 本地下发的 nginx 发行包（不入库）

---

快速开始

方式一：Docker Compose 一键启动（推荐）

前置条件：Docker + Docker Compose。

cp .env.example .env
# 编辑 .env：必填 LLM_API_KEY；MYSQL_ROOT_PASSWORD 与本地环境保持一致
docker compose up -d --build

启动后访问：

| 地址 | 说明 | | --- | --- | | http://localhost | 管理后台（admin_source 构建产物） | | http://localhost/sky-web | 用户端 H5 | | http://localhost:8080/doc.html | Java 接口文档（Knife4j） | | http://localhost:8000/healthz | AI 助手健康检查 | | http://localhost/ai/ | AI 接口（SSE，经 Nginx 转发） |

首次启动时 MySQL 自动执行 mysql/*.sql 初始化（基础表 + 演示数据 + 用户点单统计表/触发器）。

方式二：本地开发模式

1. Java 后端：JDK 17 + Maven

   cd take_out
   mvn -pl sky-server -am package -DskipTests
   java -jar sky-server/target/sky-server-1.0-SNAPSHOT.jar
   # 本地默认 profile=dev，数据库密码等见 application-dev.yml
   

2. AI 助手：Python 3.11

   cd ai_assistant
   cp .env.example .env        # 填入 LLM_API_KEY、DB_PASSWORD
   pip install -r requirements.txt
   python main.py              # 或 uvicorn main:app --port 8000
   

   Java 本地开发的真实密钥（OSS/微信/百度/JWT）只写在 take_out/sky-server/src/main/resources/application-dev.yml， 该文件已被 .gitignore 排除、不入库；AI 助手的 USER_JWT_SECRET / ADMIN_JWT_SECRET 需与 application-dev.yml 中 sky.jwt.* 保持一致。

3. 前端：Node.js 16+（admin_source 较老，建议 Node 16/18）

   cd Front_end/admin_v3 && npm install && npm run dev   # 管理后台 Vue3
   cd Front_end/sky_web && npm install && npm run dev    # 用户端 H5
   # admin_source（Vue2）使用 npm run serve（脚本已内置 openssl-legacy-provider）
   

4. 本地联调时把 AI 助手的 JAVA_BACKEND_URL 指向 http://localhost:8080， 前端开发服务器通过 Vite 代理把 /api、/user、/ai、/ws 转发到后端与 AI 服务。

---

数据库设计

数据表清单（take_out 库）

| 表 | 说明 | | --- | --- | | employee | 员工（管理端账号） | | category | 菜品/套餐分类 | | dish / dish_flavor | 菜品 / 口味 | | setmeal / setmeal_dish | 套餐 / 套餐-菜品关系 | | user | C 端用户 | | address_book | 收货地址 | | shopping_cart | 购物车 | | orders / order_detail | 订单 / 订单明细 | | user_order_stats | 新增：注册用户点单统计（AI 用户运营分析的数据源） |

另有 AI 助手首次启动时自建的 chat_history 表（聊天历史，含管理端结构化报告 JSON）。

Java 后端如何访问数据库

• 连接层：Spring Boot + Druid 连接池，MyBatis（XML Mapper）完成 SQL，配置见 sky-server/src/main/resources/application*.yml；入库的 application.yml 只含占位符， 本地真实配置在 application-dev.yml（不入库），docker 环境通过 MYSQL_ROOT_PASSWORD、SKY_ALIOSS_*、USER_JWT_SECRET、ADMIN_JWT_SECRET 等环境变量注入。
• 缓存层：Redis 承担两类职责——营业状态（SHOP_STATUS，StringRedisTemplate 字符串存取） 与缓存（RedisCacheManager，value 统一 JSON 序列化，30 分钟 TTL）。
• 初始化：Docker 启动时由 /docker-entrypoint-initdb.d/ 顺序执行 take_out.sql 与 migration_user_order_stats.sql。
• 写入路径：所有业务写操作（订单、地址、购物车等）只经 Java 服务层完成， 触发器 trg_user_insert_order_stats / trg_orders_paid_order_stats 在数据库层自动维护 用户点单统计，业务代码无需关心。

AI 助手如何访问数据库

1. 只读直连（主要通道）：PyMySQL 短连接 + 上下文管理器（db/connection.py）， 每次工具调用一条连接，天然规避 PyMySQL 多线程不安全问题；所有分析工具只执行 SELECT 聚合查询，连接与读超时受控，参数化查询防注入。
2. Java 接口通道（实时状态）：营业状态由 Java 写 Redis，Python 不直读 Redis， 而是调用已放行的 GET /user/shop/status 获取，保证状态权威、格式一致。
3. 身份通道：用户端聊天时，Python 用与 Java 相同的 JWT 密钥解析 authentication 头得到 userId，工具按该 ID 查询本人订单/地址；未登录则拒绝个人数据查询。
4. 唯一写权限：AI 助手只写 chat_history（自己的表），业务数据一律只读， 避免 AI 破坏业务数据一致性。

---

接口与集成

Java 后端接口（部分）

| 分组 | 示例接口 | 说明 | | --- | --- | --- | | 管理端 /admin/** | 员工/分类/菜品/套餐/订单管理、工作台、数据统计、营业状态 | 需 token（JWT，claim empId） | | 用户端 /user/** | 登录（微信/手机号）、菜品查询、购物车、下单/支付/取消/再来一单/确认收货、地址簿 | 需 authentication（JWT，claim userId） | | 放行接口 | GET /user/shop/status、/user/user/login、/user/user/login/phone、/user/user/sendCode | 免登录，供前端与 AI 调用 | | 实时推送 | /ws/ WebSocket | 新订单提醒（管理端） | | 文档 | /doc.html（Knife4j） | 在线接口文档 |

AI 助手接口（FastAPI + SSE）

| 接口 | 说明 | | --- | --- | | POST /api/ai/chat | 管理端经营分析，SSE；生产环境 ADMIN_AUTH_ENABLED=true 时需 token 头 | | POST /api/cs/chat | 用户端智能客服，SSE；authentication 头带用户 JWT 时支持个人订单/地址查询 | | GET /api/ai/history、DELETE /api/ai/history | 管理端聊天历史读取 / 清空 | | GET /api/cs/history、DELETE /api/cs/history | 用户端聊天历史读取 / 清空 | | GET /healthz | 健康检查 |

SSE 事件类型：status（开始提示）→ message（流式文本片段）→ result（管理端结构化报告， 仅 /api/ai/chat）→ done / error。

请求体示例：

{
  "message": "这个月经营怎么样？",
  "history": [{"role": "user", "content": "上个问题"}, {"role": "assistant", "content": "上个回答"}]
}

前端集成（Nginx 路由）

| 路径 | 转发目标 | | --- | --- | | / | 管理后台静态资源（admin_source/dist） | | /sky-web/ | 用户端 H5 静态资源（sky_web/dist） | | /api/ | Java 管理端 /admin/ | | /user/ | Java 用户端 /user/ | | /ai/ | AI 助手 /api/（关闭缓冲、长超时，支持 SSE） | | /ws/ | Java WebSocket（Upgrade 透传） |

JWT 互通约定

| 端 | 请求头 | claim | 密钥来源 | | --- | --- | --- | --- | | 用户端 | authentication | userId | USER_JWT_SECRET（与 Java sky.jwt.user-secret-key 一致） | | 管理端 | token | empId | ADMIN_JWT_SECRET（与 Java sky.jwt.admin-secret-key 一致） |

---

安全事项

1. 密钥分层管理：
   • 入库的 take_out/sky-server/src/main/resources/application.yml 只保留占位符 （${sky.jwt.admin-secret-key}、${sky.alioss.access-key-secret} 等），不含真实密钥；
   • 真实密钥只写在本地的 application-dev.yml，该文件已被 .gitignore 排除，不会入库；
   • Docker 环境通过环境变量注入（MYSQL_ROOT_PASSWORD、SKY_ALIOSS_*、 USER_JWT_SECRET、ADMIN_JWT_SECRET 等）；
   • 提醒：旧仓库（gitee）曾提交过包含阿里云 OSS、微信、百度真实密钥的 application-dev.yml，凡出现过的密钥都应视为已泄露，上线新仓库前建议轮换。
2. AI 管理端鉴权：生产环境必须设置 ADMIN_AUTH_ENABLED=true，否则任何人都能调用 /api/ai/chat 查询经营数据。
3. CORS：不要使用 *，改为实际域名白名单（CORS_ORIGINS）。
4. 开发占位逻辑仅限本地：Mock 支付、固定验证码 000000、手机号免密登录均用于开发演示， 上线需替换为真实支付与短信服务。
5. 越权防护：Java 端订单/地址归属校验 + AI 端 JWT 身份识别，个人数据查询必须携带用户令牌。
6. SQL 安全：AI 工具全部参数化查询；统一装饰器对 limit、日期等入参做白名单式校验。
7. 审计：每次工具调用写入 logs/tool_audit.jsonl，可追溯 AI 访问了哪些数据、耗时多久。
8. 最小权限：AI 助手数据库账号建议单独创建只读账号（当前为 root 演示，生产环境应收敛）。

---

常见问题

1. AI 报“LLM_API_KEY 未配置”：复制 .env.example 为 .env 并填写 LLM_API_KEY。
2. AI 报“DB_PASSWORD 未配置”：.env 中 DB_PASSWORD 要与 MySQL 密码一致。
3. 管理端分析返回 401：ADMIN_AUTH_ENABLED=true 时请求需带 token 头；本地调试可先置 false。
4. 客服问“营业状态”报错：检查 AI 助手的 JAVA_BACKEND_URL 是否可达（Docker 内为 http://backend:8080），以及 Java 服务是否已启动。
5. SSE 收不到/只收到一半：Nginx 需关闭缓冲（proxy_buffering off，已配置）； 浏览器 fetch 按 \n\n 切分，后端已统一使用 LF 分隔。
6. npm run serve（admin_source）构建报 openssl 错误：使用 Node 16/18， 或按 package.json 脚本用 NODE_OPTIONS=--openssl-legacy-provider。
7. CrewAI 首次运行报存储目录异常：项目已把存储固定到 ai_assistant/.crewai_data、 .crewai_local 并关闭遥测，若旧版本遗留问题请删除这两个目录重试。
8. 套餐销量统计为 0：已知限制——order_detail 对套餐只有 setmeal_id、未拆到菜品明细， 菜品排行/搭配只统计单品；套餐对比请使用专门的 query_setmeal_compare 工具。
9. 端口冲突：80（Nginx）、8080（Java）、8000（AI）、3306（MySQL）、6379（Redis）被占用时， 修改 docker-compose.yml 映射端口。
10. 营业状态查询通过 Java 而非直读 Redis：历史原因——旧 RedisTemplate value 为 JDK 序列化二进制，Python 直读会乱码；现 Java 已改为 StringRedisTemplate，但 AI 仍统一走 Java 接口以保持状态单一权威源。

---

TODO

• [ ] 接入真实微信支付（新增 WeChatPaymentService 实现并切换配置）
• [ ] 接入真实短信验证码服务（替换固定 000000）

License

本项目仅供学习使用，禁止未经授权的商用。

联系与贡献

欢迎任何建议、反馈与贡献！如需交流或有合作意向，欢迎通过以下方式联系：

• QQ邮箱：[email protected]
• GitHub：提交 Issue 或 PR 到本仓库

如有 Bug、需求或改进想法，欢迎随时提出，我会积极响应。 也期待 AI 应用开发相关的朋友一起交流讨论。谢谢大家