workspace/code/fms/fms-api/tools/migration/README.md

迁移工具

fms-api/tools/migration/ 下的独立 Java 工具，用于在旧库 G3HY2025 与新库 FMS 之间 迁移数据、同步元数据、导出表结构。每个工具都是单文件程序，用 javac 手动编译运行，不走 Maven。

工具清单

工具	状态	用途
FieldNameSync.java	V2 当前版本	从旧库 s_columnLib 同步字段名称与显示配置到 s_field / s_module_schema
SchemaDumpMarkdown.java	通用	导出该实例上任意库的表与视图结构为 Markdown
OtherDataMigration.java	V1 历史工具，未改造，勿用于 V2	面向 V1 表结构（s_module_field / s_module_field_list / s_module_field_edit）与 b_other_bmfl 旧树结构，V2 下这些表已不存在，仅作历史参考

---

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，位置缺失的排在最后。 列表列宽取 col_Width，未配置时省略 width 键（前端按自身默认值渲染）。

生成的 JSON 结构与前端消费侧一致 （见 fms-vue/src/components/fms-module-common/schemaRender.js）：

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 里已有字段。

编译和运行

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 控制台正确显示中文输出，可省略。

选项：

选项	说明
<moduleId>	必填，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 行

输出示例

模块: 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 同步模块 <moduleId> 的字段配置。

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 <moduleId> --dry-run 核对
4. 确认后去掉 --dry-run 执行；目标模块已有非空 schema 时需 --force
5. 运行完毕后删除 FieldNameSync*.class

---

SchemaDumpMarkdown — 表结构导出

导出该实例上任意数据库的用户表与视图结构为 Markdown 文档，用于对照旧库 G3HY2025 或 新库 FMS。新库 s_module.b_view_table 大多指向视图，因此视图与表一并导出。

javac -encoding UTF-8 -cp "mssql-jdbc-13.4.0.jre11.jar" SchemaDumpMarkdown.java

# 导出新库 FMS 到指定文件
java -Dstdout.encoding=UTF-8 -cp ".;mssql-jdbc-13.4.0.jre11.jar" SchemaDumpMarkdown "D:\path\FMS表结构.md" FMS

# 只导出表，不含视图
java -Dstdout.encoding=UTF-8 -cp ".;mssql-jdbc-13.4.0.jre11.jar" SchemaDumpMarkdown "D:\path\FMS表结构.md" FMS --tables-only

参数：<输出文件绝对路径> [数据库名，默认 G3HY2025] [--tables-only]

输出包含：对象清单（名称/类型/字段数/主键）、各表字段结构（含主键与外键）、视图字段结构。 字段「备注」列留空，供后续补充含义。

已有同步记录

模块 / 视图	同步日期	字段数	备注
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