# 声波测井岩体完整性评价网页 - 需求规格

## 1. 产品目标

提供一个单文件、本地运行的网页，用于单钻孔的逐点声波测井岩体完整性评价。用户导入 Vpm、Vpr、地质分层和岩芯图片后，在一张表中完成查看、修订、计算和 CSV 保存。

原则：逐点数据用于计算和存储；图片及地质分层用于辅助解释和滚动浏览；工程文件和图片不上传服务器。

## 2. 数据模型

| 数据 | 行粒度 | 必填字段 | 用途 |
| --- | --- | --- | --- |
| Vpm | 逐点 | 深度、Vpm | 主评价点来源。 |
| Vpr | 逐点或分段 | 逐点：深度、Vpr；分段：起深、止深、Vpr | 计算 Kv；允许逐点修订。 |
| 地质分层 | 分段 | 分层终止深度、岩性、描述 | 由相邻终止深度计算起深和止深。 |
| 图片 | 分段 | 文件名中的起深-止深 | 关联深度点并在页面合并展示。 |

单位统一为：深度 `m`，波速 `m/s`。

## 3. 导入与项目范围

1. 用户可单独选择 Vpm、地质分层、Vpr 和图片文件夹，也可点击“选择项目文件夹并扫描”。
2. 项目文件夹扫描递归读取所有子目录，自动发现图片及名称中含 `Vpm`、`地质分层`、`Vpr` 的 Excel/CSV 文件。
3. 每个表导入后均显示字段映射下拉框，用户确认“深度、Vpm、Vpr、起深、止深、岩性、描述”等对应列后才写入数据。
4. 项目起深默认取 Vpm 最小深度；终深默认取 Vpm、Vpr、分层终深和图片终深中的最大值。用户可以手工指定起深或终深。
5. 仅为已有 Vpm 的深度生成评价点；无 Vpm 的深度不虚构逐点记录。
6. 浏览器不能预设文件选择器的默认目录。用户需主动选择项目根目录一次，页面才获得本地读取授权。

## 4. 主表结构与显示规则

主表按 Vpm 深度逐点保存，页面显示九列。

| 列 | 内容 | 显示/编辑规则 |
| --- | --- | --- |
| 地质分层深度区间 | 当前点对应的地层起深-止深 | 图片块内合并显示；若一张图片跨多个地层，列出多个分层区间。 |
| 图片 | 本地图片缩略图和文件名链接 | 按图片文件名区间合并；点击缩略图可放大。 |
| 岩性及描述 | 当前地层岩性与描述 | 图片块内合并显示。 |
| 测点深度 | Vpm 点深度 | 每行显示，和 Vpm/Vpr 一一对应。 |
| 声波速度 Vpm | 实测或修改后的 Vpm | 可逐点编辑。 |
| 岩块波速 Vpr | 导入、填充或建议的 Vpr | 可逐点编辑。 |
| Kv | `(Vpm/Vpr)^2` | 自动重算。 |
| 岩体完整性 | Kv 分级结果 | 自动计算；可在下拉框中人工覆盖。 |
| 备注 | 人工说明 | 可逐点编辑。 |

图片覆盖的连续点保持一组：例如 `0-6.jpg` 覆盖 0.0、0.5、...、6.0 m 时，图片、岩性描述和地质分层区间在页面纵向合并，而测点深度至备注仍逐点显示。

## 5. Kv 与完整性分级

```text
Kv = (Vpm / Vpr)^2
```

Kv 阈值是统一的，水利项目与其他项目只切换评价名称，不改变计算公式和区间。边界归入较低完整性等级。

| Kv | 数值等级 | 其他项目名称 | 水利项目名称 |
| --- | --- | --- | --- |
| `Kv > 0.75` | 5 | 完整 | 完整 |
| `0.55 < Kv <= 0.75` | 4 | 较完整 | 较完整 |
| `0.35 < Kv <= 0.55` | 3 | 较破碎 | 完整性差 |
| `0.15 < Kv <= 0.35` | 2 | 破碎 | 较破碎 |
| `Kv <= 0.15` | 1 | 极破碎 | 破碎 |

Vpr 为空或不大于 0 时，不计算 Kv。Vpm 大于 Vpr 时保留计算结果并标记需复核。

### 5.1 项目标准切换

1. 项目设置新增“完整性标准”：`其他项目`、`水利项目`，默认使用其他项目。
2. 切换标准后，仅刷新主表、曲线、CSV 导出中“岩体完整性”的文本；Vpm、Vpr、Kv 和数值等级不改变。
3. CSV 文件头写入 `完整性标准=其他项目` 或 `完整性标准=水利项目`，确保重新导入时仍使用相同叫法。
4. 用户人工覆写完整性时，界面下拉框仅展示当前标准的五个名称。
5. 已确认：水利项目与其他项目共用阈值 `0.15、0.35、0.55、0.75`，并采用本节水利名称映射。

## 6. 波速曲线

### 6.1 目标

