# CaseOperation 

**Repository Path**: giaog/case-operation

## Basic Information

- **Project Name**: CaseOperation 
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用例格式转换服务

将 Excel/CSV 测试用例根据导入模版进行格式调整，并支持 Excel 与 XMind 双向转换；Web 端可展示转换前、转换后和并排对照内容。

## 已实现

- 支持 Excel → Excel、XMind → Excel、Excel → XMind 三种转换方式。
- 上传 `.xlsx`、`.csv` 或 `.xmind` 用例文件，自动识别表格字段或 XMind 节点。
- 可配置“前置路径”，与原始“用例目录”使用 `-` 拼接。
- 用例类型、用例状态使用下拉框；选项来自 `config/settings.json`。
- XMind → Excel 可选择输出拼接路径前的 7 列格式，或拼接路径后的 15 列导入模板格式。
- Excel → XMind 会把“用例目录”按 `-` 拆成节点，并生成带时间戳的 `.xmind` 文件。
- 展示表格或 XMind 树形节点，支持转换前、转换后、并排对照和全文搜索。
- 按静态模板生成可下载的 Excel；模板统一存放在 `resources/templates/`。
- 导出成功后自动保存历史记录、预览快照和结果文件，支持历史查看与再次下载。
- 覆盖空态、处理中、字段缺失、配置过期、成功与导出失败状态。

## 程序版本号管理

程序版本号维护在项目根目录的 `VERSION` 文件中，采用语义化版本号格式，例如 `1.2.0`。

- 后端启动时会读取 `VERSION`，并作为 FastAPI 应用版本。
- `/api/health`、`/api/version` 和 `/api/config` 会返回当前程序版本。
- Web 顶部会展示当前程序版本。
- 新生成的历史记录和 Excel → XMind 导出的 XMind 元数据会写入当前程序版本。
- 发布新版本时只需要更新 `VERSION` 文件。

## 运行环境

启动项目前，需要准备以下运行环境：

| 依赖       | 要求                                       | 作用                               |
| -------- | ---------------------------------------- | -------------------------------- |
| 操作系统     | macOS、Windows 10/11                      | 当前提供 Shell、PowerShell 和 CMD 启动脚本 |
| 终端       | macOS Terminal/zsh/bash、PowerShell 或 CMD | 执行安装和启动脚本                        |
| Conda    | Anaconda 或 Miniconda                     | 管理项目 Python 环境                   |
| Conda 环境 | 名称为 `usually`，Python 3.10 及以上版本          | 运行 FastAPI 后端及 Excel 转换逻辑        |
| pip      | 安装在 `usually` 环境中                        | 安装 `requirements.txt` 中的后端依赖     |
| Node.js  | 18 及以上版本                                 | 构建 React 前端                      |
| pnpm     | 9 及以上版本                                  | 安装前端依赖并执行 Vite 构建                |
| TCP 端口   | 默认使用 8000，可在配置文件中修改                      | 提供 Web 页面及后端接口                   |

项目不创建 `.venv`。安装和启动脚本会执行 `conda activate usually`，再使用 `usually` 环境中的 Python。Node.js 和 pnpm 仍从系统 `PATH` 获取。

### 安装并配置 Conda

安装 Anaconda 或 Miniconda，并确认 PowerShell 或 CMD 可以执行：

```powershell
conda --version
```

如果 macOS 终端尚未初始化 Conda，按当前 shell 执行其一，然后关闭并重新打开终端：

```bash
conda init zsh
conda init bash
```

如果 PowerShell 尚未初始化 Conda，执行以下命令，然后关闭并重新打开 PowerShell：

```powershell
conda init powershell
```

如果 CMD 尚未初始化 Conda，执行以下命令，然后关闭并重新打开 CMD：

```bat
conda init cmd.exe
```

本项目使用名为 `usually` 的 Conda 环境作为示例。检查环境是否存在：

```powershell
conda env list
```

如果环境不存在，可以创建：

```powershell
conda create -n usually python=3.10 -y
```

手动激活并检查环境：

```powershell
conda activate usually
python --version
python -m pip --version
```

### 安装 Node.js 和 pnpm

