零手工 SQL 自动初始化
CatCRM 内置 Flyway 数据库版本管理引擎。无论是本地开发还是 Docker 容器首次启动，都不需要手工执行任何 SQL 脚本，应用启动时会自动完成建表与初始种子数据写入，保证开发、测试与生产环境严格一致。
- 脚本存放目录：
backend/src/main/resources/db/migration - 脚本命名规则：
V{版本号}__{描述}.sql，版本号唯一且递增，例如新增表结构变更可使用V7__add_contract_signer.sql
内置迁移脚本说明
| 版本 | 脚本文件名 | 核心内容说明 |
|---|---|---|
| V1 | V1__init_schema.sql | 初始化全部 33 张表结构：包含 17 张 sys_ 系统基础表 + 16 张 crm_ 核心业务表 |
| V2 | V2__init_data.sql | 写入初始化数据：系统参数配置、数据字典、权限菜单、默认管理员账号、CRM 动态字段元数据，并重置自增序列 |
| V3 | V3__init_region_data.sql | 写入全国省市区行政区划基础数据（共 3217 条），并重置行政区划序列 |
空库与存量库兼容策略
- 全新空库：首次启动时按
V1 -> V2 -> V3顺序自动执行，数秒内即可得到完整表结构与初始业务数据。 - 存量数据库（已手工建表）：首次启动时会自动打基线（
baseline）到版本3，不会重复执行 V1~V3 建表，此后仅按序执行新增版本脚本（如V4、V5）。 - 人工接管模式：如生产环境有严格的 DBA 审批要求、需要人工执行脚本，只需在配置中设置
spring.flyway.enabled=false，再按版本顺序手工执行 SQL。
重要铁律：禁止修改已发布脚本
警告：已执行过的 Flyway 脚本严禁修改内容！Flyway 在每次启动时会校验已执行脚本的 Checksum（校验和），任何字符改动都会触发
Migration checksum mismatch导致应用启动失败。任何表结构或数据变更，请一律新增递增版本脚本。
如果在开发环境中因调试改动了历史脚本导致报错：
- 开发测试库：直接执行
DROP DATABASE catcrm; CREATE DATABASE catcrm;重建即可。 - 需保留数据的环境：使用 Flyway CLI 执行
flyway repair重新计算并修复校验和。
本地文件存储配置说明
V2__init_data.sql 种子数据中的 STORAGE_CONFIG 默认配置为本地存储（type=0，路径 upload，按进程工作目录解析）：
- Docker 容器内：容器
WORKDIR=/app→ 上传的图片与合同附件自动保存在/app/upload（对应宿主机挂载的~/catcrm/upload）。 - 本地开发启动：在
backend/工作目录启动 → 文件保存在backend/upload。