Web 公开预约重构 — Group Appointment 架构设计

更新日期: 2026-02-05

相关功能: 014-web-public-booking（重构）

参考实现: Guest Mobile App (Flutter) + 管理后台 BookingWizard

1. 用户操作流程

1.1 核心理念

对齐 Guest Mobile App：逐个服务配置，不是批量多选。每个服务独立选技师和时间，选完自动入购物车。支持多 Guest（Group Appointment）。

1.2 完整流程图

1.3 逐步详解

2. 购物车弹框设计

2.1 弹框结构

┌──────────────────────────────────────┐
│  购物车                          ✕   │
├──────────────────────────────────────┤
│                                      │
│  👤 Guest A (You)                    │
│  ┌────────────────────────────────┐  │
│  │ 💅 Full Nail Set               │  │
│  │ Tech: Emma · Feb 15, 10:00 AM │  │
│  │ $50 · 60 min                   │  │
│  │           [编辑]  [移除]       │  │
│  └────────────────────────────────┘  │
│  ┌────────────────────────────────┐  │
│  │ 🦶 Pedicure                    │  │
│  │ Tech: Any · Feb 15, 11:00 AM  │  │
│  │ $40 · 45 min                   │  │
│  │           [编辑]  [移除]       │  │
│  └────────────────────────────────┘  │
│                                      │
│  👤 Guest B (Alice)                  │
│  ┌────────────────────────────────┐  │
│  │ 💅 Gel Manicure                │  │
│  │ Tech: Emma · Feb 15, 11:00 AM │  │
│  │ $45 · 50 min                   │  │
│  │           [编辑]  [移除]       │  │
│  └────────────────────────────────┘  │
│                                      │
│  [+ 添加 Guest]                      │
│                                      │
├──────────────────────────────────────┤
│  3 services · 155 min                │
│  Total: $135            [结账 →]     │
└──────────────────────────────────────┘

2.2 添加 Guest 弹框

┌──────────────────────────────┐
│  添加同行客人                 │
├──────────────────────────────┤
│  姓名 *:  [________________] │
│  手机号:  [________________] │
│  (可选)                      │
│                              │
│       [取消]  [确认添加]     │
└──────────────────────────────┘

添加 Guest 后回到服务列表，当前活跃 Guest 切换为新 Guest，可为其选择服务。

3. API 调用序列

3.1 浏览阶段

3.2 冲突检测：excluded_slots 参数

参数格式（JSON 编码后作为 query string）：

[
  {
    "employee_id": "emp_001",   // 或 null（任意技师）
    "start_time": "10:00",      // HH:mm
    "duration": 60              // 分钟
  },
  {
    "employee_id": null,
    "start_time": "11:00",
    "duration": 45
  }
]

后端处理逻辑：

• employee_id 有值 → 该技师在该时间段被屏蔽
• employee_id = null（任意技师）→ 从可用技师池减少一个名额

前端生成逻辑：遍历购物车中所有 Guest 的所有项目，筛选出与当前选择日期相同的项目：

// 伪代码
const excludedSlots = cart.allGuests
  .flatMap(guest => guest.items)
  .filter(item => item.date === selectedDate && item.time !== null)
  .map(item => ({
    employee_id: item.employee_id,  // null = any
    start_time: item.time,
    duration: item.service.duration
  }));

3.3 确认阶段

3.4 确认预约请求体

单 Guest（无 Group）：

{
  "phone": "1234567890",
  "code": "123456",
  "store_id": "store_001",
  "guest_name": "Alice",
  "email": "alice@example.com",
  "notes": "Please use gel polish",
  "source": "customer_web",
  "notification_preferences": { "sms": true, "email": true },
  "ref": "marketing-abc",
  "sub_appointments": [
    { "service_id": "svc_1", "employee_id": "emp_1", "datetime": "2025-02-15T10:00:00" },
    { "service_id": "svc_2", "employee_id": null, "datetime": "2025-02-15T11:00:00" }
  ]
}

多 Guest（Group Appointment）：

{
  "phone": "1234567890",
  "code": "123456",
  "store_id": "store_001",
  "guest_name": "Alice",
  "email": "alice@example.com",
  "notes": "We're celebrating a birthday!",
  "source": "customer_web",
  "notification_preferences": { "sms": true, "email": true },
  "ref": "marketing-abc",

  // Primary Guest 的服务
  "sub_appointments": [
    { "service_id": "svc_1", "employee_id": "emp_1", "datetime": "2025-02-15T10:00:00" }
  ],

  // Companion Guests
  "companion_appointments": [
    {
      "guest_name": "Bob",
      "guest_phone": "0987654321",    // optional
      "items": [
        { "service_id": "svc_2", "employee_id": "emp_2", "datetime": "2025-02-15T10:00:00" }
      ]
    },
    {
      "guest_name": "Charlie",
      "items": [
        { "service_id": "svc_1", "employee_id": null, "datetime": "2025-02-15T10:30:00" }
      ]
    }
  ]
}

4. 共享服务层架构

4.1 共享服务接口设计

// backend/services/booking/bookingService.js (NEW)

/**
 * 创建预约（支持单 Guest 和 Group）
 * 被 cart_appointment.js 和 public/booking.js 共同调用
 */
async function createBooking(client, {
  // 必需
  tenantSchema,
  storeId,
  primaryGuestId,
  startDatetime,
  subAppointments,      // [{ service_id, employee_id, datetime }]
  source,               // 'customer_web' | 'customer_mobile' | 'walk_in' | ...
  createdBy,            // guest_self_service | employee_id

  // 可选
  notes,
  companionAppointments,  // [{ guest_id, guest_name, guest_phone, items }]
  notificationPreferences,
  trackingRef,
}) {
  // 1. 创建 primary appointment + sub_appointments
  // 2. 如果有 companion_appointments：
  //    a. 查找或创建 companion guest 记录
  //    b. 为每个 companion 创建 appointment + sub_appointments
  //    c. 创建 appointment_group
  //    d. 添加所有 group_members
  //    e. 更新 guest_relationships
  // 3. 返回 { appointmentId, groupCode?, allAppointmentIds }
}

4.2 文件变更清单

5. 前端状态管理

5.1 Booking Store 重构

// 新的购物车结构（按 Guest 分组）
interface GuestCart {
  id: string;              // 唯一标识
  name: string;            // Guest 姓名
  phone?: string;          // Guest 手机号（optional）
  isPrimary: boolean;      // 是否为主 Guest
  items: CartItem[];       // 该 Guest 的服务项目
}

interface CartItem {
  id: string;              // 唯一标识
  service: Service;
  employee_id: string | null;
  employee_name: string | null;
  date: string | null;     // YYYY-MM-DD
  time: string | null;     // HH:mm
}

interface BookingState {
  store: Store | null;
  guests: GuestCart[];          // 所有 Guest 及其购物车
  activeGuestId: string | null; // 当前正在配置的 Guest
  editingItemId: string | null; // 当前正在编辑的项目

  // Checkout 信息
  notificationPreferences: { sms: boolean; email: boolean } | null;
  notes: string | null;
  trackingRef: string | null;
}

5.2 关键操作

6. 前端页面变更

7. 已有基础设施（可直接复用）

8. 与 Mobile App 流程对比