# Sales SDK（plus/salesSdk） > Headless 业务数据层 SDK：通过 React Provider + Hooks 暴露 OS `BookingTicket` 数据流。 > **不依赖任何 UI 组件**；UI 层（无论是 ticketBooking、新建态空壳，还是未来的销售单组件）按需消费 hook 即可。 > 物理位置：`packages/private-materials/src/plus/salesSdk/`，与既有 `components/Sales` UI 模块完全独立。 > 命名前缀：`SalesSdk*` / `useSalesSdk*`，避免与 `components/Sales` 同名混淆。 --- ## 1. 定位与设计原则 | 维度 | 选择 | |---|---| | 数据源 | OS `BookingTicket`（pisellos）实例，复用 ticketBooking 已注册的 osKey 实例 | | 状态管理 | React Context + Hooks（不引入 miniRedux） | | 订阅机制 | `BookingTicket.effectsOn(event, cb)` + 内部 `setState` 镜像；通用 `useSyncOsModule` 适配 | | 视图模型 | UI 视图（`SalesSdkCartItemView` / `SalesSdkCustomerView`）通过 enrichment 多源合并，**仅活在 React 内存**，不写入 OS tempOrder 提交契约 | | Action 引用 | 每个 action 通过 `useMemoizedFn` 包装，引用稳定（详见 §4.5） | | 编辑/新建一体 | 同一套 Provider，新建态 `tempOrder` 由 OS 维护，编辑态额外注入 `salesDetail`；UI 不需要分两个组件 | | 入口 | `...`（单根） | --- ## 2. 顶层结构 ``` SalesSdkProvider (顶层：管理 BookingTicket 生命周期 + bootstrap) ├── SalesSdkProductProvider (商品列表：onProductsLoaded) │ └── SalesSdkSummaryProvider (汇总：getSummary + onSalesOrderLoaded) │ └── SalesSdkCartProvider (购物车：onSalesOrderLoaded + items enrich) │ └── SalesSdkCustomerProvider(客户：onCustomerSelected / ListUpdate / PaginationChange) │ └── children (业务 UI 自由消费各 hook) ``` 每个 Provider 内部仅订阅自己关心的 OS 事件；其它兄弟 Provider 各自独立维护状态片段，互不影响。 --- ## 3. Public API ### 3.1 Provider ```ts import { SalesSdkProvider } from '@pisell/private-materials/plus/salesSdk'; {children} ``` > 加车 / 资源编辑接入详见 **§4.6**。 ### 3.2 Hooks（每个都返回 data + actions 扁平结构） | Hook | 主要数据 | 主要 actions | |---|---|---| | `useSalesSdk()` | `bookingTicket`, `osKey`, `status` (`idle`/`loading`/`ready`/`error`), `error`, `isReady`, **`tempOrder`**, **`salesDetail`** | `loadDetail(orderId)`, `loadDetailByRemote(orderId)`, `refreshSalesDetail()`, `createNew()`, `restore()`, `destroy()`, `setBookingStatus(status)`, `setOrderNote(note)`, `setShopDiscount(amount)`, `setContactsInfo(info)`, `openCheckout()` | | `useSalesSdkProducts()` | `products`, `loading`, `error` | `load(params)`, `loadDetail({product_id})`, `findByIds(ids)`, `scanGlobalListener(cb)`, `scanCustomerListener(cb)`, `scanUniversal(cb, key)`, `activateCamera`, `enableScan`, `disableScan` | | `useSalesSdkCart()` | `discountList`, **`items` (enriched view)** | `addProduct`, **`addProductWithFlow`**, `confirmDetail`, `confirmBookingEdit`, **`editCartLineBooking`**, `removeItem`, `updateItem`, `setLineNote`, `setDiscount`, `scanCode`, `submit`, `recalcSummary` | | `useSalesSdkUIHosts()` | - | 读取 Provider 注入的 `openProductDetail` / `openBookingEdit` Host（调试或 UI 条件渲染） | | `useSalesSdkSummary()` | `summary`（源自 `bookingTicket.getSummary()`） | - | | `useSalesSdkCustomer()` | `selected`, `list`, `pagination`, `hasMore`, `loading`, `loadingMore`, `searchParams`, **`display` (enriched fallback view)** | `select`, `loadList`, `search`, `loadMore`, `changePage`, `addToFirst`, `clear`, `loadById` | ### 3.3 Pure utilities（可在 Provider 外使用） ```ts import { enrichCartItem, enrichCartItems, enrichCustomer, pickIdentity, deriveDisabledEdit, deriveSummary, isWalkInCustomer, useSyncOsModule, // 通用基础 hook（自定义订阅时可直接使用） runAddProductFlow, // 非 React 环境 / 单测编排加车链路 createOpenBookingEditHost, createLegacyOpenProductDetailHost, } from '@pisell/private-materials/plus/salesSdk'; ``` --- ## 4. 关键契约 ### 4.1 enrichCartItem 数据来源（多源合并） ``` SalesSdkCartItemView ⟵ ScanOrderOrderProduct (line) [OS tempOrder.products，提交契约] ⊕ ISalesBooking by line.metadata.unique_identification_number .product_uid match [编辑态：bookings*.detail / bookings*.product] ⊕ ProductData where String(p.id) == String(line.product_id) [新建/编辑态商品列表兜底] ``` | 字段 | 来源优先级 | |---|---| | `title` / `cover` / `variant_title` | bookings*.detail → productsCatalog → '' | | `bundle_titles` / `option_titles` | bookings*.detail → productsCatalog → '' | | `duration` / `product_resource` | bookings*.product → productsCatalog → undefined | | `start_at` / `end_at` | bookings 主资源 `start_date+start_time` / `end_date+end_time`（编辑态） | | `resource_id` | bookings 主资源 `relation_id`（编辑态） | | `note` | bookings*.detail.note → line.note → '' | | `_identity` | `pickIdentity(line)`，给 OS removeProductFromOrder/updateOrderProduct 用 | > **关键约束**（遵循 `.cursor/rules/data-field-semantics.mdc`）：bookings 反查严格通过 `product_uid` 与 `line.metadata.unique_identification_number` 匹配，不发明 `booking_id ↔ product` 等价关系；catalog 通过 `product_id` 字符串比对避免 number/string 误判。 ### 4.2 enrichCustomer 数据来源 ``` SalesSdkCustomerView ⟵ selected (CustomerModule) 优先：选中的完整客户对象 ⊕ tempOrder.customer_* fallback：编辑态服务端 hydrate 后写入 tempOrder 顶层 → null 都缺失 ``` `selected.id` 为 `null` / `undefined` / `''` / `0` 时视作未选中，进入 fallback；`isWalkIn` 由 `isWalkInCustomer({ id })` 判定（`'' / '0' / '1' / 0 / 1` → true）。 ### 4.3 selectors 派生 | 函数 | 输入 | 输出 | |---|---|---| | `deriveDisabledEdit(rootBooking, header)` | `appointment_status` + `payment_status`（`partially_paid` 归一为 `unpaid`） + `metadata.is_other_entrance_edited` | `{ disabledEdit, channelDisabledEdit, appointmentStatus, paymentStatus }` | | `deriveSummary(summary)` | `ScanOrderSummary` | 12 个金额字段（缺失时 `'0.00'`） | | `isWalkInCustomer(customer)` | `{ id }` | boolean | ### 4.4 BookingTicket 实例复用 `SalesSdkProvider` 通过 `pisellos.getModule(getBookingTicketKey(osKey))` 命中 ticketBooking 已注册的同 osKey 实例： - 命中 → 直接复用（不再 `new BookingTicket`） - 未命中 → `new BookingTicket(...)` + `pisellos.registerModule(...)` 这意味着 ticketBooking 与 Sales SDK 在同 osKey 下共享 `tempOrder` / `currentSalesDetail` / customer 等核心状态，可以渐进式迁移：旧 ticketBooking 与新 Sales SDK 视图共存、消费同源数据。 ### 4.5 Action 引用稳定性纪律（强制） 每个 action 必须 **单独** 通过 `useMemoizedFn` 包装： ```tsx const addProduct = useMemoizedFn(async (input) => { if (!bookingTicket) throw new Error('...'); const result = await bookingTicket.addProductToOrder(input); setSnapshot(readSnapshot(bookingTicket)); return result; }); ``` **约束**： 1. action 内部不要在 React 端再做一份 data 快照（每次执行从 OS getter 拿权威值）。 2. action **不要** 进 `useMemo(value, [...])` 的依赖数组（虽然进了也不会触发重渲，但代码噪音）。 3. 多 action 共用的派生数据交给 `selectors.ts`，不要在 action 内重复实现。 这样，业务侧在 `useEffect`/`useCallback` 中可以放心引用 action 而不担心 stale closure 或不必要的重渲。 --- ## 4.6 cart.addProduct 两阶段决策（Phase 2） 与 ticketBooking `handleSelectProduct` 对齐，OS `decideAddProduct` 拆成两段： 1. **`requiresDetail`**：规格 / SKU / 套餐 / Session / 称重（门禁 `isOpenDetailModal` / `cartDetailValue` / `open_sold_weight`） 2. **`requiresBookingEdit`**：资源 / 时间编辑抽屉（门禁 `getIsAutoClose` on prepared `cacheItem`） 3. **`added`**：两关均通过 ```ts const result = await cart.addProduct(product, { quantity: 1 }); if (result.status === 'requiresDetail') { openDetailModal(result.payload); } if (result.status === 'requiresBookingEdit') { openBookingEditDrawer(result.payload.cacheItem); } // 规格弹窗 callback： const afterDetail = await cart.confirmDetail({ item: product, detailResult: { e, extension_type, detail }, }); if (afterDetail.status === 'requiresBookingEdit') { openBookingEditDrawer(afterDetail.payload.cacheItem); return; } // 资源抽屉确认： await cart.confirmBookingEdit({ cacheItem: editedCacheItem }); ``` **关键约束**： - 第一段门禁用 **`isOpenDetailModal`**，不要用 `getIsEject` 代替（`isEject` 仅给弹窗 UI）。 - `cart.confirmDetail` 可能返回 `requiresBookingEdit`，与 `addProduct` 直接命中第二段等价。 - 跨日 / Holder：通过 `uiHosts.openMultiDaySelect` / `openHolderSelect` 接入（`runAddProductFlow` 内编排，对齐 ticketBooking AddService）；不进 OS 决策。 --- ### 4.6.1 新建 / 编辑模块接入总览 Sales SDK **不区分**「新建页」与「编辑页」两套 Provider：同一 `` 覆盖两种场景，差异仅在 bootstrap 参数。 | 场景 | Provider 配置 | 业务侧典型流程 | |---|---|---| | **新建** | 不传 `orderId`；挂载后调 `createNew()` | 选客户 → 拉商品 → `addProductWithFlow` → `submit` | | **编辑** | 传 `orderId` + `autoBootstrap`（默认 true） | 自动 `loadSalesDetail` → 改行 / 加行 / 删行 → `submit` | 加车与资源编辑涉及 **OS 决策层** + **SDK 编排层** + **UI Host 层**，推荐按下面 checklist 接入： ``` 1. 页面根节点包 SalesSdkProvider，注入 uiHosts 2. openBookingEdit → createOpenBookingEditHost()（资源抽屉，SDK 内置） 3. openProductDetail → createLegacyOpenProductDetailHost()（LCE 页）或页面自研弹窗 4. （LCE 页）子树挂 RuntimeBridge，同步 customerId / date 给规格弹窗 Host 5. 列表 / 按钮内：await cart.addProductWithFlow(product) 6. 购物车行「编辑资源」：await cart.editCartLineBooking(item) ``` **完整链路（加车）**： ``` 用户点加车 → cart.addProductWithFlow(product) → OS decideAddProduct → requiresDetail → openProductDetail Host → cart.confirmDetail → requiresBookingEdit → openBookingEdit Host → cart.confirmBookingEdit → added（直接写入 tempOrder） ``` **已加车行编辑资源**（与加车共用同一 `openBookingEdit` Host 与 `BookingEditServiceDrawer`）： ``` 用户点「编辑资源」 → cart.editCartLineBooking(item) → OS buildCacheItemFromOrderLine（反查 cacheItem） → openBookingEdit({ forceOpen: true }) // 强制打开抽屉，忽略 autoClose → transformDetailToProductAndBooking → cart.updateItem ``` > `BookingEditHostRenderer` 由 `SalesSdkProvider` 在检测到 `uiHosts.openBookingEdit` 时**自动挂载**，业务页无需手动渲染抽屉。 --- ### 4.6.2 标准 Host 工厂（推荐直接复用） SDK 已提供两个 Host 工厂，业务页**优先直接引用**，无需自行实现 Promise 编排或挂载抽屉。 | Host | 工厂函数 | 说明 | |---|---|---| | `openBookingEdit` | `createOpenBookingEditHost()` | 打开 `BookingEditServiceDrawer`；Provider 内自动挂 `BookingEditHostRenderer` | | `openProductDetail` | `createLegacyOpenProductDetailHost(deps)` | 对齐 ticketBooking `openProductModal`，走 LCE `pisell1.handleOpenProductModal` | ```tsx import React, { useMemo, useRef } from 'react'; import useEngineContext from '.../hooks/useEngineContext'; import { SalesSdkProvider, useSalesSdkCart, createOpenBookingEditHost, createLegacyOpenProductDetailHost, type LegacyProductDetailHostRuntime, } from '@pisell/private-materials/plus/salesSdk'; /** LCE 页：同步 customerId / date，供 openProductDetail Host 每次打开时读取 */ function SalesSdkHostRuntimeBridge({ runtimeRef, }: { runtimeRef: React.MutableRefObject; }) { const context = useEngineContext(); const action = context?.appHelper?.utils?.action; // 实际项目可从 useSalesSdkCustomer / bookingTicket.getBookingDate 同步，参考 demo/DemoHostRuntimeBridge.tsx return null; } function MyBookingPageShell({ osKey, orderId, children }: { osKey: string; orderId?: number; children: React.ReactNode; }) { const context = useEngineContext(); const action = context?.appHelper?.utils?.action; const runtimeRef = useRef({}); const uiHosts = useMemo( () => ({ openBookingEdit: createOpenBookingEditHost(), ...(action ? { openProductDetail: createLegacyOpenProductDetailHost({ action, getRuntime: () => runtimeRef.current, }), } : {}), }), [action], ); return ( {children} ); } ``` **接入要点**： - **`createOpenBookingEditHost()`**：零配置；内部 `requestOpenBookingEdit` → `BookingEditHostRenderer` → `BookingEditServiceDrawer`。 - **`createLegacyOpenProductDetailHost({ action, getRuntime })`**：需要 LCE `appHelper.utils.action`；`getRuntime()` 在每次打开弹窗时读取最新 `customerId` / `date`（payload 字段优先）。 - 非 LCE 页面若已有自研规格弹窗，只需实现同签名 Host 替换 `openProductDetail`（见 §4.6.5）。 - Host 引用通过 `useMemo` 保持稳定，避免 Provider 子树无意义重渲。 --- ### 4.6.3 `cart.addProductWithFlow`（列表加车，一行调用） **防抖与 Toast（SDK 内置）** - 每次调用前走 OS `decideAddProduct`：`requiresDetail` / `requiresBookingEdit` **立即**走弹窗链，不防抖。 - 仅 `action === 'add'`（可直接加车、无需资源抽屉）时：默认 **100ms** 防抖合并 `quantity`，防抖结束后再一次 `addProduct`；**预约商品（含 duration / schedules）不合并**，每次点击独立加车；点击时**立即** Toast（商品名 + `pisell2.ticket-booking.in-cart`）。 - flush 失败会清空 pending 累积（回滚待写入数量），Promise reject；下次点击重新计数。 - `options.debounceMs: 0` 关闭防抖；`options.notShowToast: true` 关闭 Toast。 Host 注入完成后，商品列表 / 扫码回调等处**一行加车**： ```tsx import { useSalesSdkCart, useSalesSdkUIHosts } from '@pisell/private-materials/plus/salesSdk'; function ProductListRow({ product }: { product: ProductData }) { const cart = useSalesSdkCart(); const hosts = useSalesSdkUIHosts(); const handleAdd = async () => { const result = await cart.addProductWithFlow(product, { quantity: 1 }); switch (result.status) { case 'added': // 已写入 OS tempOrder，cart.items 会自动刷新 break; case 'cancelled': // 用户在规格弹窗或资源抽屉点取消 break; case 'requiresDetail': // openProductDetail 未配置；需页面自行 open 后走 cart.confirmDetail console.warn('缺少 openProductDetail Host', result.payload); break; case 'requiresBookingEdit': // openBookingEdit 未配置；需页面自行 open 后走 cart.confirmBookingEdit console.warn('缺少 openBookingEdit Host', result.payload); break; } }; return ( ); } ``` **返回值**（`SalesSdkAddProductWithFlowResult`）： | status | 含义 | |---|---| | `added` | 完整链路结束，含 `{ products }` | | `cancelled` | Host 弹窗 / 抽屉内用户取消 | | `requiresDetail` | OS 命中第一段，但 `openProductDetail` 未注入 | | `requiresBookingEdit` | OS 命中第二段，但 `openBookingEdit` 未注入 | - 两个 Host 均配置时，调用方通常只需处理 `added` / `cancelled`。 - 未配置 Host 时行为与手动 `cart.addProduct` + `switch(status)` 等价，便于渐进接入。 - 底层 `cart.addProduct` / `confirmDetail` / `confirmBookingEdit` 仍保留，供 demo / 单测 / 需插入跨日流程时使用。 --- ### 4.6.4 已加车行「编辑资源」：`cart.editCartLineBooking` 购物车行已有 booking 时，编辑资源 / 时间走独立 action，**复用同一 `openBookingEdit` Host**： ```tsx import { useSalesSdkCart, type SalesSdkCartItemView } from '@pisell/private-materials/plus/salesSdk'; function CartLineActions({ item }: { item: SalesSdkCartItemView }) { const cart = useSalesSdkCart(); const handleEditBooking = async () => { const result = await cart.editCartLineBooking(item); if (result.status === 'updated') { // cart.items 已刷新 } // cancelled：用户在抽屉取消 }; if (!item._extend?.booking) return null; return ; } ``` 与加车链路的差异： | | 加车 `addProductWithFlow` | 已加车编辑 `editCartLineBooking` | |---|---|---| | 入口 | 商品 catalog | `SalesSdkCartItemView` | | cacheItem 来源 | OS `decideAddProduct` / `confirmDetail` | OS `buildCacheItemFromOrderLine` | | 写回 | `confirmBookingEdit` → `addProductToOrder` | `updateItem` + booking patch | | 抽屉 | `autoClose=true` 时可静默跳过 | `forceOpen: true`，始终展示抽屉 | **前置条件**：Provider 已配置 `uiHosts.openBookingEdit`；OS 需支持 `buildCacheItemFromOrderLine`（pisellos 新版）。 --- ### 4.6.5 跨日 / Holder Host（推荐与 `addProductWithFlow` 一并配置） ```ts import { createOpenBookingEditHost, createOpenMultiDaySelectHost, createOpenHolderSelectHost, } from '@pisell/private-materials/plus/salesSdk'; uiHosts={{ openBookingEdit: createOpenBookingEditHost(), openMultiDaySelect: createOpenMultiDaySelectHost(), openHolderSelect: createOpenHolderSelectHost(), openProductDetail: /* ... */, }} ``` 编排顺序（对齐 ticketBooking AddService）：规格弹窗 → 跨日日期（仅 `duration.type === 'days'`）→ `confirmDetail`（内含 Holder + 跨日展开）→ 资源抽屉。 ### 4.6.6 手动三段式（自定义插入点） 若需完全自研弹窗、不走内置 Host，可改用手动 API（§4.6 顶部示例）或底层纯函数： ```ts import { runAddProductFlow } from '@pisell/private-materials/plus/salesSdk'; // 单测 / 非 React：注入 mock cart API + mock hosts await runAddProductFlow( { addProduct, confirmDetail, confirmBookingEdit }, uiHosts, product, { quantity: 1 }, ); ``` 自研 `openProductDetail` 只需满足 Host 契约： ```ts openProductDetail: async (payload) => { // payload: SalesSdkAddProductRequiresDetailPayload（showConfig / isEject / productData / date 等） const detailResult = await myOpenSkuModal(payload); // 用户取消 → return null // 用户确认 → return { e, extension_type, detail }（Info2 callback 三元组） return detailResult; }; ``` --- ### 4.6.7 SalesSdkDemo（create / edit Tab 参考实现） 新建 / 编辑 Tab 使用 `SalesSdkDemoTabShell`（Demo 专用薄封装，等价于 §4.6.2 的标准接线）： - `uiHosts.openProductDetail` → `createLegacyOpenProductDetailHost`（`demo/hosts/legacyOpenProductDetail.ts`） - `uiHosts.openBookingEdit` → `createOpenBookingEditHost()` - `DemoHostRuntimeBridge` 同步 `customerId` / `date` 到 runtime ref - 一键步骤 `cart.addProductWithFlow` 走：规格弹窗 → 资源编辑抽屉 → `confirmDetail` / `confirmBookingEdit` - 购物车行「编辑资源」走 `cart.editCartLineBooking` 业务页可直接复制 `SalesSdkDemoTabShell` 的 `uiHosts` 组装方式，去掉 Demo 前缀即可。 --- ### 4.6.8 新建 / 编辑完整示例（saleDetail、ticketBooking 迁移页） ```tsx import React, { useEffect, useMemo, useRef } from 'react'; import useEngineContext from '../../../hooks/useEngineContext'; import { SalesSdkProvider, useSalesSdk, useSalesSdkCart, useSalesSdkCustomer, useSalesSdkProducts, createOpenBookingEditHost, createLegacyOpenProductDetailHost, type LegacyProductDetailHostRuntime, type SalesSdkCartItemView, } from '@pisell/private-materials/plus/salesSdk'; // ── 1. 页面 Shell：Provider + uiHosts ────────────────────────────── function BookingSalesShell({ osKey, orderId, children, }: { osKey: string; orderId?: number; children: React.ReactNode; }) { const context = useEngineContext(); const action = context?.appHelper?.utils?.action; const runtimeRef = useRef({}); const uiHosts = useMemo( () => ({ openBookingEdit: createOpenBookingEditHost(), ...(action && { openProductDetail: createLegacyOpenProductDetailHost({ action, getRuntime: () => runtimeRef.current, }), }), }), [action], ); return ( {children} ); } /** 将 customer / date 同步给 openProductDetail Host（参考 demo/DemoHostRuntimeBridge.tsx） */ function HostRuntimeSync({ runtimeRef, }: { runtimeRef: React.MutableRefObject; }) { const customer = useSalesSdkCustomer(); const { bookingTicket } = useSalesSdk(); useEffect(() => { const rawDate = bookingTicket?.getBookingDate?.(); runtimeRef.current = { customerId: customer.selected?.id, date: rawDate ? String(rawDate) : undefined, }; }, [bookingTicket, customer.selected?.id, runtimeRef]); return null; } // ── 2. 新建页：createNew → 选客户 → 加车 ─────────────────────────── function CreateOrderPage({ osKey }: { osKey: string }) { return ( ); } function CreateOrderContent() { const { createNew, submit, isReady } = useSalesSdk(); const products = useSalesSdkProducts(); const cart = useSalesSdkCart(); useEffect(() => { if (isReady) createNew(); }, [isReady, createNew]); const handleAdd = async (product: ProductData) => { const result = await cart.addProductWithFlow(product, { quantity: 1 }); if (result.status !== 'added') return; }; return (
{products.products.map((p) => ( ))}
); } // ── 3. 编辑页：orderId 自动 load → 加行 / 改资源 ─────────────────── function EditOrderPage({ osKey, orderId }: { osKey: string; orderId: number }) { return ( ); } function EditOrderContent() { const cart = useSalesSdkCart(); const { submit } = useSalesSdk(); const handleEditBooking = async (item: SalesSdkCartItemView) => { await cart.editCartLineBooking(item); }; return (
{cart.items.map((item) => (
{item.title} {item._extend?.booking ? ( ) : null}
))}
); } ``` **使用是否方便**：当前模式下一页只需 **两处固定接线**（`createOpenBookingEditHost` + `createLegacyOpenProductDetailHost`），业务代码侧 **一行 `addProductWithFlow` / 一行 `editCartLineBooking`** 即可；抽屉渲染由 Provider 托管。若页面无 LCE `action`，仅需自实现 `openProductDetail` 一个 Host。 --- 新增可选 Provider：``，对应 hook：`useSalesSdkBookingContext()`。 ticketBooking + Info2 流不依赖它，可不挂载。新 saleDetail 类组件如果要在弹窗里复用资源/容量算法，挂上即可： ```tsx // SaleDetailScreen 内部 const ctx = useSalesSdkBookingContext(); ctx.setBookingConfig(boardConfig); // /core/board/management/config 已拉到的数据灌进 OS ctx.setResources(scheduleList); // /form/schedule 已拉到的数据灌进 OS ctx.setDate(dayjs('2026-05-20')); const resources = ctx.getResourcesForProduct(product); const cacheItem = ctx.getProductExtend(buildCacheItem(product)); const errors = ctx.getResourceErrors(resources[0], cacheItem); ``` **SDK 不会发起 `/core/board/management/config` 或 `/form/schedule` 请求**，消费方在已经拉到数据的地方一次 `setBookingConfig` / `setResources` 即可（与 ticketBooking 共享同 osKey 时甚至可以不再拉一次）。 ### ResourceUnavailableReason → i18n key 对照表 `getResourceErrors` 输出的 `reason` 是 enum，文案不进 OS。UI 端按下表渲染： | reason | i18n key | 参数 | 说明 | |---|---|---|---| | `no_product` | `pisell2.text.no-product-added` | - | 行内无任何商品，对应 info2 `type='products'` | | `time_out_of_range` | `pisell1.text.resource-error-message-2` | `labelText`, `startText`, `endText`(, `isCrossDay`) | 该资源在所选时间段不在工作时段，对应 info2 `type='time'` | | `count_out_of_range` | `pisell1.text.resource-error-message-3` | `labelText`, `startText`, `endText`(, `isCrossDay`) | 该资源在所选时间段容量不足，对应 info2 `type='limit'` | | `resource_unbound` | `pisell1.text.resource-error-message-unbound` | - | 资源未绑定该商品/未挂表单，对应 info2 `type='unbound'` | > 说明：`isCrossDay=true` 时 UI 端通常在 `endText` 前补一个本地化 "tomorrow" 前缀；`params.labelText` 即资源名（资源行的显示标题）。 --- ## 5. 接入示例（不依赖 UI） ```tsx import { SalesSdkProvider, useSalesSdk, useSalesSdkCart, useSalesSdkCustomer, useSalesSdkSummary, deriveDisabledEdit, deriveSummary, } from '@pisell/private-materials'; function OrderShell({ orderId }: { orderId: number }) { return ( ); } function OrderItemsArea() { const { items, removeItem } = useSalesSdkCart(); return items.map((item) => (
{item.title} - {item.variant_title}
)); } function OrderClientArea() { const { display, select } = useSalesSdkCustomer(); if (!display) return ; return (
{display.name} {display.phone} {display.isWalkIn && Walk-in}
); } function OrderFooterArea() { const { salesDetail } = useSalesSdk(); const { summary } = useSalesSdkSummary(); const { disabledEdit } = deriveDisabledEdit(salesDetail?.rootBooking ?? null, salesDetail?.header); const { totalAmount, expectAmount, amountGap } = deriveSummary(summary); return (