# @crvouga/mockingbird-service-odx 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-odx/

版本：3\.10\.9
npm 元数据更新时间：2026-11-03T01:30:11.166Z
中文译文更新时间：2026-11-11T02:28:05.222Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-odx
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-odx/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/odx#readme
源码仓库：https://github.com/crvouga/mockingbird

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.4 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-09-22T23:55:56.153Z
- 最新版本发布：2026-11-03T01:30:10.874Z
- 近 30 天下载量：16247（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

(已退休)最佳DX合作伙伴API的模拟器:病人、伙伴链接、HL7和结构化实验室进口、功能健康报告(JSON/PDF)、网络记录和签名患者 测试网呼.

## 安装

```sh
npm install @crvouga/mockingbird-service-odx
```

也可以使用：`pnpm add @crvouga/mockingbird-service-odx`、`yarn add @crvouga/mockingbird-service-odx`、`bun add @crvouga/mockingbird-service-odx`

## README

# @crvouga/ mockingbird-service-odx (英语)

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

国家模拟器 **优化DX(ODX)** 测试套房的API:伙伴实验室及其 生物标记元素、练习病人(创建、更新、删除、伙伴链接、搜索)、实验室 《功能卫生报告》(JSON或PDF), 网络记录和签名 `PatientTest` (原始内容存档于2018-10-21). Webhoks ODX spots back.

> **该供应商已退役 2026-07-22.** 我们的队列路径只能由 `acme-pdf-enabled` 旗帜( 默认) `false`),所以一个没有PostHog的本地堆栈仍然呼叫ODX. 更便宜的修补就是通过PostHog模拟器把旗子打开 (单位:千美元)`@crvouga/mockingbird-service-posthog`); 当套房必须练习 ODX 时使用此模拟器 路径本身(生物时代的网络呼声、健康PDF上传、迁移).

-   行动范围: [支助](https://github.com/crvouga/mockingbird/blob/main/packages/service/odx/SUPPORT.md)
-   ODX 发布无 spec : `openapi.yaml` 由我们消费者的电线形状手工制作 (单位:千美元)`optimal.dx.service.ts`和QA的防线 `odx-client.ts`) (中文(简体) ).

## 安装

```bash
npm install -D @crvouga/mockingbird-service-odx
```

仅限无害环境管理。 节点 22或 Bun 1.2. 无土生属地. 给它服务 `npx mockingbird-odx serve`, (中文(简体) ), `createServer` 从 `./server` (节点),或 `createRuntime` 带有任意 获取服务器 .

## 使用量

真正的基础 URL 是 `https://odxinstanceresource.azure-api.net/<partner>`;伙伴部分为 你的账户是sult. 点 `OPTIMAL_URL` 在模拟器上( 它是压倒性的; 不需要路径前缀), 保留任何 `OPTIMAL_API_KEY` 财务报告和审定财务报表 `OPTIMAL_PRACTICE_ID`。预先登记后端的 Webhook, 或者让 `manageWebhooks` 通过注册 `POST /v1/webhook` 在生产方面:

```bash
npx mockingbird-odx serve --port 8817 \
  --webhook-url http://127.0.0.1:3000/odx/webhook   # must equal SYSTEM_API_DEPLOYMENT_URL/odx/webhook
```

```ts
import { createServer } from "@crvouga/mockingbird-service-odx/server"

// Test setup: the emulator, with the backend's webhook pre-registered.
const server = await createServer({ webhook: { url: "http://127.0.0.1:3000/odx/webhook" } })

// Application code: OPTIMAL_URL is server.url; any OPTIMAL_API_KEY and practice id.
const baseUrl = server.url
const created = await fetch(`${baseUrl}/v1/practice/p1/patient`, {
  method: "POST",
  headers: { ApiKey: "any", "content-type": "application/json" },
  body: JSON.stringify({
    firstName: "Ada",
    lastName: "Lovelace",
    gender: "Female",
    email: "ada@example.com",
  }),
})
const patient = (await created.json()) as { patientId: number }
// …the app posts HL7 to /v1/practice/p1/patient/{patientId}/test; the emulator answers the parsed
// PatientTest and posts a signed `Created` webhook to /odx/webhook.
await server.close()
```

### 路线

