Web 预约与签到模块 — CUJ 关键用户旅程

Public Booking, Checkin & Terminal | 更新时间: 2026-02-09

架构概览

在线预约系统组件关系

flowchart TB
    subgraph "Public Booking Pages"
        P1["[store]/page.tsx\n服务选择"]
        P2["[store]/employee/page.tsx\n技师选择"]
        P3["[store]/time/page.tsx\n时间选择"]
        P4["[store]/verify/page.tsx\nOTP验证+确认"]
        P5["[store]/success/page.tsx\n成功页"]
        P6["my-appointments/page.tsx\n我的预约"]
    end

    subgraph "State Management"
        BS["booking-store.ts\nZustand + SessionStorage"]
        GAS["guest-auth-store.ts\nZustand + LocalStorage"]
    end

    subgraph "Booking Components"
        SS["ServiceSelector"]
        TS["TechnicianSelector"]
        TSP["TimeSlotPicker"]
        GS["GuestSearch"]
    end

    subgraph "Backend API"
        API1["GET /public/booking/stores"]
        API2["GET /public/booking/services"]
        API3["GET /public/booking/employees"]
        API4["GET /public/booking/slots"]
        API5["POST /public/booking/confirm"]
        API6["POST /guest-auth/send-code"]
        API7["POST /guest-auth/verify-code"]
    end

    P1 --> BS
    P2 --> BS
    P3 --> BS
    P4 --> BS
    P4 --> GAS
    P5 --> BS

    P1 -.-> SS
    P2 -.-> TS
    P3 -.-> TSP

    P1 --> API2
    P2 --> API3
    P3 --> API4
    P4 --> API6
    P4 --> API7
    P4 --> API5

购物车数据模型

预约来源追踪

目录

CUJ 总览与优先级矩阵

CUJ-G1: 公共在线预约 — 单服务

P0 在线获客 — 客户通过 /booking/[store] 自助预约单个服务

用户流程

