# 迁移工具 `fms-api/tools/migration/` 下的独立 Java 工具，用于在旧库 `G3HY2025` 与新库 `FMS` 之间 迁移数据、同步元数据、导出表结构。每个工具都是单文件程序，用 `javac` 手动编译运行，不走 Maven。 ## 工具清单 | 工具 | 状态 | 用途 | | --- | --- | --- | | `FieldNameSync.java` | **V2 当前版本** | 从旧库 `s_columnLib` 同步字段名称与显示配置到 `s_field` / `s_module_schema` | | `SchemaDumpMarkdown.java` | 通用 | 导出该实例上任意库的表与视图结构为 Markdown | | `RunSqlFile.java` | 通用 | 在 FMS 库执行 `sql/` 下的建表 / 视图 / 索引脚本（按 GO 分批，单事务） | | `OtherDataProbe.java` | 迁移辅助（只读） | `list` 列出旧库 `b_other_bmfl` 的 65 个字典模块（启用/旧库行数/新库已建），输出 `otherdata-modules.txt`；`tables <表名...>` 导出新旧结构 + 旧库数据样例 | | `OtherDataMigrate.java` | **其他数据迁移** | 导入 `base_otherdata` 下 64 个字典模块的数据（雪花主键）、重建 `b_from`/`b_grade`、转换 `b_othercompany` 引用值，输出映射 `otherdata-id-map.tsv`；支持 `--dry-run` | | `TreePathRepair.java` | 核对 / 修复 | 按 `b_parent_id` 重建树表的 `b_depth` / `b_path`，默认只读报告，`--apply` 才写库 | --- ## FieldNameSync — 字段配置同步（V2） 从旧库 `G3HY2025.dbo.s_columnLib` 同步到新库 `FMS`： | 序号 | 旧库来源 | 新库目标 | 说明 | | --- | --- | --- | --- | | 1 | `col_Caption` | `s_field.b_name` | 字段中文名称 | | 2 | `col_Visible='1'` 的行 | `s_module_schema`（`b_schema_type='view'`）JSON 的 `columns` | 列表列成员 | | 3 | `col_edit='1'` 的行 | `s_module_schema`（`b_schema_type='edit'`）JSON 的 `children` | 表单成员 | | 4 | `col_Width` / `col_Position` | view 节点的 `width` 与顺序 | 列表列宽与排列 | | 5 | `col_edit_position` | edit 节点的顺序 | 表单字段排列 | ### 关联规则 ``` 旧库 s_columnLib.col_TableName = 新库 s_module.b_view_table 旧库 s_columnLib.col_FieldName = 新库 s_field.b_field ``` 两侧按 `Chinese_PRC_CI_AS` 比较，兼容 `v_b_OtherCompany` 这类大小写差异。 `s_module.b_view_table` 对不上时，用第二个命令行参数显式指定旧库表/视图名。 ### 字段名称 - 旧库有 `col_Caption` 时写入 `s_field.b_name`；为空或该字段在旧库没有记录时**保留原值**。 - 只处理 `s_field.b_canuse = 1` 的字段。 ### 显示配置：整份重建 view / edit 两份 `b_schema_json` 由旧库名单**完整重新生成**， **不保留**模块管理界面里手工调整的布局。已有非空行时必须加 `--force` 才覆盖， 否则工具在写入前整体拒绝退出。 成员资格沿用旧库语义：**旧库标志为 `'1'` 的字段才进入对应配置**， 其余字段（标志为 `'0'`、空值、旧库无记录）**直接不写入 JSON**，不写 `visible:false`。 `s_field` 里有、旧库名单里没有的字段同样不进入配置（节点不存在 = 不显示、不参与表单）。 顺序取旧库位置列：view 按 `col_Position`、edit 按 `col_edit_position`，位置缺失的排在最后； view 里备注列（`b_bz`）固定排到最后。 列表列宽取 `col_Width`，未配置时省略 `width` 键（前端按自身默认值渲染）。 生成的 JSON 结构与前端消费侧一致 （见 `fms-vue/src/components/fms-module-common/schemaRender.js`）： ```json view: {"schemaVersion":1,"columns":[{"field":"b_id","width":123},{"field":"b_name","width":122}]} edit: {"schemaVersion":1,"children":[{"field":"b_id","span":24},{"field":"b_name","span":24}]} ``` `col_ShowSummary` / `col_DisplayFormat` / `col_CanSearch` / `col_ReadOnly` / `col_DefaultValue` / `col_edit_type` 等旧库列在 V2 的 JSON 契约里没有对应位置（`schemaRender.js` 只读 `field` / `width` / `visible` / `options`），本工具不带迁移。 `query` 配置行不由本工具处理（旧库没有对应来源）。 ### 前置条件 1. **JDK 21**（源码使用文本块语法）。 2. **mssql-jdbc 驱动**，本目录已放了一份 `mssql-jdbc-13.4.0.jre11.jar`。 3. **数据库连接**：工具硬编码连接 `118.89.70.199:1433`，直连 `FMS` 并用三段名访问 `G3HY2025`。 4. **模块已注册**：目标模块的 `b_id` 必须在 `s_module` 中存在，且 `s_field` 里已有字段。 ### 编译和运行 ```bash cd fms-api/tools/migration # 设置 JDK 21 export JAVA_HOME=/path/to/jdk-21 # Linux/Mac set JAVA_HOME=D:\devtool\jdk\jdk-21 # Windows # 编译（源文件含中文注释，需指定 UTF-8 编码） javac -encoding UTF-8 -cp "mssql-jdbc-13.4.0.jre11.jar" FieldNameSync.java # 先 Dry-run 看清楚会发生什么 java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp ".;mssql-jdbc-13.4.0.jre11.jar" FieldNameSync v_b_othercompany --dry-run # 确认后执行 java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp ".;mssql-jdbc-13.4.0.jre11.jar" FieldNameSync v_b_othercompany # 运行完毕后删除 class 文件 del FieldNameSync*.class ``` > `-Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8` 用于让 Windows 控制台正确显示中文输出，可省略。 选项： | 选项 | 说明 | | --- | --- | | `` | 必填，`s_module.b_id`，例如 `v_b_othercompany` | | `[oldTableName]` | 可选，覆盖旧库表/视图名；缺省用 `s_module.b_view_table` | | `--dry-run` | 只报告不写库，结束时回滚 | | `--skip-schema` | 只同步 `s_field.b_name`，不重建 `s_module_schema` | | `--force` | 允许覆盖已存在且非空的 `s_module_schema` 行 | | `--all-otherdata` | 批量模式：同步 `base_otherdata` 下所有数据模块（不需要 ``，失败跳过继续） | ### 输出示例 ``` 模块: v_b_othercompany（合作伙伴） 类型: data 关联旧库表: v_b_othercompany（取自 s_module.b_view_table） 旧库 s_columnLib: 50 行，去重字段 50 个；当前模块 51 个字段中：进列表 15 个、进表单 41 个 === 同步前 === b_field s_field.b_name col_Caption 进列表 进表单 ---------------------------------------------------------------------------------------------- b_id 系统编号 系统编号 是 是 b_ywid b_ywid (null) 否 否 ... === 1) 字段名称 (col_Caption → s_field.b_name) === 更新: 43 条；旧库无名称、保留原值: 8 条 === 事务已提交 === === 摘要 === s_field.b_name 更新: 43 条 s_module_schema(view): 15 个节点，未进入配置 36 个字段，新增行 s_module_schema(edit): 41 个节点，未进入配置 10 个字段，新增行 提示: 该模块尚无 query 配置行，工具不处理 query，需要时在模块管理中生成。 ``` ### 用 AI 助手调用 > 帮我用 FieldNameSync 同步模块 `` 的字段配置。 > > 1. 进入 `fms-api/tools/migration/` 目录 > 2. 用 JDK 21 编译：`javac -encoding UTF-8 -cp "mssql-jdbc-13.4.0.jre11.jar" FieldNameSync.java` > 3. 先跑 `java -cp ".;mssql-jdbc-13.4.0.jre11.jar" FieldNameSync --dry-run` 核对 > 4. 确认后去掉 `--dry-run` 执行；目标模块已有非空 schema 时需 `--force` > 5. 运行完毕后删除 `FieldNameSync*.class` --- ## SchemaDumpMarkdown — 表结构导出 导出该实例上任意数据库的用户表与视图结构为 Markdown 文档，用于对照旧库 `G3HY2025` 或 新库 `FMS`。新库 `s_module.b_view_table` 大多指向视图，因此视图与表一并导出。 ```bash javac -encoding UTF-8 -cp "mssql-jdbc-13.4.0.jre11.jar" SchemaDumpMarkdown.java # 导出新库 FMS 到指定文件 java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp ".;mssql-jdbc-13.4.0.jre11.jar" SchemaDumpMarkdown "D:\path\FMS表结构.md" FMS # 只导出表，不含视图 java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp ".;mssql-jdbc-13.4.0.jre11.jar" SchemaDumpMarkdown "D:\path\FMS表结构.md" FMS --tables-only ``` 参数：`<输出文件绝对路径>` `[数据库名，默认 G3HY2025]` `[--tables-only]` 输出包含：对象清单（名称/类型/字段数/主键）、各表字段结构（含主键与外键）、视图字段结构。 字段「备注」列留空，供后续补充含义。 --- ## RunSqlFile — 执行 sql 脚本 执行 `sql/` 目录下的脚本。目标库固定取 `config/dbconfigs/G3HD.properties`，执行前校验 catalog 必须是 `FMS`；按 `GO` 把脚本拆成批次，在单个事务中依次执行，任一批失败整体回滚。 ```bash cd fms-api # 先 dry-run 看批次划分 java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp "tools/migration/mssql-jdbc-13.4.0.jre11.jar" \ tools/migration/RunSqlFile.java ../sql/fms_business_contact.sql --dry-run # 确认后执行 java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp "tools/migration/mssql-jdbc-13.4.0.jre11.jar" \ tools/migration/RunSqlFile.java ../sql/fms_business_contact.sql ``` 源码启动模式不产生 `.class` 文件；如需手动编译： ```bash cd fms-api/tools/migration javac -encoding UTF-8 -cp "mssql-jdbc-13.4.0.jre11.jar" RunSqlFile.java ``` > 含「重建」段落（`drop ... if exists`）的脚本会删除同名表及其数据，执行前确认表中数据已不需要。 --- ## TreePathRepair — 树表 b_depth / b_path 核对与修复 `b_parent_id` 是树结构的权威关系，`b_depth` / `b_path` 是派生字段（见《FMS新系统核心表结构设计》1.7）。 本工具按 `b_parent_id` 重算这两列，用于核对和修复派生字段与父子关系不一致的数据。 历史背景：模块管理 / 菜单管理的拖拽排序曾有一处缺陷，会把**根节点** `b_path` 的前导 `/` 抹掉 （`/base/` 被写成 `base/`）并整树落库。前端已修复，本工具用于核对历史数据、必要时重算。 `b_path` 的约定格式形如 `/base/base_otherdata/`（节点编码前后均带 `/`）。 ### 行为 - **默认只读报告，不写库**；确认无误后加 `--apply` 才在单个事务内更新 `b_depth` / `b_path`，失败整体回滚。 - 只更新这两列，`b_parent_id` 与其余字段一律不动；父级不存在的节点按根处理（与前端 `buildTree` 一致）。 - **成环的节点无法派生路径，只报告不修**——父子关系成环是数据问题，需人工先修 `b_parent_id`。 - 报告会区分「只缺前导 `/`」这一缺陷典型症状，并给出变更样例。 ### 用法 ```bash cd fms-api # 只读报告（默认）：核对 s_module / s_menu java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp "tools/migration/mssql-jdbc-13.4.0.jre11.jar" \ tools/migration/TreePathRepair.java # 核对全部四张树表 java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp "tools/migration/mssql-jdbc-13.4.0.jre11.jar" \ tools/migration/TreePathRepair.java --tables s_module,s_menu,b_dept,b_othercompany_category # 确认后执行修复 java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp "tools/migration/mssql-jdbc-13.4.0.jre11.jar" \ tools/migration/TreePathRepair.java --apply # 多机构：指向目标机构的连接配置（默认 config/dbconfigs/G3HD.properties） java -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -cp "tools/migration/mssql-jdbc-13.4.0.jre11.jar" \ tools/migration/TreePathRepair.java --config config/dbconfigs/OTHER.properties ``` 参数： | 参数 | 说明 | | --- | --- | | （无） | 只读报告，不写库 | | `--dry-run` | 同「无参数」，显式表达只读 | | `--apply` | 执行修复（单事务） | | `--tables a,b` | 待核对表，默认 `s_module,s_menu`；可选 `s_module` / `s_menu` / `b_dept` / `b_othercompany_category` | | `--config ` | 连接配置，默认 `config/dbconfigs/G3HD.properties` | > 修复只重算派生字段，全部内容都能由 `b_parent_id` 重新推出，因此可安全重复执行； > 执行后重跑一次只读报告应得到「待更新 0 行」。 --- ## 已有同步记录 | 模块 / 视图 | 同步日期 | 字段数 | 备注 | | --- | --- | --- | --- | | `v_b_othercompany` | 2026-07-30 | 50 | V1 时代（`s_module_field*`，已废弃） | | `v_b_contact` | 2026-07-30 | 36 | V1 时代（`s_module_field*`，已废弃） | | `b_port` | 2026-08-01 | 13 | V1 时代（`s_module_field*`，已废弃） | | `v_b_othercompany` | 2026-09-14 | 51 | V2：改名 43 条、保留原值 8 条；重建 view（15 列，含旧库列宽/顺序）与 edit（41 个字段），未进入配置的字段不写入 JSON | | `v_b_contact` | 2026-09-14 | 36 | V2：改名 28 条、保留原值 8 条；重建 view（19 列）与 edit（19 个字段）。同批新增 `b_contact` / `b_contact_type` 表、`v_b_contact` 视图与模块注册 | | 其他数据（`base_otherdata`） | 2026-09-14 | 668 | 62 张字典表（`sql/fms_business_otherdata.sql`，模块直接查表）、模块注册（`sql/fms_module_otherdata.sql`：根 + 6 个分组 + 64 个数据模块，编码 = 表名）、导入 555 行（`OtherDataMigrate.java`）；`FieldNameSync --all-otherdata --force` 同步字段名与 view/edit 配置（含重命名字段别名 `b_vessel_name`→`b_name`、`b_name_c`→`b_name`），新增通用字段名由注册脚本补齐，旧库无配置的 44 个模块补默认列（名称 + 备注）。`b_from`/`b_grade` 已重建为雪花，其引用转换待 `b_othercompany` 数据迁入后重跑 |