# 高密度电法质量检查工具：网站小程序集成说明

## 1. 交付内容

主程序：

- `高密度电法质量检查对比工具.html`

测试文件目录：

- `quality-check-integration-tests/test_source_absolute.csv`
- `quality-check-integration-tests/test_check_absolute_forward.csv`
- `quality-check-integration-tests/test_check_local_forward.csv`
- `quality-check-integration-tests/test_check_local_midpoint_mirror.csv`
- `quality-check-integration-tests/expected_results.json`

设计与溯源文档：

- `高密度检查段误差计算_讨论与公式溯源.md`

主程序是单文件 HTML，本地浏览器可直接打开，不依赖后端服务，不上传用户数据。

## 2. 功能范围

程序支持：

- 导入生产原始 CSV；
- 导入系统检查 CSV；
- 自动识别 UTF-8、GBK、GB18030；
- 显示两份文件的剖面长度、起终点、点距、电极数和层数；
- 按范围对齐、数据自动搜索或手动对齐；
- 检查数据正向放置或关于自身中点镜像；
- 检查文件使用实际 X 或从 0 起算的局部 X；
- 实时上下剖面预览；
- 实时修改起点、方向、点距、电极数和层数；
- 电阻率和极化率 M 双物性切换；
- 列表、色谱、全部层曲线、逐层曲线、散点和误差分布；
- DZ/T 0070-2016 成对观测误差计算；
- 异常识别和显式剔除；
- 导出带统计头的成果 CSV。

## 3. 推荐集成方式

### 3.1 iframe 集成

改动最少，适合先接入网站验证：

```html
<iframe
  src="/tools/高密度电法质量检查对比工具.html"
  title="高密度电法质量检查"
  style="width:100%;height:1200px;border:0"
></iframe>
```

建议：

- 将 HTML 放入网站静态资源目录；
- iframe 高度至少 1000 px；
- 允许用户选择本地文件；
- 不要对 iframe 设置会禁止下载的 sandbox；
- 如必须使用 sandbox，至少允许 `allow-downloads` 和文件选择所需能力。

### 3.2 页面直接嵌入

可将 HTML 中的 `<style>`、主体 `<main>` 和 `<script>` 分别并入网站页面。

注意：

- 保留所有元素 `id`；
- 脚本在 DOM 创建后加载；
- 避免网站全局 CSS 覆盖 `canvas`、`table`、`button` 和 `.panel`；
- 如使用前端框架，建议先作为独立组件挂载，不要拆散内部状态对象；
- 当前程序使用原生 JavaScript，不要求 npm 依赖。

### 3.3 后续模块化建议

正式产品化时可拆分为：

```text
parser.js       编码识别、CSV 解析、字段映射
geometry.js     点距、范围、电极数、层数、坐标换算
alignment.js    范围对齐、自动搜索、中点镜像
errors.js       电阻率与极化率误差计算
charts.js       实时预览和结果图形
export.js       成果 CSV
app.js          页面状态和事件联动
```

拆分前应使用本测试包建立回归测试，确保结果与当前单文件版本一致。

## 4. 输入文件格式

### 4.1 CSV 编码

支持：

- UTF-8；
- UTF-8 BOM；
- GBK；
- GB18030。

### 4.2 必需字段

| 含义 | 可识别表头 |
|---|---|
| 视电阻率 | `ρs(Ω.m)`、`ρs`、`rho`、`视电阻率` |
| 层号 | `Y(剖面)`、`layer`、`层号` |
| X 坐标 | `X(实际距离)`、`x`、`实际距离` |

### 4.3 建议字段

| 含义 | 测试文件表头 |
|---|---|
| Umn | `vp(mv)` |
| Iab | `ip(mA)` |
| 极化率 | `M` |
| 层内测点号 | `Y层第m测点` |

缺少 Umn、Iab 或 M 时，相关成果字段为空；程序不应以 0 伪造缺失数据。