flowchart TD
    A["访问 /booking/store001\n服务列表页"] --> B["浏览服务分类\n选择一个服务"]
    B --> C["添加到购物车\nautomatic navigate"]
    C --> D["/employee 选择技师\nAny Available 或指定"]
    D --> E["/time 选择日期时间\n30天内可选"]
    E --> F{"购物车完整?\nisAllComplete()"}
    F -->|"是"| G["点击 Proceed to Booking"]
    F -->|"否"| B
    G --> H["/verify 身份验证\n见 CUJ-G4"]
    H --> I["确认预约\n填写备注+通知偏好"]
    I --> J["POST /public/booking/confirm"]
    J --> K{成功?}
    K -->|"是"| L["/success 成功页\n显示确认号"]
    K -->|"否"| M["错误提示\n重试"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style L fill:#4CAF50,stroke:#2E7D32,color:#fff
    style M fill:#f44336,stroke:#c62828,color:#fff

BDD 场景

场景 G1.1: 完整单服务预约 — 指定技师

测试: web-booking.spec.ts

场景 G1.2: 选择"任意技师" — 系统自动分配

测试: web-booking.spec.ts

场景 G1.3: 指定技师后只显示该技师时段

场景 G1.4: 深夜访问 — 自动从明天开始

场景 G1.5: 返回修改 — 自动清理未完成项

CUJ-G2: 公共在线预约 — 多服务购物车

P0 提升客单价 — 客户可在一次预约中选择多个服务

用户流程

flowchart TD
    A["服务列表页"] --> B["选择第1个服务"]
    B --> C["配置技师+时间"]
    C --> D["返回服务列表\n购物车底栏显示1项"]
    D --> E["选择第2个服务"]
    E --> F["配置技师+时间\n排除已占用时段"]
    F --> G["返回服务列表\n购物车底栏显示2项"]
    G --> H{"继续添加?"}
    H -->|"是"| I["选择第N个服务"]
    H -->|"否"| J["点击购物车\n查看所有项"]
    J --> K["确认全部完整"]
    K --> L["Proceed to Booking"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style L fill:#4CAF50,stroke:#2E7D32,color:#fff

BDD 场景

场景 G2.1: 添加多个服务到购物车

测试: web-booking.spec.ts

场景 G2.2: 时段冲突检测 — Excluded Slots

场景 G2.3: 编辑购物车中已有的服务

场景 G2.4: 删除购物车中的服务

场景 G2.5: 提交时生成 sub_appointments

CUJ-G3: 公共在线预约 — Group Booking

P1 团体客户 — 主客户为同伴也预约服务

用户流程

flowchart TD
    A["主客户配置完自己的服务"] --> B["点击 Add Guest"]
    B --> C["输入同伴姓名\n可选手机号"]
    C --> D["为同伴选择服务"]
    D --> E["配置技师+时间"]
    E --> F{"继续添加同伴?"}
    F -->|"是"| B
    F -->|"否"| G["全部配置完成\nProceed to Booking"]
    G --> H["确认提交"]
    H --> I["后端创建 companion_appointments\n生成 group_code"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style I fill:#4CAF50,stroke:#2E7D32,color:#fff

BDD 场景

场景 G3.1: 为同伴预约服务

场景 G3.2: Group Booking 数据结构

CUJ-G4: 客户身份验证 — OTP

P0 身份识别 — 060-guest-auth-redesign: 手机/邮箱 OTP 验证

用户流程

flowchart TD
    A["进入 /verify 页\n购物车已完整"] --> B["Step 1: 身份验证"]
    B --> C{"选择验证方式"}
    C -->|"手机"| D["输入手机号\nSend Code"]
    C -->|"邮箱"| E["输入邮箱\nSend Code"]
    D --> F["POST /guest-auth/send-code\n发送6位OTP"]
    E --> F
    F --> G["输入验证码\n+ 输入姓名"]
    G --> H["POST /guest-auth/verify-code"]
    H --> I{验证成功?}
    I -->|"是"| J["获得 JWT tokens\n存入 guest-auth-store"]
    I -->|"否"| K["错误提示\n可重发验证码"]
    K --> F
    J --> L["Step 2: 确认预约"]
    L --> M["选择通知偏好\nSMS / Email"]
    M --> N["可选: 填写邮箱\n可选: 备注"]
    N --> O["点击确认预约"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style J fill:#4CAF50,stroke:#2E7D32,color:#fff
    style K fill:#f44336,stroke:#c62828,color:#fff

BDD 场景

场景 G4.1: 手机号 OTP 验证 — 新客户

测试: web-booking.spec.ts

场景 G4.2: 邮箱 OTP 验证 — 已有客户

场景 G4.3: 验证码过期/错误

场景 G4.4: 通知偏好设置 (014)

CUJ-G5: 自助终端 — Check In

P0 自助签到 — 有预约的客户通过门店终端签到

用户流程

flowchart TD
    A["终端欢迎页\n/terminal/store_code"] --> B["点击 Check In"]
    B --> C["输入手机号\n/checkin/store_code"]
    C --> D{"找到今日预约?"}
    D -->|"是"| E["显示今日预约列表"]
    E --> F["选择要签到的预约"]
    F --> G["状态变为 checked_in"]
    G --> H["成功页\n/checkin/store_code/success"]
    D -->|"否"| I["提示: 未找到预约"]
    I --> J["建议预约或 Walk-in"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style H fill:#4CAF50,stroke:#2E7D32,color:#fff
    style I fill:#FF9800,stroke:#E65100,color:#fff

BDD 场景

场景 G5.1: 有预约客户签到

测试: terminal-checkin.spec.ts

场景 G5.2: 未找到预约

CUJ-G6: 自助终端 — Book Appointment

P0 自助下单 — Walk-in 客户通过终端预约+自动签到

用户流程

flowchart TD
    A["终端欢迎页"] --> B["点击 Book Appointment"]
    B --> C["选择服务\n/terminal/store/select"]
    C --> D["选择技师"]
    D --> E["选择时间（仅当天）"]
    E --> F["确认页\n/terminal/store/confirm"]
    F --> G["输入姓名（必填）\n手机号（可跳过）"]
    G --> H["点击确认"]
    H --> I["创建预约 + 自动签到\nsource: kiosk"]
    I --> J["成功页\n/terminal/store/success"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style J fill:#4CAF50,stroke:#2E7D32,color:#fff

BDD 场景

场景 G6.1: Walk-in 终端预约 — 提供手机号

测试: kiosk-booking.spec.ts

场景 G6.2: Walk-in 终端预约 — 跳过手机号

测试: kiosk-booking.spec.ts

CUJ-G7: 我的预约（客户端）

P1 自助服务 — 已验证客户查看和管理自己的预约

BDD 场景

场景 G7.1: 查看我的预约列表

测试: 部分覆盖

场景 G7.2: 未认证 — 需要先验证

CUJ-G8: 签到管理（后台）

P1 后台配置 — 管理员配置签到流程、管理排队、查看统计

BDD 场景

场景 G8.1: 配置签到选项

测试: full-flow/08-checkin.spec.ts

场景 G8.2: 管理签到排队

场景 G8.3: 查看签到统计

CUJ-G9: Walk-in 快速登记

P1 不丢客户 — 前台通过 WalkInModal 快速登记无预约客户

BDD 场景

场景 G9.1: 前台 Walk-in 登记

测试: booking/walk-in.spec.ts

场景 G9.2: Walk-in 匹配已有客户

跨模块链接

关键业务规则