在主表外新增“波速曲线”视图，直观显示 Vpm、Vpr 随深度的变化，并与表格、地质分层和图片块联动，辅助识别异常低速带和完整性变化段。

### 6.2 图形设计

| 项目 | 方案 |
| --- | --- |
| 深度轴 | 与主表逐点行共享纵向位置；表格滚动时曲线同步滚动，以便逐点核对。DXF 中深度按 `1 m = 1` 输出，Y 坐标向下为负值。 |
| 波速轴 | 横向 X 轴，单位 m/s；自动取 Vpm/Vpr 有效值范围。DXF 横向绘图宽度默认 45，可在界面调整。 |
| 曲线 | Vpm 使用蓝色实线；Vpr 使用橙色实线；缺失值断线，不用 0 补线。 |
| 分层辅助 | 在对应深度绘制浅色分层界线，并显示岩性简称。 |
| 完整性辅助 | 以浅色背景带或右侧色条显示当前项目标准下的完整性等级。 |
| 悬停提示 | 显示深度、Vpm、Vpr、Kv、完整性和岩性。 |
| 联动 | 点击曲线点定位主表对应测点；点击主表测点，高亮曲线对应位置。 |
| 浏览 | 曲线置于主表右侧，与表格等高；表格高度提高以减少滚动。首期支持 DXF 导出。 |

### 6.3 性能与实现方案

1. 使用原生 Canvas 绘制曲线，不新增后端、不上传数据，适合约 2000 个逐点数据。
2. 主表与曲线共用同一份逐点数据；修改 Vpm、Vpr 或标准后立即刷新曲线。
3. 首期绘制 Vpm/Vpr 双曲线，与表格同步滚动；多孔对比、统计图和 PDF 报告不纳入本期。
4. Canvas 高度跟随逐点表体高度；曲线不单独占用主页面上方空间。

## 7. Vpr 缺失处理

1. 可导入逐点 Vpr 或分段 Vpr。
2. 未提供 Vpr 时，用户可指定统一 Vpr；生成评价表时只填补缺失点。
3. “填充/覆盖 Vpr”会以用户指定值覆盖当前表内所有 Vpr。
4. 可按岩性为缺失点建议经验 Vpr：素填土 1400、破碎带 4000、凝灰岩 5000、流纹岩 5200、火山角砾岩 4800、安山岩 6000 m/s。
5. 经验值仅为初始建议，写入“经验建议 Vpr，需复核”备注，不能替代实测或人工确认值。

## 8. 响应式界面

1. 测点深度、Vpm、Vpr、Kv、完整性五列使用同一套响应式列宽。
2. 图片列在窄屏时自动缩小，在宽屏时最大为 600 px；图片显示尺寸可选“适应行高、紧凑、大图”。
3. 地质分层区间、岩性描述和备注列可收缩。目标是在 1080p 屏幕、浏览器 125% 缩放下保持备注列可见；内容过宽时通过表格容器横向滚动，而非被裁剪。

## 9. 本地 CSV 存储

CSV 使用 UTF-8 with BOM 编码。

```csv
# 标题=综合测井岩体完整性评价;起深=0;终深=966.3;公式=Kv=(Vpm/Vpr)^2;完整性标准=其他项目;单位=深度:m,速度:m/s
深度(m),图片相对路径,岩性及描述,Vpm(m/s),Vpr(m/s),Kv,岩体完整性,备注
0,"[\"副井(0-266)/0-6.jpg\"]","素填土：杂色，松散~稍密",788,1400,0.316808,破碎,""
```

- 第 1 行：标题与项目元数据。
- 第 2 行：字段表头。
- 第 3 行起：逐点评价数据。
- 图片以相对于项目根目录的路径保存，不嵌入二进制图片。
- 重新打开 CSV 后，需再次选择项目图片目录才能恢复图片预览；这是浏览器本地文件权限限制。

## 10. 隐私与边界

- Excel、CSV 与图片仅在当前浏览器内存处理，不上传、不复制到服务器。
- Excel 解析脚本当前从 CDN 下载；该请求不包含工程数据。完全离线时可先把 Excel 转为 CSV。
- 当前版本针对单孔项目；多钻孔汇总、图片 OCR、RQD 自动识别、报告输出不在本期范围。

## 11. 验收要点

1. 使用项目根目录可递归识别全部子文件夹图片。
2. 使用样例文件可生成约 1929 个 Vpm 评价点，而不是仅 0 m 首行。
3. 第一列显示地质分层起止深度，不显示图片起止深度；图片起止深度仍由图片文件名保留。
4. 修改任意点的 Vpm 或 Vpr 后，Kv 与完整性立即刷新。
5. CSV 保存和重新导入后，逐点数值、完整性、备注和图片相对路径可恢复。
6. 切换其他项目/水利项目后，Kv 数值不变，完整性名称按第 5 节映射刷新。
7. 曲线与主表同步滚动，DXF 导出包含 VPM、VPR 两条 LWPOLYLINE 曲线，纵向按深度 1 m = 1 输出。
8. 说明内容收纳到顶部右侧“说明”弹窗，不占主页面高度。