### 4.4 字段位置

程序按表头名称识别字段，不依赖固定列号。测试文件沿用现场 CSV 的 18 列结构。

## 5. 数据几何

当前第一版按 Wenner-alpha 几何处理。

第 $n$ 层数据中心范围：

$$
x_{start,n}=X_{start}+1.5ns
$$

$$
x_{end,n}=X_{end}-1.5ns
$$

电极数：

$$
E=\frac{X_{end}-X_{start}}{s}+1
$$

第 $n$ 层理论点数：

$$
count(n)=E-3n
$$

拟深度：

$$
Y=n\times s
$$

## 6. 坐标对齐

### 6.1 正向

$$
X_{actual}=X_{actualStart}+(X_{file}-X_{logicalStart})
$$

### 6.2 关于检查剖面自身中点镜像

$$
X_{logicalMid}=\frac{X_{logicalStart}+X_{logicalEnd}}{2}
$$

$$
X_{actualMid}=\frac{X_{actualStart}+X_{actualEnd}}{2}
$$

$$
X_{actual}=X_{actualMid}-(X_{file}-X_{logicalMid})
$$

镜像仅改变用于叠加、匹配和绘图的 X，不改变层号、Umn、Iab、电阻率和极化率。

## 7. 误差公式

### 7.1 电阻率均方相对误差