从 [Node.js 官网](https://nodejs.org/) 安装 Node.js 18 或以上版本。macOS 也可以使用 Homebrew：

```bash
brew install node
```

Node.js 安装完成后执行：

```bash
npm install -g pnpm
```

如果使用 Node.js 自带的 Corepack，也可以执行：

```bash
corepack enable
```

检查安装结果：

```powershell
node --version
npm --version
pnpm --version
```

如果 `conda`、`node`、`npm` 或 `pnpm` 提示“无法识别”或“不是内部或外部命令”，需要将对应程序加入系统 `PATH`，然后重新打开 PowerShell 或 CMD。

### 项目文件要求

启动前需要确认项目根目录至少包含：

- `requirements.txt`
- `package.json`
- `config/settings.json`
- `server/`
- `web/`
- `scripts/`
- `resources/templates/ugos_pro测试用例导入模板_20260901155913.xlsx`

导入模板统一存放在 `resources/templates/` 目录。模板相对路径必须与 `config/settings.json` 中的 `template_file` 一致。

## 项目启动

### 1. 首次安装依赖

macOS 方式：

```bash
cd /Users/lazy/huangsheng/project/ecxel_check
chmod +x scripts/setup.sh scripts/start.sh
./scripts/setup.sh
```

PowerShell 方式：

```powershell
cd D:\huangsheng\project\ecxel_check
.\scripts\setup.ps1
```

CMD 方式：

```bat
cd /d D:\huangsheng\project\ecxel_check
scripts\setup.cmd
```

安装脚本会先检查系统是否能找到 `conda`、`node`，并使用 `pnpm` 或 `corepack pnpm`，自动激活 Conda `usually` 环境，然后执行以下操作：

1. 使用 Conda `usually` 环境中的 Python，根据 `requirements.txt` 安装 FastAPI、openpyxl 等后端依赖。
2. 根据 `package.json` 安装 React、Vite 等前端依赖。

项目不单独创建 `.venv`，Python 依赖会安装到 Conda `usually` 环境中。

如果 PowerShell 阻止执行本地脚本，可只为当前窗口临时放开限制后重试：

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\setup.ps1
```

依赖通常只需安装一次。修改 `requirements.txt`、`package.json` 或重新拉取项目依赖后，再次运行该脚本即可。

### 2. 启动服务

macOS 方式：

```bash
cd /Users/lazy/huangsheng/project/ecxel_check
./scripts/start.sh
```

PowerShell 方式：

```powershell
cd D:\huangsheng\project\ecxel_check
.\scripts\start.ps1
```

CMD 方式：

```bat
cd /d D:\huangsheng\project\ecxel_check
scripts\start.cmd
```

启动脚本会先构建前端生产文件，然后启动 FastAPI 服务。出现以下信息表示服务已启动：

```text
Uvicorn running on http://0.0.0.0:8000
```

启动工程时不需要输入 host、port 等额外参数。`scripts/start.sh`、`scripts/start.ps1` 和 `scripts/start.cmd` 会自动读取 `config/settings.json` 中的配置：

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 8000
  }
}
```

- `server.host`：服务监听地址。使用 `0.0.0.0` 时允许本机和局域网访问。
- `server.port`：服务监听端口，必须是 1 到 65535 之间的整数。

修改端口后直接重新运行以下命令即可，不需要追加命令行参数：

macOS 方式：

```bash
./scripts/start.sh
```

PowerShell 方式：

```powershell
.\scripts\start.ps1
```

CMD 方式：

```bat
scripts\start.cmd
```

浏览器访问：

- 本机访问：`http://127.0.0.1:8000`
- 局域网访问：`http://本机IP:8000`

局域网无法访问时，macOS 需要检查系统网络权限或防火墙设置，Windows 需要检查防火墙是否允许 TCP 8000 端口。

首次启动前必须先运行 `setup.sh`、`setup.ps1` 或 `setup.cmd`。后续在依赖未变化的情况下，可以直接运行对应的 `start` 脚本。

### 3. 停止服务

在运行服务的终端、PowerShell 或 CMD 窗口按：

```text
Ctrl + C
```

## TAPD 接入

如果要把上传用例的最后一环接到 TAPD，建议把账号信息单独放在 `config/tapd.json`，不要写进代码。

先复制一份示例文件：

```bash
cp config/tapd.json.example config/tapd.json
```

推荐字段如下：

- `auth_type`：`api` 或 `web`。有 TAPD API 账号时用 `api`；只有网页登录账号时用 `web`
- `base_url`：TAPD 接口地址，默认 `https://api.tapd.cn`
- `login_url`：TAPD 网页登录地址
- `workspace_id`：项目 ID / 工作区 ID
- `project_id`：如果你们内部也习惯叫项目 ID，可以一并保留
- `username`、`password`：网页登录账号，仅 `auth_type=web` 时使用
- `api_user`、`api_password`：TAPD API 账号
- `repo_uid`、`version_uid`、`folder_uid`：如果后面走 TestX 新接口会用到
- `namespace`：如果后面走新版命名空间接口会用到

后端会自动读取这个文件；没有该文件时也不会影响当前的格式转换功能。

## Linux 运行包

如果需要发布到 Linux 服务器或 Linux 桌面环境，可以在开发机项目根目录执行：

```bash
./scripts/package_linux.sh
```

脚本会先构建前端生产文件，然后生成：

```text
release/case-format-converter-linux-时间戳.tar.gz
```

Linux 目标机解压后执行：

```bash
tar -xzf case-format-converter-linux-*.tar.gz
cd case_format
chmod +x install.sh start.sh
./install.sh
./start.sh
```

Linux 运行包内已包含 `web/dist` 前端构建结果，目标机只需要 Python 3.10 及以上版本、pip 和 venv 模块，不需要安装 Node.js、pnpm 或 Conda。Ubuntu/Debian 可先准备基础依赖：

```bash
sudo apt update
sudo apt install -y python3 python3-pip python3-venv
```

服务监听地址和端口仍由 `config/settings.json` 中的 `server.host`、`server.port` 控制。

## 使用方式

### 1. 准备源用例文件

页面根据转换方式限制可上传的文件类型：

- Excel → Excel：`.xlsx`、`.csv`，CSV 编码建议使用 UTF-8 或 GB18030。
- XMind → Excel：`.xmind`，兼容经典 `content.xml` 和新版 `content.json` 格式。
- Excel → XMind：`.xlsx`。

程序会自动选择字段匹配度最高的工作表。源文件首行应为字段名称，并至少包含以下必填列：

- `用例名称`
- `前置条件`
- `用例步骤`
- `预期结果`

建议同时提供：

- `用例目录`
- `用例等级`
- `是否是冒烟用例`，也兼容列名 `是否冒烟用例`

### 2. 选择转换方式并上传文件

先选择 Excel → Excel、XMind → Excel 或 Excel → XMind，再将对应文件拖入上传区域，或单击“选择文件”。文件读取成功后，上传区域会显示文件名和文件大小。切换转换方式会清空已选择文件，避免误用不匹配的文件类型。

### 3. 配置转换规则

- Excel → Excel：需要配置前置路径、用例类型和用例状态。
- XMind → Excel：先选择“拼接路径前”或“拼接路径后”。选择“拼接路径后”时，才需要配置前置路径、用例类型和用例状态。
- Excel → XMind：不需要配置前置路径、用例类型和用例状态。

配置项含义：

- `前置路径`：目标用例目录的固定前缀。
- `用例类型`：从模板支持的 11 种用例类型中选择。
- `用例状态`：选择正常、待更新或已废弃。

最终目录按照以下规则生成：

```text
前置路径 - 原用例目录
```

例如：

```text
测试用例新 - 监控中心模块用例 - 02_功能测试 - 区域限制
```

### 4. 转换并核对

单击“转换并预览”。转换成功后，右侧会显示用例数量和内容；Excel 以表格展示，XMind 以可展开的树形节点展示，并提供三种核对方式：

- `转换后`：查看目标表格或目标 XMind 节点。
- `转换前`：查看源表格或源 XMind 节点。
- `并排对照`：同时查看转换前后的内容。

搜索框可以按用例标题、目录、步骤或其他可见内容过滤用例。转换成功提示会在约 3 秒后自动关闭。

如果预览后修改了输出格式、前置路径、用例类型或用例状态，页面会提示配置已变更。此时需要重新单击“转换并预览”，更新结果后才能导出。

### 5. 导出结果

确认内容无误后，单击右上角的导出按钮。不同转换方式的结果如下：

- Excel → Excel：基于 UGOS\_PRO 模板生成 15 列 Excel。
- XMind → Excel（拼接路径前）：生成 7 列原始用例 Excel。
- XMind → Excel（拼接路径后）：基于 UGOS\_PRO 模板生成 15 列 Excel。
- Excel → XMind：生成 XMind 文件，以源 Excel 文件名作为主节点和文件名基础，并追加 14 位时间戳。

文件名示例：

```text
原文件名_格式转换结果.xlsx
原XMind文件名_路径拼接前.xlsx
原XMind文件名_路径拼接后.xlsx
原Excel文件名_20260901183000.xmind
```

导出的工作簿具有以下处理：

- 保留模板的 15 个标准字段。
- 移除模板中的字段填写说明行。
- 冻结首行并启用表头筛选。
- 文本自动换行，并设置适合用例内容的列宽和行高。

### 6. 查看历史记录

每次成功导出后，系统会在顶部“历史记录”入口中新增一条记录，点击后展开历史列表。历史记录支持：

- `查看`：打开当次导出保存的预览快照，可继续使用转换前、转换后和并排对照视图。
- `下载`：重新下载当次导出的 Excel 或 XMind 文件。
- `删除`：删除单条历史记录及其对应的结果文件和预览快照。
- `清空`：一次删除全部历史记录、结果文件和预览快照。

历史文件默认保存到项目根目录的 `history/` 下，其中 `files/` 存放导出文件，`previews/` 存放预览快照，`records.json` 存放历史索引。页面只显示当前保留天数提示，不提供修改入口；过期记录会在读取或写入历史时自动清理。

## 常见问题

### 页面提示缺少必填列

检查源文件第一行的列名是否包含 `用例名称`、`前置条件`、`用例步骤`、`预期结果`，并确认没有合并单元格或额外标题行。

### 转换按钮不可点击

需要先选择转换方式，并上传与该方式匹配的 `.xlsx`、`.csv` 或 `.xmind` 文件。

### XMind 转换后的用例数量不正确

建议参照项目根目录中的 `【监控中心】人脸识别合规整改.xmind` 组织节点。用例节点应包含优先级标记、前置条件备注或步骤/预期结果子节点；普通目录节点不要直接添加用例优先级标记。

### 修改配置后页面没有更新

`config/settings.json` 在服务启动时加载。修改配置后需要停止并重新启动服务。

### 提示找不到导入模板

确认模板文件位于 `resources/templates/`，并检查 `config/settings.json` 中的 `template_file` 是否填写了正确的项目相对路径。

### 8000 端口已被占用

关闭占用该端口的旧服务，或修改 `config/settings.json` 中的 `server.port`，重启服务后使用新端口访问页面。

## 配置

编辑 `config/settings.json`：

- `server.host`：服务监听地址。
- `server.port`：服务监听端口，默认 `8000`。
- `default_prefix_path`：默认前置路径。
- `path_separator`：目录拼接及 XMind 节点拆分符，当前为 `-`。
- `case_types`：用例类型下拉选项，当前包含模板支持的 11 个合法值。
- `case_statuses`：用例状态下拉选项。
- `template_file`：导入模板相对于项目根目录的路径，默认存放在 `resources/templates/`。
- `history.storage_dir`：历史文件独立存储目录，默认 `history`。
- `history.retention_days`：历史保留天数，只能配置为 `180`、`60` 或 `30`。
- `history.retention_day_options`：允许的历史保留天数选项，默认 `[180, 60, 30]`。

修改配置后需要重启服务才能生效。

## 字段映射

| 目标字段             | 来源或规则        |
| ---------------- | ------------ |
| 用例目录             | 前置路径 + 原用例目录 |
| 用例名称             | 原用例名称        |
| 需求ID             | 空            |
| 前置条件             | 原前置条件        |
| 用例步骤             | 原用例步骤        |
| 预期结果             | 原预期结果        |
| 用例类型             | 页面下拉框        |
| 用例状态             | 页面下拉框        |
| 用例等级             | 原用例等级        |
| 创建人、备注、端类型、自动化状态 | 空            |
| 是否冒烟用例           | 原“是否是冒烟用例”   |

## XMind 节点映射

项目根目录中的 `【监控中心】人脸识别合规整改.xmind` 是当前兼容规则的参考文件。XMind → Excel 时按以下规则读取：

| XMind 内容                             | Excel 字段                |
| ------------------------------------ | ----------------------- |
| 主节点                                  | 不写入“用例目录”，仅作为工作表名称和预览标题 |
| 用例节点之前的目录节点                          | `用例目录`，多级节点以 `-` 拼接     |
| 用例节点标题                               | `用例名称`                  |
| 用例节点的 `priority-1` 至 `priority-4` 标记 | `用例等级` 1 至 4            |
| 用例节点备注                               | `前置条件`                  |
| 用例节点的直接子节点                           | `用例步骤`，按行拼接             |
| 步骤节点的子节点                             | `预期结果`，按行拼接             |

Excel → XMind 时执行反向映射：

1. 使用源 Excel 文件名（不含扩展名）作为 XMind 主节点。
2. 将 `用例目录` 按配置的 `-` 分隔符拆成多级目录节点。
3. 将 `用例名称` 生成为用例节点，将 `用例等级` 1 至 4 生成为对应优先级标记。
4. 将 `前置条件` 写入用例节点备注。
5. 将 `用例步骤` 的每一行生成为步骤节点，并将同序 `预期结果` 生成为步骤子节点。
6. 生成的 XMind 文件名追加 `yyyyMMddHHmmss` 时间戳后缀。

## 界面设计约定

页面的首要任务是完成一次可核对、可导出的格式转换。上传和规则配置固定在左侧，数据核对占据主画布；历史记录收纳在顶部按钮中展开，不占用主配置区。桌面端支持宽表格和并排比较，移动端转为上下比较。