online-order-h5/doc/architecture_design.md

多角色餐饮点餐系统架构设计 v3

一、手机端用户入口架构 (C 端)

系统根据用户进入的方式，将 App 划分为三种上下文模式 (Context Mode)。不同模式决定了用户的功能权限、UI 展示以及路由行为。

graph TD
    Entry{用户入口}

    Entry -->|打开APP/首页| Mode1[平台模式 Platform Mode]
    Entry -->|扫描店铺码/点击分享链接| Mode2[店铺模式 Shop Mode]
    Entry -->|扫描桌位码| Mode3[桌位模式 Table Mode]

    subgraph Mode1 [平台模式 (流量分发)]
        Home[首页 Index] -->|推荐| ShopList[商家列表]
        Home -->|推荐| DishList[菜品列表]
        ShopList -->|选择店铺| ShopMenu[店铺菜单]
        DishList -->|点击菜品| ShopMenu
    end

    subgraph Mode2 [店铺模式 (外卖/预约)]
        ShopQR[店铺码] -->|解析| ShopMenu
        Note2[仅限: 外卖 / 自提 / 预约]
    end

    subgraph Mode3 [桌位模式 (堂食点餐)]
        TableQR[桌位码] -->|解析| TableMenu[堂食菜单]
        Note3[仅限: 扫码下单 / 加菜]
    end

    ShopMenu -.->|扫桌码升级| TableMenu

1.1 三种模式详解

1. 平台模式 (Platform Mode)

• 场景: 用户直接打开 APP，或访问域名根路径。
• 定位: 流量分发、营销推广。
• 功能:
  • 展示推荐商家、热门店铺。
  • 展示推荐菜品（点击直接跳转对应店铺外卖页）。
  • 全局搜索（搜店铺、搜菜品）。
• 状态: shopId 为空，tableCode 为空。
• 路由: /index

2. 店铺模式 (Shop Mode)

• 场景: 扫描店铺推广码、点击店铺分享链接、从平台首页点击店铺进入。
• 定位: 单店的外卖与预约服务。
• 限制:
  • 锁定: 用户被锁定在该店铺内，无法"切换桌号"（因为没桌号）。
  • 排他: 除非用户手动返回平台首页或扫描其他店铺码，否则一直在该店铺上下文中。
  • 功能限制: 不可堂食下单（没有桌号信息）。只能选择 "外卖配送"、"到店自提" 或 "预约订座"。
• 状态: shopId 有值，tableCode 为空。
• 路由: /menu?shopId={id}

3. 桌位模式 (Table Mode)

• 场景: 扫描餐桌二维码。
• 定位: 店内堂食下单。
• 限制:
  • 强锁定: 绑定 shopId 和 tableCode。
  • 禁止切换: 无法切换店铺，无法切换桌号（除非扫描新二维码覆盖当前会话）。
  • 功能: 开启 "堂食下单" 功能。
• 状态: shopId 有值，tableCode 有值。
• 路由: /menu?shopId={id}&tableCode={code}

---

二、核心业务流程设计

2.1 状态管理 (Store)

在 user.ts 或 app.ts 中维护全局上下文：

interface AppContext {
  mode: "platform" | "shop" | "table";
  shopId?: string; // 当前锁定店铺
  tableCode?: string; // 当前锁定桌位
  shopInfo?: Shop; // 店铺详情缓存
}

2.2 路由规则与守卫

路由	描述	守卫逻辑
/index	平台首页	清除 currentShop/tableCode，进入 Platform Mode
/scan	扫码解析	解析参数 -> 判断模式 -> 写入 Store -> 跳转
/menu	菜单页	必须有 shopId (Query 或 Store)。 无 shopId -> 重定向回 /index。 有 tableCode -> 显示堂食 UI。 无 tableCode -> 显示外卖/预约 UI。

2.3 扫码解析逻辑 (/scan)

1. 获取参数: shopId (必填), tableCode (可选)。
2. 逻辑判断:
   • 有 tableCode:
     • 模式 = Table Mode
     • 调用 initGuestSession(shopId, tableCode)
     • 跳转 /menu (携带桌位信息)
   • 无 tableCode:
     • 模式 = Shop Mode
     • 设置 currentShopId = shopId
     • 跳转 /menu (仅店铺信息)

---

---

四、UI/UX 差异化设计详解

4.1 平台模式 (Platform Mode) - "发现与导流"

核心目标: 帮助用户快速找到感兴趣的餐厅或美食。

页面布局:

• 顶部栏:
  • 📍 位置定位: 显示当前送餐地址/位置。
  • 🔍 全局搜索框: 搜索店铺名、菜品名。
• 内容区:
  • Banner 轮播: 平台级活动、节日促销。
  • 金刚区 (Icons): 菜系分类 (日料、中餐、西餐...)、功能入口 (我的收藏、领券中心)。
  • 推荐模块:
  • "猜你喜欢" (基于历史)
  • "附近热推" (基于 LBS)
  • 店铺列表: 垂直滚动流，展示店铺卡片 (Logo、评分、配送时间、起送价)。
