一、项目介绍

该项目是基于 FastAPI + Dify 工作流 开发的 Web 网页应用，旨在为用户提供智能化的新能源汽车选购体验。

用户只需用自然语言描述购车需求（如预算 20 万以内、续航 500km 以上的 SUV），系统即可通过 调用Dify AI 工作流自动解析意图、匹配数据库车型并生成个性化推荐报告，大幅降低选车门槛，提升购车决策效率。

项目采用前后端不分离架构，前端页面由 FastAPI 直接渲染，后端基于 Python 生态构建，整体结构清晰、易于部署和维护。

---

二、功能模块

2.1 用户端

模块	功能说明
注册 / 登录	用户名 + 密码注册，JWT Token 身份认证，支持记住登录状态
AI 推荐	自然语言输入购车需求，Dify 工作流解析意图，返回匹配车型列表 + Markdown 推荐报告，支持历史推荐记录查看
车型浏览	全量车型展示，支持按品牌、车型级别、能源类型、价格区间筛选；车型详情页含封面图、参数表、浏览量统计
购物车管理	加入/移除购物车，生成订单（支持全款 / 定金两种付款方式），订单状态流转（待付款→已付款→发货→完成/退款）
消息通知	试驾预约状态变更、订单状态更新等系统消息推送，未读消息小红点提醒
个人中心	查看 / 修改个人资料（头像、邮箱、联系方式），浏览历史、收藏列表、推荐记录、订单记录管理

2.2 管理端

模块	功能说明
登录	管理员专属登录入口 /admin/login，角色鉴权
数据概览	用户总量、车型总数、订单统计、试驾申请数等核心数据看板
用户管理	查看用户列表，启用 / 禁用账号，查看用户详情
车型管理	新增 / 编辑 / 删除车型，上传封面图及详情图，管理车型参数
试驾管理	查看试驾申请列表，确认 / 完成 / 取消试驾，左侧导航栏实时小红点提醒新申请
个人中心	修改管理员头像、邮箱、联系方式等个人资料

---

三、项目分层架构

系统采用经典三层架构，各层职责清晰、低耦合：

┌─────────────────────────────────────────────────────────┐
│                      前端展示层                          │
│  HTML + CSS + JavaScript + Axios                        │
│  页面路由由 FastAPI 直接渲染 Jinja2 模板                  │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP / REST API
┌──────────────────────▼──────────────────────────────────┐
│                      后端应用层                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │  Routers    │  │  Services   │  │    Schemas      │  │
│  │（路由/控制）│  │（业务逻辑）  │  │（Pydantic 校验）│  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │    CRUD     │  │   Commons   │  │     Utils       │  │
│  │（数据访问） │  │（公共配置）  │  │（Dify 客户端）  │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
└──────────────────────┬──────────────────────────────────┘
                       │ SQLAlchemy ORM / httpx
┌──────────────────────▼──────────────────────────────────┐
│                   数据与 AI 层                            │
│  ┌──────────────────┐    ┌───────────────────────────┐  │
│  │    MySQL 数据库   │    │     Dify 工作流（云端）    │  │
│  │  users / cars    │    │  用户需求解析 + 推荐报告   │  │
│  │  orders / ...    │    │  生成（LLM 驱动）          │  │
│  └──────────────────┘    └───────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

关键分层说明：

• Routers：路由层，负责接收 HTTP 请求、参数校验及响应返回，不含业务逻辑
• Services：服务层，封装核心业务逻辑（如推荐流程编排、订单状态流转）
• CRUD：数据访问层，封装所有 SQLAlchemy 数据库操作
• Commons：公共组件（数据库连接、JWT 鉴权、统一响应格式、配置管理）
• Utils / dify_client：Dify 工作流 HTTP 调用客户端，含超时、降级处理

---

四、技术栈

4.1 前端

技术	用途
HTML5	页面结构，语义化标签
CSS3	样式布局，Flexbox / Grid，响应式设计
JavaScript (ES6+)	交互逻辑，DOM 操作，异步请求
Axios	HTTP 请求库，统一封装 API 调用，支持请求拦截

4.2 后端

技术	用途
FastAPI	Web 框架，自动生成 OpenAPI 文档，异步支持
SQLAlchemy	ORM 框架，数据库模型定义与查询
PyMySQL	MySQL 驱动
MySQL	关系型数据库，存储用户、车型、订单等核心数据
Pydantic	数据校验与序列化
python-jose	JWT Token 生成与验证
passlib + bcrypt	密码哈希加密存储
httpx	异步 HTTP 客户端，用于调用 Dify API
Uvicorn	ASGI 服务器，运行 FastAPI 应用

4.3 Dify 工作流调用

具体设计流程图：

调用流程：

用户输入自然语言需求
        ↓
后端获取全量车型数据（cars_info JSON）
        ↓
调用 Dify 统一推荐工作流
  输入：user_query + cars_info
  输出：params_json（结构化参数）+ report_text（推荐报告）
        ↓
根据 params_json 过滤 MySQL 数据库，获取匹配车型
        ↓
返回：匹配车型列表 + AI 推荐报告（Markdown 格式）
        ↓
保存推荐记录到数据库

