247 lines
11 KiB
Markdown
247 lines
11 KiB
Markdown
# 恒诺迁移工具
|
||
|
||
> Oracle 数据库迁移辅助工具，支持表结构、存储过程、BOS 配置的读取与写入
|
||
|
||
## 产品概述
|
||
|
||
恒诺迁移工具是一款基于 WPF + .NET 10 的 Windows 桌面应用，用于简化 Oracle 数据库对象（表、存储过程、BOS 配置）的跨库迁移工作。
|
||
|
||
## 主要功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **表结构迁移** | 读取源库表结构（DDL）、表注释、字段注释、主键/外键/索引，写入目标库 |
|
||
| **表字段迁移** | 按 `TABLE.COLUMN` 读取单个物理字段；目标字段不存在时新增，已存在时跳过 |
|
||
| **存储过程迁移** | 读取/写入存储过程和函数源码 |
|
||
| **BOS 配置迁移** | 读取 BOS 表配置写入目标库 |
|
||
| **BOS 字段配置迁移** | 按 `TABLE.COLUMN` 补充目标物理字段并迁移字段配置、限定值和引用元数据 |
|
||
| **表数据迁移** | 支持表数据的导出/导入 |
|
||
| **自动更新** | 支持通过私有服务器 Velopack 自动检查更新 |
|
||
| **断点续写** | 批量写入失败后，下次从失败行继续，无需从头开始 |
|
||
|
||
## 技术架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ WPF (UI Layer) │
|
||
│ HomeWindow.xaml ← MVVM → MainViewModel.cs │
|
||
└─────────────────────┬───────────────────────────────────┘
|
||
│
|
||
┌─────────────────────▼───────────────────────────────────┐
|
||
│ Services (业务层) │
|
||
│ ├─ DbServices.cs - 核心 DDL 操作 │
|
||
│ ├─ TabServices.cs - Tab 数据读写 │
|
||
│ └─ TabConfig.cs - Tab 配置 │
|
||
└─────────────────────┬───────────────────────────────────┘
|
||
│
|
||
┌─────────────────────▼───────────────────────────────────┐
|
||
│ Data Access (数据层) │
|
||
│ └─ SqlSugar ORM + Oracle.ManagedDataAccess │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
henlo_migration_wpf10/
|
||
├── App.xaml / App.xaml.cs # WPF 入口，自动更新，全局异常
|
||
├── Common/ # 公共工具
|
||
│ ├── CommonHelper.cs # 文件读写、路径配置
|
||
│ ├── SqlSugarHelper.cs # 数据库连接管理
|
||
│ └── SysConfig.cs # INI 配置读写
|
||
├── Services/ # 业务服务
|
||
│ ├── DbServices.cs # 核心：Oracle DDL 读写
|
||
│ ├── TabServices.cs # Tab 数据读写
|
||
│ └── TabConfig.cs # Tab 配置
|
||
├── ViewModels/ # MVVM
|
||
│ └── MainViewModel.cs # 主 ViewModel
|
||
├── Views/ # UI
|
||
│ ├── HomeWindow.xaml # 主窗口
|
||
│ └── ConnectionDialog.xaml # 连接配置
|
||
├── data/from/ # 索引文件（table.txt 等）
|
||
├── pre/ # 运行时辅助过程/函数脚本（BOS 读取缺失时自动安装）
|
||
├── pack.bat # Velopack 打包脚本
|
||
└── henlo_migration_wpf10.csproj
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 类别 | 技术 |
|
||
|------|------|
|
||
| 框架 | WPF / .NET 10.0 |
|
||
| ORM | SqlSugar 5.1.4 |
|
||
| 数据库 | Oracle (ODP.NET) |
|
||
| UI 库 | HandyControl 3.5.1 |
|
||
| MVVM | CommunityToolkit.Mvvm 8.3 |
|
||
| 自动更新 | Velopack 0.0.1298 |
|
||
|
||
## 运行环境
|
||
|
||
- **操作系统**：Windows 10/11 (x64)
|
||
- **.NET**：.NET 10.0 Runtime（或 Self-contained 发布）
|
||
- **数据库**：Oracle 11g R2 及以上
|
||
- **.NET SDK**：10.0+（仅开发时需要）
|
||
|
||
## 使用说明
|
||
|
||
### 1. 初始化配置
|
||
|
||
首次使用需配置源库和目标库的连接信息：
|
||
|
||
- **源库**：读取数据的数据库
|
||
- **目标库**：写入数据的数据库
|
||
|
||
连接信息保存在用户配置持久目录的 `config.ini` 中。Velopack 安装态或便携态位于与 `Update.exe` 同级的根目录，普通 `dotnet run`/`publish` 运行时位于程序目录。发布包不携带该文件，首次运行会创建空配置。
|
||
|
||
从旧版本更新时，新程序会在 Velopack 删除旧 `current/` 备份前迁移原 `current/config.ini`；后续更新只替换 `current/`，不会覆盖根目录中的配置。
|
||
|
||
### 2. 索引文件
|
||
|
||
索引文件位于 `data/from/` 目录：
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `table.txt` | 表结构列表 |
|
||
| `table_field.txt` | 物理表字段列表，每行使用 `TABLE.COLUMN` 格式 |
|
||
| `bos.txt` | BOS 配置列表 |
|
||
| `bos_field.txt` | BOS 单字段配置列表，每行使用 `TABLE.COLUMN` 格式 |
|
||
| `prc.txt` | 存储过程/函数列表 |
|
||
| `data.txt` | 表数据列表 |
|
||
|
||
每行一个对象名称，读取数据库时会自动更新内容。表字段生成
|
||
`data/{表名}.{字段名}_table_field.txt`，只读取源库物理表字段和字段注释，不检查 BOS 是否维护该字段；写入时目标表不存在会报错，目标字段已存在则跳过，否则按源字段类型、默认值、可空性和注释新增。
|
||
|
||
BOS 单字段配置生成
|
||
`data/{表名}.{字段名}_bos_field.txt`；源库缺少单字段读取过程时，程序会从
|
||
`pre/hmig_get_table_bos_field_31.prc` 自动安装后再读取。
|
||
|
||
单字段配置写入时，目标库缺少的限定值组和限定值会自动补充；引用字段只做存在性和唯一性检查，不存在或不唯一时停止并报错。
|
||
BOS 单字段读取会先解析 `AD_TABLE.REALTABLE_ID`：未设置时使用原 BOS 表名，已设置时沿映射找到最终实际表名（支持多级映射，缺失、不唯一或循环引用时报错）。物理字段读取和目标库写入均使用实际表名，BOS 配置仍按原 BOS 表名迁移。
|
||
只有实际对象是普通物理表且源字段存在时，才生成 `ALTER TABLE ... ADD`：写入前检查目标实际表字段，已存在则跳过物理 DDL，不存在才新增；目标实际表不存在或为视图/物化视图时报错。源普通视图、物化视图和没有物理字段的 BOS 计算字段仅导出 BOS 配置，不生成物理 DDL。独立“表字段”页签不受此 BOS 映射规则影响。
|
||
|
||
### 3. 基本操作流程
|
||
|
||
```
|
||
1. 配置源库/目标库连接
|
||
2. 点击「读取」按钮 → 从源库读取对象定义，保存到文件
|
||
3. 在右侧编辑区查看/修改代码
|
||
4. 点击「写入」或「批量写入」→ 写入目标库
|
||
```
|
||
|
||
### 4. 批量写入断点续写
|
||
|
||
当批量写入过程中某行失败：
|
||
- 记录失败行的索引（断点）
|
||
- 按钮显示「继续写入」
|
||
- 修复问题后再次点击「继续写入」，从失败行继续
|
||
- 全部成功后自动重置断点
|
||
|
||
### 5. 自动更新
|
||
|
||
支持通过私有服务器自动检查更新（基于 Velopack）：
|
||
|
||
- 应用启动时自动检查更新
|
||
- 也可手动点击「检查更新」按钮
|
||
- 检测到新版本后，下载并自动安装，重启后生效
|
||
- 更新过程中用户数据（data/、pre/）会自动备份并恢复
|
||
|
||
## 版本管理
|
||
|
||
### 版本号来源
|
||
|
||
版本号**唯一数据源**是 `henlo_migration_wpf10.csproj` 中的 `<Version>` 标签：
|
||
|
||
```xml
|
||
<PropertyGroup>
|
||
<Version>1.0.15</Version>
|
||
<AssemblyVersion>1.0.15</AssemblyVersion>
|
||
</PropertyGroup>
|
||
```
|
||
|
||
编译时 MSBuild 自动将版本号写入 `Version.ini`，程序启动时读取并显示在标题栏。
|
||
|
||
### 版本号命名规范
|
||
|
||
| 场景 | 规则 | 示例 |
|
||
|------|------|------|
|
||
| Bug 修复 | 递增 patch | 1.0.15 → 1.0.16 |
|
||
| 新增功能（向下兼容） | 递增 minor | 1.0.15 → 1.1.0 |
|
||
| 破坏性变更 | 递增 major | 1.0.15 → 2.0.0 |
|
||
|
||
**建议**：日常维护使用 patch 版本，小功能用 minor 版本。
|
||
|
||
## 发布流程
|
||
|
||
### 第一步：确认版本号
|
||
|
||
1. 打开 `henlo_migration_wpf10.csproj`
|
||
2. 确认或修改 `<Version>` 标签为新版本号
|
||
3. 建议同步修改 `Version.ini` 中的版本号（保持一致）
|
||
|
||
> ⚠️ 版本号只能递增。Velopack 根据版本号判断是否需要更新。
|
||
|
||
### 第二步：本地打包
|
||
|
||
在项目根目录双击运行 `pack.bat`：
|
||
|
||
```bash
|
||
# pack.bat 自动完成以下步骤：
|
||
# 1. 从 csproj 读取 <Version>
|
||
# 2. dotnet publish Release 版本
|
||
# 3. 创建 data/ 目录结构（.gitkeep 占位）
|
||
# 4. vpk pack 打包为 nupkg
|
||
# 5. 输出到 releases/ 目录
|
||
```
|
||
|
||
打包产物在 `releases/` 目录：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `henlo_migration-win-Portable.zip` | 便携版压缩包，直接分发给用户 |
|
||
| `henlo_migration-<版本>-full.nupkg` | Velopack 更新包，上传到服务器 |
|
||
| `RELEASES` | Velopack 更新元数据文件，随 nupkg 一起上传 |
|
||
|
||
### 第三步：上传到更新服务器
|
||
|
||
将以下三个文件上传到服务器对应目录（当前配置：`http://zjhenlo.henlo.net:8878/henlo_migration/auto_update/`）：
|
||
|
||
1. `henlo_migration-<版本>-full.nupkg`
|
||
2. `RELEASES`
|
||
3. `henlo_migration-win-Portable.zip`（可选，用户可直接下载这个完整包）
|
||
|
||
> ⚠️ 必须同时上传 `RELEASES` 文件，Velopack 依赖它判断版本信息。
|
||
|
||
### 第四步：通知用户更新
|
||
|
||
用户端应用会在启动时自动检测到新版本，弹出更新提示。
|
||
|
||
如需手动触发测试更新，可删除程序目录下的 `.velopack` 缓存文件夹后重启。
|
||
|
||
## 注意事项
|
||
|
||
- 写入前请确认目标库表是否存在，工具不会自动建表（表结构 DDL 除外）
|
||
- 批量写入失败时会停止，后续行不会被处理
|
||
- 索引文件修改后需重新读取才能生效
|
||
- 便携版数据（data/、pre/）在更新时自动备份恢复，无需手动迁移
|
||
|
||
## 常见问题
|
||
|
||
**Q: 写入时报 ORA-00922 错误？**
|
||
A: 可能是表名或列名使用了 Oracle 保留字，需要加双引号。工具已自动处理大部分情况。
|
||
|
||
**Q: 如何只更新部分行？**
|
||
A: 使用上下箭头调整行的顺序，或使用「移到顶部」功能调整优先级。
|
||
|
||
**Q: 索引文件在哪里？**
|
||
A: `data/from/` 目录下。
|
||
|
||
**Q: 更新后用户数据会丢失吗？**
|
||
A: 不会。Velopack 更新前会自动将 data/ 和 pre/ 备份到 %TEMP%，更新后恢复。
|
||
|
||
**Q: 如何强制重新检测更新？**
|
||
A: 删除程序目录下的 `.velopack` 文件夹，然后重启应用。
|
||
|
||
## 许可证
|
||
|
||
内部使用工具。
|