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

# PisellSalesGrid 设计说明

## 1 定位

- **PisellSalesGrid** 是 **PisellRecordBoard** 的上层壳：用一组 **Perspective**（每套含 grid / toolBar / search / floorMap 等打散配置）驱动同一列表区域，由外部通过 **`currentPerspective`** 决定当下模板，**组件内不提供 Tab 切换 UI**。
- 典型场景：销售管理里「订单列表」与「预约监控」等多套列与工具栏并存，由路由或父级状态切换 `currentPerspective`。

## 2 信息架构

- **主体**：仅 **`layoutType="grid"`** 路径，Shell 内渲染 **GridLayout**（可选在同一 Perspective 内配置 **floorMap**，由 RecordBoard 工具栏切「表格 / 平面图」）。
- **顶栏与表格**：来自当前 Perspective 的 `childComponentProps`（或由 `getChildComponentProps(ctx)` 生成）；筛选、排序、关键词等与 RecordBoard 一致。
- **批量操作栏**：组件内置一组订单向 **batch actions**（发货、发票、打印、标签、状态流转等），与 Perspective 配置的 `batchActionBar` 合并；成功后可刷新列表并清空多选。

## 3 数据与视角

### 3.1 内置请求 vs 受控

- **未传入 `data`**：由组件根据 `currentPerspective` 发起列表请求——**`monitor`** 走预约 booking 列表，其余走订单列表（具体接口见实现 `serve.ts`）。
- **传入 `data`**：进入受控模式，不再自动请求；分页、筛选、`refresh` 等应由父组件配合 `onRefresh` / `refreshAsync` 自行衔接。

### 3.2 Perspective 切换

- 切换 `currentPerspective` 时，内部以 **`key={currentPerspective}`** 重建 **PisellRecordBoard**，避免多套列配置与上下文互相污染。
- 默认 **`searchParams`** 随视角变化：`monitor` 默认当日预约时间窗与支付筛选；非 `monitor` 默认订单日区间与排序等（与 `getDefaultSearchParams` 一致）。

### 3.3 筛选持久化（sessionStorage）

- 传入 **`__id`** 时，将 **`searchParams`** 写入 session（Dayjs 序列化为 ISO 标记对象）。
- **默认不持久化 filter.values**（`PERSIST_FILTER_BY_DEFAULT = false`），仅持久化排序、关键词等非筛选项，避免跨会话语言或筛选项定义变更导致还原异常；列显隐仍由 RecordBoard + **localStorage** 规则处理。

## 4 列渲染扩展

- **`columnRenderers`**：按列 **`type`** 将自定义 `render` 合并进 `grid.columns`，用于在不动 RecordBoard 源码的前提下覆盖某一类型的单元格展示。
- 优先级：**传入的 `columnRenderers`** 覆盖列上默认 → 最终仍服从 RecordBoard 对未知列类型的兜底逻辑。

## 5 运行时上下文

- **`SalesGridRuntimeContext`**（`refresh` / `refreshAsync` / `currentPerspective`）注入 **`getChildComponentProps`**，便于列配置、操作按钮等访问「刷新当前列表」而不重复绑定请求细节。
- 受控模式下优先使用父组件传入的 **`onRefresh` / `refreshAsync`**。

## 6 约束与依赖环境

- 依赖引擎注入的 **`request`**（与 `utils/request` 单例对齐）；批量操作依赖订单相关接口与 **`locales.getText`** 文案。
- **`document.body.id`** 在挂载时设为 `'body'`（历史兼容，接入新页面时注意是否与其它全局假设冲突）。