---

## title: PisellReservation 功能清单（对照 RecordBoard 下沉评估）

order: 9
category: plus

下表按**能力点**列出当前实现位置，便于逐项判断能否迁入 `**@pisell/materials` 的 PisellRecordBoard**（或相邻基础层）。最后一列 **「是否下沉」** 请自行填写（如：是 / 否 / 需抽象后）。

---

## 使用说明

- **实现位置**：以主要文件为准，括号内为补充。
- **与 RecordBoard 关系**：`PisellReservation` 本质是 **组装 `PisellRecordBoard` + 业务数据与 UI**，RecordBoard 已具备
  bodyView、`floorMap` 合并、`ShellFrame` 等；下列多数为**业务层**。

---

## A. 列表与数据源

| #   | 功能                                 | 实现位置                                                                                                                                | 说明                                                  | 是否下沉 |
|-----|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|------|
| A1  | 内置 / 受控列表判定                        | `PisellReservation.tsx` → `shouldUseBuiltinReservationList`                                                                         | 无 `data` 或空数组且未受控分页时走内置 booking                     |      |
| A2  | 表格用 booking 列表请求                   | `hooks/usePisellReservationBookingData.ts`                                                                                          | GET booking、分页、onSearch/onReset、`patchSearchParams` |      |
| A3  | 表格初始筛参（支付态 + 营业日窗口）                | `usePisellReservationBookingData.ts` → `getGridTableBookingSearchParams`                                                            | 与 Sales Monitor 对齐                                  |      |
| A4  | 资源台列表请求                            | `hooks/usePisellReservationResourceTableData.ts` + `serve/formResourcePage.ts`                                                      | `GET form/resource/page`，大页                         |      |
| A5  | 平面图用「按桌筛选」booking 第二路请求            | `PisellReservation.tsx` → `floorDayBookingData`（`extraRequestParams.form_record_ids`）                                               | 依赖资源列表 `form_record_ids`                            |      |
| A6  | 合并 `searchParams` 支付态默认值           | `PisellReservation.tsx` → `mergeGridBookingSearchParams`                                                                            | 与 QuickFilter 合并时避免空筛                               |      |
| A7  | 营业日锚定 `booking_time_start_between` | `usePisellReservationBookingData.ts` → `bookingTimeWindowForAnchorDay`；`reservationDataUtils.ts` / `mergeSearchParamsBookingWindow` | 02:00–次日 02:00                                      |      |
| A8  | 资源 + 预约 → `tables` 行               | `reservationTablesMerge.ts` → `buildReservationMergedTableRows` 等                                                                   | 含受控 `data`、`dataSourcesProp`、宿主列表分支                 |      |
| A9  | 其它合并捷径                             | `bookingToReservationTables.ts`、`formResourceToReservationTables.ts`、`salesEmbeddedResourceToTableRows.ts`                          | 被 A8 或数据链引用                                         |      |
| A10 | 根级 `dataSources` 合并                | `PisellReservation.tsx` → `useMemo` `dataSources`                                                                                   | 展开 prop 后覆盖 `gridDataSourceKey`                     |      |
| A11 | 表格列 / 筛排 / 工具栏（Monitor 对齐）         | `useBookingPerspective` + `getRelationTables`（`pisellSalesManagement`）+ `bookingChildProps`                                         | `reservationResourceGridColumns.tsx` 等接入点           |      |

---

## B. 时间轴、日程与「跟随当前」

| #   | 功能                            | 实现位置                                                                                                                         | 说明                                                                       | 是否下沉 |
|-----|-------------------------------|------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|------|
| B1  | 顶栏日程带 + 时间轴 UI                | `PisellReservationToolbarTabs`（`PisellReservationSubcomponents.tsx`，与主文件内旧版可能重复）+ `PisellReservationScheduleBand`（materials） | 平面图下展示；表格下仅切换器在工具栏                                                       |      |
| B2  | 日程受控 / 非受控状态                  | `PisellReservation.tsx` → `internalSchedule` / `scheduleValueProp`                                                           |                                                                          |      |
| B3  | 日程防抖提交                        | `PisellReservation.tsx` → `queueCommittedSchedule` / `flushCommittedSchedule`                                                | 驱动请求与宿主回调，避免拖动连刷                                                         |      |
| B4  | 日历日变化 → patch booking 窗口      | `PisellReservation.tsx` → `debouncedSchedule` effect                                                                         | 内置列表 + `floorDayBookingData.patchSearchParams`                           |      |
| B5  | 表格 ↔ 平面图切换时同步列表区间             | `ScheduleSyncOnFloorEnter`（`PisellReservationSubcomponents.tsx`）                                                             | 进入平面图时按当前日程更新 `booking_time_start_between`                               |      |
| B6  | 「跟随当前」墙钟                      | `PisellReservation.tsx` → `followWallClock` + `setInterval(30s)`                                                             | 改 `schedule` 并 `flushCommittedSchedule`                                  |      |
| B7  | 时间轴用户操作 → 退出跟随                | `onTimeNavigatorUserInteraction`                                                                                             |                                                                          |      |
| B8  | 受控数据源 + 平面图 → `onSearch` 透传日程 | `PisellReservation.tsx` → `debouncedSchedule` effect                                                                         | `reservationDate` / `reservationAt`                                      |      |
| B9  | 时间轴营业区间常量                     | `reservationConstants.ts` → `RESERVATION_TIMELINE_BUSINESS_RANGE`                                                            | 与列表窗口默认一致                                                                |      |
| B10 | 时间轴密度 / 折线                    | `reservationDensity.ts` + `loadReservationDensity`                                                                           | 优先 `sales.getTimelineHighlights`，否则本地 `computeReservationDensityBuckets` |      |

