geomative/GeomativeStudio/.qoder/repowiki/zh/content/核心功能/数据导入导出/数据导入.md

数据导入

**本文引用的文件** - [IOManager.cpp](file://cpp/Managers/IOManager.cpp) - [IOManager.h](file://h/IOManager.h) - [Constant.h](file://h/Constant.h) - [DataOperator.h](file://h/DataOperator.h)

目录

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

简介

本文件面向“数据导入”功能的完整流程进行深入文档化，重点覆盖：

• CIOManager::Import 方法如何验证源.accdb文件的有效性（数据库版本检查、密码验证机制）
• 导入过程中的事务管理与数据一致性保障
• ImportProjectToDB、ImportTzToDB 等系列方法如何解析外部数据库并安全导入到当前系统数据库
• 数据映射规则、主键处理、外键约束维护及冲突解决策略
• 导入失败时的回滚机制与错误报告方式

项目结构

数据导入功能位于 Managers 层，核心类为 CIOManager，负责导入与导出的统一入口；导入流程围绕 Access 数据库（.accdb）展开，使用 ADO/ADOX 进行连接与表结构创建，并通过事务保证一致性。

graph TB
subgraph "导入模块"
CIO["CIOManager<br/>导入/导出入口"]
Imp["Import()<br/>验证与事务控制"]
Proj["ImportProjectToDB()"]
Tz["ImportTzToDB()"]
Spt["ImportSptToDB()"]
Rsp["ImportRspTdToDB()"]
Ipsp["ImportIpspTdToDB()"]
end
subgraph "系统数据库"
SysConn["_ConnectionPtr<br/>系统数据库连接"]
Cat["ADOX::Catalog<br/>表结构管理"]
end
subgraph "外部数据库(.accdb)"
ExtConn["_ConnectionPtr<br/>外部数据库连接"]
DbVer["dbversion 表<br/>版本校验"]
end
CIO --> Imp
Imp --> Proj
Imp --> Tz
Imp --> Spt
Imp --> Rsp
Imp --> Ipsp
Imp --> SysConn
CIO --> Cat
Imp --> ExtConn
ExtConn --> DbVer

图表来源

• IOManager.cpp
• IOManager.h

章节来源

• IOManager.cpp
• IOManager.h

核心组件

• CIOManager：导入/导出的统一入口，提供 Import/Export 方法，内部封装对各业务表的导入逻辑。
• 外部数据库（.accdb）：包含 project、tz、td、tdhead、parameter、rspcon、ipspcon、gr、scon、channel、script、dbversion 等表。
• 系统数据库：通过 ADOX 创建目标表结构，使用 ADO 执行插入与更新。
• 常量与返回码：统一的执行状态码（成功/失败/取消/重复/关联异常等），用于错误上报与流程控制。

章节来源

• IOManager.h
• Constant.h

架构总览

导入流程采用“打开外部数据库 -> 版本校验 -> 开启系统数据库事务 -> 分表导入 -> 提交或回滚”的模式。每个导入方法均以“先查询是否存在同名记录 -> 若不存在则插入 -> 存在则跳过（去重）”的策略避免重复导入；同时通过外键字段（如 PRID、TZID、PAID、SCID、DEID、TDID）将不同表之间的关系映射到系统数据库。

sequenceDiagram
participant U as "用户"
participant M as "CIOManager"
participant E as "外部数据库(.accdb)"
participant S as "系统数据库"
participant T as "事务"
U->>M : 调用 Import()
M->>E : 打开外部数据库并设置密码
M->>E : 查询 dbversion 表进行版本校验
alt 校验失败
M-->>U : 返回取消/失败
else 校验成功
M->>S : BeginTrans()
M->>S : 导入 project
M->>S : 导入 tz
M->>S : 导入 scon/channel/script
M->>S : 导入 td/rspcon/ipspcon/gr
alt 导入过程中发生异常
M->>S : RollbackTrans()
M-->>U : 返回失败
else 成功
M->>S : CommitTrans()
M-->>U : 返回成功
end
end

图表来源

• IOManager.cpp
• IOManager.cpp

详细组件分析

CIOManager::Import 验证与事务控制

• 文件选择与连接
  • 弹出文件对话框选择 .accdb 文件，构造连接字符串并设置数据库密码。
  • 设置最大锁数属性以提升并发写入能力。
• 版本检查
  • 通过查询外部数据库的 dbversion 表，要求存在特定键值（版本标识）才视为有效外部数据库。
  • 若未命中或抛出异常，关闭连接并提示错误后返回取消/失败。
• 事务管理
  • 成功通过版本检查后，开启系统数据库事务。
  • 按顺序调用 ImportProjectToDB、ImportTzToDB、ImportSptToDB、ImportRspTdToDB、ImportIpspTdToDB。
  • 成功则提交，失败则回滚并返回失败。

章节来源

• IOManager.cpp

ImportProjectToDB：工程表导入

• 映射字段
  • 将外部 project 的 CN、PRname、PRdesc、location、PRdate、duration、PS、CS、PM、QAS、standard 映射到系统 project。
• 冲突处理
  • 先按 CN 查询系统 project 是否已存在，若不存在则插入；存在则跳过。
• 主键/唯一性
  • 以 CN 作为唯一键进行去重判断。

章节来源

• IOManager.cpp

ImportTzToDB：测区表导入

• 映射字段
  • 外部 tz 的 TZname、PRCN、TZdesc、location 映射到系统 tz。
• 关系解析
  • 通过外部 tz.PRCN 查找系统 project 的 ID（PRID），再以 PRID+TZname 在系统 tz 中查重。
• 冲突处理
  • 若系统 tz 中不存在相同 PRID+TZname，则插入；否则跳过。

章节来源

• IOManager.cpp

ImportSptToDB：脚本与通道导入

• 映射字段
  • 外部 scon 的 CN、Sname、Eamount、CHamount、TPamount、definer、DEdate、SCdesc 映射到系统 scon。
  • 外部 channel 的 CN、CHnumber、AR 映射到系统 channel（通过 SCID 关联 scon）。
  • 外部 script2d 的 CN、CHnumber、TSN、C1、C2、P1、P2、K、N 映射到系统 script2d（通过 CHID 关联 channel）。
• 冲突处理
  • scon：按 CN 去重；插入后获取新 ID（SCID）。
  • channel：按 CN+CHnumber 去重；插入后获取新 ID（CHID）。
  • script2d：按 CN+CHnumber+TSN 去重；插入时使用 CHID。
• 外键维护
  • td 表导入完成后，根据外部 SCCN 更新 td.SCID 字段，完成脚本与测线的关联。

章节来源

• IOManager.cpp

ImportRspTdToDB：电阻率测线导入

• 映射字段
  • 外部 td 的 TDname、DESN、PRCN、TZname、SCCN、TDtype、HFname、CFname、CFRamount、GRFname、GRFRamount 映射到系统 td。
  • 外部 tdhead 的 TDname、DESN、Cdate、Ctime、rolling、RCamount、Rdirection、CRtime、CPE、CPN、weather、temperature、height、humidity、PM、OP、QA 映射到系统 tdhead。
  • 外部 parameter 的 TDname、DESN 对应的 LCHamount、RCHamount、LCamount、RCamount、LEamount、REamount、Felectrode、Espacing、Clayout、CLfun 映射到系统 parameter。
  • 外部 rspcon 的 TDname、DESN 对应的 A、B、M、N、K、SP、Ro、Vp、Ip、SD、RgA、RgB、RgM、RgN、Ttime 映射到系统 rspcon。
  • 外部 gr 的 TDname、DESN 对应的 electrode、CableH、CableT、P1GR、P2GR 映射到系统 gr。
• 关系解析
  • 通过 PRCN 获取 PRID，再通过 PRID+TZname 获取 TZID。
  • 通过 DESN 获取 DEID（设备 ID），若不存在则置为 0。
  • 通过 SCCN 获取 SCID，若不存在则置为 0。
  • 插入 parameter 后获取 PAID；插入 td 后获取 TDID；随后插入 rspcon/gr 使用 TDID。
• 冲突处理
  • td：按 TDname+DESN 去重；不存在则插入并生成 TDID。
  • rspcon/gr：按 TDname+DESN+时间戳（或唯一组合）去重；不存在则插入。
• 外键维护
  • 通过 PRID、TZID、PAID、SCID、DEID、TDID 维护层级关系。

章节来源

• IOManager.cpp

ImportIpspTdToDB：激电测线导入

• 映射字段
  • 与电阻率测线类似，但映射到系统 rspcon 的字段为 SP、Ro、VP、IP、M1..M7、TH、D、Zp、FG、Am、Bm、Cm、Dm、r。
• 关系解析与冲突处理
  • 同样基于 PRCN->PRID、PRID+TZname->TZID、DESN->DEID、SCCN->SCID、TDname+DESN->TDID 的映射链路。
  • 以 TDname+DESN 去重插入 td；随后按 TDname+DESN+唯一字段去重插入 rspcon/gr。

章节来源

• IOManager.cpp

数据映射规则与主键/外键处理

• 映射规则
  • 外部表字段与系统表字段一一对应，部分日期/数值类型在插入前进行格式化或空值处理。
  • 外部表中的“编号”字段（如 CN、PRCN、SCCN、DESN）作为跨表关联与去重的关键键。
• 主键处理
  • 系统侧通过自增主键（如 scon.ID、channel.ID、script2d.ID、td.ID、parameter.ID）生成并维护。
  • 外部侧以 CN、PRCN、SCCN、DESN 等作为唯一键进行去重。
• 外键约束维护
  • 通过 PRCN->PRID、PRID+TZname->TZID、DESN->DEID、SCCN->SCID、TDname+DESN->TDID 等映射，确保 td、rspcon、gr、parameter 等表的外键字段正确指向父表。
• 冲突解决策略
  • 优先采用“存在即跳过”的策略，避免重复导入导致的数据冗余与索引冲突。
  • 对于脚本与测线的二次关联（如 td.SCID 的更新），在导入 scon 后统一执行，确保外键完整性。

章节来源

• IOManager.cpp
• IOManager.cpp
• IOManager.cpp

事务管理与一致性保障

• 事务边界
  • 在 Import() 中开启系统数据库事务，随后依次导入各表；任一环节失败均触发回滚。
• 错误传播
  • 导入过程中捕获 COM 错误并返回失败码；UI 层根据返回码进行提示与后续处理。
• 并发与锁
  • 外部数据库连接设置最大锁数，减少锁竞争带来的写入阻塞。

章节来源

• IOManager.cpp

导入失败的回滚与错误报告

• 回滚机制
  • 导入任一阶段抛错，立即回滚系统数据库事务并关闭外部数据库连接。
• 错误报告
  • 通过统一的状态码（成功/失败/取消/重复/关联异常等）向调用方反馈结果。
  • UI 层根据状态码弹出提示或进入错误处理流程。

章节来源

• IOManager.cpp
• Constant.h

依赖关系分析

• CIOManager 依赖系统数据库连接与 ADOX Catalog，用于创建目标表结构与执行插入。
• 导入方法之间存在强依赖顺序：project -> tz -> scon/channel/script -> td/rspcon/ipspcon/gr。
• 外部数据库必须包含 dbversion 表且包含特定键值，否则导入被拒绝。

classDiagram
class CIOManager {
+Import() uint
+Export() uint
-ImportProjectToDB(pImp)
-ImportTzToDB(pImp)
-ImportSptToDB(pImp)
-ImportRspTdToDB(pImp)
-ImportIpspTdToDB(pImp)
-m_pConnection
-m_pCatalog
}
class Constant {
+APP_SUCCESS
+APP_FAIL
+APP_CANCLE
+APP_DUPLICATE
+APP_RELATION
+APP_OVERFLOW
+APP_DEFAULT
}
CIOManager --> Constant : "使用返回码"

图表来源

• IOManager.h
• Constant.h

章节来源

• IOManager.h
• Constant.h

性能考量

• 外部数据库写入优化
  • 在导入前设置最大锁数，降低锁竞争，提高批量写入效率。
• 查询与去重策略
  • 通过唯一键（CN、PRCN、SCCN、DESN、TDname+DESN 等）进行去重，避免重复插入。
• 事务粒度
  • 将所有导入步骤置于同一事务内，减少中间态，保证一致性的同时也意味着单次失败需整体回滚。
• I/O 与网络
  • .accdb 文件通常本地存储，性能瓶颈主要在数据库写入与索引构建；建议在导入前关闭不必要的 UI 刷新与日志输出。

[本节为通用性能建议，不直接分析具体文件]

故障排查指南

• 常见问题与定位
  • 外部数据库无法打开或密码错误：检查连接字符串与密码设置；确认 .accdb 文件未损坏。
  • 版本校验失败：确认外部数据库包含 dbversion 表且包含指定键值。
  • 导入失败回滚：查看返回码与异常栈，定位具体导入方法；检查唯一键冲突与外键映射是否正确。
• 建议排查步骤
  • 独立运行 ImportProjectToDB/ImportTzToDB，确认基础表导入成功。
  • 检查 scon/channel/script 的关联是否正确，必要时手动执行 td.SCID 更新。
  • 对照外部与系统表结构，核对字段映射与空值处理逻辑。

章节来源

• IOManager.cpp
• IOManager.cpp
• IOManager.cpp
• IOManager.cpp

结论

本导入流程通过严格的版本校验、事务控制与去重策略，实现了从外部 .accdb 到系统数据库的可靠迁移。其关键特性包括：

• 明确的验证与错误处理路径
• 以唯一键驱动的去重与外键映射
• 事务边界内的原子性与一致性
• 清晰的失败回滚与状态码反馈

在实际部署中，建议结合业务场景对字段映射与去重策略进行微调，并在导入前做好备份与测试，以确保数据完整性与可追溯性。