# Uft30ChangeCode 使用手册

| 文档信息 | 内容 |
| --- | --- |
| 软件名称 | Uft30ChangeCode（UF20 → UFT3 转码工具） |
| 手册版本 | V1.6.0 |
| 更新日期 | 2026-10-02 |
| 适用对象 | 使用本工具进行代码转码的开发/维护人员 |

---

## 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 函数名映射 |
| 元数据更新 | 解析源码、构建/刷新元数据缓存 |
| 设置（底部） | 项目环境路径与主题配置 |
| 帮助 / 关于（底部） | 在线帮助、版本信息 |

![主界面总览（功能转码 → 业务转码）](images/01_main_overview.png)

## 5. 功能操作详解

### 5.1 元数据更新（首次使用必做）

![元数据更新页面](images/11_metadata_update.png)

**前提**：元数据更新按"设置"页配置的项目环境路径扫描源码，请先完成 §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 全量转码

![全量转码工作台](images/01_main_overview.png)

**说明**：全量转码仅支持 **LS_ 开头**的功能（"内存交易"改造范围），按清单对功能进行整体转码。清单保存在 `cust.json` 的 `convert.dir` 节点（见 §6.1）。

**表格列**：`UF20函数名` | `是否存在` | `核心` | `是否柜面接口`（**双击函数名所在行**可在弹窗中修改函数名）。

- "是否存在"显示 **否**：说明元数据未更新或该功能在 UF20 元数据中检索不到（见 §7 FAQ）；
- **核心**：下拉选择该功能转码后归属的核心，可选 **ucbp**（默认）/ **uses** / **uarg** / **usms**；SQL 方言由核心自动派生——ucbp/uses 对应 mdb，uarg/usms 对应 db；
- **是否柜面接口**：下拉选择 **否**（默认）/ **是**，标识该功能是否为柜面接口；
- 每次显示页面时自动刷新"是否存在"列。

**操作步骤：**

1. 切到 **全量转码** Tab；
2. 点击 **添加**，弹窗内**每行输入一个** LS_ 函数名（支持批量粘贴）；输入非 LS 函数将被拒绝，并提示切换到"按需转码"；
3. 也可在 **UF20功能查询** 中双击或右键选中 LS_ 功能直接加入（见 §5.3.1）；
4. **双击函数名所在行**可在弹窗中修改函数名；**删除选中** / **清空列表**（二次确认）维护清单；
5. 点击 **开始转换**，进度条与状态文字显示转换进度；转换中按钮变为 **停止转换**，可随时点击终止任务。

**清单同步**：手工编辑 `cust.json` 保存后约 0.3 秒内界面自动刷新（文件监视 + 防抖），程序与手工编辑双向同步。

##### 5.2.1.2 按需转码

![按需转码工作台](images/03_ondemand_convert.png)

**说明**：按需转码针对**非 LS 功能**转码，支持**单文件转码**与**递归转码**两种模式，转码范围不包含核心文件、module 模块文件。

- **非递归模式**：仅对目标文件本身执行转码，不会处理该文件内调用的函数；
- **递归模式**：转码目标文件的同时，自动对文件中所调用的关联函数一并完成转码。

**添加功能（三种方式）：**

- **方式一（推荐）**：进入 **UF20功能查询**，双击或右键目标非 LS 函数（支持多选后右键批量加入）→ 弹窗提示"已将 N 个功能加入**按需转码**"；
- **方式二**：按需转码 Tab 点击 **添加**，弹窗内每行输入一个函数短名（如 `AS_xxx`）；误带 `.service_design` 等后缀会自动剥离；新增功能递归模式默认 **否**；若输入 LS_ 开头函数仅给出提示（建议放入全量转码），不会拦截；
- **方式三**：手工编辑配置文件 `cust_nonls.json`（见 §6.2），保存后程序自动检测并刷新界面。

**表格列**：`UF20函数名` | `是否存在` | `是否递归` | `db模式`（**双击函数名所在行**可在弹窗中修改函数名）。

- LS_ 开头的函数名以橙色字体显示提醒（不拦截）。

**设置递归模式与 db 模式：**

1. 在目标行的 **是否递归** 下拉框选择 **否**（单文件）或 **是**（递归）；
2. 在 **db模式** 下拉框选择 SQL 语法转换方言：**否** = mdb（默认）、**是** = db；
3. 选择后立即写入 `cust_nonls.json` 并生效，无需额外点击。

**执行转码：** 点击 **开始转换**，进度显示与停止方式同全量转码；任务互斥规则相同。

**清单同步**：外部编辑保存后约 0.3 秒内界面自动刷新，支持程序内修改与外部文件修改双向同步。

