kitchen/docs/superpowers/specs/2026-04-17-order-assistant-design.md

点餐助手设计规格文档

创建时间: 2026-04-17 状态: 已确认

一、功能概述

点餐助手是工具中心新增工具，支持双向场景：

• 用户点餐：用户在App创建点单，生成二维码，商家扫码查看
• 商家推单：商家在App推单，顾客扫码下单

核心能力：菜品管理、二维码/条形码生成、WebSocket实时同步、网页端展示。

二、数据模型

OrderItem（点单项）

字段	类型	必填	说明
id	String	✅	UUID
name	String	✅	菜品名称
source	enum	✅	browseHistory / search / manual / merchantRecommend
quantity	int	✅	数量，默认1
price	double?	❌	单价
ingredients	String?	❌	食材备注
note	String?	❌	备注信息
recipeId	String?	❌	关联菜谱ID

Order（点单）

字段	类型	必填	说明
id	String	✅	UUID，唯一值
orderNo	String	✅	订单编号（时间戳+随机数）
type	enum	✅	userOrder / merchantPush
status	enum	✅	draft / active / completed / cancelled
items	List<OrderItem>	✅	菜品列表
totalAmount	double?	❌	总金额
note	String?	❌	整单备注
createdAt	String	✅	ISO8601
updatedAt	String	✅	ISO8601
createdBy	String	✅	创建者标识
tableNo	String?	❌	桌号
recordCount	int	✅	记录条数

本地存储

• order_assistant_records：SharedPreferences JSON存储历史点单
• order_assistant_count：记录总条数计数器
• 浏览记录来源：复用 BrowseHistoryController

三、API接口

Base URL: https://eat.wktyl.com/api/kitchen

REST API

方法	路径	说明	请求体	响应
POST	/order	创建点单	Order JSON	{ orderId, orderNo }
GET	/order/{id}	获取点单详情	-	Order JSON
PUT	/order/{id}	更新点单	Order JSON	{ success }
GET	/order/{id}/qr	获取二维码URL	-	{ qrUrl, barcodeUrl }
GET	/orders	历史点单列表	?page&limit&status	{ list, total }

WebSocket

ws://eat.wktyl.com/ws/kitchen/order/{orderId}

事件：
- order.updated  → 点单内容变更
- item.added     → 新增菜品
- item.removed   → 移除菜品
- status.changed → 状态变更

二维码/条形码编码

• 二维码：编码URL https://eat.wktyl.com/api/kitchen?id={orderId}
• 条形码：编码订单编号 orderNo（Code128）

开发阶段Mock策略

App端先使用本地 SharedPreferences + Mock API Service，后端就绪后切换。

四、App端页面设计

页面结构

OrderAssistantPage
├── 顶部导航栏（毛玻璃）
│   ├── 返回按钮
│   ├── 标题「点餐助手 🍽️」
│   └── 历史记录按钮
├── 模式切换（SegmentedControl）
│   ├── 🧑 用户点餐
│   └── 🏪 商家推单
├── 点单信息区
│   ├── 桌号输入
│   ├── 整单备注
│   └── 记录条数统计
├── 菜品列表区
│   ├── 已添加菜品卡片（可滑动删除）
│   └── 添加菜品按钮
├── 添加菜品弹窗（ActionSheet）
│   ├── 📖 从浏览记录选择
│   ├── 🔍 搜索菜品
│   ├── ✏️ 手动填写
│   └── ⭐ 商家推荐
├── 底部操作栏
│   ├── 总金额
│   ├── 生成二维码按钮
│   └── 生成条形码按钮
└── 二维码/条形码展示弹窗
    ├── 二维码图片（可保存）
    ├── 条形码图片（可保存）
    └── 分享按钮

交互流程

1. 用户点餐：选择菜品 → 填写备注 → 生成二维码 → 商家扫码
2. 商家推单：选择推荐菜品 → 生成二维码 → 顾客扫码下单
3. 菜品来源：浏览记录/搜索/手动填写/商家推荐

文件结构

lib/src/
├── models/tools/
│   └── order_model.dart          # Order + OrderItem 模型
├── controllers/tools/
│   └── order_assistant_controller.dart  # 点餐助手控制器
├── services/tools/
│   └── order_api_service.dart    # API服务（含Mock）
├── pages/tools/
│   ├── order_assistant_page.dart # 主页面
│   └── widgets/
│       ├── order_item_card.dart  # 菜品卡片
│       ├── add_item_sheet.dart   # 添加菜品弹窗
│       ├── browse_history_picker.dart # 浏览记录选择器
│       ├── search_dish_sheet.dart     # 搜索菜品
│       ├── manual_input_sheet.dart    # 手动填写
│       └── qr_code_dialog.dart   # 二维码展示弹窗

五、网页端设计

文件位置

web_order/index.html — 纯HTML/CSS/JS单文件，独立部署到 eat.wktyl.com

URL参数

https://eat.wktyl.com/api/kitchen?id={orderId}
https://eat.wktyl.com/api/kitchen?orderNo={orderNo}

页面结构

点单展示页（移动端优先响应式）
├── 顶部
│   ├── Logo + 标题「点餐助手」
│   ├── 点单类型标签
│   └── 实时状态指示器 🟢
├── 点单信息卡片
│   ├── 订单编号（条形码）
│   ├── 桌号
│   ├── 创建时间
│   └── 整单备注
├── 菜品列表
│   ├── 菜品卡片（名称/数量/食材/备注/来源/价格）
│   └── 实时更新动画
├── 合计区域
│   ├── 菜品总数
│   └── 总金额
├── 操作区（商家推单模式）
│   ├── 确认下单按钮
│   └── 修改数量
└── 底部
    ├── 最后更新时间
    └── WebSocket连接状态

实时同步

• WebSocket连接 wss://eat.wktyl.com/ws/kitchen/order/{orderId}
• 事件驱动更新：order.updated / item.added / item.removed / status.changed
• 降级策略：WebSocket断开时切换5秒轮询

视觉风格

• iOS 26 风格：毛玻璃卡片、圆角、柔和阴影
• 响应式：手机单列 / 平板双列 / 桌面三列
• 动画：菜品新增淡入、删除淡出、状态变更闪烁
• 深色模式自动适配

六、工具注册

在 ToolItem.defaultTools 中新增：

ToolItem(
  id: 'order_assistant',
  name: '点餐助手',
  icon: '🍽️',
  needsNetwork: true,
  category: 'cooking',
  route: '/tools/order-assistant',
  description: '点餐推单，二维码分享',
  waterfallSlot: WaterfallSlotConfig(show: true, priority: 7),
)

路由注册：/tools/order-assistant → OrderAssistantPage