167 lines
11 KiB
Markdown
167 lines
11 KiB
Markdown
# AGENTS.md
|
||
|
||
## 项目定位
|
||
|
||
恒诺迁移工具是一个仅运行于 Windows 的 Oracle 数据库迁移桌面工具。当前维护目标是 `henlo_migration_wpf10/`：WPF + .NET 10，程序集名为“恒诺迁移工具”。工具从源库读取表结构、BOS 配置、存储过程/函数和表数据，将 SQL 保存为本地文本；经用户确认后，再把本地 SQL 执行到目标库。
|
||
|
||
本文是仓库级开发约定。分析、修改和验证默认都以当前 WPF 项目为准，除非任务明确点名旧项目。
|
||
|
||
## 目录边界
|
||
|
||
- `henlo_migration_wpf10/`：当前唯一主程序，优先分析和修改。
|
||
- `henlo_migration/`：旧 .NET Framework 4.8 / WinForm 版本，已废弃；不要把旧版的窗体、AntdUI 或 AutoUpdater.NET 设计套到主程序。
|
||
- `henlo_migration_core10/`：未投入使用的 .NET Core 版本，默认不修改。
|
||
- `hc_preview/`：界面预览或辅助内容，不是主程序源码。
|
||
- `产品部署/`：部署相关资料或产物，只有发布任务才处理。
|
||
- `VELOPACK_MIGRATION.md`、`VELOPACK操作手册.md`：更新与发布背景资料；若与代码冲突，以当前代码和 `pack.bat` 为准。
|
||
|
||
## Git 仓库
|
||
|
||
- 项目远程仓库：`https://gitea.momozhua.site/qiangayi/henlo_migration_wpf10.git`
|
||
- 当前根目录已经初始化为 Git 工作区，默认分支为 `main`，远程名为 `origin`。
|
||
- 可以使用 `git status`、`git diff` 和提交历史检查改动。不要使用 `git reset --hard`、强制推送或其他会丢失本地/远程改动的命令。
|
||
- fetch、pull、commit、push 等会改变工作区、历史或远程状态的操作必须符合用户当前任务；上传远程仓库需要明确授权。
|
||
|
||
## 当前技术基线
|
||
|
||
- 项目文件：`henlo_migration_wpf10/henlo_migration_wpf10.csproj`
|
||
- 目标框架：`net10.0-windows`
|
||
- UI：WPF + HandyControl 3.5.1
|
||
- MVVM：手写 `INotifyPropertyChanged`/命令实现，引用 CommunityToolkit.Mvvm 8.3.2，但当前主 ViewModel 未使用其源生成器
|
||
- Oracle 访问：SqlSugar 5.1.4.157 + Oracle.ManagedDataAccess.Core 23.5.0
|
||
- 配置解析：ini-parser 2.5.2
|
||
- JSON：Newtonsoft.Json 13.0.3
|
||
- 自动更新：Velopack 0.0.1298
|
||
- 当前版本号：以 `.csproj` 的 `<Version>` 为唯一事实来源，不在本文硬编码版本
|
||
- Nullable：项目设置为 `<Nullable>disable</Nullable>`，源码中仍存在 `?` 注解，因此构建有既有 `CS8632` 警告
|
||
|
||
## 主程序结构
|
||
|
||
### 启动与界面
|
||
|
||
- `App.xaml`：应用资源、HandyControl 主题和 `MainViewModel` 资源注册；启动页是 `Views/HomeWindow.xaml`。
|
||
- `App.xaml.cs`：Velopack 初始化、后台/手动更新、更新前后 `data/` 与 `pre/` 备份恢复、全局异常日志。
|
||
- `Views/HomeWindow.xaml`：单窗口主界面，包含四个迁移 Tab、连接状态、SQL 编辑区和批量操作。
|
||
- `Views/HomeWindow.xaml.cs`：只处理窗口关闭和手动检查更新等窗口事件。
|
||
- `Views/ConnectionDialog.*`：源库/目标库连接配置与测试。
|
||
- `Views/ErrorDialog.*`：错误详情展示和复制。
|
||
- `Behaviors/ClickToCopyBehavior.cs`、`Converters/StatusColorConverter.cs`：界面辅助行为与状态颜色转换。
|
||
|
||
### 状态与编排
|
||
|
||
- `ViewModels/MainViewModel.cs`：主状态容器和命令编排；初始化四个 `TabServices`，管理数据库连接、单行/批量读写、SQL 编辑与断点续写。
|
||
- `Models/TableRowModel.cs`：每个迁移对象的名称、所属 Tab、读写状态。
|
||
- `Enums/`：Tab、状态、工作类型和输出扩展名枚举。
|
||
|
||
### 业务与数据访问
|
||
|
||
- `Services/TabConfig.cs` / `ITabConfig.cs`：将 Tab、索引文件、输出后缀和读取委托组合成配置。
|
||
- `Services/TabServices.cs`：索引列表加载/保存、单行读写、排序、删除和状态切换。
|
||
- `Services/DbServices.cs`：Oracle SQL 的提取与执行核心：
|
||
- `GetTableSql`：读取表 DDL、注释、主外键、唯一键和索引；
|
||
- `GetTableBos`：读取 BOS 配置；
|
||
- `GetPrcSql` / `GetAllPrc`：读取存储过程或函数源码；
|
||
- `GetTableData`：生成表数据 INSERT SQL；
|
||
- `ExecuteCreate`：按 `\n/` 分隔 SQL，在目标库逐条执行并检查 `USER_ERRORS`；
|
||
- `PreProcess`：在源库执行 `pre/` 下全部脚本。
|
||
- `Common/SqlSugarHelper.cs`：维护 `orig`（源库）和 `dest`（目标库）两个 SqlSugar 连接。
|
||
- `Common/SysConfig.cs`：读取和写入运行目录下的 `config.ini`。
|
||
- `Common/CommonHelper.cs`：运行目录、`data/`、`data/from/`、`pre/` 路径及文本读写。
|
||
|
||
## 真实数据流
|
||
|
||
四个 Tab 的映射由 `MainViewModel` 构造函数定义：
|
||
|
||
| Tab | 索引文件 | 内容文件 | 源库读取方法 |
|
||
| --- | --- | --- | --- |
|
||
| 表配置 | `data/from/table.txt` | `data/{对象名}_creat.txt` | `DbServices.GetTableSql` |
|
||
| BOS 配置 | `data/from/bos.txt` | `data/{对象名}_bos.txt` | `DbServices.GetTableBos` |
|
||
| 存储过程 | `data/from/prc.txt` | `data/{对象名}_prc.txt` | `DbServices.GetPrcSql` |
|
||
| 表数据 | `data/from/data.txt` | `data/{对象名}_data.txt` | `DbServices.GetTableData` |
|
||
|
||
读取流程：索引项 -> 调用源库读取委托 -> 生成 SQL 文本 -> 保存到 `data/` -> 更新读取状态并显示内容。
|
||
|
||
写入流程：索引项 -> 读取对应 `data/*_{后缀}.txt` -> `DbServices.ExecuteCreate` -> 在目标库执行 -> 更新写入状态。批量写入遇到第一条失败即停止，并在内存中记录断点；断点不会跨进程持久化。
|
||
|
||
删除列表项会同时删除对应内容文件。调整顺序会立即覆盖索引文件。新增对象名会被转为小写，数据库读取时再按需要转大写。
|
||
|
||
## 配置和运行时文件
|
||
|
||
- `config.ini` 保存源库和目标库的 IP/服务名、用户名、密码。当前实现是明文读写，不要把注释或 UI 文案误当成加密能力。
|
||
- 不要在日志、回答、补丁或测试输出中展示真实连接串和密码。
|
||
- 修改或发布时不要用样例配置覆盖用户现有 `config.ini`。
|
||
- `data/` 和 `pre/` 是用户可编辑、更新时需要保留的运行数据；不要无故清空、批量改名或删除。
|
||
- `error.log` 是全局异常日志，`execute_log.txt` 记录目标库执行的 SQL；两者都是运行时文件，排查时可能含敏感业务信息。
|
||
- `bin/`、`obj/`、`publish/`、`releases/`、`.vs/` 是构建、IDE 或发布产物。不要手工修改其中的 DLL、EXE、PDB、NuGet 包或生成源码。
|
||
- `*.csproj.Backup*.tmp`、`_build*`、`_make_pack.bat`、`_write_pack.ps1`、`_debug_encoding.ps1` 是历史/辅助文件；正常构建和发布不要以它们为权威入口。
|
||
|
||
## 开发约定
|
||
|
||
- 保持现有命名空间 `henlo_migration` 和现有目录分层。
|
||
- UI 状态、命令和业务编排放在 `MainViewModel`；可绑定的属性变更必须触发 `OnPropertyChanged`，命令可用性变化时同步触发 `RaiseCanExecuteChanged`。
|
||
- XAML 负责布局、样式和绑定；code-behind 仅保留必须依赖 Window/控件事件的逻辑。
|
||
- 通用 Oracle 提取/执行逻辑放在 `DbServices`，不要在 View 或 ViewModel 中复制 SQL。
|
||
- 新增 Tab 能力时同时检查 `TabsEnum`、`CodeExt`、`TabConfig`、`MainViewModel` 映射、XAML 绑定、索引文件复制规则和更新备份范围。
|
||
- 耗时数据库调用不得阻塞 UI 线程；沿用现有异步命令和 `Task.Run` 边界，UI 更新通过 WPF Dispatcher 或正常 await 回到 UI 上下文。
|
||
- 保持 SQL 文件的 Oracle 分隔约定：`DbServices.SplitStatements` 依赖换行后的 `/`（实际分隔符为 `\n/`）。修改生成 SQL 时必须验证普通 DDL、PL/SQL 块和末尾分隔符。
|
||
- 数据库对象名和用户数据不能直接拼入任意 SQL。查询参数优先使用 `SugarParameter`；确需生成 DDL 时必须处理标识符和字符串转义。
|
||
- 不要静默吞掉新异常。UI 可展示友好提示，但排障信息应保留在错误对话框或日志中；修改现有空 `catch` 时要评估用户体验。
|
||
- 不做与任务无关的大规模格式化、Nullable 改造、依赖升级或旧项目同步。
|
||
|
||
## 数据库安全边界
|
||
|
||
源库和目标库不是等价环境：
|
||
|
||
- `Get*` 方法通常查询源库；`ExecuteCreate` 明确写目标库。
|
||
- `PreProcess` 会在源库执行 `pre/` 下的 SQL/PLSQL，虽然名为预处理，但不是只读操作。
|
||
- 连接按钮会把界面中的连接信息写回 `config.ini`，并重建同时包含源库和目标库的 SqlSugarScope。
|
||
- 界面的“断开”当前只更新连接状态，并未释放或关闭底层连接对象。
|
||
|
||
除非用户明确要求并确认数据库、对象和影响范围，否则不要连接真实数据库、执行预处理、执行写入、清理数据或测试破坏性 SQL。需要验证数据库写入逻辑时优先使用代码审查、可控测试库或事务化的最小复现。真实目标库写入前必须提醒备份并确认权限。
|
||
|
||
## 构建与验证
|
||
|
||
在仓库根目录运行：
|
||
|
||
```powershell
|
||
dotnet restore .\henlo_migration_wpf10\henlo_migration_wpf10.csproj
|
||
dotnet build .\henlo_migration_wpf10\henlo_migration_wpf10.csproj -c Debug
|
||
```
|
||
|
||
仅在依赖已经恢复且不希望访问包源时可用：
|
||
|
||
```powershell
|
||
dotnet build .\henlo_migration_wpf10\henlo_migration_wpf10.csproj -c Debug --no-restore
|
||
```
|
||
|
||
当前没有测试项目。最低验证要求：
|
||
|
||
1. 所有 C#/XAML 修改至少执行一次主项目构建。
|
||
2. 仅文档修改可不构建，但要重新读取文件检查 Markdown、路径和命令。
|
||
3. XAML/绑定修改除构建外，应在 Windows 上启动应用，检查四个 Tab、连接弹窗、按钮可用性和错误弹窗；不要因此连接生产库。
|
||
4. SQL 生成/拆分修改需用不含真实数据的代表性 SQL 验证表 DDL、注释、约束、PL/SQL 和 INSERT。
|
||
5. 更新逻辑修改需分别考虑普通 `dotnet run`（非 Velopack 安装）和 Velopack 安装态。
|
||
|
||
既有 `CS8632` 警告不是本次修改自动引入的错误，但不得新增编译错误。若任务专门处理 Nullable，应统一决定启用 Nullable 还是移除注解，不要零散压制警告。
|
||
|
||
本地调试可运行：
|
||
|
||
```powershell
|
||
dotnet run --project .\henlo_migration_wpf10\henlo_migration_wpf10.csproj
|
||
```
|
||
|
||
启动会读取或创建运行目录下的配置，并可能尝试初始化更新检查；不适合无界面的 CI 验证。
|
||
|
||
## 版本与发布
|
||
|
||
- 版本号只修改 `.csproj` 中的 `<Version>`，必须单调递增；显示版本来自程序集元数据。
|
||
- 正式发布入口是 `henlo_migration_wpf10/pack.bat`。脚本会清理 `publish/`、执行 `dotnet publish -c Release --self-contained false -r win-x64`，再调用 `vpk pack --noInst` 输出到 `releases/`。
|
||
- `pack.bat` 依赖本机 `dotnet`、`vpk` 和 Windows 批处理环境；不要把“构建通过”等同于“打包通过”。
|
||
- 发布是显式任务。未经要求不要运行打包、删除发布目录、修改版本号或上传更新服务器。
|
||
- 打包后核对便携 ZIP、full/delta nupkg、`RELEASES`/JSON 元数据以及实际版本号。上传服务器属于外部写操作，必须另行获得明确授权。
|
||
- 若修改运行时必需文件，检查 `.csproj` 的 `CopyToOutputDirectory` 规则和 `App.xaml.cs` 的更新备份/恢复范围。
|
||
|
||
## 完成任务时的交付说明
|
||
|
||
简要说明：修改了什么、影响哪一层、执行了哪些验证、构建是否有错误/警告、是否因缺少 Oracle 测试库或 Velopack 安装态而存在未验证项。不要声称已验证真实数据库迁移，除非确实在明确授权的测试环境完成。
|