369 lines
20 KiB
Markdown
369 lines
20 KiB
Markdown
# Uft30ChangeCode 使用手册
|
||
|
||
| 文档信息 | 内容 |
|
||
| --- | --- |
|
||
| 软件名称 | Uft30ChangeCode（UF20 → UFT3 转码工具） |
|
||
| 手册版本 | V1.6.0 |
|
||
| 更新日期 | 2026-09-14 |
|
||
| 适用对象 | 使用本工具进行代码转码的开发/维护人员 |
|
||
|
||
---
|
||
|
||
## 1. 软件简介
|
||
|
||
Uft30ChangeCode 是一款桌面端 UF20 → UFT3 代码转码工具，主要提供：
|
||
|
||
- **业务转码**：**全量转码**（LS_ 功能清单式整体转码）与**按需转码**（非 LS 功能，支持单文件/递归两种模式）两个工作台；
|
||
- **代码检索**：查看功能的调用链路（向上调用方、向下被调），支持导出调用文件与链路文本；
|
||
- **功能查询**：检索 UF20 / UFT3 功能元数据，支持**多关键词批量查询**（逗号/空格分隔）；UF20 查询结果可双击/右键**一键加入**转码清单，UFT3 仅用于查询核对；
|
||
- **数据映射**：维护 UF20 → UFT3 的表替换、函数替换对照表；
|
||
- **元数据更新**：解析 UF20/UFT3 源码，建立功能索引缓存（首次使用前必须执行）。
|
||
|
||
## 2. 运行环境
|
||
|
||
| 项目 | 要求 |
|
||
| --- | --- |
|
||
| 操作系统 | Windows 10/11（64 位） |
|
||
| 运行库 | Qt 6.6.2 运行库（随部署包提供） |
|
||
| 磁盘权限 | 对安装目录及源码目录具有读写权限 |
|
||
|
||
## 3. 安装与启动
|
||
|
||
1. 将部署包解压到任意目录（建议路径不含中文与空格）；
|
||
2. 确认目录下包含 `Uft30ChangeCode.exe` 与 `uf2touft3\config\` 配置目录；
|
||
3. 双击 `Uft30ChangeCode.exe` 启动，主界面左侧为功能导航栏。
|
||
|
||
> **首次使用必读**：请先在底部"设置"中配置 UFT30/UF20 项目环境路径（见 §5.5），再到"元数据更新"页执行一次元数据更新（见 §5.1）。否则各页面的"是否存在"判断与功能查询均不可用。
|
||
|
||
## 4. 界面总览
|
||
|
||
启动后左侧导航栏包含以下页面：
|
||
|
||
| 导航项 | 用途 |
|
||
| --- | --- |
|
||
| 功能转码 → 业务转码 | 全量转码与按需转码工作台（页内 Tab 切换） |
|
||
| 功能转码 → 代码检索 | 功能调用链路查询与导出 |
|
||
| 功能查询 → UF20功能查询 | 检索 UF20 功能（支持批量关键词），双击/右键一键加入转码清单 |
|
||
| 功能查询 → UFT3功能查询 | 检索 UFT3 功能元数据（仅查询核对，不加入清单） |
|
||
| 数据映射 → 表替换 | 维护 UF20 → UFT3 表名映射 |
|
||
| 数据映射 → 函数替换 | 维护 UF20 → UFT3 函数名映射 |
|
||
| 元数据更新 | 解析源码、构建/刷新元数据缓存 |
|
||
| 设置（底部） | 项目环境路径与主题配置 |
|
||
| 帮助 / 关于（底部） | 在线帮助、版本信息 |
|
||
|
||
## 5. 功能操作详解
|
||
|
||
### 5.1 元数据更新（首次使用必做）
|
||
|
||
**前提**：元数据更新按"设置"页配置的项目环境路径扫描源码，请先完成 §5.5 的路径配置。
|
||
|
||
**操作步骤：**
|
||
|
||
1. 左侧导航进入 **元数据更新**；
|
||
2. 页面分为 **UFT30更新范围** 与 **UF20更新范围** 两个卡片，勾选需要更新的元数据项（默认全选）：
|
||
- UFT30：数据类型、标准字段、表结构、接口数据；
|
||
- UF20：数据类型、标准字段、标准错误号、接口数据、常量、菜单功能、模块、表结构；
|
||
3. 可用 **全选 / 全不选** 按钮快速调整勾选范围；
|
||
4. 点击 **更新UFT30** 或 **更新UF20**，页面显示进度与当前处理项；
|
||
5. 等待完成提示后，再使用其他功能页面。
|
||
|
||
**选项说明：**
|
||
|
||
- **增量快速跳过**：增量更新先对比源码目录整体修改时间，源码无任何变化时秒级完成，不再逐文件重复扫描；
|
||
- **强制全量更新**（进度条右上角复选框）：默认增量更新，仅重新处理有变化的文件；勾选后将重新扫描并解析全部接口文件、重建增量缓存，耗时较久，勾选时需二次确认；
|
||
- 源码变更后请重新执行更新，保证索引与实际代码一致；
|
||
- 更新过程在后台线程执行，界面不会卡死。
|
||
|
||
### 5.2 功能转码
|
||
|
||
#### 5.2.1 业务转码
|
||
|
||
业务转码页顶部通过 Tab 切换 **全量转码** / **按需转码** 两个工作台。
|
||
|
||
> **任务互斥**：任一 Tab 转换期间，另一 Tab 的"开始转换"按钮被禁用并提示等待，避免并发冲突。
|
||
|
||
##### 5.2.1.1 全量转码
|
||
|
||
**说明**：全量转码仅支持 **LS_ 开头**的功能（"内存交易"改造范围），按清单对功能进行整体转码。清单保存在 `cust.json` 的 `convert.dir` 节点（见 §6.1）。
|
||
|
||
**表格列**：`UF20函数名` | `是否存在` | `操作`（行尾编辑按钮）。
|
||
|
||
- "是否存在"显示 **否**：说明元数据未更新或该功能在 UF20 元数据中检索不到（见 §7 FAQ）；
|
||
- 每次显示页面时自动刷新"是否存在"列。
|
||
|
||
**操作步骤：**
|
||
|
||
1. 切到 **全量转码** Tab；
|
||
2. 点击 **添加**，弹窗内**每行输入一个** LS_ 函数名（支持批量粘贴）；输入非 LS 函数将被拒绝，并提示切换到"按需转码"；
|
||
3. 也可在 **UF20功能查询** 中双击或右键选中 LS_ 功能直接加入（见 §5.3.1）；
|
||
4. 点击行尾编辑按钮可修改函数名；**删除选中** / **清空列表**（二次确认）维护清单；
|
||
5. 点击 **开始转换**，进度条与状态文字显示转换进度；转换中按钮变为 **停止转换**，可随时点击终止任务。
|
||
|
||
**清单同步**：手工编辑 `cust.json` 保存后约 0.3 秒内界面自动刷新（文件监视 + 防抖），程序与手工编辑双向同步。
|
||
|
||
##### 5.2.1.2 按需转码
|
||
|
||
**说明**：按需转码针对**非 LS 功能**转码，支持**单文件转码**与**递归转码**两种模式，转码范围不包含核心文件、module 模块文件。
|
||
|
||
- **非递归模式**：仅对目标文件本身执行转码，不会处理该文件内调用的函数；
|
||
- **递归模式**：转码目标文件的同时，自动对文件中所调用的关联函数一并完成转码。
|
||
|
||
**添加功能（三种方式）：**
|
||
|
||
- **方式一（推荐）**：进入 **UF20功能查询**，双击或右键目标非 LS 函数（支持多选后右键批量加入）→ 弹窗提示"已将 N 个功能加入**按需转码**"；
|
||
- **方式二**：按需转码 Tab 点击 **添加**，弹窗内每行输入一个函数短名（如 `AS_xxx`）；误带 `.service_design` 等后缀会自动剥离；新增功能递归模式默认 **否**；若输入 LS_ 开头函数仅给出提示（建议放入全量转码），不会拦截；
|
||
- **方式三**：手工编辑配置文件 `cust_nonls.json`（见 §6.2），保存后程序自动检测并刷新界面。
|
||
|
||
**表格列**：`UF20函数名` | `是否存在` | `是否递归` | `操作`（行尾编辑按钮）。
|
||
|
||
- LS_ 开头的函数名以橙色字体显示提醒（不拦截）。
|
||
|
||
**设置递归模式：**
|
||
|
||
1. 在目标行的 **是否递归** 下拉框选择 **否**（单文件）或 **是**（递归）；
|
||
2. 选择后立即写入 `cust_nonls.json` 并生效，无需额外点击。
|
||
|
||
**执行转码：** 点击 **开始转换**，进度显示与停止方式同全量转码；任务互斥规则相同。
|
||
|
||
**清单同步**：外部编辑保存后约 0.3 秒内界面自动刷新，支持程序内修改与外部文件修改双向同步。
|
||
|
||
#### 5.2.2 代码检索
|
||
|
||
**说明**：代码检索用于查看功能的**调用链路**——该功能调用了哪些下游函数、被哪些上游功能调用，用于转码前评估影响范围、转码后核对结果。
|
||
|
||
页面顶部 Tab 切换 **转码业务** / **非转码业务** 两种模式，两种模式各自维护检索路径与索引，互不干扰。
|
||
|
||
**通用操作：**
|
||
|
||
1. **代码检索路径**：选择需要分析的代码目录（默认 `bin\uf2touft3\change_code`），点 **浏览** 更改；
|
||
2. 首次显示页面会**自动构建索引**（优先读取缓存，秒级加载）；若手动更改过路径，需点 **刷新索引** 重新加载；
|
||
3. 索引构建在后台线程执行，期间显示进度框，完成后写入缓存；
|
||
4. 每次转码任务完成后，程序会自动静默刷新索引；
|
||
5. 检索路径按模式持久化保存，下次启动自动恢复（见 §6.3）。
|
||
|
||
**转码业务模式：**
|
||
|
||
- 左侧显示 **业务转码函数列表**（与全量转码清单 `cust.json` 的 `convert.dir` 同步）；
|
||
- **双击**左侧函数 → 右侧树显示调用链路（向上：哪些上游功能调用了它；向下：它调用了哪些下游函数）；该模式仅支持从列表双击查询，不提供手动输入检索行；
|
||
- 树列为：`函数名`、`目录`、`模块`；当前查询行**蓝色高亮**；
|
||
- **原代码已支持** 行**绿色高亮**（该函数无需转码，行前带 UFT3 功能号前缀）；其他标记：`[未找到]`、`[循环调用]`、`[层级截断]`；
|
||
- 点 **导出调用文件**：将链路上所有需转码文件按原目录结构复制到 `<检索路径>\function_output\<查询函数名>\`，并生成链路文本 `_call_chain.txt`；
|
||
- 树标题行右侧 **全部展开 / 全部折叠** 按钮控制树展示层级，列宽自适应内容且可拖拽调整。
|
||
|
||
**非转码业务模式：**
|
||
|
||
该模式通过页面顶部输入行检索，支持两种检索方式（下拉框切换）：
|
||
|
||
- **按函数名检索**：输入函数名（如 `LS_xxx` / `LF_xxx`，也支持带功能号前缀的 `功能号-函数名` 格式），回车或点 **查询链路** 直接查询；
|
||
- **按功能号检索**：输入 UFT3 功能号，程序先通过 UFT3 功能元数据将功能号解析为对应函数（英文名），再查询调用链路。前提是元数据已更新（见 §5.1），否则提示"功能数据未加载"；功能号不存在时提示"未找到功能号对应函数"。
|
||
|
||
查询成功后调用链路显示在右侧树中，展示规则（列、高亮、状态标记）与转码业务模式一致。
|
||
|
||
- 点 **导出调用链路**：仅导出 `_call_chain.txt` 链路文本到 `<检索路径>\function_output\<查询函数名>\`（不复制源文件）。
|
||
|
||
### 5.3 功能查询
|
||
|
||
#### 5.3.1 UF20 功能查询
|
||
|
||
**操作步骤：**
|
||
|
||
1. 进入 **UF20功能查询** 页；
|
||
2. 左侧下拉选择检索字段：**函数名** / **功能号**，输入关键字回车或点搜索图标；
|
||
- **批量查询**：多个关键词用**逗号、分号或空格**分隔（中英文均可），如 `LS_证券参数, LS_股票名单`；各关键词命中结果取**并集**展示；
|
||
- 单个关键词可命中同一功能的多个字段，结果按"函数名+功能号"自动去重；
|
||
3. 搜索框内可切换**精确匹配**（默认模糊匹配）；
|
||
4. 查看结果列表，列：`函数名`、`英文名`、`功能号`；
|
||
5. **双击或右键选中行一键加入转码工作台**：LS_ 开头功能 → **全量转码**；其它功能 → **按需转码**；
|
||
- 支持 **Ctrl/Shift 多选**后一次加入；右键行不在选区内时仅加入该行；
|
||
- 加入结果**只弹一个提示框**（"全量转码"、"按需转码"字样加粗）：同时包含两类功能时显示"已将 N 个功能加入全量转码，已将 M 个功能加入按需转码"；重复添加的功能自动跳过并在提示中注明；全部已存在时提示"均已在转码列表中"。
|
||
|
||
**查询提示**：查询反馈显示在页面底部提示栏（颜色随日间/夜间主题自动适配），不弹对话框打断操作——输入为空提示"请输入查询内容"；无匹配结果提示"⚠️ 未找到匹配的功能"；查询成功后显示"已查询 X 个业务功能函数（M 个无匹配）"并接默认操作提示。
|
||
|
||
#### 5.3.2 UFT3 功能查询
|
||
|
||
- 界面与 UF20 功能查询一致（函数名 / 功能号检索、**批量关键词**、精确匹配），结果列为 `函数名`、`英文名`、`功能号`，查询提示同样在页面底部提示栏反馈；
|
||
- 仅用于查询核对 UFT3 功能元数据，**双击/右键不加入转码清单**；
|
||
- 代码检索中"原代码已支持"行前的功能号即来自 UFT3 元数据。
|
||
|
||
### 5.4 数据映射
|
||
|
||
**说明**：数据映射维护 UF20 → UFT3 的**替换对照表**，转码引擎按映射替换代码中的表名 / 函数名。两类映射均保存在 `cust.json`（见 §6.1）；界面修改后点 **保存** 写盘生效，外部编辑 `cust.json` 保存后界面自动刷新（程序自身保存后的 2 秒内暂停文件监控，此间的外部修改需再次保存文件才会被检测到）。
|
||
|
||
#### 5.4.1 表替换
|
||
|
||
维护 UF20 表名 → UFT3 表名的映射。
|
||
|
||
**操作步骤：**
|
||
|
||
1. 进入 **数据映射 → 表替换**；
|
||
2. 顶部搜索框实时过滤两列内容（不区分大小写）；
|
||
3. **双击单元格**直接修改；
|
||
4. 点 **添加** 弹窗输入 UF20 / UFT3 表名（UF20 表名必填且不可重复）；
|
||
5. **删除选中** 需二次确认（支持多选）；
|
||
6. 修改后点 **保存** 生效。
|
||
|
||
#### 5.4.2 函数替换
|
||
|
||
维护 UF20 函数名 → UFT3 函数名的映射，操作方式与表替换完全相同。
|
||
|
||
### 5.5 系统设置（底部"设置"）
|
||
|
||
**环境配置**：
|
||
|
||
| 配置项 | 说明 |
|
||
| --- | --- |
|
||
| UFT30项目环境路径 | UFT30 项目根目录 |
|
||
| UF20项目环境路径 | UF20 项目根目录 |
|
||
| UF20账户项目环境路径 | UF20 账户项目根目录 |
|
||
| 转码生成路径 | 转码结果输出目录 |
|
||
|
||
- 路径保存在 `config\config.ini` 的 `[projectPath]` 节，供元数据更新与转码引擎使用；
|
||
- 保存时程序自动同步维护 `uft30pub = <UFT30路径>\upub\dev_codes`；
|
||
- **元数据更新（§5.1）按这些路径扫描源码，首次使用必须先配置**。
|
||
|
||
**系统配置**：
|
||
|
||
- 主题模式：日间模式 / 夜间模式，即时切换。
|
||
|
||
**按钮**：
|
||
|
||
- **保存设置**：写盘生效；
|
||
- **恢复默认**：清空全部路径与主题并恢复默认（二次确认）。
|
||
|
||
## 6. 配置文件说明
|
||
|
||
### 6.1 cust.json
|
||
|
||
- **路径**：`bin\uf2touft3\config\cust.json`
|
||
- **作用**：一个文件承载三类配置——全量转码清单、表替换映射、函数替换映射。
|
||
|
||
| 节点 | 结构 | 用途 |
|
||
| --- | --- | --- |
|
||
| `convert.dir` | 数组，元素为 `"函数名.service_design"` | 全量转码清单 |
|
||
| `tableCompareUf2_Uf3` | 对象 `{UF20表名: UFT3表名}` | 表替换映射 |
|
||
| `functionReplace` | 对象 `{UF20函数名: UFT3函数名}` | 函数替换映射 |
|
||
|
||
**手工编辑示例（以实际文件结构为准）：**
|
||
|
||
```json
|
||
{
|
||
"convert": {
|
||
"dir": [
|
||
"LS_CustQry.service_design",
|
||
"LS_AcctChk.service_design"
|
||
]
|
||
},
|
||
"tableCompareUf2_Uf3": {
|
||
"UF20表A": "UFT3表A"
|
||
},
|
||
"functionReplace": {
|
||
"UF20函数1": "UFT3函数1"
|
||
}
|
||
}
|
||
```
|
||
|
||
**编辑注意：**
|
||
|
||
- 程序内修改（全量转码 / 表替换 / 函数替换页）会自动写回该文件；
|
||
- 手工编辑保存后各页面自动检测并刷新；
|
||
- 全量转码清单函数名可省略 `.service_design` 后缀展示，`dir` 为数组结构，程序保存时保留文件其余内容与格式。
|
||
|
||
### 6.2 cust_nonls.json（按需转码清单）
|
||
|
||
- **路径**：`bin\uf2touft3\config\cust_nonls.json`
|
||
- **作用**：保存按需转码功能清单及每项的递归标志，供界面与转码引擎共用。
|
||
|
||
| 节点 | 结构 | 说明 |
|
||
| --- | --- | --- |
|
||
| `convert.dir` | 对象 `{功能名: 0 或 -1}` | `0` = 否（单文件转码），`-1` = 是（递归转码） |
|
||
| `convert.dir["*"]` | 引擎兜底键 | 非清单功能，界面不展示、保存时自动保留 |
|
||
| `convert.ext` | 后缀数组 | 引擎识别的功能文件后缀，程序保存时自动维护 |
|
||
|
||
**手工编辑示例（以实际文件结构为准）：**
|
||
|
||
```json
|
||
{
|
||
"convert": {
|
||
"dir": {
|
||
"*": -1,
|
||
"AS_CustQry": 0,
|
||
"LF_AcctChk": -1
|
||
},
|
||
"ext": [
|
||
".service_design",
|
||
".function_design",
|
||
".aservice_design",
|
||
".procedure_design",
|
||
".afunction_design"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**编辑注意：**
|
||
|
||
- 保持 JSON 格式合法（逗号、引号完整）；若格式非法，程序将保留内存中的现有清单并在日志中记录警告；
|
||
- 兼容旧版 `dir` 为数组的格式（无递归标志，一律按"否"加载）；
|
||
- 外部编辑保存后约 0.3 秒内界面自动刷新；程序自身写入该文件时不会触发重复刷新，可放心与手工编辑混用。
|
||
|
||
### 6.3 config.ini 与 change_code.ini
|
||
|
||
- **`bin\uf2touft3\config\config.ini`**：`[projectPath]` 节保存设置页的项目环境路径（`uft30` / `uf20` / `ufAcct20` / `createPath` / `uft30pub`），供元数据更新与转码引擎使用；
|
||
- **`bin\uf2touft3\config\change_code.ini`**：程序私有配置（与 config.ini 分离，避免程序更新时被覆盖）：
|
||
- `[log]` 节：日志配置（`file`：日志基础文件名，默认 `change_code.log`，输出到 exe 目录 `logs\` 下，文件名带当天日期前缀）；
|
||
- `codeSearch` 节：代码检索两种模式的检索路径持久化。
|
||
|
||
## 7. 常见问题（FAQ）
|
||
|
||
### 7.1 元数据与索引问题
|
||
|
||
**Q1：全量转码/按需转码页"是否存在"列全部显示"否"？**
|
||
A：元数据缓存未就绪。请先确认"设置"页项目环境路径配置正确，再到"元数据更新"页执行一次更新并等待完成。
|
||
|
||
**Q2：首次打开页面"是否存在"显示"否"，重开程序后变正常？**
|
||
A：已知问题——首次打开时索引尚未加载完成。规避方法：执行元数据更新后再进入转码页面；后续版本将实现索引就绪后自动刷新。
|
||
|
||
### 7.2 业务转码问题
|
||
|
||
**Q3：全量转码"添加"时提示函数无法加入？**
|
||
A：全量转码仅支持 **LS_ 开头**的功能。非 LS 功能请切到业务转码的"按需转码"Tab 添加。
|
||
|
||
**Q4：递归模式选"是"后转码范围包含核心文件吗？**
|
||
A：不包含。按需转码（无论是否递归）均不处理核心文件、module 模块文件。
|
||
|
||
**Q5：切换"是否递归"后需要保存吗？**
|
||
A：不需要，下拉选择后立即写入 `cust_nonls.json` 并生效。
|
||
|
||
### 7.3 代码检索、清单与转码执行问题
|
||
|
||
**Q6：双击/右键 UF20 功能查询中的函数加入了哪个清单？**
|
||
A：按功能名自动分流——**LS_ 开头**加入"全量转码"，**其它功能**加入"按需转码"；可 Ctrl/Shift 多选后批量加入，结果合并为一个提示框（重复项自动跳过）。UFT3 功能查询仅用于核对，不加入清单。
|
||
|
||
**Q7：手工修改 cust_nonls.json / cust.json 后界面没刷新？**
|
||
A：界面刷新有约 0.3 秒防抖延迟；若长时间未刷新，检查 JSON 格式是否合法、文件是否保存在 `bin\uf2touft3\config\` 目录下。
|
||
|
||
**Q8：代码检索双击函数提示"请先刷新索引"？**
|
||
A：手动更改过检索路径后需点"刷新索引"重新加载；首次显示页面通常会自动构建索引。
|
||
|
||
**Q9：点击"开始转换"后提示任务失败？**
|
||
A：多为转码引擎 `bin\uf2touft3\uf2touft3.exe` 缺失、被杀毒软件隔离或被占用导致启动失败（程序会立即提示并恢复界面，不会卡死）。确认引擎文件存在后重试。
|
||
|
||
**Q10：进度条走到后段却提示"转换失败（N 个文件转换失败）"？**
|
||
A：个别功能文件转码失败时，程序会如实提示失败而不会误报"转换完成"，进度条停留在当前位置。请到 exe 目录 `logs\` 下查看当天的日志，定位失败文件（日志含 `FAIL` 行与失败汇总）后重试。
|
||
|
||
## 8. 日志与问题反馈
|
||
|
||
### 8.1 日志
|
||
|
||
- 程序运行日志输出到 exe 目录 `logs\` 下（文件名带日期前缀，基础名可在 `config\change_code.ini` 的 `[log]` 节配置，默认 `change_code.log`）；
|
||
- 转码过程中若出现文件转换失败，日志会记录 `FAIL` 行与失败汇总，界面提示"转换失败（N 个文件转换失败）"，请结合日志定位问题；
|
||
- 配置保存/加载失败、索引刷新失败等异常均会写入警告日志。
|
||
|
||
### 8.2 问题反馈
|
||
|
||
- 反馈问题时请提供：操作步骤、界面提示内容、日志文件，以及 `cust.json` / `cust_nonls.json` 当前内容。
|
||
|
||
---
|
||
|
||
*配套文档：《详细设计文档》（`docs/详细设计文档.md`），含系统架构图与各模块流程图。*
|