---

## C. 宿主 Sales / PisellOS

| #  | 功能                                          | 实现位置                                                                      | 说明                | 是否下沉 |
|----|---------------------------------------------|---------------------------------------------------------------------------|-------------------|------|
| C1 | `sales.getResourceBookingList(时刻, 当日 list)` | `PisellReservation.tsx` → `useEffect`                                     | 合并进画布行；Promise/同步 |      |
| C2 | `sales.getTimelineHighlights(list, 轴起, 轴止)` | `PisellReservation.tsx` → `useEffect`                                     | 时间轴背景密度           |      |
| C3 | 结果归一化                                       | `reservationTablesMerge.ts` → `normalizeSalesResourceBookingListResult` 等 |                   |      |
| C4 | 引擎 `request` 注入                             | `PisellReservation.tsx` → `request.setRequest`                            | 私有包 `utils`       |      |

---

## D. 平面图与店铺方案

| #   | 功能                                               | 实现位置                                                                             | 说明                                                                               | 是否下沉 |
|-----|--------------------------------------------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------|------|
| D1  | GET（code）/PUT（id）店铺 floor-plan、layout 映射         | `floorPlanApi.ts`                                                                | `getShopFloorPlanByCode`、`ShopFloorPlanDetail`、`saveViewConfigToShopFloorPlan` 等 |      |
| D2  | 默认 floor 配置 + 远程合并                               | `useReservationFloorPlan.ts` + `reservationMock.ts`                              | `mergeFloorMapElementKindsWithDefaults` 等                                        |      |
| D3  | `floorMap` props 合并（labels、forms、onSave、Tab 尾区等） | `useReservationFloorMapMerged.tsx`                                               | 依赖 D1、预约 mock 列                                                                  |      |
| D4  | 随语言刷新 palette / 分类文案                             | `reservationMock.ts` → `applyReservationFloorMapLiveLabels`                      | `engineLocale` 驱动                                                                |      |
| D5  | 按 kind 渲染平面图项                                    | `reservationCards.tsx` → `getReservationRenderItemByKind`                        | 绑定 `ReservationFloorRoomCard` 等                                                  |      |
| D6  | 按 `dataSourceKey` 查行                             | `reservationCards.tsx` → `findReservationRow`                                    |                                                                                  |      |
| D7  | 平面图 HUD 统计                                       | `ReservationFloorMapHud.tsx`                                                     | 视口叠加                                                                             |      |
| D8  | 只读点击 → 宿主结账抽屉                                    | `floorMapHostCheckout.ts` + `floorMapItemClickBefore`                            | `pisell1.handleOpenHostCheckoutDrawer`                                           |      |
| D9  | 编辑/只读模式（内部 mapEdit）                              | `PisellReservation.tsx` + `ReservationFloorMapCanvasTabsTrailing`（Subcomponents） | 与 `floorMap.mode` 受控互斥                                                           |      |
| D10 | `floorMapLayoutRef` 透传                           | `PisellReservation.tsx` → `PisellRecordBoard`                                    | 给尾区按钮等                                                                           |      |

---

## E. RecordBoard 壳与视图切换

| #  | 功能                                                             | 实现位置                                                                   | 说明                          | 是否下沉 |
|----|----------------------------------------------------------------|------------------------------------------------------------------------|-----------------------------|------|
| E1 | `PisellRecordBoard` + `ShellFrame` + `GridLayout` / `FloorMap` | `PisellReservation.tsx`                                                | 标准用法                        |      |
| E2 | `bodyView` 同步到 ref                                             | `RecordBoardBodyViewCapture`                                           | 供 effect 判断当前视图             |      |
| E3 | `bodyViewStorageKey` 持久化                                       | `reservationConstants.ts` → `PISELL_RESERVATION_BODY_VIEW_STORAGE_KEY` | 表格/平面图记忆                    |      |
| E4 | 平面图下 Segmented 表格/平面图切换                                        | `PisellReservationToolbarTabs` + `useRecordBoardShellBodyMeta`         | 有 Grid 且有 Floor 槽时显示        |      |
| E5 | 表格视图下隐藏顶栏 `topRight` 透传                                        | `ReservationGridTopRight`                                              | 平面图编辑入口在画布行                 |      |
| E6 | `fillHeight` 与 grid `scroll.autoCalc`                          | `PisellReservation.tsx`                                                | 来自 `bookingChildProps.grid` |      |

