# Wix facade 公共 API

## 更新记录

- 2026-07-16: 创建 `1.0.0` API 文档。
- 2026-07-16: 补充客户端装配、参数返回和扩展约束。

## `CreateWixProxy`

```js
CreateWixProxy(Options): { Handle(Request): Promise<Response> }
```

使用 core 通用配置，默认 `AllowedPathPrefixes` 为：

```text
/hzhx/wix_server
```

## `CreateWixClient`

```js
CreateWixClient(Options): WixClient
```

支持三种调用来源：

1. `InvokePayload`：调用现有 Base44 Function。
2. `Proxy`：使用调用方提供的 core 代理。
3. `ApiBaseUrl` 等配置：facade 内部创建代理。

返回：

- `Request`
- `Proxy`
- `WixDeviceApi`

示例：

```js
const Client = NodeFacadeBase44Wix.CreateWixClient({
  InvokePayload: CallWixFunction,
});
```

内部使用 core `CreateFacadeClientContext`，来源优先级为 `InvokePayload` → `Proxy` → 默认 Wix Proxy。

## WixDeviceApi 基础方法

```js
Request(Fun, Data, ExtraQJson)
QueryTask(TaskNameOrObject)
SendIocpServerData(SignOrObject)
```

`Request` 拒绝空 `Fun`。`ExtraQJson` 必须是普通对象才会被合并，`Fun` 始终使用显式参数覆盖。

参数说明：

- `Fun`：真实 `node_wix_server` 支持的命令名；
- `Data`：命令数据，保持后台 wire 结构；
- `ExtraQJson`：可选 RequestId 等 QJson 顶层字段，不能覆盖显式 `Fun`。

返回值：保留后台 `{ result, ret_str }` 或其他真实 QJson 响应，不做业务成功假设。

## WixDeviceApi 命令方法

- `SoracomDevice`
- `RegisterSoracomDevice`
- `ActivateSoracomDevice`
- `DeactivateSoracomDevice`
- `ChangeSoracomSpeedClass`
- `QuerySoracomSpeedClass`
- `QuerySoracomStatus`
- `QuerySoracomTraffic`
- `SendNWsDev`
- `SendProgramToTb1`
- `SendProgramToTcc160`
- `SendNovaFile`
- `SendBlackSlide`
- `SendNovaTime`
- `SendNovaCommand`
- `ClearStorageMemory`
- `ReadNovaDirFile`
- `DeleteNovaFile`
- `UploadNovaFile`
- `FirmwareUpdate`
- `SendProgramWithSpeed`

所有命令接收一个 `Data` 参数并返回 Promise，返回值保留 `node_wix_server` 原始 QJson 响应。

## 错误处理

- core 路径、鉴权、网络和超时错误会转换为抛出的 `Error`。
- `node_wix_server` 返回的 `{ result, ret_str }` 保持原样，由业务 Function 判断 `result`。
- 上游非 2xx 错误可从 `BackendProxyError` 读取 `StatusCode`、`UpstreamCode`、`RequestId`。

## 扩展注意事项

普通单参数命令加入 `WIX_DEVICE_COMMANDS` 即可；只有参数兼容规则不同的命令才在 `CreateWixService` 中写显式方法。必须先从 `node_wix_server` 验证命令真实存在，不能根据页面按钮名称猜测 Fun。