版本与变更策略
本页说明开放平台 API 和文档的版本治理原则，帮助合作方理解当前应该接入哪个版本，以及后续如何处理升级和兼容问题。
当前版本状态
截至目前：
- 当前对外稳定开放版本：
2.0 - 当前已公开文档默认对应：
2.0 - 后续新增实现与能力演进：进入
3.0
这意味着如果文档页面没有特别声明版本，现阶段应默认按 2.0 理解和接入。
版本命名规则
平台采用显式的大版本命名方式管理接口版本。
API 路径
2.0：/v2/...3.0：/v3/...
例如：
plain.txt
/v2/nc.ms.drug.package.detail
/v3/...
文档路径
当前公开文档路径仍以现有 /doc/* 代表 2.0。
后续 3.0 文档将采用显式版本命名空间进行区分，避免和 2.0 混用。
2.0 的维护原则
2.0 是当前稳定版本，主要服务于已接入或正在接入的合作方。
2.0 的维护目标是稳定，而不是持续引入新语义。
因此，2.0 默认只做以下类型的更新：
- 文档勘误和表达修正
- 参数说明补充
- 示例优化
- 不改变既有语义的缺陷修复
原则上，以下内容不应继续直接写入 2.0：
- 新能力
- 新版本的核心实现
- 会改变字段语义的调整
- 会影响旧客户端理解的行为变化
3.0 的定位
3.0 是后续能力演进的主版本线。
凡是属于下面这些情况，默认都应进入 3.0：
- 新增能力或新产品化接口
- 需要重新组织字段结构的升级
- 返回语义或业务口径发生明显变化
- 需要引入新的接入方式、批量机制或结果模型
换句话说，3.0 不是对 2.0 的零散补丁，而是承接后续实现的主版本。
兼容原则
版本兼容遵循以下基本原则：
1. 已公开的 2.0 链接保持稳定
现有 2.0 文档链接和公开路径应继续可访问，避免影响已接入客户和外部引用。
2. 新版本不覆盖旧版本语义
3.0 的新增能力和字段演进，不应反向覆盖 2.0 文档页的原有含义。
3. 版本差异要显式表达
如果同一业务能力在 2.0 和 3.0 中都存在，文档中应明确写出差异点，例如：
- 请求参数是否变化
- 返回字段是否变化
- 字段含义是否变化
- 调用方式和分页机制是否变化
变更分类建议
为了避免版本线混乱，建议把变更分成三类：
文档型变更
只修正文案、错别字、示例或解释，不改变接口含义。
这类变更可以继续进入当前版本文档。
非破坏性补充
例如补充说明、增加背景信息、完善场景解释。
如果不影响旧客户端理解，也可以继续在当前版本文档中维护。
版本级演进
例如字段结构调整、返回语义变化、能力边界重定义、新主流程设计。
这类变更应进入 3.0，并在必要时提供迁移说明。
对合作方的实际建议
如处于准备接入阶段：
- 没有特殊说明时，按
2.0文档接入 - 不要把尚未公开的
3.0规划能力当作当前稳定能力 - 如果场景明确依赖后续新实现，应在立项阶段就确认是否走
3.0
如已在使用 2.0：
- 可以继续按
2.0稳定文档运行 - 后续如需升级到
3.0，应优先关注版本差异和迁移说明
文档治理口径
从文档维护角度，当前推荐使用以下口径：
content/docs当前视为2.0内容源- 现有
/doc/*路径继续代表2.0 - 后续
3.0文档独立建设，避免直接覆盖当前文档
这套规则的目标只有一个：让存量客户继续稳定接入 2.0，同时给后续 3.0 演进留出清晰边界。