用途
sprint.migration 是一个 Bitrix 框架的数据库迁移模块，以 Composer 包（andreyryabin/sprint.migration）形式分发，也可从 Marketplace 获取。它的核心目标是把项目中的数据库结构与内容变更写成 PHP 类，并纳入版本控制系统（VCS）管理，从而让数据库变更可追踪、可复现、可回滚。
需要区分的是：模块自身拥有的表、事件和代理应写入该模块的安装程序（bitrix-modules），而不是放进迁移文件。
主要能力
- 版本类：迁移以
namespace Sprint\Migration; Version<YmdHis> extends Version的形式定义，通过up()与down()方法描述正向与回滚操作。 - 辅助与构建器：提供 HelperManager 辅助方法以及 builder 构建器，用于生成迁移文件与常见操作，具体方法名参见 helpers-builders 规则文档。
- 命令行工具：通过
php {module}/tools/migrate.php <command>执行迁移相关命令。 - 配置文件：使用
migrations.*.php配置文件进行设置。 - 版本记录表：默认使用
sprint_migration_versions表记录已应用的迁移。
使用方式
默认配置（config cfg）如下：
- 迁移目录：
{local|bitrix}/php_interface/migrations（若存在local/php_interface则使用 local）。 - 版本表：
sprint_migration_versions。 - 类命名：
namespace Sprint\Migration; Version<YmdHis> extends Version。 - CLI：
php {module}/tools/migrate.php <command>。
若模块未安装，应先检查 /local/modules/sprint.migration/ 与 /bitrix/modules/sprint.migration/，再通过 Loader::includeModule('sprint.migration') 判断；若确实缺失，建议通过 Marketplace 或 Composer 安装，不要自行编写迁移框架。
适用场景
- 需要把 Bitrix 项目的数据库结构与内容变更纳入版本控制。
- 需要以可回滚的 PHP 类方式编写、审查并应用迁移。
- 需要借助 CLI 与配置文件批量管理迁移。
限制与注意事项
- 基线要求：main 23.0+；已验证版本：sprint.migration 5.15.1、main 26.800.0。
- 不要修改模块源码，只编写迁移文件与
migrations.*.php配置。 - 应通过 add 或 builder 创建文件；手工命名会破坏时间戳校验。
- 实体应通过 CODE/XML_ID 标识，绝不使用来自其他数据库的 id。
- 已应用的迁移不可变，如需修正应新增一个迁移向前修复。
- 在共享或生产数据库上执行 up/down 必须获得明确的人工批准。
- 关于 CLI 命令、配置、版本命名与控制台用户，参见 rules/cli-config.md；关于编写 Version::up()/down()、可重启批次与交换文件，参见 rules/writing.md；关于辅助与构建器映射及方法名，参见 rules/helpers-builders.md；关于安全规则、审查与应用清单，参见 rules/checklist.md。