---

## F. 新建预约与路由

| #  | 功能                | 实现位置                                                  | 说明                            | 是否下沉 |
|----|-------------------|-------------------------------------------------------|-------------------------------|------|
| F1 | 从引擎路由筛 proCode 页  | `PisellReservation.tsx` → `newReservationRoutes`      | `booking_ticket` / `sales2` 等 |      |
| F2 | 新建按钮 + Modal 选路由  | `PisellReservationScheduleEndActions` + `PisellModal` | 单路由直跳                         |      |
| F3 | `history.push` 跳转 | `handleRouteJump`                                     |                               |      |

---

## G. 国际化、引擎与其它 UX

| #  | 功能                                              | 实现位置                                                                                | 说明                                           | 是否下沉 |
|----|-------------------------------------------------|-------------------------------------------------------------------------------------|----------------------------------------------|------|
| G1 | `locales.init(PISELL_RESERVATION_PAGE_LOCALES)` | `PisellReservation.tsx`                                                             | 合并 orderList + salesManagement + reservation |      |
| G2 | 文案 key 常量                                       | `reservationConstants.ts`（I18N_*）+ `locales.ts` / `locales-ja.ts` / `locales-pt.ts` |                                              |      |
| G3 | 页面标题等                                           | `rest` 透传 RecordBoard + `I18N_PAGE_TITLE`                                           |                                              |      |
| G4 | MUI DatePicker `adapterLocale`                  | `PisellReservation.tsx` + `LocalizationProvider`                                    | 随 `engineLocale`                             |      |
| G5 | Loading 延迟展示                                    | `PisellReservation.tsx` → `loadingShown` 防抖                                         | 避免闪烁                                         |      |
| G6 | 外层页面 class / FAB 槽                              | `PisellReservation.tsx` + `PisellReservation.less`                                  |                                              |      |

---

## H. 类型与配置

| #  | 功能                                                     | 实现位置                                        | 说明                               | 是否下沉 |
|----|--------------------------------------------------------|---------------------------------------------|----------------------------------|------|
| H1 | `PisellReservationProps` / `PisellReservationTableRow` | `types.ts`                                  | floorPlan、schedule、dataSources 等 |      |
| H2 | 默认 `GRID_DS_KEY`、`floorPlan` 默认 id/code                | `reservationConstants.ts`、`floorPlanApi.ts` |                                  |      |

---

## I. 文档与 Story

| #  | 功能            | 实现位置                                     | 说明 | 是否下沉 |
|----|---------------|------------------------------------------|----|------|
| I1 | Storybook     | `PisellReservation.stories.tsx`          |    |      |
| I2 | 深入架构 / 多数据源文档 | `docs/pisell-reservation-deep-dive.md` 等 |    |      |

---

## J. 辅助模块（被上层引用）

| #  | 功能               | 实现位置                                                                             | 说明      | 是否下沉 |
|----|------------------|----------------------------------------------------------------------------------|---------|------|
| J1 | 时刻游标过滤预约         | `filterBookingsAtTimeCursor.ts`                                                  | 合并链或展示用 |      |
| J2 | RoomCard 数据映射与组件 | `floorRoomCard/`*                                                                |         |      |
| J3 | 样式               | `PisellReservation.less`、`ReservationCards.less`、`ReservationFloorMapHud.less` 等 |         |      |
| J4 | API 说明           | `api/api.md`                                                                     |         |      |

---

## 与「下沉 RecordBoard」相关的粗粒度结论（仅供参考）

- **E 组**多数已是 RecordBoard **既有能力**，预约页只是 **调用方式**，不必再「搬进」RecordBoard。
- **A2–A11、B、C、F、G1–G2** 与 **预约 / Sales / 店铺接口** 强相关，通常 **保留在业务** 或抽成 **可注入 hook**。
- **D1–D4** 若其它业务复用同一 **floor-plan HTTP 契约**，可把 **HTTP + layout 映射** 下沉；**D5–D9** 仍偏预约 UI。
- 若你希望把某几行合并成「下沉包」，建议在表里用 **是否下沉 = 是（合并为 xxx hook）** 标注。

---

与 **[深入架构](./pisell-reservation-deep-dive.md)**、**[多数据源](./pisell-reservation-multi-datasource.md)** 对照阅读。