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

# PisellSalesGrid 开发文档

## 1 基本信息

| 项 | 内容 |
|----|------|
| 包 | `@pisell/private-materials` |
| 入口 | `src/plus/pisellSalesGrid/index.tsx` |
| 实现 | `PisellSalesGrid.tsx` |
| 样式 | `PisellSalesGrid.less` |
| 类型 | `types.ts`（`PisellSalesGridProps`、`SalesGridPerspectiveConfig`、`SalesGridRuntimeContext` 等） |
| 请求 | `serve.ts`（`getOrderList`、`getBookingList`、`formatBookingResult` 等） |
| 批量操作 | `hooks/useActions.tsx`（合并进 `batchActionBar.actions`） |

## 2 依赖

- **@pisell/materials**：`PisellRecordBoard`、`PisellQuickFilter`、`PisellModal`（actions 内）。
- **ahooks**：`useRequest`（manual 请求与 `run` / `runAsync`）。
- **dayjs**：默认筛选区间、`serve` 内参数格式化。
- **antd**：`Checkbox`、`Button`（批量操作弹窗）。
- **@pisell/utils**：`locales`（订单列表批量文案）。
- **引擎**：`useEngineContext`（注入 `request`）；部分打印逻辑读 `window.app.data.storage`。

## 3 核心流程

### 3.1 Perspective 解析

- `getCurrentPerspectiveConfig(perspectives, currentPerspective)`：按 key 查找，缺省回退第一项。
- 若配置 **`getChildComponentProps`**：用 **`SalesGridRuntimeContext`** 调用工厂，结果作为 `childComponentProps`；否则使用静态 **`childComponentProps`**。

### 3.2 列表请求（非受控）

- `currentPerspective === 'monitor'` → **`getBookingList`**（GET `/shop/schedule/booking`，参数经 `formatBookingParams`）。
- 否则 → **`getOrderList`**（POST `/shop/order/v2/list`，参数经 `formatParams`）。
- 请求参数由 **`searchParams`**（`keyword` / `filter.values` / `sort`）与 **`pagination`**（`skip` ← `pageNumber`，`num` ← `pageSize`）拼成 **`requestParams`**，再合并 **`extParams?.list`**。
- `useEffect` 在 `requestParams`、`currentPerspective`、`extParams` 变化时触发 `run`（受控时跳过）。

### 3.3 受控模式

- `props.data !== undefined` 为受控：数据源与 loading/total/pagination/onSearch 等以 props 为准；**`runtimeContext.refresh`** 走 **`propsOnRefresh` / `propsRefreshAsync`**（若提供）。

### 3.4 grid 合并

- **`mergeColumnRenderersIntoGrid`**：将 **`columnRenderers`** 按列 **`type`** 写入对应列的 **`render`**。
- 多选：props 受控则使用 `selectedKeys` / `selectedRows` / `onSelectionChange`，否则使用内部 `useState`。

### 3.5 批量操作

- **`useActions({ onRefresh: initLoad, onClearSelection })`**：`initLoad` 与当前视角的请求函数一致，用于操作成功后刷新。

## 4 存储与序列化

- 前缀 **`pisell_sales_grid_search_params_${__id}`**（sessionStorage）。
- **`serializeSearchParams` / `deserializeSearchParams`**：Dayjs 以 `{ __isDayjs, value }` 标记往返。
- **`PERSIST_FILTER_BY_DEFAULT`**：为 `false` 时写入存储前剔除 **`filter`**，读取后同样不还原 filter（仅 sort、keyword 等）。

## 5 `serve.ts` 要点

- **`normalizeListPayload`**：兼容嵌套 `data.data` 列表结构。
- **`formatBookingResult` / `formatBookingData`**：booking 行补充 `order_detail`、`id` 等与表格列对齐（预约模块也会引用 **`formatBookingResult`**）。
- **`unsubscribeOrderQuery` / `unsubscribeBookingQuery`**：列表订阅取消（组件本体当前未强制卸载调用，按需在外层配合）。

## 6 与主文档的差异提示

- 使用文档中出现的 **`defaultChildComponentProps`** 在当前 **`PisellSalesGridProps`** 与组件实现中**不存在**；若需默认配置，请在业务侧合并进 **`perspectives`** 或在外层包装组件。

## 7 相关文档

- 使用说明：`docs/PisellSalesGrid.md`
- RecordBoard：`@pisell/materials` PisellRecordBoard 文档