#### 5.2.2 代码检索

![代码检索页面（转码业务模式）](images/04_code_search.png)

**说明**：代码检索用于查看功能的**调用链路**——该功能调用了哪些下游函数、被哪些上游功能调用，用于转码前评估影响范围、转码后核对结果。

页面顶部 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 功能查询

![UF20 功能查询页面（批量关键词：证券）](images/05_uf20_function_search.png)

**操作步骤：**

1. 进入 **UF20功能查询** 页；
2. 左侧下拉选择检索字段：**函数名** / **功能号**，输入关键字回车或点搜索图标；
   - **批量查询**：多个关键词用**逗号、分号或空格**分隔（中英文均可），如 `LS_证券参数, LS_股票名单`；各关键词命中结果取**并集**展示；
   - 单个关键词可命中同一功能的多个字段，结果按"函数名+功能号"自动去重；
3. 搜索框内可切换**精确匹配**（默认模糊匹配）；
4. 查看结果列表，列：`函数名`、`英文名`、`功能号`；
5. **双击或右键选中行一键加入转码工作台**：LS_ 开头功能 → **全量转码**；其它功能 → **按需转码**；
   - 支持 **Ctrl/Shift 多选**后一次加入；右键行不在选区内时仅加入该行；
   - 加入结果**只弹一个提示框**（"全量转码"、"按需转码"字样加粗）：同时包含两类功能时显示"已将 N 个功能加入全量转码，已将 M 个功能加入按需转码"；重复添加的功能自动跳过并在提示中注明；全部已存在时提示"均已在转码列表中"。

**查询提示**：查询反馈显示在页面底部提示栏（颜色随日间/夜间主题自动适配），不弹对话框打断操作——输入为空提示"请输入查询内容"；无匹配结果提示"⚠️ 未找到匹配的功能"；查询成功后显示"已查询 X 个业务功能函数（M 个无匹配）"并接默认操作提示。

#### 5.3.2 UFT3 功能查询

![UFT3 功能查询页面（关键词：fund）](images/06_uft3_function_search.png)

- 界面与 UF20 功能查询一致（函数名 / 功能号检索、**批量关键词**、精确匹配），结果列为 `函数名`、`英文名`、`功能号`，查询提示同样在页面底部提示栏反馈；
- 仅用于查询核对 UFT3 功能元数据，**双击/右键不加入转码清单**；
- 代码检索中"原代码已支持"行前的功能号即来自 UFT3 元数据。

#### 5.3.3 UF20 & 内存表映射查询

![UF20 & 内存表映射查询页面（模糊查询：acct）](images/07_table_mapping_search.png)

检索 UF20（2.0）表与内存表之间的映射关系，结果四列：`UF20表名`、`UF20表中文名`、`内存表名`、`内存表中文名`；**双击结果行可添加映射到「数据映射 → 表替换」**。

**操作步骤：**

1. 进入 **功能查询 → UF20 & 内存表映射查询**；
2. 输入 **UF20 表名或内存表名**（二者均可检索），回车或点搜索图标；
   - **批量查询**：多个表名用**逗号、分号或空格**分隔（中英文均可），各关键词命中结果取并集展示；
   - 搜索框内可切换**精确匹配**（默认模糊匹配，不区分大小写）；
3. 查看结果列表：
   - 映射关系命中（表名在映射文件 `bin/uf2touft3/config/table_mapping.json` 中配置过）→ 四列完整展示，中文名分别取自 `uf20_cache.db` / `uft3_cache.db`；一个 UF20 表映射到多个内存表（value 为数组）时展示为多条记录；
   - 无映射关系 → 仅展示数据库中能取到的一侧字段，映射相关列置空，底部提示注明无映射数量；
4. **双击结果行**将该映射关系添加到「数据映射 → 表替换」：
   - 仅当该行 UF20 表名与内存表名均非空（有完整映射关系）才可添加；
   - 表替换中已存在该 UF20 表名时自动跳过，并在提示栏注明当前映射值（不覆盖）；
   - 添加成功后**自动保存**到 `cust.json`（提示栏回执"已添加并自动保存"，无需再到表替换页手动保存），同时同步追加到映射文件 `table_mapping.json` 中缺失的条目，**再次查询立即可见**。

