# 版本控制与弃用

> FHIR R4 和 REST v1 接口、Webhook 负载和 SDK 如何变化，以及如何宣布重大更改。

Source: https://developers.anpheros.com/zh/guides/versioning

- 位于 `/fhir/R4` 的 **FHIR R4** 和位于 `/v1` 的 **REST v1** 是稳定接口。新增更改（新字段、新资源类型、新端点、新事件类型）会直接发布，无需通知；SDK 和 `docs/openapi.json` 会在同一提交中重新生成，否则测试会失败。
- **重大更改**会获得新的前缀（`/v2`），并至少有 **6 个月**的并行运行期；在此期间，旧前缀将返回 `Deprecation` 和 `Sunset` 标头。
- **Webhook 负载**会包含一个 `type`；新类型是新增的。订阅 `*` 的用户必须忽略未知类型。
- **SDK** 遵循 semver；主 SDK 版本可能会弃用旧的 API 前缀。
- **安全修复**可能会收紧验证（例如值集），而无需版本升级；除非是修复活跃漏洞，否则此类收紧会在变更日志中提前 30 天通知。

## 更新日志

### 2026年10月14日 (新增：同意页面品牌化，团队单点登录)

- 团队单点登录：组织可以与其 SAML 或 OIDC 提供商及其电子邮件域 (`PUT /admin/organizations/{id}/sso`, 平台管理员) 相关联，并且可以要求成员进行单点登录。`GET /admin/sso/discover?email=` (无身份验证) 返回工作电子邮件的提供商。`OrganizationOut` 增加了 `sso_provider_id`、`sso_domains` 和 `sso_required`。请参阅 [团队单点登录](https://developers.anpheros.com/zh/guides/team-sso)。

- `PUT /admin/applications/{id}/branding` 设置应用程序的徽标 (PNG/JPEG/WebP 数据 URI，最大 64 KB) 和强调色 (与白色文本的对比度至少为 4.5:1)，显示在托管的同意页面上。`ApplicationOut` 增加了 `logo` 和 `brand_color`。请参阅 [身份验证和 OAuth](auth-and-oauth.md#your-brand-on-the-consent-page)。
- 定价页面和 [定价](https://developers.anpheros.com/zh/guides/pricing)：添加了私有 Beta 说明。生产环境将在验证和签署 DPA 后开放，计划将通过电子邮件开具发票，并且额度尚未自动强制执行。

### 2026年10月14日 (错误形状和实验室映射修复)
- 实验室导入：*Uree* / *Urea* 映射到尿素 (`3091-6`；mmol/L 为 `22664-7`)，而不是尿素氮 (`3094-0`)，后者保留给 *BUN* / *Urea nitrogen* (mmol/L 为 `14937-7`)。值不会被转换。没有生产数据使用旧的映射。
- 实验室导入：报告上带有方法的 LDL 映射到计算 LDL (`13457-7`) 或直接 LDL (`18262-6`)；没有方法则保持 `2089-1`。*Direct* 现在是一个限定符，因此 *Bilirubina directa* 不再映射到总胆红素 (`1975-2`)；它保留实验室的代码。没有生产数据使用旧的映射。
- `/v1` 下的未知端点和方法以记录的错误形状 (`404 not-found`, `405 not-supported`) 而不是 `{"detail": "Not Found"}` 进行响应；无效的查询参数和 `/v1` 下的每 IP 速率限制使用 `{"error": …}` 而不是 `OperationOutcome` (在 `/fhir/R4` 下不变)；`/v1` 下意外的 `500` 携带 `error.type = "exception"` (它曾携带 `error.code`)。
- 实验室导入：具有本地或非 LOINC 编码系统的 HL7 v2 结果在 `urn:anpheros:lab-code` 下保留实验室的代码 (以前是 `urn:hl7:<system>`，例如 `urn:hl7:l`)。已存储的结果不会更改。
- 实验室导入：英文 LOINC 名称和同义词被识别 (*Hemoglobin A1c*, *Glycated hemoglobin*, *HDL cholesterol*, *LDL cholesterol*, *Haemoglobin*)；裸露的 *Glucose* 映射到血清或血浆 (2345-7)，如同 *Glicemie*。带有概念缺乏的限定符的名称 (*urine*, *non-HDL*…) 不再与相关测试匹配：在此更改之前，没有 LOINC 代码的 *HDL cholesterol* 和 *LDL cholesterol* 被存储为总胆固醇 (2093-3)。
- 实验室导入：重新发送报告不再因 LOINC 映射更改而导致结果重复。新结果携带第二个标识符 `urn:anpheros:lab-import:v2`，该标识符由报告构建 (报告 ID、报告上的名称和代码、日期、值、单位)；现有标识符保持不变，并且通过名称、日期、值、单位和报告 ID 识别早期结果。具有报告上不同名称但相同 LOINC 代码、日期和值的两个结果 (例如 *Glucose* 和 *Glicemie*) 不再合并为一个。

### 2026年10月13日 (新增，无合同变更)
- 同意在每个派生视图 (`/v1/context`, `/v1/patients/{id}/timeline`, portal, `$everything`) 上强制执行，使用一个共享规则；请求但未覆盖的部分出现在上下文的 `omitted` 中。
- OpenAPI 现在声明 `servers`、`securitySchemes` (`bearer`, `apiKey`, `oauth2`, `firebase`)、每个操作的 `security` 以及每个操作的响应模式；生成的客户端获得类型化的响应。
- 每个 `401` 都携带 `WWW-Authenticate: Bearer`。
- CapabilityStatement 广告 SMART (`oauth-uris` 扩展，`SMART-on-FHIR` 服务) 和 IPS 实现指南。
- 代理后面的重定向保留 `https://`。
- `python-multipart` 0.0.20 → 0.0.32；`pip-audit` 在已知漏洞时阻止构建。
- Webhook URL 必须是公共 HTTPS：在注册时，localhost (以前在沙箱中接受但从未传递)、私有和保留地址以及解析到它们的名称将被拒绝，并在 `url` 上返回 400；传递仅连接到它们刚刚检查过的 IP 地址 (DNS 重新绑定)。

## 一致性强制执行（2026 年 9 月 23 日宣布）

目前，未能满足 IPS / HL7 Europe 实验室要求的写入操作将返回 `201`/`200`，并带有 `Anpheros-Conformance` 标头。在观察期（计划：自本通知起 60-90 天）后，平台将切换到**阻止**模式：此类写入操作将返回 `422`，并带有 `OperationOutcome`，列出所有缺失项。需要更多时间的集成商可以在过渡期间获得项目豁免。2026 年 9 月 23 日新增的资源类型：`Procedure`、`DiagnosticReport`、`CarePlan`、`FamilyMemberHistory`、`ServiceRequest`、`Goal`（增量）。