| 路线 | 行为 |
| --- | --- |
| `GET /v1/partner/labs` | `[{labId, name, isCurrentLab}]`: AHA (1), 查询(2), LabCorp (3). |
| `GET /v1/elements/{labId}` | 要件`ELEMENTS`实验室: `elementId`, (中文(简体) ), `elementName`, (中文(简体) ), `elementGenderType`, (中文(简体) ), `cuUnit`, (中文(简体) ), `siUnit`, (中文(简体) ), `cuToSiConversionFactor`, (中文(简体) ), `elementReferences[{elementCode}]` (LOINC代码为HL7 OBX-3被映射出). 包括九种同龄输入(494,496,506,511,537/538,556,564,568,571). 未知实验室 ~ 404 `{Message}`。 。 。 . |
| `POST /v1/practice/{pid}/patient` | 创建一个 `OdxPatient` 带有数字 `patientId` (10001...) (中文(简体) ). `firstName`, (中文(简体) ), `lastName`, (中文(简体) ), `email` ,否则ASP.NET问题细节400. `dateOfBirth` 变成 `YYYY-MM-DDT00:00:00`· ; `gender` 改为 `Male`编号 :`Female`编号 :`Unknown`。 。 。 . |
| `PUT /v1/practice/{pid}/patient/{id}` | 替换患者; 404 `{Message}` 在那个惯例中未知. |
| `DELETE /v1/practice/{pid}/patient/{id}` | 204; 放弃测试(QA destroption). |
| `POST /v1/practice/{pid}/patient/{id}/partner/{localUserId}` | 身体为文字 `false`; 存储我们的用户代号(admin-visible). 答复 `true`。 。 。 . |
| `GET /v1/practice/{pid}/patients` | 所有患者;其中任何一位 `email`, (中文(简体) ), `firstName`, (中文(简体) ), `lastName`, (中文(简体) ), `dateOfBirth` 这是一个对案件不敏感的搜索 答案 **404 当没有匹配时** (我们的客户通行证) `ignore404`) (中文(简体) ). |
| `POST …/patient/{id}/test` | HL7 导入 : `{labProfileId, labId, testDate, unitType, userId, externalReference, externalMessageControlId?, externalPatientTestId, menstrualPhase, isFasting, hl7}`目标3 `code^text` 根据实验室代码绘制到元素的地图, `EL<id>`,或名称(hs-CRP选择病人的性别);OBX-5等值 `<0.2` 变成 `comparison: "<"`。未映射/非数值观测地 `importLogs`释放 `Created`。没有MSH或OBX的信息是400. |
| `PUT …/patient/{id}/test/{testId}` | 再入; 输出 `Updated` (ODX发送一个Created+更新的配对,数据相同). |
| `POST …/patient/{id}/testresults` | 结构化导入( E)`results[{elementId, value, comparison}]`; 发射 `Created`。 。 。 . |
| `GET …/patient/{id}/tests` | 病人的测试,最古老的第一. |
| `POST /v1/reports/FunctionalHealthReport` | `outputType: Json` → `{metadata, labs, elements, sections}` 与部分 我们 `storeHealthData` a. 读取(组、上/下最佳、“功能体系统”条件、健康问题); `Pdf` • 有效的单页 `application/pdf`。未知测试 ~ 404. |
| `GET /v1/webhooks` | `[{partnerWebhookId, signingKey, createDate, entityEvents: {PatientTest}, webhookUrl}]` - 我们的后卫呼吁这个 **每个** 输入到 webhook 获取密钥. |
| `POST /v1/webhook`, (中文(简体) ), `PUT /v1/webhook/{id}` | 登记册/更新`manageWebhooks`) (中文(简体) ). |

错误: 缺少/ 未知 `ApiKey` 第401条 `{statusCode, message}` (Azure API 管理形状); ODX 错误 `{Message}`; 验证 → ASP.NET 问题细节 `{title, status, errors}`。 。 。 .

### 网络呼号

