# OrderInvoice 低代码接入

## 当前交付边界

本目录是独立 Web Invoice 源码。组件已从 Private Materials `src/index.ts`
根导出，并在 `lowcode/order-invoice/meta.ts` 注册 metadata。
旧产物不会自动获得该导出；需要加载包含本次改动的配套 OS SDK 和物料产物。

## 页面内容

设计器组件名、`componentName` 和 `exportName` 均为 `OrderInvoice`，
包为 `@pisell/private-materials`，运行库导出为 `PrivateMaterials.OrderInvoice`。
专用页面主体只放这个组件：

```json
{
  "componentName": "Page",
  "props": {},
  "children": [{ "componentName": "OrderInvoice", "props": {} }]
}
```

页面不需要订单编辑器或 POS Server。外层弹窗、关闭和下载按钮属于 PC/H5 宿主。
上面是页面树片段，完整本地 schema 已在两个宿主的
`src/components/LowCode/schemas/orderInvoice.ts` 中注册。

## 宿主参数

组件优先读取显式 props，未提供时读取
`appHelper.constants.hostPageProps`。宿主已接好以下参数：

| 参数                   | 作用                                                                                |
| ---------------------- | ----------------------------------------------------------------------------------- |
| `osKey`                | 当前页面拥有的 `OrderInvoicePreviewImpl` 实例名。不要在设计器写死某个订单的实例名。 |
| `locale`               | 页面界面语言；小票语言由 OS result 决定。                                           |
| `onReady(handle)`      | 完整小票渲染后提供下载句柄。                                                        |
| `onError(error)`       | 数据准备失败，宿主显示重试。                                                        |
| `onDispose(identity?)` | 仅清理匹配 identity 的下载句柄，兼容无参数旧回调。                                  |

```ts
type OrderInvoiceHandle = {
  identity: string;
  downloadPdf(): Promise<void>;
};
```

宿主只应在当前 identity 匹配、准备完成时启用下载按钮。
关闭或切单后句柄失效；不要缓存到其他订单。`downloadPdf()` 表示已生成 PDF
并发起浏览器下载，不保证浏览器已将文件写入设备磁盘。

组件也提供可选 `result: OrderInvoiceResult`，用于设计样本或嵌入预览。
其完整类型定义位于 `OrderInvoice.tsx`，普通运行通过 `osKey` 获取真实快照。
直接传入旧用户端订单详情 JSON 不满足该类型契约。

## 所需运行能力

- `appHelper.utils.pisellos`：宿主已有的浏览器 Core，已注册只读 Invoice 实例。
- `appHelper.utils.html2canvas` 和 `appHelper.utils.jsPDF`：宿主已有的 PDF 库。
- 配套 OS SDK 导出 `OrderInvoicePreviewImpl`，使用客户 `/h5/order/sales/:id`
  完整快照及 Document/DEFAULT 模板。
- 普通和虚拟币小票共享纸张与导出入口，文字通过图片进入窄幅 PDF，不生成文本层。

## 正式页面 ID

两端 `src/components/OrderInvoiceModal/config.ts` 中的
`ORDER_INVOICE_PAGE_ID` 为 `h5_detail_invoice`，复用已有低代码页面。
本次语言选择通过现有 OS 实例及 hostPageProps 更新，不需要重搭页面或变更 schema。
不要在物料里写死页面 ID、订单 ID、店铺 ID 或发布版本。

## 验证状态

源码、根导出与 LESS/TypeScript 静态检查已完成。
浏览器渲染、普通/虚拟币同单对照、真实 PDF 分页和移动设备保存仍需配套产物联调。
本说明不代表现有线上产物已具备新组件。

## 配置打印语言

OS `OrderInvoicePreview` 从模板 language 中提供 `languageOptions` 和
`selectedLanguage`；宿主选择器调用实例 `selectLanguage(code)`，不重新准备订单或
加载低代码页面。`result.locale` 为主语言，`secondaryLocale` 仅在 `cn_en` 时为
`zh_CN`。页面 UI 的 `locale` 不随此选择改变。

物料使用 `receipt_key` 关联来源相同的双语节点，保留仅次语言有内容的行。
`receipt_item_kind` / `receipt_value_kind` 区分共享值和翻译文本，避免时间、编号和
金额重复；合并后的同一纸张用于预览及 PDF。虚拟币明细用 `receipt_source_index`
回到原始商品、规格和套餐金额，标题及表头显式使用小票语言，不依赖全局界面语言。

所选语言进入 OS 的 result identity。切换或关闭会终止旧 PDF 导出句柄；宿主必须
等待新 identity 的 `onReady` 后才启用下载。