---
title: 开发文档
order: 3
category: plus
---

# PisellReservation 开发文档

## 1 基本信息

| 项 | 内容 |
|----|------|
| 包 | `@pisell/private-materials` |
| 对外入口 | `src/plus/pisellReservation/index.tsx` |
| Core 实现 | `PisellReservation.tsx`（导出 `PisellReservationCore`） |
| 页面壳 | `PisellReservationBookingPage.tsx`（导出 `PisellReservation`、`PisellReservationBookingPage`） |
| 场控壳 | `PisellVenueControlPage.tsx`；资源墙壳 `PisellVenueWallPage.tsx` |
| 样式 | `PisellReservation.less` |
| 类型 | `types.ts`（`PisellReservationProps`、`PisellReservationTableRow` 等） |

## 2 依赖概览

- **@pisell/materials**：`PisellRecordBoard`、平面图类型、`ReservationScheduleBandValue` 等。
- **@pisell/date-picker**：`LocalizationProvider` + `AdapterDayjs`（与引擎 locale 映射）。
- **@pisell/utils**：`locales`、分页与筛选合并工具（各 `data/*.ts` 内引用）。
- **ahooks**：`useMemoizedFn`、`useRequest`。
- **dayjs**：日程与营业日边界计算。
- **引擎**：`useEngineContext` / `usePisellOS`（`request`、路由、`business_code`、宿主模块）。

## 3 模式：内置列表 vs 受控列表

- 判定：`shouldUseBuiltinReservationList`（`data/reservationDataUtils.ts`），依据是否传入受控 `data`、分页回调等。
- **内置**：`usePisellReservationBookingData` 管理 grid 列表；另一实例以大页 + `form_record_ids` 拉平面图当日数据；`subscribeRealtimePush` 等参数两路有差异（见 `PisellReservation.tsx` 注释）。
- **受控**：列表字段来自 props；仅在平面图/日历/资源墙且非内置时，防抖日程变更通过 `onSearch` 合并 `reservationDate` / `reservationAt`。

## 4 核心数据流（内置模式）

1. `usePisellReservationResourceTableData`：资源维度（表格列需要的资源/表单数据）。
2. `gridBookingData` + `floorDayBookingData`：两路 booking 请求与 `patchSearchParams`。
3. `useReservationSalesHostData`：可选宿主 `sales.getResourceBookingList` / 时间轴高光；失败回退本地合并逻辑。
4. `buildReservationMergedTableRows`：合并为 `tables`，写入 `dataSources[gridDataSourceKey]`。
5. `useReservationFloorPlan` + `useReservationFloorMapMerged`：远程平面图 GET/PUT、与 props 合并 sceneElements。
6. `useReservationHudDrawer`、`useFloorMapBookingInteraction`、`useReservationCalendarSlot`、`useReservationToolBarMerged`：子视图与交互。

## 5 日程与防抖

- `useReservationScheduleDebounced`：`scheduleValue` 受控 vs 内部 state、`debouncedSchedule` 用于接口。
- `useReservationWallClockFollow`：跟随开关与用户手势退出跟随。
- `useEffect`（debounced 落定）：换日时 patch `floorDayBooking` 的 booking 时间窗；日历视图避免用单日窗口覆盖月/周区间。

## 6 关键纯函数与数据模块（单测优先）

| 目录/文件 | 职责 |
|-----------|------|
| `data/bookingToReservationTables.ts` | booking → `PisellReservationTableRow` |
| `data/formResourceToReservationTables.ts` | 资源接口 → 行 |
| `data/reservationTablesMerge.ts` | 合并 grid/floor/sales 行 |
| `data/reservationDataUtils.ts` | 搜索参数与列表模式工具 |
| `data/calendarAdapter.ts` | 日历列资源与 booking 条目 |
| `floorMap/reservationCards.tsx` | `getReservationRenderItemByKind` 平面图卡片 |

## 7 与 RecordBoard 的关系

- 从 `RecordBoardProps` 剔除并由本组件接管的字段：`toolBar`、`floorMap`、`dataSources`、`grid`、`search`、`data`、`pagination` 等（见 `types.ts`）。
- 其余属性透传 `PisellRecordBoard`；子视图通过 `ShellFrame` 挂载 **GridLayout / FloorMap / Calendar / ResourceWall**。
- **注意**：`RecordBoardBodyViewCapture`、`ScheduleSyncOnFloorEnter` 有意放在 `ShellFrame` 外兄弟节点，避免切换子视图时被卸载（见源码注释）。

## 8 调试

- `useReservationDebugLoggers`：开发态聚合打印合并表、日程、floor 绑定 id 等（按需保留或开关）。

## 9 相关文档

- 使用说明：`docs/PisellReservation.md`
- 仓库内深度说明：`docs/pisell-reservation-deep-dive.md`、`pisell-reservation-feature-inventory.md`（若存在）