---
title: 设计文档
order: 2
category: plus
---

# PisellReservation 设计说明

## 1 定位与目标用户

- **定位**：店铺端预约监控页，与 Sales Monitor 预约列表在**列、筛选、排序**上对齐，并在同一页面提供**表格 / 平面图 / 日历 / 资源墙**等多子视图切换能力。
- **默认导出**：低代码场景常用 `PisellReservation`（见 `PisellReservationBookingPage`），与 Core 能力一致，差别主要在 `bodyViewStorageKey` 等页面壳预设。

## 2 信息架构

### 2.1 顶栏（平面图相关子视图）

- **日程带 + 时间轴**：与 `@pisell/materials` 中 **PisellReservationScheduleBand** 一致的单状态 `{ date, at }`，避免「营业日」与「轴上时刻所属日」脱节。
- **工具区**：合并 Sales Management 注入的预约视角 **ToolBar**（筛选、快捷条件等）；右侧可配置「跟随当前」「新建预约」等（可通过 `scheduleEndSlot` 替换）。
- **表格视图**：顶栏不展示完整日程带组合（仅保留业务传入的 extra tabs），降低表格-only 场景的视觉噪音。

### 2.2 主体（RecordBoard Shell）

- **表格（grid）**：分页预约列表，驱动筛选与排序状态。
- **平面图（floorMap）**：画布桌位卡片与列表数据对齐；支持本地/远程平面图配置、编辑态切换（未受控 `floorMap.mode` 时内置编辑开关）。
- **日历（calendar）**：依赖合并后的资源列与当日 booking 映射；可见时间区间由 viewport 与搜索参数协同维护（避免月视图被单日窗口误覆盖）。
- **资源墙（resourceWall）**：大屏资源卡片墙；筛选与平面图 booking 请求共用一套 `form_record_ids` 语义。

## 3 时间与营业日

- **默认时间轴区间**：锚定营业日 **02:00 — 次日 02:00**（与列表请求窗口一致）；可被 `timeNavigatorProps.range` 或门店 **core.operating_day_boundary** 推导结果覆盖。
- **顶栏日程防抖**：用户拖动轴或换日时，接口侧使用**落定后的日程**（debounced），减少拖拽中途的请求风暴。
- **跟随当前**：开启后按墙钟周期刷新 `schedule`，并锁定日程导航、隐藏「此刻」按钮等（与 TimeNavigator / Schedule 的合并策略一致）；用户手动改日期或轴时刻应退出跟随。

## 4 数据与一致性

- **内置列表模式**：不传受控 `data` / 分页时，由内部请求 booking；**表格**与**平面图当日全量**分两路 `usePisellReservationBookingData`（分页 vs 大页）以避免并发订阅互相抢占。
- **合并桌位行**：资源列表 + 当日 booking + 可选宿主 sales 列表 → `buildReservationMergedTableRows`，输出写入 `dataSources[gridDataSourceKey]`（默认 `tables`）。
- **受控列表模式**：外部传入 `data`、分页与 `loading`；平面图只读模式下通过 `onSearch` 透出 `reservationDate` / `reservationAt` 供外层对齐。

## 5 平面图交互

- **点击预约卡片**：优先调用 `onFloorMapBookingClick`；若未拦截，则按引擎侧策略打开**预约详情弹窗**（展示态）；历史上曾支持宿主结账抽屉，当前以实现代码为准。
- **HUD 抽屉**（可选 `floorMapHudTableDrawer`）：缩小画布配套表格，便于窄屏核对绑定资源行。

## 6 扩展与约束

- **时间轴吸附**：预约场景在 Core 内强制关闭 step 吸附与 `axis-moves`，避免松手后时刻被对齐到粗粒度刻度。
- **国际化**：页面级文案通过 `@pisell/utils` `locales.init` 注册 `PISELL_RESERVATION_PAGE_LOCALES`，随引擎 `locale` 切换。