从零搭建集智能客服、仲裁通知、角色化界面于一体的线上菜场系统

背景与痛点

传统农贸市场一直面临三大顽疾：

• 交易纠纷 – 缺斤少两、商品质量争议难以追溯

• 食品安全 – 农产品来源不明，消费者缺乏信任

• 沟通成本 – 买家、摊主、市场管理三方信息割裂

为了解决这些问题，我开发了 “智慧菜篮子”——一个线上线下融合的智慧农贸平台，并重点集成了 Dify 工作流驱动的智能客服，让AI自动处理常见咨询，复杂问题一键转人工仲裁。

本文将分享项目的整体架构、技术选型、核心实现细节以及踩坑经验。

---

一、技术栈一览

层级	技术	版本	理由
前端	HTML5 + CSS3 + Vanilla JS	-	轻量无依赖，快速开发
后端	FastAPI	0.104+	高性能、自动API文档、类型安全
ORM	SQLAlchemy	2.0+	成熟稳定，防SQL注入
数据库	SQLite	3.45+	嵌入式，中小项目友好
AI集成	Dify Workflow	0.6+	低代码编排，秒级接入LLM

完整架构图如下：

text

前端层（买家/卖家/管理面板）
        │
        ▼
API层（FastAPI：认证、商品、订单、客服）
        │
        ▼
数据层（SQLite + SQLAlchemy）
        │
        ▼
AI层（Dify工作流：意图识别→自动回复/人工仲裁）

---

二、核心功能与实现

2.1 角色化前端：一套页面三套面板

同一个 index.html 根据登录用户角色动态切换界面：

• 买家 – 商品浏览、购物车、下单、溯源查询

• 卖家 – 订单状态管理（待付款→备货中→配送中→已完成）

• 管理员 – 仲裁通知监控、纠纷处理

关键代码逻辑：

javascript

if (currentUser.role === 'buyer') {
    renderStalls(); renderProducts();
} else if (currentUser.role === 'seller') {
    renderSellerPanel();   // 显示订单管理按钮
} else if (currentUser.role === 'manager') {
    renderManagerPanel();
    startArbitrationPolling(); // 启动轮询监控
}

2.2 智能客服 + 人工仲裁（最大亮点）

为什么用 Dify 而不是直接调用 OpenAI API？

• 工作流可视化编排，非技术也能调整意图分类逻辑

• 内置 class_name 输出字段，方便判断是否需要人工介入

• 支持 blocking 模式，避免 SSE 流式解析的坑

工作流设计

text

用户提问 → Dify工作流 → 意图识别
                ├─ 常见问题（营业时间、退货政策）→ 直接回答
                └─ 复杂/投诉类 → class_name="human" → 创建仲裁通知 → 管理员弹窗处理

核心后端代码（FastAPI）

python

@app.post("/api/customer-service/message")
def chat_with_cs(chat: ChatMessage, db: Session = Depends(get_db)):
    payload = {
        "inputs": {"query": chat.message},
        "response_mode": "blocking",   # 关键：不是SSE流式
        "user": current_user.id
    }
    resp = requests.post(dify_url, json=payload, headers=headers, timeout=30)
    result = resp.json()
    final_outputs = result.get("data", {}).get("outputs", {})
    
    # 判断是否需要人工介入
    if final_outputs.get("class_name") == "human":
        notification = ArbitrationNotification(
            user_id=current_user.id,
            message=chat.message
        )
        db.add(notification)
        db.commit()
        return {"answer": "您的问题已转交人工仲裁员，请稍后", "need_human": True}
    return {"answer": final_outputs.get("answer", "已收到")}

前端轮询新通知（10秒间隔）

javascript

let lastCount = 0;
setInterval(async () => {
    const res = await apiGet('/notifications/pending');
    if (res.notifications.length > lastCount) {
        showToast('⚠️ 新的仲裁请求！');
        showArbitrationDetail(res.notifications[0]);
    }
    lastCount = res.notifications.length;
}, 10000);

2.3 安全与权限控制

• 密码加密：SHA256 + 随机盐值，数据库中存储 salt:hash

• Token认证：登录生成随机 token 存入数据库，请求头携带 Authorization: Bearer <token>

• 角色中间件：每个接口通过 Depends(get_current_user) 检查权限

python

def get_current_user(token: str = Header(...), db: Session = Depends(get_db)):
    user = db.query(User).filter(User.token == token).first()
    if not user:
        raise HTTPException(status_code=401)
    return user

2.4 订单状态机

卖家端通过同一个按钮推进订单状态：

python

if order.status == "待付款": order.status = "备货中"
elif order.status == "备货中": order.status = "配送中"
elif order.status == "配送中": order.status = "已完成"

---

三、踩坑与解决

坑1：Dify API 返回空值

• 现象：按照官方SSE示例解析，总是得到空内容。

• 原因：使用了 response_mode: "streaming" 且 SSEClient 解析方式有误。

• 解决：改用 response_mode: "blocking"，直接 resp.json() 读取 data.outputs。

坑2：JavaScript 函数未定义导致按钮无响应

• 现象：点击“确认订单”无反应。

• 原因：函数定义在 $(document).ready 内，全局作用域不可访问。

• 解决：将事件绑定函数挂载到 window 对象，或在 bindEventListeners 中统一注册。

坑3：实时性要求与轮询开销平衡

• 方案：管理员端使用10秒轮询，而非 WebSocket（降低复杂度），实际测试中通知延迟可接受。

---

四、数据库设计精简

核心表结构（SQLAlchemy模型）：

表名	主要字段	作用
users	id, username, password_hash, role, token	统一账户体系
stalls	id, name, market_id, category, rating	摊位信息
products	id, name, price, origin, has_trace	农产品与溯源标记
orders	id, order_number, status, total_amount	订单主表
arbitration_notifications	id, user_id, message, status	待处理仲裁单

ER关系：

• User 1:N Order

• Market 1:N Stall 1:N Product

• Order 1:1 Dispute（纠纷可选）

---

五、运行与部署

环境准备（.env 文件）：

text

DATABASE_URL=sqlite:///./market.db
DIFY_API_KEY=app-xxxxx
DIFY_WORKFLOW_URL=https://api.dify.ai/v1/workflows/run

一键启动：

bash

pip install fastapi uvicorn sqlalchemy requests python-dotenv
python init_db.py   # 创建表并插入演示数据
uvicorn app:app --reload --port 8000

访问：

• 前端：http://localhost:8000/static/index.html

• API文档：http://localhost:8000/docs

---

六、总结与展望

项目亮点

1. 低成本AI集成：Dify工作流让智能客服上线时间从周级缩短到小时级

2. 仲裁闭环：AI无法处理的问题自动生成通知，管理员实时介入

3. 角色自适应界面：一套代码服务三类用户，维护成本低

可扩展方向

• 接入微信小程序，扩大触达范围

• 使用 WebSocket 替代轮询，提升实时性

• 增加OCR电子秤接口，自动录入商品重量

• 基于Dify工作流增加情绪分析节点，优先处理愤怒用户