S1000D Issue 版本、补丁与迁移怎么管理？
S1000D 项目遇到 Issue 更新、工具补丁或数据迁移时，先建立清晰的版本基线，再评估规则、Schema、数据模块、媒体和交付物的影响。版本号本身不能替代迁移验证；可复现的矩阵、日志和验收记录，才是后续维护的依据。
Issue、补丁和迁移分别是什么？
Issue 版本是项目采用的规范基线，可能关联数据模块结构、编码规则、Schema、校验工具和出版要求。补丁通常是对既定版本的修正、兼容更新或工具缺陷修复；它不必然等同于新的 Issue。迁移则是把项目资产、规则、配置和交付流程从一个已确认基线调整到另一个基线，并证明结果可用、可追溯、可回退。
实际项目中还会同时存在标准版本、工具版本、项目规则版本和产品配置版本。它们的发布时间和升级节奏可能不同，因此应把“规范更新”“工具补丁”“数据转换”和“交付重发布”分开记录。
项目版本矩阵怎么建？
版本矩阵不要求把所有内部构建号都公开，但项目内部必须能回答：当前内容由什么版本创建、用什么规则检查、由什么工具发布，以及目标环境需要什么版本才能复现。
| 对象 | 需要记录的基线 | 常见变化 | 迁移关注点 |
|---|---|---|---|
| 规范与 Issue | 采用的 Issue、项目生效日期、适用范围和批准记录 | 元素/属性约束、定义或实施解释发生变化 | 确认是否影响数据模型、编制规则和交付承诺；不要只看版本名称。 |
| Schema 与校验包 | Schema、规则文件、校验器版本及校验配置 | 结构约束、枚举、必填项或错误级别变化 | 用旧数据和新建数据分别校验，记录新增错误、警告和豁免依据。 |
| BREX、代码表与业务规则 | 规则集、代码表、适用性模型和变更单 | 编码含义、允许值、命名或筛选条件变化 | 检查规则引用、适用性真值组合、跨系统代码映射和审批状态。 |
| CSDB、编辑器与发布工具 | 编辑器/CSDB、转换器、渲染器和插件版本 | 解析、校验、导出、渲染或接口行为变化 | 保留工具配置和依赖，验证导入、编辑、预览、导出及批处理结果。 |
| 数据模块与媒体 | DM、PM、ICN、附件、引用关系和源文件状态 | 批量转换、命名变化、引用更新或媒体重采样 | 检查身份状态、引用链、图形热点、清晰度、版权和可追溯关系。 |
| 交付物与运行环境 | 目标设备/浏览器、交付格式、安装包和发布清单 | 阅读器、部署环境或输出格式变化 | 在目标环境抽检目录、检索、适用性、警告、安全信息和离线能力。 |
矩阵中的“当前”和“目标”应分别填写，不要把供应方建议版本直接写成项目已批准基线。若某项尚未确认，可标注“待确认”并阻止正式发布。
工具补丁和数据迁移有什么区别？
工具补丁可能修正解析、校验、渲染或接口问题，也可能改变默认配置。它通常先作用于工具链，不代表所有历史数据已经完成转换。数据迁移则会改变文件、元数据、引用或规则配置，需要生成转换日志、异常清单和可回退副本。
| 变化类型 | 可以先做什么 | 不能直接假设什么 |
|---|---|---|
| 仅工具补丁 | 在隔离环境安装，锁定配置，比较校验与渲染结果。 | 不能假设所有旧数据都自动获得新规则或新输出能力。 |
| 规则或代码表调整 | 建立影响清单，先处理代表性模块和边界条件。 | 不能假设旧的适用性、枚举值和审批状态仍然有效。 |
| Schema 或 Issue 迁移 | 制定转换映射、回退方案和双轨验证计划。 | 不能假设只改 XML 声明就完成结构和语义迁移。 |
| 交付环境变化 | 在目标阅读器或部署环境进行端到端抽检。 | 不能假设源端预览等同于客户现场的显示、检索和筛选结果。 |
迁移流程怎么走？
- 冻结基线：记录当前 Issue、Schema、BREX/代码表、CSDB/编辑器、发布工具、产品配置和交付环境，生成可校验的清单。
- 定义目标：说明升级原因、目标基线、涉及项目和数据范围，确认哪些内容必须保持兼容，哪些内容允许重构。
- 做差异分析：逐项比较结构、规则、编码、适用性、引用、媒体、渲染和接口，形成影响矩阵与风险等级。
- 准备隔离环境：复制 CSDB、配置和依赖，保留原始只读快照；先用小批量代表性数据试迁移。
- 执行转换与复核：运行转换工具，保存日志、警告、失败项和人工处理记录；对高风险模块进行人工比对。
- 双轨验证：用旧基线与新基线分别检查同一组样例，比较校验结果、目录、适用性、引用、媒体、检索和输出。
- 试发布与回退演练：在目标环境生成候选交付物，执行安装、打开、更新和回退演练，确认失败时可以恢复原版本。
- 批准上线：完成验收清单、问题关闭、版本矩阵和发布说明，由项目责任人批准后再切换正式基线。
迁移验收清单
下面的清单可作为项目评审的起点，实际条目应按合同、设备安全要求和交付环境补充。每一项都应关联样例、日志、截图或签署记录。
| 检查项 | 通过标准 | 建议证据 |
|---|---|---|
| 版本与范围 | 当前/目标基线、影响范围和批准人清晰可查。 | 版本矩阵、变更单、批准记录。 |
| 结构与规则 | 代表性 DM/PM 通过目标校验；新增错误和豁免均有处置结论。 | 校验报告、BREX/代码表版本、异常清单。 |
| 引用与适用性 | 内部/外部引用可解析，型号、批次和边界配置筛选结果正确。 | 引用检查表、适用性测试组合、对比截图。 |
| 媒体与安全信息 | 图形、热点、附件、警告、注意和禁止信息在目标环境可见且位置正确。 | 媒体清单、抽检截图、人工复核记录。 |
| 交付与运行 | 目录、检索、导航、打印/导出和部署方式符合交付要求。 | 候选包、目标环境测试记录、发布清单。 |
| 可追溯与回退 | 每个转换对象可追溯到源版本；旧包、配置和恢复步骤可用。 | 转换日志、哈希清单、回退演练记录。 |
最容易遗漏的迁移风险
- 只记录工具版本，没有记录 Schema、BREX、代码表和适用性配置。
- 只用“标准型号”测试，没有覆盖可选装置、批次差异和边界组合。
- 转换后 XML 能通过结构校验，却出现引用断裂、媒体丢失或筛选内容为空。
- 补丁改变了默认输出或渲染行为，但发布说明没有提示阅读器和客户环境。
- 新旧版本并行维护时没有定义主数据、差异合并和停止旧版本的条件。
- 没有保留转换日志、原始快照和回退包，后续无法解释或重现交付结果。
常见问题
S1000D Issue 升级就是给文件打补丁吗？
不一定。Issue 变化可能影响规则、Schema、工具校验、数据模块和交付流程；补丁通常是针对既定版本的修正或兼容更新。项目应先确认影响范围，再决定局部修补、批量转换还是完整迁移。
迁移前应该先确定哪些版本？
至少要记录项目采用的 Issue、Schema 或校验包、BREX 与代码表、CSDB 或编辑器版本、出版工具链、媒体处理组件和交付格式。具体版本号以项目合同、配置基线和供应方发布记录为准。
旧数据能直接用新版本工具打开吗？
不能默认可以。即使工具能够打开文件，也需要检查结构校验、适用性、引用、媒体、渲染和回退策略，并用代表性数据和边界配置完成回归验证。
补丁需要重新验收整套出版物吗？
取决于补丁的影响范围。涉及解析、校验、适用性、渲染、输出或接口的补丁，应至少覆盖受影响功能和代表性出版物；范围不明时，应按项目风险决定是否扩大抽检。
怎样判断迁移可以发布？
应以可追溯证据为准：版本矩阵已批准，转换日志和异常已处理，关键数据模块通过校验，适用性和引用结果正确，媒体与安全信息完整，目标交付物抽检通过，并保留回退包和签署记录。