dev-schema-upgrade-sql

name	dev-schema-upgrade-sql
description	MallBase 数据库真相源、正式字段与升级 SQL 规则；修改 backend/install/data/schema 或 demo seed、新增/改名字段、移除运行时字段探测，或用户明确要求已有库升级、本地 upgrade SQL、发布迁移和 SimpleSqlMigrationService 时使用。

Schema、正式字段与升级 SQL

真相源

1. 全新安装的表结构和初始配置以 backend/install/data/schema/*.sql 为真相源；演示数据放在 backend/install/data/demo/*.sql。
2. 修改字段或 seed 时先更新真相源，并同步 Controller 参数、Validate 场景、Model、Service、前端类型和测试中实际受影响的契约。
3. schema/*.sql 面向全新安装，可能包含 DROP TABLE；不要把整份安装 schema 直接用于已有业务库。

正式字段

字段结构定型后，业务代码直接依赖正式 schema。不要为了绕过未执行迁移而增加以下长期兼容：

• SHOW COLUMNS、DESCRIBE 或 information_schema 运行时探测。
• has*Column()、filter*Data() 一类按列存在性静默丢字段。
• “有新字段就写，没有就降级”的双轨持久化。

若真实数据库缺字段，修复部署或迁移，不在请求链路隐藏结构不一致。仅输入/输出归一化且不探测数据库结构的协议兼容可以保留，并应有清晰边界。

已有库边界

只有用户明确要求“已有库升级”“升级 SQL”“测试服/线上迁移”或等价目标时，才规划和生成增量 SQL。普通功能、schema、seed 或 UI 任务不要主动扩大到已有库升级，也不要把它列成默认风险项。

本地手工 SQL

backend/install/data/upgrade/ 是 .gitignore 中的本地运维目录，不是发布迁移真相源：

1. 仅在用户明确要求本地或指定环境升级 SQL 时创建。
2. 使用 YYYY_MM_DD_<summary>.sql 一类可识别名称。
3. 写成可安全重复执行的目标 MySQL SQL；建表、加列、加索引和 seed 都要使用目标版本支持的合法幂等方式，并在对应 MySQL 版本验证。
4. 不提交该目录，不把它与正式发布迁移混为一谈。

发布升级迁移

backend/app/service/upgrade/SimpleSqlMigrationService.php 执行发布流程已经暂存到升级根目录的迁移：

• 每个迁移必须同时提供 migrations/<migrationId>/up.sql 和 migrations/<migrationId>/down.sql，运行时路径分别位于 upgrade/staging/<jobId>/migrations/<migrationId>/。
• Agent 逐条传入 migration_id、版本及 up/down 描述；每个描述都精确包含 path、staging_path、SHA-256 和文件大小。不保留旧的单 SQL 兼容入口。
• 服务在执行正向 SQL 前先完整校验 up/down 两个文件，并在 upgrade/run/simple-migrations.json 记录正向语句级检查点。
• 当前自动数据库回滚恢复升级前的 database.sql 快照，不执行 down SQL； down 文件是签名发布包中的可逆性审查证据，不能替代数据库快照。
• 多条语句用独占行 -- mallbase:statement-breakpoint 分隔；每段只能是一条 SQL。
• up.sql、down.sql 单文件不得超过 16 MiB；Platform、Agent 与 PHP 必须使用同一上限。
• 不在迁移文件中使用 DELIMITER、SOURCE、LOAD DATA LOCAL 或自行控制 BEGIN/COMMIT/ROLLBACK/AUTOCOMMIT。
• 迁移语句仍应可安全重试，不能依赖本地 backend/install/data/upgrade/ 被发布系统自动发现。

只有任务明确涉及发布包或升级平台时，才把变更接入这条发布迁移链路。

自检

• 全新安装 schema 已包含最终结构。
• 请求链路没有运行时字段探测或静默丢字段。
• 已有库 SQL 确实来自用户明确要求。
• 本地手工 SQL 与发布迁移的来源、路径和提交边界没有混用。
• 发布迁移同时存在 up/down，且两个描述的路径、摘要和大小都经过校验。
• SQL 已在目标 MySQL 版本验证语法与幂等性。