新增按需转码功能;支持批量查询和批量添加
This commit is contained in:
taocong45644
taocong
+792
@@ -0,0 +1,792 @@
|
||||
# Uft30ChangeCode 详细设计文档
|
||||
|
||||
| 文档信息 | 内容 |
|
||||
| --- | --- |
|
||||
| 项目名称 | Uft30ChangeCode（UF20 → UFT3 转码工具） |
|
||||
| 文档版本 | V1.6.0 |
|
||||
| 更新日期 | 2026-09-14 |
|
||||
| 技术栈 | Qt 6.6.2（MinGW 64-bit）/ C++ / ElaWidgetTools / SQLite |
|
||||
|
||||
---
|
||||
|
||||
## 1. 引言
|
||||
|
||||
### 1.1 编写目的
|
||||
|
||||
本文档面向开发与维护人员，描述 Uft30ChangeCode 转码工具的总体架构、模块划分、核心流程与关键设计决策，作为后续开发、测试与维护的依据。
|
||||
|
||||
### 1.2 系统定位
|
||||
|
||||
Uft30ChangeCode 是一款桌面端 **UF20 → UFT3 代码转码工具**，提供：
|
||||
|
||||
- **元数据更新**：后台解析 UF20/UFT3 源码，构建功能元数据索引并落库（SQLite 双缓存库）；
|
||||
- **业务转码**：**全量转码**（LS_ 功能清单式整体转码，清单存 `cust.json`）与**按需转码**（非 LS 功能，单文件/递归两种模式，清单存 `cust_nonls.json`，转码范围不含核心文件、module 模块文件），转码动作由外部引擎 `bin/uf2touft3/uf2touft3.exe` 执行；
|
||||
- **代码检索**：功能**调用链路查询**（向上调用方、向下被调），双模式（转码业务/非转码业务），支持导出调用文件与链路文本；
|
||||
- **功能查询**：检索 UF20 / UFT3 功能元数据，支持**多关键词批量查询**（逗号/分号/空格分隔，OR 并集）；UF20 查询结果**双击/右键一键分流**——可多选，LS_ 功能加入全量转码、其它功能加入按需转码，加入结果合并为单次提示；UFT3 仅用于查询核对；
|
||||
- **数据映射**：维护 UF20 → UFT3 的表替换、函数替换对照表（存 `cust.json`，转码引擎按映射替换代码中的表名/函数名）；
|
||||
- **系统设置**：项目环境路径与主题配置（元数据更新与转码引擎依赖这些路径）。
|
||||
|
||||
### 1.3 术语约定
|
||||
|
||||
| 术语 | 说明 |
|
||||
| --- | --- |
|
||||
| UF20 / UFT3 | 新旧两代系统版本，转码即将 UF20 风格代码转换为 UFT3 风格 |
|
||||
| LS 功能 | "内存交易"改造范围的功能类别；**全量转码仅支持 LS_ 开头功能**，按需转码仅针对非 LS 功能 |
|
||||
| 递归标志 | `cust_nonls.json` 中 `convert.dir` 的取值：`0`=否（不递归），`-1`=是（递归） |
|
||||
| 元数据 | 从源码解析出的功能/函数索引信息，存于 SQLite 缓存库 |
|
||||
| 调用链路 | 某功能的向上调用方（谁调用了它）与向下被调（它调用了谁）构成的关系树 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 总体设计
|
||||
|
||||
### 2.1 技术选型
|
||||
|
||||
| 类别 | 选型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| GUI 框架 | Qt 6.6.2（MinGW 64-bit） | 跨平台 C++ 桌面框架 |
|
||||
| UI 组件库 | ElaWidgetTools | Fluent 风格控件（ElaWindow / ElaPivot / ElaTableView / ElaComboBox 等） |
|
||||
| 本地存储 | Qt SQL（QSqlDatabase） | SQLite 双缓存库 `uf20_cache.db` / `uft3_cache.db`，由 `DataCache` 单例统一管理 |
|
||||
| 并发 | QtConcurrent + 信号槽 | 元数据后台解析、代码索引后台构建，避免阻塞 UI |
|
||||
| 进程调用 | QProcess（`PythonRunner` 封装） | 调用外部转码引擎（打包 exe，兼容 Python 脚本模式） |
|
||||
| 文件监听 | QFileSystemWatcher（+ QTimer 防抖） | 监听外部修改 `cust.json`（数据映射/全量转码）与 `cust_nonls.json`（按需转码） |
|
||||
| 日志 | LogManager（单例） | 统一 info/warning/error 日志输出到 exe 目录 `logs\` |
|
||||
|
||||
### 2.2 系统分层架构
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph SHELL["主窗口（src/mainwindow）"]
|
||||
M1["MainWindow（ElaWindow）<br/>页面注册 / 任务调度互斥 / 引擎调用"]
|
||||
end
|
||||
|
||||
subgraph UI["UI 层（src/pages）"]
|
||||
A2[元数据更新 MetadataUpdatePage]
|
||||
A3a["业务转码容器 BusinessConvertPage<br/>（ElaPivot：全量/按需）"]
|
||||
A3[全量转码 BatchConvertPage]
|
||||
A4[按需转码 NonLsConvertPage]
|
||||
A5["功能查询 FunctionSearchPage<br/>（UF20 / UFT3 两个子页）"]
|
||||
A6[代码检索 CodeSearchPage]
|
||||
A7["数据映射 TableMappingPage<br/>FunctionMappingPage"]
|
||||
A8[设置 SettingsPage]
|
||||
A9[关于 AboutDialog]
|
||||
end
|
||||
|
||||
subgraph CORE["业务核心层"]
|
||||
B1["业务策略（src/utils）<br/>BusinessStrategy + Factory<br/>UF20 / UFT3 实现"]
|
||||
B2["配置读取器（src/utils）<br/>ConfigReaderBase + Traits<br/>UF2ConfigReader / UFT3ConfigReader"]
|
||||
B3["元数据解析器组（src/metadataupdate）<br/>MetaDataProcessor / FileDB<br/>+ uf2* / uft3* 解析器"]
|
||||
end
|
||||
|
||||
subgraph UTIL["公共支撑层（src/utils）"]
|
||||
C1[DataCache 缓存读写]
|
||||
C2[CallChainAnalyzer 调用链分析]
|
||||
C3[ConfigManager 配置管理]
|
||||
C4[LogManager 日志]
|
||||
C5[Constants 常量]
|
||||
C6[VersionChecker 更新检查]
|
||||
end
|
||||
|
||||
subgraph EXT["引擎与外部资源"]
|
||||
D1[PythonRunner<br/>QProcess 封装]
|
||||
D2[("bin/uf2touft3/uf2touft3.exe<br/>转码引擎")]
|
||||
D3[("bin/uf2touft3/cache/<br/>uf20_cache.db / uft3_cache.db")]
|
||||
D4[("bin/uf2touft3/config/<br/>cust.json / cust_nonls.json")]
|
||||
D5[("bin/uf2touft3/change_code/<br/>默认代码检索根目录")]
|
||||
D6[UF20/UFT3 源码目录]
|
||||
end
|
||||
|
||||
M1 --> UI
|
||||
M1 --> D1
|
||||
D1 --> D2
|
||||
A3 -.读写.-> D4
|
||||
A4 -.监听/读写.-> D4
|
||||
A7 -.监听/读写.-> D4
|
||||
A6 -.扫描.-> D5
|
||||
B3 -.解析.-> D6
|
||||
B3 --> C1
|
||||
C1 --> D3
|
||||
C2 --> C1
|
||||
UI --> CORE
|
||||
UI --> UTIL
|
||||
CORE --> UTIL
|
||||
```
|
||||
|
||||
**分层职责：**
|
||||
|
||||
- **主窗口**：ElaWindow 容器与导航注册；**全局唯一的 `PythonRunner` 实例**，接收全量/按需转码页的 `startConvert` 信号，负责**任务互斥**、引擎进程启停与输出回收；
|
||||
- **UI 层**：页面构建、用户交互、表格/树渲染，不直接访问数据库/源码，统一经由支撑层与核心层完成；
|
||||
- **业务核心层**：以**策略模式**隔离 UF20/UFT3 差异（`BusinessStrategy`），以**模板方法模式**统一配置读取流程（`ConfigReaderBase` + Traits）；元数据解析器组负责将源码解析为结构化键值数据；
|
||||
- **公共支撑层**：缓存读写、调用链分析、配置、日志、版本检查等横切能力。
|
||||
|
||||
### 2.3 目录结构
|
||||
|
||||
```
|
||||
Uft30ChangeCode/
|
||||
├── src/
|
||||
│ ├── mainwindow/ # MainWindow（ElaWindow 主窗口 + 导航注册 + 转码任务调度）
|
||||
│ ├── metadataupdate/ # 元数据解析核心（MetaDataProcessor / FileDB
|
||||
│ │ # + uf2datatype / uf2stdfields / uf2table / uf2interface
|
||||
│ │ # / uf2errnumber / uf2menuandfunction / uf2module 等）
|
||||
│ ├── pythonrunner/ # PythonRunner（外部转码引擎进程封装，QProcess）
|
||||
│ ├── components/ # 通用组件（ElaSearchEdit 搜索框、InterDialog 弹窗）
|
||||
│ ├── pages/
|
||||
│ │ ├── businessconvert/ # 业务转码容器页（ElaPivot：全量/按需 Tab）
|
||||
│ │ ├── batchconvert/ # 全量转码页
|
||||
│ │ ├── nonlsconvert/ # 按需转码页
|
||||
│ │ ├── codesearch/ # 代码检索页（调用链路查询）
|
||||
│ │ ├── functionsearch/ # 功能查询（FunctionSearchPage 基类 + UF20/UFT3 子页）
|
||||
│ │ ├── datamapping/ # 数据映射（表替换 / 函数替换）
|
||||
│ │ ├── metadatupdate/ # 元数据更新页
|
||||
│ │ ├── settings/ # 设置页
|
||||
│ │ └── about/ # 关于（AboutDialog 对话框）
|
||||
│ └── utils/ # Constants.h / business_strategy / configreaderbase
|
||||
│ # / uf2configreader / uft3configreader / callchainanalyzer
|
||||
│ # / datacache / configmanager / logmanager
|
||||
│ # / version / versionchecker
|
||||
├── 3rd/ElaWidgetTools/ # 第三方 UI 库
|
||||
├── bin/
|
||||
│ ├── Uft30ChangeCode.exe # 构建产物
|
||||
│ └── uf2touft3/
|
||||
│ ├── uf2touft3.exe # 转码引擎
|
||||
│ ├── config/ # cust.json / cust_nonls.json / config.ini / change_code.ini
|
||||
│ ├── cache/ # uf20_cache.db / uft3_cache.db（元数据缓存库）
|
||||
│ └── change_code/ # 默认代码检索根目录
|
||||
└── docs/ # 本文档与使用手册
|
||||
```
|
||||
|
||||
### 2.4 模块清单
|
||||
|
||||
| 模块 | 主要类 | 设计模式 | 职责 |
|
||||
| --- | --- | --- | --- |
|
||||
| 主窗口导航 | `MainWindow` | — | ElaWindow 容器、页面注册、**转码任务调度与互斥**、引擎进程管理 |
|
||||
| 业务转码容器 | `BusinessConvertPage` | — | ElaPivot 承载全量/按需两个工作台 |
|
||||
| 全量转码 | `BatchConvertPage` | — | `cust.json` 的 `convert.dir` 清单管理（仅 LS_ 功能）、触发转码 |
|
||||
| 按需转码 | `NonLsConvertPage` | — | 非 LS 功能清单管理、递归模式选择、外部修改同步 |
|
||||
| 功能查询 | `FunctionSearchPage`（基类）、`UF20/UFT3FunctionSearchPage` | 模板方法（基类复用） | 元数据检索（多关键词批量查询）；UF20 双击/右键一键分流加入转码清单（合并单次提示），UFT3 纯查询 |
|
||||
| 代码检索 | `CodeSearchPage`、`CallChainAnalyzer` | — | 调用链路查询、索引构建与缓存、导出 |
|
||||
| 数据映射 | `TableMappingPage`、`FunctionMappingPage` | — | `cust.json` 表替换/函数替换映射维护 |
|
||||
| 元数据更新 | `MetadataUpdatePage` + `src/metadataupdate/` 解析器组 | 观察者（信号槽） | 后台解析源码、进度上报、原子落库 |
|
||||
| 设置 | `SettingsPage` | — | 项目环境路径、主题配置 |
|
||||
| 缓存 | `DataCache` | 单例 | QSqlDatabase 双库读写、功能查询内存缓存 |
|
||||
| 引擎调用 | `PythonRunner` | — | 外部进程封装（打包 exe / Python 脚本双模式） |
|
||||
| 日志 | `LogManager` | 单例 | 统一日志 |
|
||||
| 版本检查 | `VersionChecker` | — | 启动时在线检查新版本（`update_info.json`） |
|
||||
|
||||
---
|
||||
|
||||
## 3. 全局流程
|
||||
|
||||
### 3.1 应用启动流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
S([main 入口]) --> A[初始化 QApplication / 高分屏属性]
|
||||
A --> B[初始化 LogManager 日志单例]
|
||||
B --> C[初始化 ConfigManager 读取全局配置]
|
||||
C --> D[构造 MainWindow ElaWindow]
|
||||
D --> E["注册导航页面<br/>功能转码：业务转码 / 代码检索<br/>功能查询：UF20 / UFT3<br/>数据映射：表替换 / 函数替换<br/>元数据更新；底部：设置 / 帮助 / 关于"]
|
||||
E --> F[DataCache.initDatabase<br/>打开 uf20_cache.db / uft3_cache.db]
|
||||
F --> G{缓存库是否有效?}
|
||||
G -- 是 --> H[正常进入主界面]
|
||||
G -- 否/为空 --> I[各页面提示: 请先执行元数据更新]
|
||||
H --> J[VersionChecker 后台检查在线版本]
|
||||
I --> J
|
||||
J --> K["singleShot(0) 首帧渲染后:<br/>异步预热 uf20 / uft3 功能缓存"]
|
||||
K --> L([等待用户操作])
|
||||
```
|
||||
|
||||
> 说明：页面在启动时统一注册到 `MainWindow`（ElaWindow 侧边栏分组导航 + 底部按钮）。`DataCache` 在启动时打开两个缓存库（不存在则自动创建），功能查询使用**内存缓存**（`refreshFunctionCache`），首次查询前需元数据落库。启动流程末尾经 `QTimer::singleShot(0)` 在首帧渲染后提交线程池**异步预热**两库功能缓存（`warmupFunctionCacheAsync`，幂等：已就绪或在途则跳过），用户进入功能查询页时无需再等待主线程重建（详见 §8.6）。
|
||||
|
||||
### 3.2 页面导航机制
|
||||
|
||||
- `MainWindow` 基于 `ElaWindow` 实现，侧边栏按分组注册页面：**功能转码**（业务转码、代码检索）、**功能查询**（UF20、UFT3）、**数据映射**（表替换、函数替换）、**元数据更新**；底部为设置、帮助、关于；
|
||||
- 业务转码页内部通过 ElaPivot 切换全量/按需两个工作台；
|
||||
- 页面切换由 ElaWindow 内部路由完成，各页面通过 `showEvent` 感知可见性变化（如按需转码页每次显示时刷新表格，代码检索页每次显示时重读 `cust.json` 清单并按需构建索引）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心数据流
|
||||
|
||||
### 4.1 元数据更新流程
|
||||
|
||||
元数据更新是全工具的数据基石：解析 UF20/UFT3 源码目录，构建功能/函数索引并写入 SQLite 缓存库。解析在**工作线程**中执行，通过信号槽向页面汇报进度，UI 不卡顿。支持**增量更新**（按源文件 mtime 比对跳过未变更文件）与**强制全量更新**（二次确认后全量重扫）。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户（元数据更新页）
|
||||
participant P as MetadataUpdatePage
|
||||
participant R as 元数据解析器组<br/>(src/metadataupdate)
|
||||
participant T as 工作线程
|
||||
participant C as DataCache
|
||||
participant DB as (SQLite 缓存库)
|
||||
|
||||
U->>P: 勾选更新范围 / 点击"更新UFT30 / 更新UF20"
|
||||
P->>R: 启动解析任务（增量 或 强制全量）
|
||||
R->>T: 提交后台解析
|
||||
loop 遍历源码文件
|
||||
T->>T: 解析元数据（uf2* / uft3* 解析器）
|
||||
T->>P: 信号: 进度 / 当前处理项
|
||||
T->>C: saveDataset(键值行, srcMtime)
|
||||
C->>DB: 原子写（临时表 + RENAME）+ 更新 _meta
|
||||
end
|
||||
T-->>R: 解析完成
|
||||
R->>P: 信号: 更新完成（统计结果）
|
||||
P->>C: refreshFunctionCache()
|
||||
P->>U: 展示结果
|
||||
```
|
||||
|
||||
**设计要点：**
|
||||
|
||||
1. **后台化**：解析与写库全部在工作线程，UI 线程仅收发信号；
|
||||
2. **原子落库**：`saveDataset` 以"临时表 + RENAME"方式整体替换表数据，并更新 `_meta` 元信息表（记录源文件 mtime，供增量判断）；
|
||||
3. **增量/全量**：默认增量（mtime 比对），且先做**源码目录整体 mtime 快速比对**（0.5s 容差），源码无变化时整个更新秒级跳过；"强制全量更新"复选框需二次确认；
|
||||
4. **缓存生效时机**：更新完成后调用 `refreshFunctionCache` 重建功能查询内存缓存，各页面"是否存在"判断随之生效。
|
||||
|
||||
### 4.2 数据缓存与存在性判断流程
|
||||
|
||||
`DataCache` 是所有"是否存在 / 元数据查询"的统一入口，底层经 `QSqlDatabase` 访问 SQLite，功能查询走内存索引缓存。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([页面发起查询<br/>如 checkUF20CnameExists / searchUF20Functions]) --> B{内存功能缓存<br/>是否已构建?}
|
||||
B -- 否 --> C[读取 *interface 表<br/>refreshFunctionCache 建内存索引]
|
||||
C --> D{加载成功?}
|
||||
D -- 是 --> E[在内存索引中匹配]
|
||||
D -- 否 --> F[返回 未找到<br/>并记录 logWarning]
|
||||
B -- 是 --> E
|
||||
E --> G{命中?}
|
||||
G -- 是 --> H[返回 存在 + 元数据<br/>cname / eName / functionNo]
|
||||
G -- 否 --> F
|
||||
```
|
||||
|
||||
### 4.3 配置读取流程（模板方法 + Traits）
|
||||
|
||||
`ConfigReaderBase` 定义统一的读取骨架（打开文件 → 逐段解析 → 校验 → 输出结构化配置），UF20 与 UFT3 的差异通过子类 + `ConfigReaderTraits` 萃取，避免大量 if-else 分支。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([调用方指定版本]) --> B{版本?}
|
||||
B -- UF20 --> C[UF2ConfigReader]
|
||||
B -- UFT3 --> D[UFT3ConfigReader]
|
||||
C --> T["Traits<UF2><br/>关键字段/节名/正则差异"]
|
||||
D --> T2["Traits<UFT3><br/>关键字段/节名/正则差异"]
|
||||
T --> E[ConfigReaderBase::read<br/>模板方法统一骨架]
|
||||
T2 --> E
|
||||
E --> F[打开配置文件]
|
||||
F --> G{打开成功?}
|
||||
G -- 否 --> X[logWarning + 返回失败]
|
||||
G -- 是 --> H[逐节解析 parseSection 子类实现]
|
||||
H --> I{校验通过?}
|
||||
I -- 否 --> X
|
||||
I -- 是 --> J[输出结构化配置对象]
|
||||
X --> K([结束])
|
||||
J --> K
|
||||
```
|
||||
|
||||
### 4.4 转码执行流程（引擎调用）
|
||||
|
||||
转码动作由外部引擎 `bin/uf2touft3/uf2touft3.exe` 执行。`MainWindow` 持有全局唯一 `PythonRunner`（`UsePackagedExe` 模式，兼容 Python 脚本模式），并负责**全量/按需任务互斥**。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant P as BatchConvertPage /<br/>NonLsConvertPage
|
||||
participant M as MainWindow
|
||||
participant R as PythonRunner
|
||||
participant E as uf2touft3.exe（引擎）
|
||||
|
||||
U->>P: 点击"开始转换"
|
||||
P->>M: startConvert 信号
|
||||
M->>M: beginConvert 任务互斥<br/>（禁用另一 Tab 的开始按钮）
|
||||
M->>R: 组装参数并启动（UsePackagedExe）
|
||||
R->>E: QProcess 启动引擎进程
|
||||
loop 引擎运行
|
||||
E-->>R: stdout / stderr
|
||||
R->>M: standardOutput / standardError 信号
|
||||
M->>M: 前置失败检测(FAIL 行计数)<br/>再解析翻译进度
|
||||
M->>P: 进度与状态展示（进度条 / 停止转换按钮）
|
||||
end
|
||||
E-->>R: finished(exitCode)
|
||||
R->>M: finished 信号
|
||||
M->>M: 成败路由: exitCode==0 且 m_failCount==0<br/>→ onConvertFinished / 否则 onConvertFailed
|
||||
M->>M: 解除任务互斥，展示结果 + 日志
|
||||
M->>M: 成功时: 代码检索页 refreshIndexSilent()<br/>（双模式静默刷新索引）
|
||||
```
|
||||
|
||||
**要点：**
|
||||
|
||||
- **全量转码**：引擎读取 `cust.json` 的 `convert.dir` 清单，对清单内 LS_ 功能整体转码；
|
||||
- **按需转码**：`NonLsConvertPage::buildArguments()` 组装引擎参数（含 `-m 2` 模式标识），功能清单与递归标志由 `cust_nonls.json` 提供，引擎按映射关系（`cust.json`）完成表名/函数名替换；
|
||||
- **成败判定**：引擎在个别文件转码失败时退出码仍可能为 0，因此 `MainWindow` 在输出解析链最前端检测 `FAIL` 行（`[N/M] FAIL 函数名`）与汇总行（`批量转码完成: X/Y 通过, Z 失败`）累计 `m_failCount`；收尾按 `正常退出 && 退出码==0 && m_failCount==0` 判定成功，失败时页面调用 `onConvertFailed`——进度条**保持当前进度**（不置 100%）、状态文字"转换失败（N 个文件转换失败）"（详见 §8.7）；
|
||||
- **转码后联动**：任务成功后自动静默刷新代码检索索引，保证调用链路反映最新代码。
|
||||
|
||||
---
|
||||
|
||||
## 5. 业务模块详细设计
|
||||
|
||||
### 5.1 业务转码容器（BusinessConvertPage）
|
||||
|
||||
**职责**：单页承载全量转码与按需转码两个工作台，顶部 ElaPivot Tab 切换。
|
||||
|
||||
- 两个工作台（`BatchConvertPage` / `NonLsConvertPage`）作为子页内嵌；
|
||||
- **任务互斥**在 `MainWindow` 层统一控制：任一工作台转换期间，另一工作台的"开始转换"按钮禁用并提示等待，避免并发冲突。
|
||||
|
||||
### 5.2 全量转码模块（BatchConvertPage）
|
||||
|
||||
**职责**：维护 LS_ 功能转码清单并对功能执行整体转码，表格展示"UF20函数名 / 是否存在 / 操作"。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([进入全量转码页]) --> B["加载清单<br/>cust.json → convert.dir 数组"]
|
||||
B --> C[updateTable 渲染 ElaTableView]
|
||||
C --> D{逐行判断}
|
||||
D --> E["checkUF20CnameExists(函数名)<br/>查询 DataCache"]
|
||||
E --> F["存在 → 显示 是<br/>不存在 → 显示 否"]
|
||||
F --> G{用户点击开始转换}
|
||||
G --> H["startConvert 信号 → MainWindow<br/>任务互斥 + PythonRunner 启动引擎"]
|
||||
H --> I{转码结果}
|
||||
I -- 成功 --> K[提示成功 + 日志]
|
||||
I -- 失败 --> L[提示失败原因 + logWarning]
|
||||
```
|
||||
|
||||
**要点：**
|
||||
|
||||
- 清单**仅允许 LS_ 开头**的功能（`validateLsFunctionNames` 校验），非 LS 输入被拒绝并提示切换到按需转码；
|
||||
- 清单持久化于 `cust.json` 的 `convert.dir` 数组（元素为 `"函数名.service_design"`）；保存时用**正则定位数组做局部替换**，保留文件其余内容与格式；
|
||||
- `QFileSystemWatcher + QTimer`（300ms 防抖）监听 `cust.json` 外部修改，与手工编辑双向同步；
|
||||
- "是否存在"列依赖元数据缓存；**首次运行若未执行元数据更新，可能整列显示"否"**（详见 §8.2）。
|
||||
|
||||
### 5.3 按需转码模块（NonLsConvertPage）
|
||||
|
||||
**职责**：管理"非 LS 功能"的按需转码清单，支持**单文件转码**与**递归转码**两种模式（下拉选择），转码范围不包含核心文件、module 模块文件。清单持久化于 `bin/uf2touft3/config/cust_nonls.json`，并监听外部修改。
|
||||
|
||||
#### 5.3.1 数据结构
|
||||
|
||||
| 成员 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `m_funcList` | `QStringList` | 功能名有序清单（与表格行序一致） |
|
||||
| `m_recursionMap` | `QMap<QString,int>` | 功能名 → 递归标志（`0`=否，`-1`=是），与 json 的 `convert.dir` 同值 |
|
||||
| `m_tableModel` | `QStandardItemModel` | 表格模型，列：`UF20函数名 / 是否存在 / 是否递归 / 操作` |
|
||||
| `m_configWatcher` | `QFileSystemWatcher` | 监听 `cust_nonls.json` 文件与其所在目录 |
|
||||
| `m_reloadTimer` | `QTimer` | 防抖定时器，外部修改后延迟重载 |
|
||||
| `m_lastFileMtime` | `QDateTime` | 上次已处理的文件修改时间，用于过滤自身写入触发的变更 |
|
||||
|
||||
#### 5.3.2 添加功能流程（来自 UF20 功能查询页双击）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant S as UF20FunctionSearchPage
|
||||
participant N as NonLsConvertPage
|
||||
participant J as cust_nonls.json
|
||||
|
||||
U->>S: 双击非 LS 函数
|
||||
S->>S: 校验非 LS / 去重
|
||||
S->>N: addFunction(函数名)
|
||||
N->>N: m_funcList.append(name)
|
||||
N->>N: m_recursionMap.insert(name, 0) // 默认"否"
|
||||
N->>N: updateTable() // 立即渲染新行
|
||||
N->>J: saveToCustNonLsJson(m_funcList)
|
||||
Note over N,J: 写盘后刷新 m_lastFileMtime，<br/>避免 watcher 误判为外部修改
|
||||
N-->>U: 弹窗"已将功能 [x] 添加到按需转码"
|
||||
```
|
||||
|
||||
#### 5.3.3 表格刷新流程（updateTable）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([updateTable]) --> B["removeRows 清空模型<br/>（不使用 blockSignals）"]
|
||||
B --> C{遍历 m_funcList}
|
||||
C --> D[构建行: 函数名 / 是否存在<br/>存在性查询 DataCache]
|
||||
D --> E["是否递归列: setIndexWidget<br/>放置 ElaComboBox(否/是)"]
|
||||
E --> F["操作列: setIndexWidget<br/>放置编辑按钮"]
|
||||
F --> G{还有下一行?}
|
||||
G -- 是 --> D
|
||||
G -- 否 --> H["viewport()->update()<br/>resizeRowsToContents()<br/>scrollToTop() / clearSelection()"]
|
||||
H --> I([刷新完成])
|
||||
```
|
||||
|
||||
**关键设计决策——禁用 `blockSignals`：**
|
||||
|
||||
早期版本在重建模型时使用 `m_tableModel->blockSignals(true)` 防止勾选误触发写盘。但 `QTableView` 依赖 `rowsInserted/rowsRemoved` 信号更新内部布局缓存，屏蔽后**新增行不可见**（数据层行数正确、视图层不渲染）。现方案：
|
||||
|
||||
- 重建期间不屏蔽信号；
|
||||
- 误触发防护改由数据侧保证：`m_recursionMap` 先行预填充，下拉切换回调中"**值相等则短路**"，重建时 `setCurrentIndex` 不会产生多余写盘。
|
||||
|
||||
#### 5.3.4 递归模式切换流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([用户切换下拉 否/是]) --> B["currentIndexChanged(index)"]
|
||||
B --> C["recursion = index==1 ? -1 : 0"]
|
||||
C --> D{m_recursionMap 中<br/>旧值 == 新值?}
|
||||
D -- 是 --> E([短路返回, 不写盘])
|
||||
D -- 否 --> F[m_recursionMap 更新]
|
||||
F --> G[saveToCustNonLsJson 持久化]
|
||||
G --> H[刷新 m_lastFileMtime]
|
||||
H --> I([完成])
|
||||
```
|
||||
|
||||
#### 5.3.5 外部修改同步流程（文件监听 + 防抖）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["QFileSystemWatcher<br/>fileChanged / directoryChanged"] --> B[启动/重启 m_reloadTimer 防抖]
|
||||
B --> C{"onReloadTimeout:<br/>当前 mtime != m_lastFileMtime ?"}
|
||||
C -- 否 --> D([忽略: 自身写入或无效变更])
|
||||
C -- 是 --> E[loadFromCustNonLsJson 重新解析]
|
||||
E --> F{解析成功?}
|
||||
F -- 是 --> G[m_funcList / m_recursionMap 更新<br/>updateTable 重绘]
|
||||
F -- 否 --> H[logWarning + 保留内存现状]
|
||||
G --> I([界面与磁盘一致])
|
||||
H --> I
|
||||
```
|
||||
|
||||
**要点：**
|
||||
|
||||
- `fileChanged` 在部分编辑器保存时会**移除监听**，回调中检测到即对路径重新 `addPath`，保证持续监听；
|
||||
- 目录监听用于捕获"文件被删除重建"的场景；
|
||||
- mtime 比较过滤掉程序自身写盘引发的回环刷新；
|
||||
- **兼容旧版格式**：旧版 `convert.dir` 为数组（无递归标志），加载时自动兼容、一律按"否"处理；新版为对象 `{功能名: 0|-1}`，引擎兜底键 `"*"` 由程序保存时自动保留。
|
||||
|
||||
#### 5.3.6 按需转码执行模式
|
||||
|
||||
| 模式 | 递归标志 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| 非递归（单文件） | `0` | 仅对目标文件本身执行转码，不处理该文件内调用的函数 |
|
||||
| 递归 | `-1` | 转码目标文件的同时，自动对文件中所调用的关联函数一并完成转码 |
|
||||
|
||||
两种模式均**不包含核心文件、module 模块文件**。执行时 `buildArguments()` 组装引擎参数（含 `-m 2`），由 `MainWindow` 统一经 `PythonRunner` 启动引擎。
|
||||
|
||||
### 5.4 功能查询模块（FunctionSearchPage 基类 + UF20/UFT3 子页）
|
||||
|
||||
**职责**：检索 UF20 / UFT3 功能元数据（依赖 `DataCache`），列：`函数名 / 英文名 / 功能号`；支持函数名/功能号字段切换、精确匹配开关与**多关键词批量查询**。UF20 页结果表支持多选，双击/右键一键加入转码工作台；UFT3 页为纯查询（不接入转码链路）。
|
||||
|
||||
#### 5.4.1 多关键词批量查询
|
||||
|
||||
- **拆词**：查询框输入按**中英文逗号、分号与空白**统一拆分为关键词列表（`splitKeywords`，全角字符以 `QStringLiteral` 字符串字面量处理，规避多字节字符常量问题）；
|
||||
- **匹配语义**：多关键词之间为 **OR 并集**——任一关键词在所选字段（函数名/功能号/任一）命中即收录结果；
|
||||
- **去重**：结果按 `cname + '|' + functionNo` 组合键去重（同一功能可能被多个关键词或多个字段重复命中）；
|
||||
- **零命中统计**：`DataCache` 多词检索接口带 `keywordsWithoutMatch` 出参，返回零命中关键词个数；
|
||||
- **接口形态**：单词版 `searchUF20Functions(keyword, ...)` 内部委托多词版（`QStringList{keyword}`），两库多词重载共用匿名命名空间 `filterFunctionInfos()` 的单次遍历实现。
|
||||
|
||||
**查询反馈（tip 栏）**：页面底部提示栏随查询状态变化——空关键字提示"请输入查询内容"、无结果提示"⚠️ 未找到匹配的功能"、成功后显示"已查询 X 个业务功能函数（M 个无匹配）"并拼接默认操作提示（UF20 含双击/右键操作说明与批量查询示例），全程不弹模态对话框；提示文字颜色经 `ElaTheme` 主题取色并连接 `themeModeChanged` 信号联动刷新，日间/夜间模式均可读。
|
||||
|
||||
#### 5.4.2 UF20 功能查询一键加入转码工作台
|
||||
|
||||
UF20 页结果表为**扩展多选**（ExtendedSelection）+ 自定义右键菜单；**双击与右键共用**收集逻辑 `addSelectedRowsToConvert()`：收集选区（或右键行）按 `LS_` 前缀分流为两个列表，**一次 emit** 合并信号：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant S as UF20FunctionSearchPage
|
||||
participant M as MainWindow
|
||||
participant B as BatchConvertPage（全量）
|
||||
participant N as NonLsConvertPage（按需）
|
||||
|
||||
U->>S: 双击 / 右键"一键添加功能"（可多选）
|
||||
S->>S: 收集选区，按 LS_ 前缀分流
|
||||
S->>M: addFunctionsToConvert(lsNames, nonLsNames)
|
||||
M->>B: addFunctionsBatch(lsNames, notify=false) 静默
|
||||
M->>N: addFunctionsBatch(nonLsNames, notify=false) 静默
|
||||
Note over B,N: 各自去重（已存在跳过）、写 cust.json / cust_nonls.json；<br/>返回 {新增数, 跳过数}，保存失败返回 {-1,-1} 并弹警告
|
||||
M->>U: 合并为单个提示框（RichText）：<br/>"已将 N 个功能加入全量转码，已将 M 个功能加入按需转码"
|
||||
```
|
||||
|
||||
**要点：**
|
||||
|
||||
- **单次提示**：两工作台 `addFunctionsBatch` 支持静默模式（`notify=false` 不弹任何提示框），由 `MainWindow` 统一汇总——加入成功后**只弹一个**消息框，"全量转码"/"按需转码"字样经 `Qt::RichText` **加粗**；重复项自动跳过并注明"另有 N 个已存在"；全部已存在时提示"均已在转码列表中"；
|
||||
- **右键交互**：右键行不在选区内时设为唯一选中（Windows 惯例），在选区内则保持多选；空白区域右键不弹菜单；
|
||||
- 批量添加**逐条免弹窗**，替代早期逐条模态确认。
|
||||
|
||||
> **UFT3 功能查询**：界面与 UF20 版一致（含批量关键词查询），仅用于核对 UFT3 元数据，**双击/右键不加入转码清单**；代码检索中"原代码已支持"行的功能号前缀即来自 UFT3 元数据。
|
||||
|
||||
### 5.5 代码检索模块（CodeSearchPage + CallChainAnalyzer）
|
||||
|
||||
**职责**：功能**调用链路查询**（非内容检索）——展示某功能的向上调用方（谁调用了它）与向下被调（它调用了谁），用于转码前评估影响范围、转码后核对结果。
|
||||
|
||||
#### 5.5.1 双模式设计
|
||||
|
||||
页面顶部 ElaPivot 切换两种模式，各模式**独立的分析器实例、检索路径、调用链树**，互不干扰：
|
||||
|
||||
| 模式 | 检索入口 | 导出 |
|
||||
| --- | --- | --- |
|
||||
| 转码业务 | 左侧"业务转码函数列表"（每次显示时重读 `cust.json` 的 `convert.dir`），双击查询 | 导出调用文件（复制需转码文件）+ `_call_chain.txt` |
|
||||
| 非转码业务 | 顶部输入行：**函数名**（支持 `功能号-函数名` 带前缀格式）或**功能号**（经 UFT3 元数据解析为函数英文名）查询 | 仅导出 `_call_chain.txt` |
|
||||
|
||||
检索路径按模式持久化于 `change_code.ini` 的 `[codeSearch]` 节（`convertPath` / `searchPath`）。
|
||||
|
||||
#### 5.5.2 索引构建与缓存加速
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([显示页面 / 切换模式]) --> B{索引已就绪?}
|
||||
B -- 是 --> Z([直接可用])
|
||||
B -- "否，且路径未被手动更改" --> C{"cacheQuickValid<br/>快速粗判缓存（stat 根目录子项，毫秒级）"}
|
||||
C -- 命中 --> D["后台 loadFromCache<br/>（跳过指纹校验，秒级加载）"]
|
||||
C -- 未命中 --> E[后台 buildIndex 全量构建]
|
||||
D -- 失败 --> E
|
||||
E --> F[saveToCache 写缓存]
|
||||
D --> Z
|
||||
F --> Z
|
||||
B -- "否，且路径被手动更改" --> G[提示用户点击"刷新索引"手动触发]
|
||||
```
|
||||
|
||||
- 构建与缓存加载均在 `QtConcurrent` 后台线程执行，界面显示模态进度框；
|
||||
- **手动更改路径**后需点"刷新索引"重新加载（弹窗提示）；
|
||||
- 每次转码任务完成后 `MainWindow` 调用 `refreshIndexSilent()`：双模式**静默**（无弹窗）依次后台刷新并写缓存。
|
||||
|
||||
#### 5.5.3 调用链查询与树渲染
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([runQuery 函数名]) --> B["buildCallTree（向下被调链）<br/>buildCallerForest（向上调用方森林，每条链以向下链收尾）"]
|
||||
B --> C[populateTree 渲染调用链树]
|
||||
C --> D["树列：函数名 / 目录 / 模块<br/>默认展开 2 级，列宽按内容自适应"]
|
||||
D --> E{节点状态}
|
||||
E -- ok --> F[普通行]
|
||||
E -- notfound --> G["[未找到] 红色字"]
|
||||
E -- cycle --> H["[循环调用] 橙色字"]
|
||||
E -- depthlimit --> I["[层级截断]"]
|
||||
E -- supported --> J["[原代码已支持] 整行绿色高亮<br/>行前带 UFT3 功能号前缀（功能号来自 UFT3 元数据）"]
|
||||
D --> K["当前查询节点整行蓝色高亮<br/>（自定义 Delegate 强制绘制，绕过 Ela 主题覆盖）"]
|
||||
```
|
||||
|
||||
- 状态 `supported` 表示函数未在检索目录源码中找到，即无需转码、原代码已支持；
|
||||
- 高亮经 `RowHighlightRole` / `RowHighlightBlueRole` + 自定义 `CallTreeDelegate` 强制绘制，避免 Ela 主题覆盖背景色。
|
||||
|
||||
#### 5.5.4 导出设计
|
||||
|
||||
- **导出调用文件**（转码业务）：收集链路上所有非 `supported` 节点的源文件，按相对检索根的目录结构复制到 `<检索路径>\function_output\<查询函数名>\`，并生成链路文本 `_call_chain.txt`（缩进树形，含状态标记）；
|
||||
- **导出调用链路**（非转码业务）：仅生成 `_call_chain.txt`，不复制源文件；
|
||||
- 目录名经 `sanitizeDirName` 清洗 Windows 非法字符。
|
||||
|
||||
### 5.6 数据映射模块（TableMappingPage / FunctionMappingPage）
|
||||
|
||||
**职责**：维护 UF20 → UFT3 的**表替换**（`tableCompareUf2_Uf3`）与**函数替换**（`functionReplace`）映射，两页代码同构，均读写 `cust.json` 对应节点；转码引擎按映射替换代码中的表名/函数名。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([进入表替换 / 函数替换页]) --> B["readCustJson 读取映射节点"]
|
||||
B --> C["渲染表格（QStandardItemModel）<br/>QSortFilterProxyModel 两列不区分大小写过滤"]
|
||||
C --> D{用户操作}
|
||||
D -- 双击 / F2 编辑 --> E[更新模型]
|
||||
D -- 添加 --> F["弹窗：UF20 名必填 + 查重"]
|
||||
D -- 删除选中 --> G[二次确认（支持多选）]
|
||||
E --> H[点击保存]
|
||||
F --> H
|
||||
G --> H
|
||||
H --> I["读取原始文本<br/>extractTopLevelKeyOrder 提取顶层 key 顺序"]
|
||||
I --> J["writeCustJson 按序写回：<br/>本映射节点有序输出，其余节点原样保留"]
|
||||
J --> K["保存后 2s 内忽略 fileChanged<br/>（QTimer）并重新 addPath"]
|
||||
L[外部编辑 cust.json] -. fileChanged .-> M[loadData 立即刷新]
|
||||
```
|
||||
|
||||
**要点：**
|
||||
|
||||
- 保存采用**保留顶层 key 顺序的整体重写**：先从原始文本用正则提取 key 出现顺序，再按顺序写出，避免 JSON 重排破坏手工维护的文件结构；
|
||||
- 自身保存后 2 秒内的 `fileChanged` 事件被忽略（防回环），此后恢复监听；
|
||||
- 添加弹窗校验：UF20 名非空且不与现有行重复。
|
||||
|
||||
### 5.7 元数据更新页面（MetadataUpdatePage）
|
||||
|
||||
**职责**：元数据更新的人机入口——勾选更新范围、触发更新、展示进度与统计结果（见 §4.1 时序图）。
|
||||
|
||||
- 页面分 **UFT30更新范围** 与 **UF20更新范围** 两个勾选卡片（UFT30：数据类型/标准字段/表结构/接口数据；UF20：数据类型/标准字段/标准错误号/接口数据/常量/菜单功能/模块/表结构），提供全选/全不选快捷操作；
|
||||
- **强制全量更新**复选框（勾选需二次确认）：默认增量更新（mtime 比对），勾选后全量重扫重建；
|
||||
- 源码扫描范围来自设置页配置的项目环境路径（见 §5.8）。
|
||||
|
||||
### 5.8 设置页面（SettingsPage）
|
||||
|
||||
**职责**：环境路径与界面主题配置。
|
||||
|
||||
| 配置项 | 说明 |
|
||||
| --- | --- |
|
||||
| UFT30 / UF20 / UF20账户项目环境路径 | 元数据更新与转码引擎的源码扫描根目录 |
|
||||
| 转码生成路径 | 转码结果输出目录 |
|
||||
|
||||
- 路径保存于 `config.ini` 的 `[projectPath]` 节；保存时程序自动同步维护 `uft30pub = <UFT30路径>\upub\dev_codes`；
|
||||
- 主题模式（日间/夜间）即时切换；"恢复默认"需二次确认。
|
||||
|
||||
---
|
||||
|
||||
## 6. 公共支撑模块
|
||||
|
||||
### 6.1 DataCache（单例）
|
||||
|
||||
- 元数据缓存的门面：双库（`uf20_cache.db` / `uft3_cache.db`，位于 `bin/uf2touft3/cache/`），由 QSqlDatabase 直接管理，无独立 SQLite 封装类；表结构统一为 `(name TEXT PRIMARY KEY, data TEXT)`（`data` 存 JSON），与 Python 侧 `src/store/schema.py` 对齐；
|
||||
- **原子写**：`saveDataset()` 先写临时表再 `RENAME` 替换正式表，随后更新 `_meta` 表记录源文件 mtime，供增量更新判断；
|
||||
- **写闸门**：`saveDataset()` 全程持有 `m_writeGate` 写闸门；`clearCache()` 以 `tryLock` 探测在途落库任务——在途时仅重置内存状态并记录警告、跳过连接重置，避免关闭正在写入的连接（闸门在 `database()` 取连接之后获取，锁序安全无死锁，详见 §8.4）；
|
||||
- **内存功能索引**：`refreshFunctionCache()` 将两库功能表加载至内存（`FunctionInfo{cname, eName, functionNo}`），支撑功能查询页即时检索；启动时 `MainWindow` 经 `warmupFunctionCacheAsync(db)` **异步预热**（后台线程构建内存索引，幂等：已就绪/在途跳过，详见 §8.6）；
|
||||
- **检索 API**：`searchUF20Functions()` / `searchUFT3Functions()` 支持按中文名/英文名/功能号字段过滤，均有**单词与多词两个重载**——多词版（`QStringList` + `keywordsWithoutMatch` 出参）实现 OR 并集、按 `cname|functionNo` 去重与零命中统计，单词版内部委托多词版；两库共用匿名命名空间 `filterFunctionInfos()` 过滤实现——代码检索"按功能号检索"即经 `searchUFT3Functions(raw, "function_no", true)` 将功能号解析为函数英文名；
|
||||
- **数据集 API**：`datasetExists()` / `getAllRows()` / `getRowData()` 供功能查询页读取指定功能完整数据。
|
||||
|
||||
### 6.2 LogManager（单例）
|
||||
|
||||
- 两步初始化：`initLogConfig()` 读取 `change_code.ini` 的 `[log]` 节（级别/开关），`initLogFile()` 按"日期前缀"命名在 `exe/logs/` 目录创建日志文件；
|
||||
- 提供 `log / logInfo / logWarning / logError` 四级接口，MainWindow、ConfigManager、ConfigReaderBase 及各页面统一经单例写入。
|
||||
|
||||
### 6.3 ConfigManager（单例）
|
||||
|
||||
- 管理 `config.ini`（`[projectPath]` 节），启动时全量加载至内存缓存；
|
||||
- `setValue()` 更新缓存并立即回写文件；读取侧复用 `ConfigReaderBase`（QSettings 兼容读取，加载过程经 LogManager 记录）。
|
||||
|
||||
### 6.4 Constants.h（全局常量）
|
||||
|
||||
| 常量 | 值 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| ToolDir / ChangeCodeDir / FunctionOutput / CacheDir | `uf2touft3` / `change_code` / `function_output` / `cache` | 引擎目录与输出子目录 |
|
||||
| Exe | `uf2touft3.exe` | 转码引擎可执行文件名 |
|
||||
| CustJson / CustNonLsJson | `config/cust.json` / `config/cust_nonls.json` | 转码配置文件 |
|
||||
| Uf20DbFile / Uft3DbFile | `uf20_cache.db` / `uft3_cache.db` | 双缓存库文件名 |
|
||||
| ChangeCodeIni | `change_code.ini` | 路径持久化与日志配置文件 |
|
||||
| CodeSearch::ConvertPathKey / SearchPathKey | `codeSearch/convertPath` / `codeSearch/searchPath` | 代码检索路径配置键 |
|
||||
| updateInfo() | `<Base>/download/uft3changecode/update_info.json` | 版本检查地址 |
|
||||
|
||||
另含界面表格列索引、递归扫描标志等常量，集中管理避免魔法数字。
|
||||
|
||||
### 6.5 CallChainAnalyzer（调用链分析）
|
||||
|
||||
代码检索页持有两个实例（转码业务 / 非转码业务），各自独立索引与缓存。
|
||||
|
||||
| 环节 | 方法 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 全量构建 | `buildIndex` | 扫描源码目录解析调用关系，完成后 `saveToCache` 持久化 |
|
||||
| 快速粗判 | `cacheQuickValid` | 比对源目录特征与缓存指纹，秒级判断缓存是否可复用 |
|
||||
| 缓存加载 | `loadFromCache(skipFingerprint)` | 命中时秒级恢复索引；`skipFingerprint=true` 跳过指纹校验强制重载 |
|
||||
| 最优匹配 | `lookupBest` | 将输入函数名解析为索引中的目标函数 |
|
||||
| 向下被调 | `buildCallTree` | 以查询函数为根展开"它调用了谁" |
|
||||
| 向上调用方 | `buildCallerForest` | 反向展开"谁调用了它" |
|
||||
|
||||
- 节点状态：`ok` / `notfound`（索引中未找到）/ `cycle`（循环调用，终止展开）/ `depthlimit`（超出深度上限）/ `supported`（转码业务中该函数已支持转码，绿色标识）；
|
||||
- 查询流程：双击列表行 → `runQuery` → buildCallTree + buildCallerForest → 填充树控件 → `expandToDepth(2)` 默认展开两层；蓝色当前行、绿色 supported 行经自定义 Role 由 CallTreeDelegate 强制绘制。
|
||||
|
||||
### 6.6 PythonRunner（引擎进程封装）
|
||||
|
||||
- `RunMode` 枚举：`UsePackagedExe`（打包 exe）/ `UsePythonScript`（Python 脚本）/ `AutoDetect`；本程序固定采用 UsePackagedExe，指向 `bin/uf2touft3/uf2touft3.exe`；
|
||||
- 封装 QProcess：`start()` 启动、`stop()` 终止、`runSync()` 同步等待；`start()` 为**异步启动**（不再 `waitForStarted` 阻塞 UI 线程），重复发起检查覆盖 `Starting/Running` 状态；
|
||||
- 信号：`finished(exitCode)` / `standardOutput(QString)` / `standardError(QString)` / `errorOccurred(QProcess::ProcessError)`；MainWindow 将输出汇聚至页面日志区，`finished` 用于解除任务互斥，`errorOccurred` 的 `FailedToStart` 用于启动失败收尾（详见 §8.5）。
|
||||
|
||||
### 6.7 VersionChecker
|
||||
|
||||
- 启动时经 QNetworkAccessManager 拉取 `update_info.json`，解析多版本发布列表，取 `Version::compare` 比较后的最大版本为最新版；
|
||||
- 与当前版本比较后发射 `newVersionAvailable(latestVersion, releaseNotes)` / `checkError(msg)` / `noUpdateNeeded()`，MainWindow 弹出更新提示，"关于"页亦可手动检查。
|
||||
|
||||
---
|
||||
|
||||
## 7. 数据设计
|
||||
|
||||
### 7.1 SQLite 缓存库
|
||||
|
||||
- 位置：`bin/uf2touft3/cache/`，双库 `uf20_cache.db` / `uft3_cache.db`；
|
||||
- 每个元数据文件一张表：`(name TEXT PRIMARY KEY, data TEXT)`，`data` 为该文件解析结果的 JSON；
|
||||
- `_meta` 表记录每张表对应的源文件 mtime，元数据更新时据此跳过未变化文件（增量更新）；
|
||||
- 原子写：新建临时表插入完成后 `RENAME` 覆盖正式表，避免中途失败留下半写状态。
|
||||
|
||||
### 7.2 cust.json（转码配置）
|
||||
|
||||
| 配置 | 内容 | 消费方 |
|
||||
| --- | --- | --- |
|
||||
| `tableCompareUf2_Uf3` | UF20→UFT3 表名映射 | 全量/按需转码的表替换 |
|
||||
| `functionReplace` | 函数替换规则 | 转码的函数替换 |
|
||||
| 其余键 | 引擎自身配置 | 原样透传 |
|
||||
|
||||
- 数据映射两页各自只读写所属节，其余内容原样保留；
|
||||
- 程序保存时经 `extractTopLevelKeyOrder` 提取顶层 key 顺序、`writeCustJson` 按原顺序写回，不破坏 JSON 键序。
|
||||
|
||||
### 7.3 cust_nonls.json（非转码业务配置）
|
||||
|
||||
```json
|
||||
{
|
||||
"convert": {
|
||||
"dir": { "功能名": 0, "另一功能": -1, "*": 0 },
|
||||
"ext": ["c", "h"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `dir.<功能名>`：`0` 纳入转码、`-1` 不纳入；`"*"` 为兜底键；
|
||||
- `ext`：纳入转码的扩展名白名单；
|
||||
- 兼容旧版数组格式（仅扩展名列表），读取时自动转换。
|
||||
|
||||
### 7.4 ini 配置
|
||||
|
||||
| 文件 | 节/键 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| config.ini | `[projectPath]` | UFT30/UF20/项目环境路径、转码生成路径；保存时同步维护 `uft30pub = <UFT30路径>\upub\dev_codes` |
|
||||
| change_code.ini | `[log]` | 日志级别/开关，LogManager 启动时读取 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 关键设计决策与问题记录
|
||||
|
||||
### 8.1 表格刷新不使用 blockSignals
|
||||
|
||||
按需转码页 `updateTable()` 全量刷新模型时**有意不用** blockSignals：QTableView 依赖 `rowsRemoved` / `rowsInserted` 信号更新内部布局缓存，屏蔽信号会导致新增行不可见。替代方案：先 `removeRows` 清空再逐行重建；`m_recursionMap` 已预填充，值相等时不写盘，避免刷新回环。
|
||||
|
||||
### 8.2 启动时引擎存在性校验
|
||||
|
||||
MainWindow 启动即校验 `bin/uf2touft3/uf2touft3.exe` 是否存在：缺失时记录错误日志并界面提示，后续转码请求直接拒绝，避免 QProcess 启动失败的报错含糊难排查。
|
||||
|
||||
### 8.3 外部配置修改的监听与防抖
|
||||
|
||||
两套机制并行，按页面职责选择：
|
||||
|
||||
| 页面 | 监听对象 | 机制 |
|
||||
| --- | --- | --- |
|
||||
| 全量转码 / 按需转码 | cust.json / cust_nonls.json | 同时监听**文件与所在目录**（Windows 编辑器原子替换"写临时文件→重命名"常使 fileChanged 失效，directoryChanged 更可靠）；变更后经 300ms 防抖定时器，比对 mtime 有变化才重载 |
|
||||
| 数据映射（表/函数替换） | cust.json | `fileChanged` 后立即重载；程序自身保存后 2 秒内（`m_isSaving` + `QTimer::singleShot(2000)`）忽略变更，防止保存回环 |
|
||||
|
||||
### 8.4 落库与清缓存的并发保护（写闸门）
|
||||
|
||||
`saveDataset()`（后台线程落库）与 `clearCache()`（重置缓存连接）并发时，直接关闭连接会中断在途写入。设计：`saveDataset` 取得数据库连接后全程持有 `m_writeGate` 写闸门；`clearCache` 等待预热任务结束后以 `tryLock` 探测闸门——加锁失败说明落库在途，仅重置内存状态并记录警告、跳过连接重置；加锁成功则持闸门完成连接清理。锁序安全：`saveDataset` 在取闸门前已完成 `database()` 调用（`m_connMutex` 短暂持锁即释放），与 `clearCache` 的"闸门 → 连接锁"顺序不构成死锁环。
|
||||
|
||||
### 8.5 转码引擎异步启动与幂等收尾
|
||||
|
||||
`PythonRunner::start()` 原在主线程 `waitForStarted(3000)` 等待启动，杀毒软件扫描引擎 exe 时界面可卡顿达 3 秒。现改为异步启动：`start()` 触发 `QProcess::start` 后立即返回，启动结果经 `started` / `errorOccurred` 信号异步上报。MainWindow 连接 `errorOccurred`，对 `FailedToStart` 立即执行失败收尾（恢复两 Tab 界面并提示）；配合 `m_taskActive` 在途守卫，正常结束（`finished`）与启动失败（Qt 对 FailedToStart 亦会补发 `finished(-1, CrashExit)`）两条路径的收尾**幂等**——先到者执行、后到者跳过，避免重复弹窗。`runSync()` 同步语义不受影响（启动失败视为"已结束"，`waitForFinished` 立即返回）。
|
||||
|
||||
### 8.6 功能缓存启动预热
|
||||
|
||||
功能查询内存缓存（2 万~5 万条）原先在**首次进入页面时于主线程同步重建**（uf20 约 4.3s、uft3 约 2.7s），且 uft3 无触发点、每次进页都重建。现改为**启动即预热**：`MainWindow` 构造尾部经 `QTimer::singleShot(0, ...)` 在首帧渲染完成后调用 `DataCache::warmupFunctionCacheAsync("uf20"/"uft3")`，向 QtConcurrent 线程池提交后台重建；接口**幂等**（缓存已就绪或预热在途时直接返回），进页面时的同步路径仅在预热未完成且等待超限（≤5s）时才兜底重建，正常情况下进页面"接管"预热结果即可，无感知加载。元数据更新落库后 `refreshFunctionCache` 触发重建，预热不干扰该链路。
|
||||
|
||||
### 8.7 转码失败的准确判定（FAIL 行检测）
|
||||
|
||||
引擎在**个别文件转码失败时退出码仍为 0**（实测：`[N/M] FAIL 函数名` 行后流水线正常收尾），仅凭退出码会把失败误报为"转换完成"。设计：`MainWindow::onPythonRunnerOutput` 在解析链**最前端**做失败检测——正则累计 `FAIL` 行数（含 `[n/m]` 计数格式），并匹配汇总行 `批量转码完成: X/Y 通过, Z 失败` 取最大值，累计至 `m_failCount`；`[n/m]` 翻译进度解析仅在无 FAIL 行时执行（FAIL 行含 `[n/m]` 会被误判为进度百分比）。收尾（`onPythonRunnerFinished`）按 `正常退出 && 退出码==0 && m_failCount==0` 路由成败：失败时调用两页 `onConvertFailed`——进度条**保持当前进度**（不置 100%）、状态显示"转换失败（N 个文件转换失败）"、日志记录 ERROR 并弹窗提示查看 `logs\` 日志。
|
||||
|
||||
---
|
||||
|
||||
## 9. 构建与部署
|
||||
|
||||
### 9.1 构建
|
||||
|
||||
- Qt 6.6.2（MinGW 64-bit）+ ElaWidgetTools + CMake；
|
||||
- 第三方库经 `3rdparty/` 引入，构建产出 `bin/Uft30ChangeCode.exe`。
|
||||
|
||||
### 9.2 部署清单（bin/）
|
||||
|
||||
| 路径 | 说明 |
|
||||
| --- | --- |
|
||||
| `Uft30ChangeCode.exe` | 主程序 |
|
||||
| `uf2touft3/uf2touft3.exe` | 转码引擎（外部进程） |
|
||||
| `uf2touft3/config/cust.json` | 表/函数映射配置（数据映射页读写） |
|
||||
| `uf2touft3/config/cust_nonls.json` | 非转码业务配置（业务转码页读写） |
|
||||
| `uf2touft3/cache/uf20_cache.db` / `uft3_cache.db` | 元数据缓存库（首次元数据更新生成） |
|
||||
| `config.ini` / `change_code.ini` | 程序路径配置 / 日志配置 |
|
||||
| `logs/` | 日志输出目录（运行生成） |
|
||||
| `change_code/`、`uf2touft3/function_output/` | 转码输出 / 调用链导出目录（运行生成） |
|
||||
|
||||
---
|
||||
|
||||
## 10. 附录：页面与源码对照
|
||||
|
||||
| 页面/功能 | 源码位置 |
|
||||
| --- | --- |
|
||||
| 主窗口与导航、引擎调度 | `src/mainwindow/` |
|
||||
| 业务转码 | `src/pages/businessconvert/`（容器）+ `src/pages/batchconvert/`（全量）+ `src/pages/nonlsconvert/`（按需） |
|
||||
| 功能查询 | `src/pages/functionsearch/`（UF20 / UFT3 双模式） |
|
||||
| 代码检索 | `src/pages/codesearch/`（含 CallChainAnalyzer） |
|
||||
| 数据映射 | `src/pages/datamapping/`（TableMappingPage / FunctionMappingPage） |
|
||||
| 元数据更新 | `src/pages/metadataupdate/`（页面）+ `src/metadataupdate/`（解析器组） |
|
||||
| 设置 / 关于 | `src/pages/settings/` / `src/pages/about/` |
|
||||
| 公共支撑 | `src/utils/`（DataCache、LogManager、ConfigManager、VersionChecker、Constants 等）、`src/pythonrunner/`、`src/components/` |
|
||||
Reference in New Issue
Block a user