20260914172820
This commit is contained in:
oneao committed
1 parent
c31329d387
commit
549c8bd2eb
38 files changed
+3430
-502
No files matched your search
@@ -1,65 +1,85 @@
|
||||
# FieldNameSync — 模块字段配置迁移工具
|
||||
# 迁移工具
|
||||
|
||||
> **状态：面向 V1 表结构的历史工具。** 本工具操作 `s_module_field` / `s_module_field_list` /
|
||||
> `s_module_field_edit`，与《FMS新系统核心表结构设计V2》的 `s_field` / `s_module_schema`
|
||||
> 不兼容，仅作历史参考；V2 的字段迁移需按新结构重写。
|
||||
`fms-api/tools/migration/` 下的独立 Java 工具，用于在旧库 `G3HY2025` 与新库 `FMS` 之间
|
||||
迁移数据、同步元数据、导出表结构。每个工具都是单文件程序，用 `javac` 手动编译运行，不走 Maven。
|
||||
|
||||
从旧库 `G3HY2025.dbo.s_columnLib` 同步字段配置到新库 `FMS`。
|
||||
## 工具清单
|
||||
|
||||
## 同步的三项内容
|
||||
| 工具 | 状态 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `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_module_field.b_name` | 字段中文名称 |
|
||||
| 2 | `col_Visible` | `s_module_field_list.b_visible` | 列表是否显示（1=显示, 0=隐藏） |
|
||||
| 3 | `col_edit` | `s_module_field_edit.b_visible` | 编辑表单是否显示（1=显示, 0=隐藏） |
|
||||
| 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_viewtable
|
||||
旧库 s_columnLib.col_FieldName = 新库 s_module_field.b_field
|
||||
旧库 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` 对不上时，用第二个命令行参数显式指定旧库表/视图名。
|
||||
|
||||
## 前置条件
|
||||
### 字段名称
|
||||
|
||||
### 1. JDK 21
|
||||
- 旧库有 `col_Caption` 时写入 `s_field.b_name`；为空或该字段在旧库没有记录时**保留原值**。
|
||||
- 只处理 `s_field.b_canuse = 1` 的字段。
|
||||
|
||||
工具使用 Java 文本块语法（`"""`），需要 JDK 21+ 编译。
|
||||
### 显示配置：整份重建
|
||||
|
||||
### 2. mssql-jdbc 驱动
|
||||
view / edit 两份 `b_schema_json` 由旧库名单**完整重新生成**，
|
||||
**不保留**模块管理界面里手工调整的布局。已有非空行时必须加 `--force` 才覆盖，
|
||||
否则工具在写入前整体拒绝退出。
|
||||
|
||||
确保本地 Maven 仓库存在驱动 jar：
|
||||
```
|
||||
%USERPROFILE%\.m2\repository\com\microsoft\sqlserver\mssql-jdbc\13.4.0.jre11\mssql-jdbc-13.4.0.jre11.jar
|
||||
成员资格沿用旧库语义：**旧库标志为 `'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`）：
|
||||
|
||||
```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}]}
|
||||
```
|
||||
|
||||
如果不存在，从项目根目录 `fms-api/` 执行 `mvnw dependency:resolve` 下载。
|
||||
`col_ShowSummary` / `col_DisplayFormat` / `col_CanSearch` / `col_ReadOnly` / `col_DefaultValue` /
|
||||
`col_edit_type` 等旧库列在 V2 的 JSON 契约里没有对应位置（`schemaRender.js` 只读
|
||||
`field` / `width` / `visible` / `options`），本工具不带迁移。
|
||||
|
||||
### 3. 数据库连接
|
||||
`query` 配置行不由本工具处理（旧库没有对应来源）。
|
||||
|
||||
工具硬编码连接 `118.89.70.199:1433`，数据库 `FMS`，直连新旧两库（同一实例）。
|
||||
### 前置条件
|
||||
|
||||
### 4. 新库已有 `s_module_field_edit.b_visible` 列
|
||||
1. **JDK 21**（源码使用文本块语法）。
|
||||
|
||||
如果报 `Invalid column name 'b_visible'`，执行以下 SQL 添加列：
|
||||
```sql
|
||||
ALTER TABLE dbo.s_module_field_edit ADD b_visible int NOT NULL DEFAULT 1;
|
||||
```
|
||||
2. **mssql-jdbc 驱动**，本目录已放了一份 `mssql-jdbc-13.4.0.jre11.jar`。
|
||||
|
||||
### 5. 模块已在 s_module 中注册
|
||||
3. **数据库连接**：工具硬编码连接 `118.89.70.199:1433`，直连 `FMS` 并用三段名访问 `G3HY2025`。
|
||||
|
||||
目标模块的 `b_viewtable` 必须已在 `s_module` 表中配置，且已有 `s_module_field` 记录。
|
||||
4. **模块已注册**：目标模块的 `b_id` 必须在 `s_module` 中存在，且 `s_field` 里已有字段。
|
||||
|
||||
## 编译和运行
|
||||
### 编译和运行
|
||||
|
||||
```bash
|
||||
# 进入迁移工具目录
|
||||
cd fms-api/tools/migration
|
||||
|
||||
# 设置 JDK 21
|
||||
@@ -67,51 +87,93 @@ 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 "%USERPROFILE%\.m2\repository\com\microsoft\sqlserver\mssql-jdbc\13.4.0.jre11\mssql-jdbc-13.4.0.jre11.jar" FieldNameSync.java
|
||||
javac -encoding UTF-8 -cp "mssql-jdbc-13.4.0.jre11.jar" FieldNameSync.java
|
||||
|
||||
# 运行（参数为 s_module.b_viewtable 的值；本例模块注册的是表名 b_port，非视图名 v_b_port）
|
||||
java -cp ".;%USERPROFILE%\.m2\repository\com\microsoft\sqlserver\mssql-jdbc\13.4.0.jre11\mssql-jdbc-13.4.0.jre11.jar" FieldNameSync b_port
|
||||
# 先 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 b_name list edit
|
||||
------------------------------------------------------------------
|
||||
b_id 系统编号 显示 显示
|
||||
b_name 公司全称 显示 显示
|
||||
b_field s_field.b_name col_Caption 进列表 进表单
|
||||
----------------------------------------------------------------------------------------------
|
||||
b_id 系统编号 系统编号 是 是
|
||||
b_ywid b_ywid (null) 否 否
|
||||
...
|
||||
|
||||
=== 1) 字段名称 (col_Caption → b_name) ===
|
||||
更新: 47 条
|
||||
|
||||
=== 2) 列表显示 (col_Visible → s_module_field_list.b_visible) ===
|
||||
更新已有: 50 条
|
||||
新增: 0 条
|
||||
|
||||
=== 3) 编辑显示 (col_edit → s_module_field_edit.b_visible) ===
|
||||
更新已有: 44 条
|
||||
新增: 0 条
|
||||
=== 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 助手调用
|
||||
### 用 AI 助手调用
|
||||
|
||||
如果通过 AI 助手（如 CodeBuddy）执行，告诉 AI 以下步骤即可：
|
||||
|
||||
> 帮我用 FieldNameSync 工具同步视图 `<viewName>` 的字段配置。
|
||||
> 帮我用 FieldNameSync 同步模块 `<moduleId>` 的字段配置。
|
||||
>
|
||||
> 1. 进入 `fms-api/tools/migration/` 目录
|
||||
> 2. 用 JDK 21 编译：`javac -cp "mssql-jdbc 驱动 jar 路径" FieldNameSync.java`
|
||||
> 3. 运行：`java -cp ".;驱动 jar 路径" FieldNameSync <viewName>`
|
||||
> 4. 运行完毕后删除 `FieldNameSync.class` 文件
|
||||
> 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` 大多指向视图，因此视图与表一并导出。
|
||||
|
||||
```bash
|
||||
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 | 已同步 |
|
||||
| `v_b_contact` | 2026-07-30 | 36 | 已同步 |
|
||||
| `b_port` | 2026-08-01 | 13 | 已同步（`s_module.b_viewtable='b_port'` 表名，非 `v_b_port`；更新字段名 8 条，列表/编辑显示各 8 条） |
|
||||
| `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 |
|
||||
Reference in new issue
Block a user