**查询提示**（页面底部提示栏，不弹窗）：默认提示"💡 输入 UF20 表名或内存表名进行查询，支持精确/模糊匹配；双击记录行可添加到「数据映射 → 表替换」"；无命中提示"⚠️ 未找到匹配的表"；缓存库无表数据提示"请先在「元数据更新」页面执行更新"；**映射文件解析失败**（手工编辑 `table_mapping.json` 留下尾随逗号、缺引号等）提示"⚠️ 映射文件 table_mapping.json 解析失败（第 N 行附近）…"并停止查询（不再单侧展示，避免误判为映射丢失），按行号修正文件后重新查询即可；成功显示"已查询 X 条记录（其中 Y 个无映射关系，N 个表中文名缺失，M 个关键词无匹配）"——一对多映射按多条记录计；中文名缺失表示映射关系里有该表、但本地缓存库未收录（元数据更新未覆盖该表来源工程），需扩大元数据更新的工程范围。

### 5.4 数据映射

**说明**：数据映射维护 UF20 → UFT3 的**替换对照表**与**不转码清单**，转码引擎按映射替换代码中的表名 / 函数名，清单内的功能函数名则跳过替换。各页数据均保存在 `cust.json`（见 §6.1）；界面修改后点 **保存** 写盘生效，外部编辑 `cust.json` 保存后界面自动刷新（程序自身保存后的 2 秒内暂停文件监控，此间的外部修改需再次保存文件才会被检测到）。

#### 5.4.1 表替换

![表替换页面](images/08_table_replace.png)

维护 UF20 表名 → UFT3 表名的映射。

**操作步骤：**

1. 进入 **数据映射 → 表替换**；
2. 顶部搜索框实时过滤两列内容（不区分大小写）；
3. **双击单元格**直接修改；
4. 点 **添加** 弹窗输入 UF20 / UFT3 表名（UF20 表名必填且不可重复）；
5. **删除选中** 需二次确认（支持多选）；
6. 修改后点 **保存** 生效；保存成功后自动与映射文件 `bin/uf2touft3/config/table_mapping.json` 对账同步，「UF20 & 内存表映射查询」中**立即可查**：
   - **新增**的映射自动追加到该文件；
   - **修改一对一映射的内存表名**后，文件中同名条目的值同步更新；
   - 该文件中配置为**一对多数组**的条目（一个 UF20 表对应多个内存表）保持不变，不会被表替换中的单值覆盖；
   - 在表替换中**删除**条目暂不同步到该文件（映射文件是全量参考库，删除仅表示转码时不再使用该替换）。

#### 5.4.2 函数替换

![函数替换页面](images/09_function_replace.png)

维护 UF20 函数名 → UFT3 函数名的映射，操作方式与表替换相同，但**不涉及** `table_mapping.json` 自动同步（该同步为表替换独有）。

#### 5.4.3 不转码功能函数

![不转码功能函数页面](images/10_nochange_fullname.png)

维护**不参与函数名替换**的功能函数清单，对应 `cust.json` 顶层键 `noChangeFullNameCode`（字符串数组）。转码时，清单内的功能函数名保持原样，不做 UF20 → UFT3 全名替换。

**操作步骤：**

1. 进入 **数据映射 → 不转码功能函数**；
2. 顶部搜索框实时过滤条目（不区分大小写）；
3. **双击单元格**直接修改；
4. 点 **添加** 弹窗输入功能函数名（必填，重复时保存被拦截提示）；
5. **删除选中** 需二次确认（支持多选）；
6. 修改后点 **保存** 生效；保存按原文件顶层键顺序写回 `cust.json`，不影响其它配置。

> **典型用途**：某功能在 UFT3 中名称未变化、或不希望被批量替换时，将其加入本清单即可跳过替换。

### 5.5 系统设置（底部"设置"）

![系统设置页面](images/12_settings.png)

**环境配置**：

| 配置项 | 说明 |
| --- | --- |
| UFT30项目环境路径 | UFT30 项目根目录 |
| UF20项目环境路径 | UF20 项目根目录 |
| UF20账户项目环境路径 | UF20 账户项目根目录 |
| UF20清算项目环境路径 | UF20 清算参数项目目录，供清算相关元数据处理使用 |
| 转码生成路径 | 转码结果输出目录 |

- 路径保存在 `config\config.ini` 的 `[projectPath]` 节，供元数据更新与转码引擎使用；
- 保存时程序自动同步维护 `uft30pub = <UFT30路径>\upub\dev_codes`；
- 保存与恢复默认均**保留 config.ini 中的手工注释、空行与键顺序**，只更新对应配置项的值（程序运行期间手工编辑的配置也不会被保存动作覆盖，仅界面显式修改过的项以界面为准）；
- **元数据更新（§5.1）按这些路径扫描源码，首次使用必须先配置**。

**系统配置**：

- 主题模式：日间模式 / 夜间模式，即时切换。

**按钮**：

- **保存设置**：写盘生效；
- **恢复默认**：清空全部路径与主题并恢复默认（二次确认）。