$$
m_\rho=\sqrt{\frac{1}{2n}\sum_{i=1}^{n}
\left(\frac{\rho_i-\rho'_i}{\bar\rho_i}\right)^2}
$$

### 7.2 电阻率单点误差

$$
q_{\rho,i}=\left|\frac{\rho_i-\rho'_i}{2\bar\rho_i}\right|\times100\%
$$

### 7.3 极化率均方相对误差

$$
m_M=\sqrt{\frac{1}{2n}\sum_{i=1}^{n}
\left(\frac{M_i-M'_i}{\bar M_i}\right)^2}
$$

### 7.4 极化率绝对均方误差

$$
\varepsilon_M=\sqrt{\frac{1}{2n}\sum_{i=1}^{n}(M_i-M'_i)^2}
$$

当 $\bar M_i=0$ 时，相对误差不可计算，程序输出绝对误差，不输出 `NaN`。

## 8. 成果 CSV

成果文件采用 UTF-8 BOM。

```text
第1行：源文件统计信息
第2行：检查文件统计信息
第3行：电阻率和极化率误差统计
第4行：数据字段头
第5行起：数据体
```

第四行字段：

```text
横坐标X(m)
纵坐标Y-拟深度(m)
源Umn(mV)
源Iab(mA)
源电阻率(Ω·m)
源极化率M
检查Umn(mV)
检查Iab(mA)
检查电阻率(Ω·m)
检查极化率M
电阻率误差q(%)
极化率误差(相对%，低值段为绝对值)
```

## 9. 测试数据说明

### 9.1 源数据

`test_source_absolute.csv`：

- 起点 1000 m；
- 终点 1120 m；
- 点距 10 m；
- 13 电极；
- 4 层；
- 22 个数据点；
- X 使用实际坐标。

### 9.2 实际坐标正向检查

`test_check_absolute_forward.csv`：

- 实际范围 1030–1120 m；
- 10 电极；
- 3 层；
- 12 个数据点；
- 选择正向；
- 预期匹配 12/12。

### 9.3 局部坐标正向检查

`test_check_local_forward.csv`：

- 文件逻辑范围 0–90 m；
- 实际叠加起点填写 1030 m；
- 选择正向；
- 预期匹配 12/12。

### 9.4 局部坐标中点镜像检查

`test_check_local_midpoint_mirror.csv`：

- 文件逻辑范围 0–90 m；
- 文件内数据已经按物理位置反向排列；
- 实际叠加起点填写 1030 m；
- 勾选检查数据反向；
- 程序按自身中点镜像；
- 预期匹配 12/12。

### 9.5 注入异常点

三个检查文件均在以下物理位置注入异常：

```text
层号：1
实际 X：1085 m
```

该点的检查电阻率放大为源值的 5 倍，检查极化率增加 5，用于验证异常识别、圆环标记和剔除后重算。

## 10. 预期计算结果

完整精度结果见 `expected_results.json`。

全部 12 点：

| 指标 | 预期值 |
|---|---:|
| 电阻率均方相对误差 | 27.2248879683% |
| 极化率均方相对误差 | 25.3918607746% |
| 极化率绝对均方误差 | 1.0208227891 |

剔除注入异常点后，剩余 11 点：

| 指标 | 预期值 |
|---|---:|
| 电阻率均方相对误差 | 0.7035888370% |
| 极化率均方相对误差 | 1.3885052796% |
| 极化率绝对均方误差 | 0.0212132034 |

## 11. 手工验收步骤

1. 打开 `高密度电法质量检查对比工具.html`。
2. 原始数据选择 `test_source_absolute.csv`。
3. 确认左卡片显示 120 m、1000–1120 m、10 m、13 电极、4 层。
4. 检查数据选择任一检查文件。
5. 确认右卡片显示 90 m、10 电极、3 层。
6. 按对应测试类型设置实际起点和方向。
7. 确认实时预览上下剖面对齐。
8. 点击“计算并对比”。
9. 确认匹配 12/12。
10. 分别切换电阻率和极化率选项卡。
11. 检查异常点是否在第 1 层、X=1085 m 处突出显示。
12. 导出成果 CSV，检查前三行统计和第四行 12 个字段。

## 12. 自动化验收建议

至少覆盖：

- UTF-8 与 GBK 文件读取；
- 三个检查文件均匹配 12/12；
- 中点镜像后 X 映射正确；
- 电阻率全部点误差符合 JSON；
- 极化率全部点相对和绝对误差符合 JSON；
- 删除异常点后的三项误差符合 JSON；
- M=0 时相对误差输出“不可计算”；
- 成果 CSV 第四行字段顺序完全一致；
- 物性选项卡切换后统计、列表和图形同步变化；
- 参数改变时实时预览重绘。

建议数值断言容差：

```text
绝对误差 <= 1e-9
或相对误差 <= 1e-8
```

## 13. 关键页面元素

网站自动化或二次开发可使用以下元素：

| 元素 | ID/选择器 |
|---|---|
| 原始文件 | `#originalFile` |
| 检查文件 | `#checkFile` |
| 对齐方式 | `#alignmentMode` |
| 检查数据反向 | `#reverseCheck` |
| 实际起点 | `#rangeStart` |
| 实际终点 | `#rangeEnd` |
| 点距 | `#overlaySpacing` |
| 电极数 | `#overlayElectrodes` |
| 层数 | `#maxLayers` |
| 计算按钮 | `#calculateBtn` |
| 导出按钮 | `#exportBtn` |
| 实时预览 | `#alignmentPreview` |
| 电阻率选项卡 | `.property-tab[data-field="rho"]` |
| 极化率选项卡 | `.property-tab[data-field="m0"]` |
| 结果图 | `#chart` |
| 结果表 | `#tableBody` |

## 14. 集成注意事项

- 浏览器文件输入无法由普通网页脚本自动读取任意本地路径，必须由用户选择文件；
- 大数据量时建议将解析和自动搜索迁移到 Web Worker；
- 当前自动搜索以匹配数优先、视电阻率对数差次优；
- 自动搜索结果必须允许人工预览和调整；
- 低通色标只影响显示，不影响原始数值和误差计算；
- 异常倍数只影响候选异常识别，不改变规范公式；
- 极化率低值段正式判定限值应结合 DZ/T 0070-2016 表 3；
- 不要将“不可计算”转换成 0；
- 导出时必须同时保留全部点误差和剔除后误差。