容错机制： 当 Dify 工作流调用超时或失败时，自动降级为离线推荐模式，使用本地规则引擎生成兜底报告，保证用户体验不中断。

4.4 数据库设计（核心数据表）

数据表	说明
users	用户信息（username、password_hash、role、avatar 等）
cars	车型信息（brand、price、battery_range、car_type、energy_type 等）
recommend_records	AI 推荐记录（user_query、parsed_params、matched_cars、report_content）
test_drives	试驾预约（real_name、phone、appointment_time、status）
orders	订单信息（order_number、amount、status、order_type、deposit_amount）
carts	购物车
favorites	收藏夹
browsing_history	浏览历史
notifications	消息通知

汽车表设计展示：

---

五、项目主要功能

5.1 用户端核心流程

① 注册与登录
用户访问 /register 填写用户名和密码完成注册，登录后系统颁发 JWT Token，前端本地存储后续用于接口鉴权。

② AI 智能推荐
用户在推荐页 /recommend 输入自然语言购车需求，系统调用 Dify 工作流自动分析，几秒内返回：

• 结构化需求参数（价格区间、续航要求、车型级别等）
• 匹配的车型卡片列表
• 个性化 AI 推荐报告（Markdown 渲染）

③ 车型浏览与详情
/cars 页面展示全量车型，支持多维度筛选。点击进入详情页可查看：封面图、参数表（续航/充电/尺寸级别）、详情图集，同时记录浏览历史。

④ 购物车与下单
收藏心仪车型后加入购物车，支持 全款购买（填写收货地址）和 定金预订（选择线下提车时间）两种购买方式，支付完成后订单进入管理端流转。

⑤ 试驾预约
在车型详情页点击「预约试驾」，填写姓名、电话、预约时间，管理员在后台确认后用户收到消息通知。

5.2 管理端核心流程

① 数据概览：登录后默认展示核心数据看板，可快速了解平台运营状态。

② 车型管理：新增/编辑车型时支持图片上传（上传至 /static/uploads/），填写完整的车型参数信息。

③ 试驾管理：左侧导航栏「试驾管理」菜单项显示未处理申请数量的小红点，管理员可确认、完成或取消试驾预约，状态变更后系统自动推送消息通知给对应用户。

---

六、演示过程中遇到的问题

6.1 个人原因

没有提前完全熟悉项目的所有功能以及项目演示过程中遇到突发情况的应对措施。

改进方向： 演示前应完整走查所有主要流程，对可能的异常场景准备备用展示方案，必要时预先录制演示视频作为补充。

6.2 项目本身存在的 Bug

问题描述： 用户端登录接口（/api/auth/login）未对账号角色做严格限制，管理员账号可以从用户端正常登录，并借助用户端接口对其他用户数据进行查询和修改操作，存在越权访问风险。

根本原因： 用户端与管理端共用了同一套 JWT 认证逻辑，路由层未区分用户角色进行接入校验。

修复思路：

• 用户端登录接口增加角色校验，拒绝管理端账号登录
• 管理端接口统一使用 require_admin 依赖，普通用户 Token 无法访问管理接口
• 或将用户端与管理端的认证体系完全隔离，分别维护独立的 Token 有效期和权限范围

---

七、收获与总结

7.1 完整体验了项目开发全流程

需求分析 → 数据库设计 → 后端 API 开发 → 前端页面开发 → 调试  → 部署运行

深刻理解了前后端协作的实际场景：前端如何通过 Axios 调用后端 RESTful API、如何处理 Token 鉴权、如何渲染异步数据；后端如何设计分层架构保证代码可维护性。

7.2 掌握了 AI 工作流集成方法

首次将 Dify 低代码 AI 工作流与传统 Web 后端相结合，学会了：

• 如何设计工作流的输入/输出接口，生成apikey在项目中调用工作流
• 如何在后端异步调用外部 AI 服务（httpx 异步客户端）
• 如何处理 AI 智能推荐的超时、降级等容错逻辑

7.3 技术能力提升

• FastAPI：掌握路由、依赖注入、中间件、异步处理、静态文件服务等核心特性
• SQLAlchemy ORM：熟练使用 ORM 进行复杂查询、关联查询和数据建模
• JWT 认证：从零实现了基于 Token 的无状态身份认证体系
• 前端工程化：掌握原生 JS + Axios 进行前后端数据交互的完整实践

---

八、未来展望

优化方向	具体描述
图片数据化	当前车型图片为本地静态资源，可以通过爬虫自动抓取各品牌官网图片，实现图片数据的自动化更新与管理
功能完善	补充车型横向对比功能（多车型参数对比表）；增加用户评分/评价模块（UGC 内容）；建立用户论坛/社区，促进用户间购车经验交流
商业化扩展	增加商户端入驻功能，入驻商户可自主管理车型上架；接入真实支付平台（微信支付 / 支付宝）完成真实交易闭环
AI 能力升级	基于用户历史行为（浏览记录、收藏、推荐历史）构建个性化推荐模型，进一步提升推荐准确率；引入多轮对话能力，优化 AI 推荐交互体验
安全加固	修复已知的角色越权漏洞
用户体验	优化 Dify 推荐等待时长的用户反馈（进度提示）

---