• 底部导航: [首页] [订单] [我的]

4.2 店铺模式 (Shop Mode) - "外卖与品牌"

核心目标: 展示店铺品牌形象，提供便捷的外卖/自提服务。

页面布局:

• 店铺头部 (Header):
  • 品牌重展示: 大幅店招背景图、Logo、店铺名称。
  • 服务信息: 评分 ⭐4.8、配送时间 30min、公告跑马灯。
  • 服务切换: [外卖配送] / [到店自提] / [预约订座] Tab 切换。
• 菜单区:
  • 公告栏: 优惠券领取、满减活动提示。
  • 布局: 左侧分类栏 + 右侧商品流 (标准外卖布局)。
• 底部结算栏:
  • 显示：购物车预览、预估配送费、起送价进度条。
  • 按钮：去结算 (跳转确认订单页)。

4.3 桌位模式 (Table Mode) - "高效点餐"

核心目标: 快速下单，减少服务员介入，明确就餐状态。

页面布局:

• 顶部栏:
  • 桌台信息: 醒目展示 [ A1 桌 ]，旁边可有 多人点餐 状态提示。
  • 人数设置: 快捷调整就餐人数。
• 菜单区:
  • 极简头部: 压缩店铺信息，最大化菜单展示区域。
  • 特色功能: 呼叫服务员 (加水/催单) 悬浮球。
  • 商品展示: 突出 "推荐/热销"，支持大图模式。
• 底部操作栏:
  • 显示：当前已选金额、数量。
  • 按钮：选好了 -> 确认下单 (直接落单到厨房，区别于外卖的"去结算")。
• 特殊状态:
  • 下单后：底部变为 "加菜模式"，显示 "已下单金额" 和 "待下单金额"。

---

五、多 Agent 并行开发计划

为提高开发效率，任务可拆分为三个独立的开发轨道 (Tracks)，可由多个 Agent 并行执行：

Track A: 平台前端开发 (Agent A)

• 目标: 完成 /index 平台首页及公共组件。
• 任务:
  1. 封装通用 UI 组件: SearchBar, ShopCard, DishCard.
  2. 实现 src/views/index/index.vue:
     • 集成 Banner 轮播。
     • 实现分类金刚区。
     • 实现推荐店铺流 (Mock Data)。

Track B: 店铺与外卖流程 (Agent B)

• 目标: 完善 /menu 的外卖模式 (Shop Mode)。
• 任务:
  1. 封装 <ShopHeader> 组件: 展示店招、评分、配送信息。
  2. 封装 <DeliveryFooter> 组件: 购物车预览、起送价逻辑、去结算。
  3. 改造 menu.vue: 适配 shopId，集成 B 端组件。

Track C: 堂食点餐流程 (Agent C)

• 目标: 完善 /menu 的堂食模式 (Table Mode)。
• 任务:
  1. 封装 <TableHeader> 组件: 桌号显示、人数切换、呼叫服务。
  2. 封装 <TableFooter> 组件: 堂食下单逻辑 (直接提交订单)。
  3. 改造 cart.ts: 区分堂食购物车(需提交)与外卖购物车(本地存储)。

集成阶段 (Integrator Agent)

• 目标: 路由整合与联调。

• 任务:

  1. 确认 app.ts 状态管理无误。
  2. 验证 scan/index.vue 到各模式的跳转。
  3. 全局样式统一与代码审查。 Admin[系统管理员 admin] end

subgraph Company[公司层] Owner[老板 owner] end

subgraph Shop[店铺层] Manager[店长 manager] Staff[员工 staff] end

subgraph Customer[顾客层] Customer1[顾客 customer] Guest[访客 guest] end

Admin -->|管理| Owner Owner -->|拥有多家| Shop Manager -->|管理| Staff Shop -->|服务| Customer1 Shop -->|服务| Guest

### 4.1 角色权限矩阵

功能模块 admin owner manager staff customer ────────────────────────────────────────────────────────────────── [平台管理] 查看所有公司 ✓ ✗ ✗ ✗ ✗ 创建/编辑公司 ✓ ✗ ✗ ✗ ✗

[公司/多店铺管理] 查看公司下所有店铺 ✓ ✓ ✗ ✗ ✗ 多店铺汇总报表 ✓ ✓ ✗ ✗ ✗

[单店铺管理] 店铺仪表盘 ✓ ✓ ✓ ✗ ✗ 菜单管理 ✓ ✓ ✓ ✗ ✗ 员工管理 ✓ ✓ ✓ ✗ ✗

[日常运营] 桌位管理 ✓ ✓ ✓ ✓ ✗ 订单处理 ✓ ✓ ✓ ✓ ✗ 收银结账 ✓ ✓ ✓ ✓ ✗