# 测区创建与配置

<cite>
**本文引用的文件**
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp)
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp)
- [TestingZone.h](file://h/TestingZone.h)
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp)
- [opcreatetzdlg.h](file://h/opcreatetzdlg.h)
- [DialCfgTerrain.cpp](file://cpp/Views/DialCfgTerrain.cpp)
- [testzone.xml](file://CACHE/testzone.xml)
- [project.xml](file://CACHE/project.xml)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件围绕“测区创建与配置”主题，系统梳理GeomativeStudio中测区（Testing Zone）的创建流程、用户输入校验、测区类型（TZtype）业务规则、与数据库的交互、以及测区配置界面（如DialCfgTerrain）的数据绑定与持久化策略。重点说明：
- CProManager类中创建新测区的核心方法调用链与事务控制
- TestingZone类如何构建测区元数据模型及其字段约束
- 测区配置界面的UI逻辑与数据绑定机制
- 用户配置参数如何序列化并持久化到testzone.xml文件
- 常见配置错误的排查与修复建议

## 项目结构
与测区创建与配置直接相关的模块分布如下：
- 管理层：CProManager（工程与测区管理）
- 模型层：CTestingZone（测区元数据封装）
- 视图层：opcreatetzdlg（创建测区对话框）、DialCfgTerrain（地形配置对话框）
- 缓存与持久化：CACHE目录下的testzone.xml、project.xml

```mermaid
graph TB
subgraph "管理层"
PM["CProManager<br/>测区创建/下发/同步"]
end
subgraph "模型层"
TZ["CTestingZone<br/>测区元数据"]
end
subgraph "视图层"
Dlg["COpCreateTzDlg<br/>创建测区对话框"]
Terrain["CDialCfgTerrain<br/>地形配置对话框"]
end
subgraph "缓存与持久化"
XML_TZ["CACHE/testzone.xml"]
XML_PRJ["CACHE/project.xml"]
end
Dlg --> PM
PM --> TZ
PM --> XML_TZ
PM --> XML_PRJ
Terrain --> XML_TZ
```

图表来源
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L945-L1013)
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp#L1-L82)
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [DialCfgTerrain.cpp](file://cpp/Views/DialCfgTerrain.cpp#L539-L693)
- [testzone.xml](file://CACHE/testzone.xml#L1-L57)
- [project.xml](file://CACHE/project.xml#L1-L22)

章节来源
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L945-L1013)
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp#L1-L82)
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [DialCfgTerrain.cpp](file://cpp/Views/DialCfgTerrain.cpp#L539-L693)
- [testzone.xml](file://CACHE/testzone.xml#L1-L57)
- [project.xml](file://CACHE/project.xml#L1-L22)

## 核心组件
- CProManager：提供测区创建、设备下发、同步等功能；负责数据库事务与设备通信。
- CTestingZone：封装测区元数据（名称、类型、创建日期、描述、位置、CN等），用于UI展示与业务逻辑。
- COpCreateTzDlg：测区创建对话框，负责用户输入校验与TZtype赋值。
- CDialCfgTerrain：地形配置对话框，负责地形数据的导入、校验与写入原始dat文件。

章节来源
- [TestingZone.h](file://h/TestingZone.h#L1-L33)
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp#L1-L82)
- [opcreatetzdlg.h](file://h/opcreatetzdlg.h#L1-L53)
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [DialCfgTerrain.cpp](file://cpp/Views/DialCfgTerrain.cpp#L539-L693)

## 架构总览
测区创建与下发的关键流程如下：
- 用户通过对话框输入测区基本信息（名称、类型、日期、位置、描述）
- CProManager在数据库中插入测区记录并生成唯一CN
- 将测区元数据序列化为testzone.xml并下发至设备
- 设备侧接收后，写入dev_syn_td标记同步状态

```mermaid
sequenceDiagram
participant U as "用户"
participant D as "COpCreateTzDlg"
participant PM as "CProManager"
participant DB as "数据库"
participant DEV as "设备"
participant FS as "本地文件系统"
U->>D : 打开创建测区对话框
D->>D : 输入校验与TZtype赋值
D-->>PM : 返回测区参数
PM->>DB : 插入tz记录并生成CN
PM->>FS : 生成testzone.xml
PM->>DEV : 下发testzone.xml
DEV-->>PM : 返回下发结果
PM->>DB : 写入dev_syn_td(IsSyned=true)
PM-->>U : 创建完成/错误提示
```

图表来源
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L945-L1013)
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L800-L943)
- [testzone.xml](file://CACHE/testzone.xml#L1-L57)

章节来源
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L945-L1013)
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L800-L943)

## 详细组件分析

### CProManager类：创建新测区的核心流程
- 对话框调用与参数收集
  - 通过COpCreateTzDlg收集测区名称、位置、描述、创建日期等参数。
  - 对话框内部将TZtype固定为“3”，体现“默认测区”的强制逻辑。
- 数据库插入与ID回填
  - 使用Command执行INSERT语句，插入tz记录并返回ID。
  - 通过查询再次确认ID，保证后续流程使用正确ID。
- XML生成与下发
  - 以CMarkup生成testzone.xml，包含type、location、desc、create_date、test_date、cn、testzone_name等节点。
  - 调用AddTzInDev创建设备端测区目录与类型标记，随后通过SendFile下发testzone.xml。
- 同步状态维护
  - 下发成功后，向dev_syn_td写入IsSyned=true，标记该测区已同步。

```mermaid
flowchart TD
Start(["开始"]) --> OpenDlg["打开测区创建对话框"]
OpenDlg --> Validate["输入校验<br/>名称必填"]
Validate --> |通过| InsertTZ["插入tz记录"]
Validate --> |不通过| Error["提示错误并终止"]
InsertTZ --> GenXML["生成testzone.xml"]
GenXML --> SendFile["下发testzone.xml到设备"]
SendFile --> |成功| MarkSync["写入dev_syn_td(IsSyned=true)"]
SendFile --> |失败| Rollback["删除设备端测区并回滚"]
MarkSync --> End(["结束"])
Error --> End
Rollback --> End
```

图表来源
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L945-L1013)
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L800-L943)

章节来源
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L945-L1013)
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L800-L943)

### TestingZone类：测区元数据模型
- 字段定义与约束
  - 名称、创建日期、描述、位置、CN、TZtype等均来自数据库tz表查询结果。
  - ShowDetailInfo根据TZtype映射为“1D VES | 2D ERI”、“3D ERT”或“All Type”，用于UI展示。
- 数据来源
  - 通过ADO Recordset按ID查询tz表，填充成员变量。
- 使用场景
  - 在工程树或详情面板中展示测区信息；与CProManager配合进行测区同步。

```mermaid
classDiagram
class CTestingZone {
+DWORD m_dwID
-_ConnectionPtr m_pConnection
-CString m_szTZname
-CString m_szCDate
-CString m_szDesc
-CString m_szLocation
-CString m_szCN
-CString m_szTZtype
+ShowDetailInfo(tzDetailList) bool
+CTestingZone(dwID, connection)
+~CTestingZone()
}
```

图表来源
- [TestingZone.h](file://h/TestingZone.h#L1-L33)
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp#L1-L82)

章节来源
- [TestingZone.h](file://h/TestingZone.h#L1-L33)
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp#L1-L82)

### COpCreateTzDlg：测区创建对话框与TZtype业务规则
- 用户输入验证
  - 名称必填校验；其他字段长度限制（位置、描述）。
- TZtype强制逻辑
  - 对话框内部将m_edTzType硬编码为“3”，即“默认测区”类型。
  - 这意味着创建新测区时，类型必须为3，否则后续流程会报错或不一致。
- 交互细节
  - OnOK中完成UpdateData与校验，随后设置TZtype并关闭对话框。

章节来源
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [opcreatetzdlg.h](file://h/opcreatetzdlg.h#L1-L53)

### DialCfgTerrain：地形配置界面与数据绑定
- UI与数据绑定
  - 通过DoDataExchange绑定控件，支持列表项编辑、删除、新增等操作。
  - 支持从dat文件导入地形数据，写入指定位置并追加结束符。
- 输入校验与写入策略
  - 校验dat文件头三行是否包含有效装置类型信息；禁止Wenner(gamma)与1D装置写入地形数据。
  - 根据装置类型确定末尾0的个数，确保文件格式正确。
  - 写入格式包含“地形数据标志”“点数”“各点坐标”“首电极对应点号”“若干0结束符”。

```mermaid
flowchart TD
Enter(["进入地形配置"]) --> Import["导入dat文件"]
Import --> Parse["解析文件头信息<br/>校验装置类型"]
Parse --> |不合法| Warn["提示错误并终止"]
Parse --> |合法| Edit["编辑地形点列表"]
Edit --> Save["保存到原文件"]
Save --> Write["写入标志/点数/坐标/首电极点号/结束符"]
Write --> Done(["完成"])
Warn --> Done
```

图表来源
- [DialCfgTerrain.cpp](file://cpp/Views/DialCfgTerrain.cpp#L539-L693)

章节来源
- [DialCfgTerrain.cpp](file://cpp/Views/DialCfgTerrain.cpp#L539-L693)

### XML文件生成规则与持久化
- testzone.xml生成规则
  - 根元素为testzone，子元素包含type、location、desc、create_date、create_time、test_date、test_time、cn、testzone_name、testzone_3D_script、vess、eris、erts等。
  - 元素层级清晰，便于设备侧解析与同步。
- project.xml生成规则
  - 根元素为project，包含工程相关信息及testzones节点，其中包含多个测区的TYPE与CN。
- 持久化路径
  - 本地缓存路径：CACHE/projects/{PrCN}/{TzCN}/testzone.xml
  - 设备侧路径：/SD/projects/{PrCN}/{TzCN}/testzone.xml

章节来源
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L800-L943)
- [testzone.xml](file://CACHE/testzone.xml#L1-L57)
- [project.xml](file://CACHE/project.xml#L1-L22)

## 依赖关系分析
- CProManager依赖ADO数据库连接与设备通信接口，负责事务控制与文件下发。
- CTestingZone依赖数据库查询结果，用于UI展示与业务逻辑。
- COpCreateTzDlg与DialCfgTerrain分别负责用户输入与地形数据配置，最终驱动CProManager完成测区创建与下发。
- XML文件作为中间介质，贯穿本地与设备两端的数据交换。

```mermaid
graph LR
Dlg["COpCreateTzDlg"] --> PM["CProManager"]
Terrain["CDialCfgTerrain"] --> PM
PM --> DB["数据库"]
PM --> XML["testzone.xml"]
PM --> DEV["设备"]
TZ["CTestingZone"] --> DB
```

图表来源
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L945-L1013)
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp#L1-L82)
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [DialCfgTerrain.cpp](file://cpp/Views/DialCfgTerrain.cpp#L539-L693)

章节来源
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L945-L1013)
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp#L1-L82)
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [DialCfgTerrain.cpp](file://cpp/Views/DialCfgTerrain.cpp#L539-L693)

## 性能考量
- 数据库事务：CProManager在下发成功后才提交事务，避免半写状态；失败时回滚并清理设备端测区，减少资源浪费。
- 文件IO：XML生成与下发采用一次性写入，避免频繁小块写入；地形文件写入采用定位与覆盖策略，减少磁盘碎片。
- UI响应：对话框在关键校验处短路返回，降低无效计算；列表控件批量更新，提升渲染效率。

## 故障排查指南
- 测区类型设置错误
  - 现象：创建测区时报TZType错误或设备端同步失败。
  - 原因：对话框内部强制TZtype为“3”，若外部逻辑绕过对话框，可能导致类型不一致。
  - 处理：确保通过COpCreateTzDlg创建测区，或在调用CProManager前显式设置TZtype为“3”。

- 必填字段缺失
  - 现象：对话框提示名称为空或校验失败。
  - 处理：完善名称、位置、描述等字段后再提交；注意长度限制。

- 地形文件写入失败
  - 现象：写地形数据到原文件失败或未找到结束符。
  - 原因：dat文件格式不符合要求、装置类型不支持写地形、首电极点号越界。
  - 处理：检查文件头三行、装置类型合法性、点号范围；确保末尾0个数符合约定。

- 下发失败
  - 现象：设备返回失败或本地提示发送失败。
  - 处理：检查设备通信状态、路径权限、文件完整性；必要时删除设备端测区并重试。

- 同步状态异常
  - 现象：dev_syn_td中IsSyned未置位或置位错误。
  - 处理：确认下发成功后是否执行写入dev_syn_td；若失败则回滚并清理设备端测区。

章节来源
- [opcreatetzdlg.cpp](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
- [DialCfgTerrain.cpp](file://cpp/Views/DialCfgTerrain.cpp#L539-L693)
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L800-L943)

## 结论
- 测区创建流程由对话框输入、数据库插入、XML生成与下发、同步状态维护构成，CProManager承担核心协调职责。
- TestingZone提供稳定的测区元数据封装，支撑UI展示与业务逻辑。
- DialCfgTerrain负责地形配置，严格遵循文件格式规范，保障设备侧可正确解析。
- TZtype强制为“3”的设计体现了默认测区的业务规则，应严格遵守以避免后续错误。

## 附录
- 关键流程参考路径
  - [创建测区对话框](file://cpp/Views/opcreatetzdlg.cpp#L54-L92)
  - [创建测区数据库流程](file://cpp/Managers/ProManager.cpp#L945-L1013)
  - [下发测区XML流程](file://cpp/Managers/ProManager.cpp#L800-L943)
  - [测区元数据模型](file://cpp/ProblemZone/TestingZone.cpp#L1-L82)
  - [地形配置与写入](file://cpp/Views/DialCfgTerrain.cpp#L539-L693)
  - [测区XML样例](file://CACHE/testzone.xml#L1-L57)
  - [工程XML样例](file://CACHE/project.xml#L1-L22)