每个测试进口或再进口站 `{entityType: "PatientTest", eventType, data: <PatientTest>}` 连接到每个已注册的 Webhook URL 订阅该事件,并 `optimaldx-signature: <UPPERCASE hex HMAC-SHA256(signingKey, rawBody)>`。 。 。 . `data` 是全数 病人试验(`results[].comparison` 永远是弦,正如我们的接收器的 zod DTO 要求. 非-2xx的答案被重审(即即时5 s,5 min,30 min,2 h). `GET /__admin/webhooks`, (中文(简体) ), `/__admin/webhooks/events`, (中文(简体) ), `POST /__admin/webhooks/flush` 财务报告和审定财务报表 `…/replay` 工作如常.

### 管理员(超过标准合同)

| 路线 | 效果 |
| --- | --- |
| `POST /__admin/tests/:id/webhook` | `{eventType?: Created|Updated|Deleted, signature?: valid|short|bad}`: 释放出一个被存储的测试的网页. |
| `DELETE /__admin/tests/:id` | 释放 `Deleted` 并放弃测试. |
| `GET /__admin/patients`, (中文(简体) ), `GET /__admin/tests` | 命名空间的记录(病人包括 `partnerUserId`; HL7 文本从未被存储). |
| `GET`编号 :`PUT /__admin/settings` | `{apiKeys?: string[]}` (空接受任何密钥). |

错误预设( E)`POST /__admin/faults {"preset": "<name>", "count"?: n}`: `wrong_length_signature`, (中文(简体) ), `bad_signature`, (中文(简体) ), `empty_success`, (中文(简体) ), `no_content`, (中文(简体) ), `not_found`, (中文(简体) ), `server_error`, (中文(简体) ), `slow`, (中文(简体) ), `webhook_duplicate`, (中文(简体) ), `webhook_reorder`, (中文(简体) ), `webhook_drop`。 。 。 .

### 命名空间

`x-mockingbird-namespace`页:1 `/__admin/ns/<name>` 前缀在 `OPTIMAL_URL`,或用 API 键: `PUT /__admin/credentials {"credentials": {"<OPTIMAL_API_KEY>": "<namespace>"}}`。 。 。 .

### 已知的消费者错误

-   **错误的签名 − 500.** `OdxSignatureGuard.verifyHmac` 电话 `crypto.timingSafeEqual` 不同长度的缓冲器,可抛出 `RangeError` 改为 回来的假,所以一个短 `optimaldx-signature` 是一个500(ODX然后重试)而不是一个 403. 国家 `wrong_length_signature` 预设发送32个特征的签名来复制.
-   `manageWebhooks` “更新”一个自有的旧 URL 的呆滞注册( 无), 然后注册 新的,所以 stale 注册积累.
-   `updateWebhook` 通过方法为 `'Put'`; 节点的取来使其正常化( Bun 的取出没有—— 即 随着应用程序运行在节点上,消费端口恢复正常.

### 故意不模拟

-   临床逻辑:报告状况和健康问题仅产生结果 生物年龄没有计算.
-   真正的元素目录(千个元素,实验室专用代码):13个元素体 满足消费者的需求 HL7除MSH/OBX以外的部分被忽略;PID从未被存储.
-   报告主题,超出元数据标签的收件人,以及PDF内容.
-   没有正式的SDK存在,所以没有SDK放入测试.

## API 密码

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `OdxAPI` | 类 | 进程模拟器 : `fetch(request)`, (中文(简体) ), `reset()`, (中文(简体) ), `emit(testId, eventType, signature?)`, (中文(简体) ), `patients()`, (中文(简体) ), `tests()`选项: `sqlite`, (中文(简体) ), `now`, (中文(简体) ), `namespace`, (中文(简体) ), `settings`, (中文(简体) ), `onWebhook`。 。 。 . |
| `createRuntime` | 函数 | 服务合同的模拟者。 选项 : `webhook: {url, signingKey?}`, (中文(简体) ), `settings`, (中文(简体) ), `retryDelaysMs`, (中文(简体) ), `fetch`, (中文(简体) ), `clock`, (中文(简体) ), `seed`, (中文(简体) ), `adminKey`, (中文(简体) ), `onLog`。 。 。 . |
| `ODX_PRESETS` | 对象 | 每个命名的断层预设. |
| `ODX_NAMESPACE` | 字符串 | 服务名称, `"odx"`。 。 。 . |
| `SIGNATURE_HEADER` | 字符串 | `"optimaldx-signature"`。 。 。 . |
| `signOdx` | 函数 | `(signingKey, body) → UPPERCASE hex HMAC-SHA256`。 。 。 . |
| `apiKeyCredential` | 函数 | 这个 `ApiKey` 页眉( 如何将证书映射到命名空间) . |
| `ELEMENTS`, (中文(简体) ), `LABS` | 数组 | 元素体和伙伴实验室. |
| `matchElement`, (中文(简体) ), `parseObservations` | 函数 | HL7 OBX解析和代码 → 元素映射. |
| `DEFAULT_SETTINGS` | 对象 | 人名空间默认值 . |
| `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds` | 数值 | 销售商为OpenAPI合同及其业务代号. |
| `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` (单位:千美元)`./server`(中文(简体) ) | 节点 | 服务过来 `node:http`; 数据 `serve` CLI目标; 第8817口. |

部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

## 常见问题

### @crvouga/mockingbird-service-odx 是什么？

\(已退休\)最佳DX合作伙伴API的模拟器:病人、伙伴链接、HL7和结构化实验室进口、功能健康报告\(JSON/PDF\)、网络记录和签名患者 测试网呼\.

### 如何安装 @crvouga/mockingbird-service-odx？

在项目目录运行 npm install @crvouga/mockingbird-service-odx，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-odx，可以用 npx mockingbird-odx 直接运行。

### @crvouga/mockingbird-service-odx 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crvouga/mockingbird-service-odx 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @crvouga/mockingbird-service-odx 可以商用吗？

@crvouga/mockingbird-service-odx 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crvouga/mockingbird-service-odx 的下载量有多少？

根据 npm 官方下载统计，@crvouga/mockingbird-service-odx 在 2026/10/11 – 2026/11/09 这 30 天内被下载 16,247 次，日均约 542 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crvouga/mockingbird-service-odx 还在维护吗？

最新版本 3\.10\.9 发布于 2026/11/03（8 天前）；至今共发布 41 个版本，其中过去 12 个月发布了 41 个；首次发布于 2026/09/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。