## 6. 配置文件说明

### 6.1 cust.json

- **路径**：`bin\uf2touft3\config\cust.json`
- **作用**：一个文件承载四类配置——全量转码清单、表替换映射、函数替换映射、不转码功能函数清单。

| 节点 | 结构 | 用途 |
| --- | --- | --- |
| `convert.dir` | 对象数组，元素 `{name, core, viaUmgr, dialect}` | 全量转码清单（含核心、柜面接口配置） |
| `tableCompareUf2_Uf3` | 对象 `{UF20表名: UFT3表名}` | 表替换映射 |
| `functionReplace` | 对象 `{UF20函数名: UFT3函数名}` | 函数替换映射 |
| `noChangeFullNameCode` | 字符串数组 | 不转码功能函数清单，转码时跳过这些函数名的替换 |

`convert.dir` 元素字段说明（详见 `docs/详细设计文档.md` §7.5）：

| 字段 | 说明 |
| --- | --- |
| `name` | 功能名（含 `.service_design` 后缀） |
| `core` | 归属核心：`ucbp`（默认）/ `uses` / `uarg` / `usms` |
| `viaUmgr` | 是否柜面接口：`false`（默认）/ `true` |
| `dialect` | SQL 方言，由 core 派生：`ucbp`/`uses` → `mdb`，`uarg`/`usms` → `db`（程序保存时自动生成，无需手工填写） |

**手工编辑示例（以实际文件结构为准）：**

```json
{
    "convert": {
        "dir": [
            {
                "name": "LS_CustQry.service_design",
                "core": "ucbp",
                "viaUmgr": false,
                "dialect": "mdb"
            },
            {
                "name": "LS_AcctChk.service_design",
                "core": "uarg",
                "viaUmgr": true,
                "dialect": "db"
            }
        ]
    },
    "tableCompareUf2_Uf3": {
        "UF20表A": "UFT3表A"
    },
    "functionReplace": {
        "UF20函数1": "UFT3函数1"
    },
    "noChangeFullNameCode": [
        "AF_NoChange1",
        "LF_NoChange2"
    ]
}
```

**编辑注意：**

- 程序内修改（全量转码 / 表替换 / 函数替换 / 不转码功能函数页）会自动写回该文件；
- 手工编辑保存后各页面自动检测并刷新；
- 全量转码清单函数名可省略 `.service_design` 后缀展示，`dir` 为对象数组结构，程序保存时保留文件其余内容与格式；
- 兼容旧版 `dir` 为字符串数组（仅函数名）的格式，旧条目按 core=ucbp、viaUmgr=false、dialect=mdb 加载。

### 6.2 cust_nonls.json（按需转码清单）

- **路径**：`bin\uf2touft3\config\cust_nonls.json`
- **作用**：保存按需转码功能清单及每项的递归标志与 SQL 方言（db 模式），供界面与转码引擎共用。

| 节点 | 结构 | 说明 |
| --- | --- | --- |
| `convert.dir[功能名]` | 对象 `{depth, dialect}` | `depth`: `0` = 否（单文件转码）、`-1` = 是（递归转码）；`dialect`: `mdb` = 否（默认）、`db` = 是 |
| `convert.dir["*"]` | 引擎兜底键（数值） | 非清单功能，界面不展示、保存时原样保留 |
| `convert.ext` | 后缀数组 | 引擎识别的功能文件后缀，程序保存时自动维护 |

**手工编辑示例（以实际文件结构为准）：**

```json
{
    "convert": {
        "dir": {
            "*": -1,
            "AS_CustQry": { "depth": 0, "dialect": "mdb" },
            "LF_AcctChk": { "depth": -1, "dialect": "db" }
        },
        "ext": [
            ".service_design",
            ".function_design",
            ".aservice_design",
            ".procedure_design",
            ".afunction_design"
        ]
    }
}
```

**编辑注意：**

- 保持 JSON 格式合法（逗号、引号完整）；若格式非法，程序将保留内存中的现有清单并在日志中记录警告；
- 兼容旧版格式：`dir` 值为数值（`0`/`-1`，无方言，按"否/mdb"加载）或为数组（无递归标志，一律按"否/mdb"加载）；
- 外部编辑保存后约 0.3 秒内界面自动刷新；程序自身写入该文件时不会触发重复刷新，可放心与手工编辑混用。

### 6.3 config.ini 与 change_code.ini

- **`bin\uf2touft3\config\config.ini`**：`[projectPath]` 节保存设置页的项目环境路径（`uft30` / `uf20` / `ufAcct20` / `UftdbSett` / `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`），含系统架构图与各模块流程图。*