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

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

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

```mermaid
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` 中维护全局上下文：

```typescript
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)。<br>无 `shopId` -> 重定向回 `/index`。<br>有 `tableCode` -> 显示堂食 UI。<br>无 `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
──────────────────────────────────────────────────────────────────
[平台管理]
查看所有公司 ✓ ✗ ✗ ✗ ✗
创建/编辑公司 ✓ ✗ ✗ ✗ ✗

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

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

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

```

```