简介：这份源代码资源名为 geolog-app，是一个基于 Python 与 Django 框架构造的地质数据处理类网络应用项目，主要面向初学网络开发的程序员，以及想要了解地质数据如何通过网页来展示与处理的学习者。通过阅读和运行这份代码，可以清晰地看到从建立数据模型、编写业务视图、配置地址路由到渲染网页模板与整理静态文件的完整开发流程。压缩包总共包含二十二个文件，其中十四个为 Python 文件，构成了后台逻辑的主体；此外还有若干说明文档、依赖项清单、网页模板、样式表、轻量级数据库文件以及部署相关配置，整套内容压缩后体积仅为14KB，非常小巧。到目前为止，已经有一百六十二人学习或浏览过这一资源，是一个不折不扣的轻量级实践范例；资源内部提供了一套可以运行的 Django 应用，不仅有后端的数据模型和视图函数，也保留了简单的前端页面与样式，同时包含了数据库快照与部署说明，方便学习者在本地把项目跑起来，或进一步部署到云端。对于想快速掌握 Django 标准目录结构、了解前后端如何联动的新手来说，这份代码是一份短小却不失完整的参考样板。 我第一次想认真做一个地质野外记录工具，是许多年前在河西走廊测剖面的时候。那天下午突然下了场暴雨，几十页纸质记录本被打湿，岩性描述和产状数据混在一起几乎没法看。晚上回到驻地，我们三个人对着照片和记忆，花了将近四个小时才把当天的测点重新复原。从那时起我就确定，野外记录这件事必须数字化，但绝不是把纸面文字原封不动敲进手机那么简单。
后面这几年，我利用项目间隙做了一个面向地质填图和矿产勘查场景的移动端采集工具，也就是标题里的 geolog-app。它解决的核心问题，就是把“测点、分层、产状、样本、照片、素描”这类地质记录要素变成结构化数据，在无网环境下也能可靠记录，回到驻地后自动同步并导出成能被 GIS、地质成图软件识别的格式。这篇文章我会直接讲我在设计数据模型、坐标系处理、离线同步和实际野外测试中遇到的真实问题。如果你也在做类似野外数字化工具，或者正考虑用移动端替代纸质记录，应该能少走不少弯路。
1. 为什么野外记录工具不能只做“电子笔记本”
市面上很多野外记录 App 的通病，是做了一个比纸张更贵的电子表格。它们把纸质记录本的字段原样搬到屏幕上，却忽略了一个关键事实：地质人员在露头前的思维并不是线性的。到了测点之后，你通常会先看地形和岩石类型，再决定测哪条剖面、采集哪个样，中间随时可能回头补充信息、调整层序编号、甚至因为发现新的接触关系而重新分层。
如果 App 强制用户按照“新建测点→填写岩性→填写产状→拍照片→保存”的固定顺序操作，人在野外很容易产生抵触感。我在 geolog-app 里做的第一件事，就是弱化“步骤”概念，把一个测点看作一个容器，里面的岩性描述、产状、分层、照片、素描图都是可以随时追加或修改的独立对象。用户可以先用 10 秒锁定坐标、拍两张照片、录一段语音，回到营地后再统一补全描述。这样既保证现场不丢信息，也不打断观察节奏。
1.1 纸质记录数字化真正难在哪里
和纯办公室场景不同，地质记录包含大量难以字段化的内容：岩层的空间关系需要一张素描图来表达，手标本的结构构造需要一组不同角度照片，风化程度和蚀变类型又依赖行业惯用术语。如果只是给每个测点提供一个多行文本输入框，那导出的数据仍然是一堆非结构化文本，后期做统计分析时依旧要人工判读。
所以数字化难点不在“录入”，而在“拆解”。我在设计时把一张传统记录页拆成几个稳定模块：基础定位信息、地质分层序列、测量数据、样本清单、媒体附件。这样每个模块都能独立检索、独立校验、独立导出。纸质记录本上的“备注”栏，我仍然保留，但位置上放在了所有结构化字段之后，提醒用户优先填写标准字段。
1.2 geolog-app 的设计前提
开发前我给自己定了五条不能妥协的原则：
- 离线优先：没有信号时必须功能完整，不能有任何“转圈等待”。
- 单手可操作：野外经常一手拿锤子一手拿手机，UI 按钮必须大、间距必须大。
- 字典先行：岩性、蚀变、风化程度、颜色等字段全部提供可选字典，尽量少让用户打长文本。
- 数据可逆：数据可以随时导出成 GeoJSON、CSV、Excel，而不是锁定在某个私有格式里。
- 低功耗：连续数小时开着定位和相机，电量消耗必须可控。
这五条原则贯穿了整个开发过程。后续很多次技术选型，我都会回到这份清单来问自己：这个功能改动，到底是在帮助地质人员，还是仅仅在满足工程师的表达欲。
2. 数据模型：从“露头—分层—样本”到可逆导出的关系结构
geolog-app 最核心的数据模型，我设计成三层：Project（项目）、Outcrop（露头/测点）、Stratum（分层记录），外加独立的 Sample（样本）与 Measurement（测量值）。这个模型既适用于沉积岩剖面测制，也适用于火山岩路线调查，做矿区坑道编录时同样能套用。
一个项目下可以有多个露头或测点；一个露头可以包含多个分层；一个分层可以关联多张照片、多个产状数据、多个样本。样本同时保留自己的经纬度、岩性描述和采样人信息，因为有些标本是沿着剖面随手捡的，并不严格挂在某个分层下面。
2.1 三级结构如何匹配真实野外动作
设计时我反复推演过野外剖面测制的全过程：地质人员从剖面起点出发，沿途每个关键位置设一个观测点，记录岩性、产状、接触关系，采集代表性样本。回到室内整理时，需要把这些观测点串成一条连续的剖面柱状图。如果 App 里只有“点”和“照片”两层数据，后期重建层序会很吃力；如果没有“项目”这个顶层，多个成员的数据合并时又会乱成一锅粥。
所以我在联系上采用了“项目必须存在、露头属于项目、分层属于露头”的强约束，但同时又允许一个露头没有分层——如果用户只是做一个踏勘点，不测剖面，那就只需填写点位和照片即可。强约束保证后续数据归集的清晰，弱约束保证实际操作不被流程绑架。
底层用 SQLite 存储，核心建表语句大致是这样：
CREATE TABLE outcrop ( id TEXT PRIMARY KEY, project_id TEXT NOT NULL, name TEXT NOT NULL, lat REAL NOT NULL, lon REAL NOT NULL, elevation REAL, recorded_at_utc TEXT NOT NULL, description TEXT, schema_version INTEGER DEFAULT 1 ); CREATE TABLE stratum ( id TEXT PRIMARY KEY, outcrop_id TEXT NOT NULL, layer_order INTEGER NOT NULL, rock_type TEXT, lithology_desc TEXT, attitude TEXT, thickness REAL, sample_ids TEXT, attached_photo_ids TEXT );看到sample_ids存 JSON 字符串，可能有人会觉得不符合关系数据库洁癖。但移动端 SQLite 环境下，我倾向于减少不必要的关联表。一个分层对应的样本数量通常有限，把 ID 列表直接序列化存储，读取时一次性解析，写起来简单，同步时也不会产生大量中间表的冲突。导出到电脑端时再展开成标准关系表即可。
2.2 字典表与枚举约束：省掉后期数据清洗
早期原型里我让用户自由输入岩性，结果在一次 20 人的野外实习中，单是“灰岩”就有“灰岩”“石灰岩”“灰质灰岩”“石灰石”四种写法。从地质角度这些词不完全一样，但在统计图例时会带来大量清洗工作量。
所以我在后续版本里把所有关键描述字段都改成“字典选择 + 自由补充”的组合模式。岩性字典按三大岩类分组，风化程度按国际惯用的五级分类，颜色采用标准岩石颜色表。自由补充文本单独存放在一个note字段里，不会污染主字段的统计口径。这个改动虽然让录入界面稍微复杂了一些，但数据质量的提升立竿见影。
3. 坐标、高程与“和地图不吻合”的元凶
坐标是整个 App 里最不能出错的数据，但也是最容易在开发时被忽略的地方。很多同类工具直接把手机定位返回的经纬度写进数据库，看起来没问题，一旦叠加国内常用地图底图，就会发现点位整体偏移。这不是手机 GPS 故障，而是坐标系不一致导致的。
手机 GNSS 芯片直接输出的是 WGS-84 坐标，而国内大多数在线地图底图基于 GCJ-02 加密坐标系。如果 App 内部直接用 WGS-84 坐标和 GCJ-02 底图叠加，坐标偏移少则几十米，多则上百米。这个误差在山区公路上可能只是“点显示在路对面”，但在地质界线点、矿化露头上就可能直接导致后期图面精度不达标。
3.1 WGS-84 与 GCJ-02 的转换策略
我在 geolog-app 里做了两层设计：内部存储统一使用 WGS-84 原始值，显示时判断当前底图坐标系，再按需转换成 GCJ-02。换句话说，数据库里永远保存国际标准 GPS 坐标，屏幕显示的坐标只服务于眼前的地图操作，导出给 GIS 软件时也优先输出 WGS-84 或用户指定的坐标系。
这里有一个容易被忽视的细节：绝对不要在数据库中反复覆盖坐标。最初版本我图省事，在显示层直接修改了坐标字段，结果用户来回切换底图后，数据库里的坐标被来回转换，精度越转越差。后来改成“原始坐标 + 显示层转换”模式后，问题彻底消失。这条经验我写在代码注释的第一行：坐标字段一旦写入，除非用户主动编辑，否则任何图层切换、地图缩放都不允许改写它。
3.2 高程可编辑与定位稳定度判定
手机定位的高程数据比平面坐标更不可靠。在峡谷、陡崖或者深切割地区，多路径效应会带来非常大的跳动。所以应用里并没有把高程当成一个只读数据，而是允许用户在已知三角点或水准点上手动校正。
另一个实用的功能是“定位稳定度提示”。App 连续采样几个定位点，计算这些点之间的位移差和水平精度因子（HDOP）。如果位移在持续缩小且 HDOP 值较低，就提示用户可以锁定点位；如果定位仍在大范围漂移，则提醒用户再等几秒。这个小功能在树木茂密的山谷里尤其有用，能明显减少因为提前锁定坐标而导致的点位偏移。
3.3 数据导出时如何避免坐标系二次污染
导出功能里，我提供的是“源坐标”和“投影后坐标”两种模式。源坐标严格按照数据库里的 WGS-84 经纬度输出；投影后的坐标则通过地图投影库在导出时实时计算，比如 UTM 分带或高斯-克吕格投影。导出过程是一次性的、可回溯的运算，不会回写数据库。这样即使某个项目需要多个坐标系的成果，也不需要改动原始数据。
千万别在导出功能里搞“所见即所得”——直接把屏幕上经过加密偏移的坐标导出到 Shapefile。我见过不止一个项目因为导出的是 GCJ-02 坐标，到了专业 GIS 里叠不上国家控制点，最后不得不把全部点位重新换算一遍。
4. 三个高频野外功能是怎么落地的
有了数据模型和坐标基础，接下来就是地质人员每天都会用到的三个功能：可量测照片、数字罗盘、露头素描图。这三个功能做不好，App 就只能停留在“记录卡片”的水平，谈不上真正替代纸质手图。
4.1 可量测照片：比例尺不是摆设
传统野外照片记录最麻烦的问题，是后期看图时不知道画面里的地质体到底有多大。一块砾岩中的砾石直径是 2 厘米还是 5 厘米，没有参照物时只能靠猜。我在相机界面里加了一个可拖动的虚拟比例尺，拍照前用户把刻度条拖到和镜头中的地质锤或钢卷尺对齐，照片保存时会把比例尺长度写进 Exif 和照片关联的元数据。
后期使用者在电脑端浏览照片时，可以直接调出比例尺叠加层，做肉眼量算或粗略的像素尺寸换算。这个设计不追求摄影测量级的精度，但它在野外工作中非常实用，等于给每张地质照片都自带了一个“尺度记忆”。
4.2 数字罗盘与手动产状输入
产状数据（走向、倾向、倾角）是地质记录的高频核心项。手机自带磁力计可以替代地质罗盘，但存在一个显著问题：当测点附近有铁矿体或强磁性岩体时，罗盘读数会出现不可控偏差。因此 geolog-app 里的数字罗盘只作为一个辅助工具，界面显示实时方位角和倾角，同时旁边永远有一个“手动输入”入口。
实际测试中，数字罗盘在正常地层区精度足够做路线填图，但在接触带和矿化蚀变带附近，我强烈建议用传统地质罗盘测得数据后手动填入。应用里也可以为每个测点添加磁场异常备注，这样后期整理数据时能够快速判断哪些产状值需要重新核查。
4.3 露头素描图与照片锚点
露头素描一直是最难数字化的内容，但也是地质记录中价值最高的部分之一。我实现了一个轻量画布，支持手指画线、标注层界线、写岩性符号，并且可以在素描图上打点，把点与某张照片关联起来。这样后期阅读时，点击素描图上的锚点就能直接跳转到对应照片，实现“图上定位—照片验证—文字描述补充”的联动。
画布上有一层半透明的网格，方便用户在画产状符号时保持大致方位。网格间距对应实际比例尺后，还能用来粗略估算层厚。我一直在避免把素描功能做成专业绘图软件，因为它只是野外快速记录的工具，精度要求不需要达到室内清图的水平，稳定、快速、不闪退才是第一位的。
5. 离线优先同步：从本地 SQLite 到多端合并
野外信号不可控，所以 geolog-app 从一开始就走离线优先架构。所有数据先写本地 SQLite，所有写操作同时生成一条带递增序号的操作日志。App 检测到网络时，会按照操作日志的顺序把变更同步到服务端，再拉取其他成员的新增数据。
这套方案没有用复杂的 CRDT 框架，而是采用基于修订号的增量同步。每个数据行都带rev字段和updated_at时间戳。同步时客户端上传本地新增的变更集，服务端合并后返回其余端点的变更，客户端再合并入本地库。
5.1 操作日志与增量同步的实现思路
同步的最小单位是“单条数据行的变更”，不是“整个数据库文件”。只有这样才能避免野外工作时因为一个点位数据出错，导致整个库同步失败。
简化后的增量同步逻辑如下：
// 客户端上传自上次同步以来的所有变更 const changes = await db.query( "SELECT * FROM change_log WHERE rev > ? ORDER BY rev ASC", [lastSyncedRev] ); for (const change of changes) { await syncClient.pushChange(change); } // 拉取远端新增变更 const remoteChanges = await syncClient.pullChanges(lastSyncedRev); for (const change of remoteChanges) { await applyRemoteChange(change); }每一条同步请求都带一个本地生成的change_id，服务端做幂等处理。即使同一条变更被重复推送，服务端也不会重复应用。这是分布式同步里最基础但最容易漏掉的保障。
5.2 不采用“最后写入者获胜”的冲突处理
很多同步方案为了省事，直接采用“最后写入者获胜”的冲突策略。这个策略在野外协作中是有风险的：两位地质人员同一天在不同位置各自补充同一个露头的不同分层描述，其中一条记录晚保存了几分钟，晚保存的版本如果整体覆盖早保存的版本，那早上的分层数据就丢了。
我采用的策略是以“字段级别加行级别”双轨判断：同一行数据的不同字段发生冲突时，尽量保留两边不同的字段；同一字段确实发生冲突时，两个版本都保留，打上“待裁决”标记。回到有网络的室内，项目负责人在 Web 端看到冲突列表再做最终取舍。这个处理和 Git 合并是同一个思路：自动化能做的先自动做，不能自动做的给用户一个可靠的裁决入口。
5.3 一次弱网同步卡死的完整排查
离线同步上线后，我最担心的事情还是发生了。一次在新疆东天山地区的模拟实测中，App 同步到第 55 个露头点时彻底卡住，没有报错，也没有崩溃，同步进度条一直停在 55。
我开始排查：先看应用日志，发现同步循环在抛异常后没有中断标志，而是不断重试同一条变更。再看服务端日志，发现第 55 个变更的请求返回了 400 Bad Request。进一步定位，问题出在露头点的照片列表里，一张照片的文件名包含中文夹杂特殊字符，“%”和空格混在一起，上传时被多端转义后服务端无法解析。
修复方案分两层：客户端在上传前对所有文件名做严格的字符白名单校验，遇到不合规文件名自动重命名为 UUID 后加后缀；服务端增加一个更宽容的解析逻辑，先把文件名做一次解码，再处理上传内容。补丁上线后，这个问题再也没有出现过。
那次卡死给我最大的教训是：同步功能不能只看“正常路径”，任何一次失败的变更都需要有明确的退避重试和用户可感知的报错提示，否则用户会以为整个 App 坏了，实际只是某个文件名不合格。
6. 野外实测后我修改过的几个细节
App 在办公室模拟测试时一切正常，真正拿到野外连续用上几天，才暴露出大量设计时想象不到的问题。下面几条是我在多次野外实测后修改的细节，也是我认为所有野外采集工具都值得注意的地方。
6.1 大按钮、手套模式和防误触
冬季野外作业很多地方需要戴手套，触控屏操作会变得非常笨拙。我把测点记录页的核心操作按钮全部放大到 48dp 以上，按钮间距也做了加大，尽量避免戴手套时误触相邻功能。同时做了一个“手套模式”设置，打开后增大长按判定时间、关闭部分滑动操作，牺牲一点交互流畅度换取操作准确性。
这个改动在实际使用中比任何花哨功能都受欢迎。团队成员在零下十几度的环境里不需要摘手套就能完成记录，效率和点按准确率都提升了一个档次。
6.2 电池焦虑：后台定位与屏幕常亮的平衡
野外连续记录 8 小时，手机电量是最现实的问题。最初版本相机页和地图页会强制屏幕常亮，结果半天不到电量见底。后来我把屏幕超时策略改成分场景处理：纯文本录入场景允许自动息屏，地图导航场景保持常亮但不频繁刷新定位，拍照场景只在取景时唤醒相机。
另外，后台 GPS 连续定位是耗电大户。我加了一个智能降频策略：当用户静止超过 30 秒，定位频率自动从每秒一次降到每 30 秒一次；当检测到位移超过 20 米时，再自动切回高频。这样既保证路径抽稀合理，又显著降低功耗。实测下来，单日耗电比早期版本降低了约 40%。
6.3 对想自建野外采集工具的同行的几条建议
如果你打算自己做一个类似工具，我有几条用真金白银换来的建议：
- 永远不要把功能做得比野外流程更复杂。用户已经扛着锤子、罗盘、样袋，没有精力学习一个新交互范式。
- 字典表要跟随规范更新，不能锁死在版本里。地层单位、岩性分类、蚀变类型这些内容需要支持服务端远程更新。
- 数据导出功能要提前做，最好从第一天就支持 GeoJSON 和 CSV。因为团队最关心的往往是回到室内能不能马上用上数据，而不是 App 界面有多漂亮。
- 同步出问题时，一定要留下可读的日志。野外环境欠佳，没有日志辅助，排查问题会变成猜谜。
- 组内多人同时记录时，样本编号的冲突比想象中更常见。设计规则时最好用“项目前缀 + 日期 + 流水号”这种全局唯一结构。
我会经常把 geolog-app 的数据和旧纸质记录本同时摆在桌面上看。纸质记录本上的字迹虽然潦草，但那种带有现场感的符号、箭头、随手画的岩层边界，确实有一种数字化工具难以完全替代的温度。也正因如此，geolog-app 的目标从来不是让地质人员完全不碰纸笔，而是让每一个测点的核心数据都能被高效记录、可信保存、顺畅输出到后续成果中。在一次次野外测试里，最让我欣慰的不是代码跑通，而是一个刚入行的地质队员告诉我，他第一天用这个工具就能独立完成一整条剖面的记录，再也不用半夜对着湿掉的记录本心算补数据了。
本文还有配套的精品资源，点击获取
