v0.2.14

v0.2.14 —— 堵掉两条「静默产出错数据」：地形不再拿假高原冒充真地形，拼接不再把缺瓦片的半张图当成品

先说结论：这一版没有新功能，是一轮纠错，重点是两条会安静地给出错数据的缺陷。 它们的共同形态是：文件打得开、任务显示「已完成」、日志一个字都不报，只有你自己拿 GIS 去量才发现不对。另外还修了一批「界面/文档对你说反话」的问题 —— 其中最要紧的一条是配置页当面告诉你「底图不走代理」，而底图恰恰是走代理的，正好把「底图打不开」这个最常见的现场问题引到了错误的方向。已有瓦片不失效、不必重切；升级后首次启动会自动给两张地形表加列，不需要你做任何事。

地形不再把「假高原」声明成可用数据

• 症状：上传一小块 DEM（比如 0.05° 见方，约 5.5 公里）切地形，在最浅的那一层会看到两块几十公里见方的巨型台地贴在真实地形旁边，高差可达数千米。全程 HTTP 200、作业完成、零告警。
• 原因：判断「这张瓦片要不要声明为可用」用的是「它和 DEM 有没有交集」，而交集可以只有一个像素。DEM 之外的采样点并不是空值，而是被最外圈的源像素向外拉平成台地。实测那一层真实数据只占瓦片面积的 0.51%，也就是 4225 个顶点里只有 16 个是真的。Cesium 取「第一个声明可用的层」，于是随包的全球底图永远没机会出场，用户看到的就是那张假的。
• 现在改成看覆盖率：某一层的瓦片被真实数据覆盖得太少就不再声明（照常出图，只是不声明），Cesium 自然回落到全球底图那份真实的粗地形；瓦片每深一级缩小一半，覆盖率很快追上来，你的 DEM 在它真正有意义的层级上照常出现。正常规模的 DEM（1°×1° 的标准 granule、全球栅格）完全不受影响。

瓦片下载：有瓦片失败时不再拼接，也不会把上一轮的半张图当成品留下

• 症状：选了「瓦片 + GeoTIFF」或只要 GeoTIFF 的任务，拿到的那张 GeoTIFF 地理范围比你框的选区小（或者内部有洞），而任务显示「已完成」、错误信息是空的。
• 原因是两步叠加：拼接阶段拿到的是「成功的那些瓦片」，失败的根本不在里面，于是用一个比你选区小的集合拼出一张看起来很完整的图；随后暂停/恢复时，「文件已存在就跳过拼接」这条断点逻辑又把那张残缺图原样保留了下来。
• 现在：某一层只要还有失败的瓦片就整层不拼，任务判失败并写明「哪些层没有拼接产物」；补齐重跑时，本轮下到过新瓦片的层一律重拼。纯粹的重跑（全部命中缓存、一块新的都没下）仍然跳过拼接，十分钟级的重算照样省掉。
• 同一段代码还有一处：最后一次进度写库失败时，以前只记一条日志，而「任务成没成功」恰恰是查库得出的 —— 那批失败记录就在丢掉的那次写库里，于是「N 块瓦片失败」被写成了「已完成，无错误」。现在这种情况直接判失败并说明计数不可信。

配置页那句关于底图和代理的话，说反了

• 配置页一直写着「底图由浏览器直连加载，不经过代理设置」。自 v0.2.12 起底图瓦片就是由程序在服务端转发的，和下载走同一条出网路径，同样吃你填的代理。而「底图打不开、只剩一个蓝球」是这个程序最常见的现场问题 —— 那句话等于告诉你「配代理没用」，正好把你从唯一有效的那一步支开了。中英两版都改了。

换了底图之后，看过的区域不会再一整天不变

• 底图瓦片带 24 小时浏览器缓存，而它的地址里没有任何「这是哪一家」的标识。于是你在配置页把底图从 Esri 换成 Google 再刷新，已经浏览过的区域画面纹丝不动，而且整整一天都是这样，界面上没有任何补救办法。现在地址里带上了源标识，换源即换地址，立刻生效。

框选：三个入口的校验口径统一了

• 以前用鼠标在地图上单击（没有拖动）会得到一个零面积的选区，界面还会一本正经地给出「约 6 张瓦片」的预估；手动输入范围时，经度填 400 会被收下、状态栏显示「已选区域 300.000°」；跨 180° 经线的选区不但被收下，状态栏还会显示一个负数宽度，「创建下载任务」按钮照样可点，点下去才收到后端一句英文报错，而且报错里的经度数字是你从来没输入过的（提交前被静默改写过）。
• 现在三个入口走同一道校验，规则与后端逐条一致（北纬 > 南纬、纬度 ±90、经度 ±180、东经 > 西经），拒绝时给的是中文说明。跨反经线的选区明确不支持 —— 后端从来就不接受它，前端以前的「放行」纯粹是个陷阱。

弹窗上按 Esc，不会再把身后的面板一起关掉

• 从配置面板里点「浏览」打开目录选择框，按一次 Esc 只想关掉这个框，结果连配置面板一起滑走了。键盘操作也受影响：Tab 反复被拉回弹窗的第一个控件，到不了目录列表和「选择」按钮。

给排障和构建的人

• 临时目录配置不再接受 ~。 stitch_tmpdir / contour_warp_tmpdir 填 ~/xxx 时保存会成功，但真正用它的三处代码都不展开 ~：等高线任务在预处理阶段直接失败，拼接的中间产物会落进一个名字真的叫 ~ 的目录。现在保存时就会拒绝，请填完整的绝对路径。
• CI 现在会验 GDAL 绑定。 之前只有本地 build.sh / build.bat 跑这道闸，CI 直接调打包脚本绕过去了 —— 一个缺 _gdal_array 的坏包能构建成功、冒烟通过、照样发出去。
• 发版构建不再一个平台失败就取消另外两个，避免留下只挂了部分平台产物的 Release。
• 切片作业永久卡在「运行中」的最后两个入口补上了（DEM 的切片作业、本地地形任务）。上一版补了三张表，这两张当时被一条「它们自己有兜底」的注释漏掉了，而那条注释是错的。

---

以下是本版早前已经完成的部分

详情面板改说实话：显示实际切到的层级，说不准的写「未知」；任务不再永久卡在「运行中」

任务详情面板显示的是实际切到的层级，不再是你填的那一级（这一版唯一的新能力）

• 以前 DEM 地形和本地地形两个详情面板显示的都是你在表单里填的「最大层级」—— 那是基准层级。一旦选了精细或快速档，它与产物就差一级：面板写「0 - 14」，layer.json 里写的是 15。本地地形那个模态框更糟，0 - 14 是一个自称精确的错范围。
• 现在切片收尾时会把产物实际的最深层级写进库，面板读的是它，标签写「实际层级」。同一份 DEM 换个档位重切一遍，两条记录并排摆着就知道差在哪。
• 这件事没被记录的时候会明说，不拿基准值冒充结果。 这一版之前切的作业（那时还没有这一列）、以及还没切完的作业，库里根本没有这个数；面板回落到基准值，同时把标签换成「基准层级」。
• 本地地形的详情里补上了「切片档位」和「顶点法线」两行 —— 上一版只有 DEM 侧有，而本地地形（上传 tif 那条路）恰恰是用户唯一能亲手选档位的入口。

「顶点法线」这一行现在会说「未知」—— 在此之前，它对着一批真的带光照的地形断言「未开启」

• 上一版新增「顶点法线」这一列时，库里的存量行统一填成了 0，面板据此显示「未开启（无光照数据）」，鼠标悬停还会给出「整幅场景的光照会退化成全球日夜渐变」那段警告。方向正好说反了：这一列出现之前，切片器默认就是烘法线的，那批老瓦片的光照好得很。面板等于用一种确定的语气，描述了一件它根本没记录、而且猜反了的事。
• 现在这一列是三态：没有记录 → 「未知（这一行没有记录）」；明确关闭 → 「未开启（无光照数据）」；明确开启 → 「已开启」。那段吓人的悬停说明只挂在明确关闭这一档上 —— 未知状态下挂出去，是拿一件没记录的事吓人。
• 顺带修掉一个真的会改变产物的错：本地地形重新起切时，把「没有记录」按布尔读成了「关」，也就是把一个原本带光照的老任务，静默地按「不要光照」重切一遍。现在没有记录就走配置里的默认值，并且把这一轮真正用的值写回那一行 —— 切过一次之后，它就不再是未知了。
• ⚠️ 一条必须说清楚的局限：已经装过 v0.2.13 的人，那批老作业会继续显示「未开启」。 上一版的升级已经把它们回填成 0，在数据库里和「用户真的关掉了法线」逐位相同，分不出来。这里刻意没有做数据修复迁移：方向猜错的批量改写，比一个错标签更糟。从 v0.2.12 或更早直接升上来的库不受影响，那些行显示的是「未知」。

任务不会再永久卡在「运行中」（DEM 与本地地形两条管线都堵上了）

• 症状：一个任务在界面上显示「运行中」，后台却根本没有线程在跑，而且它既开始不了、也删不掉 ——「开始」只受理待处理和已暂停，删除同样被拒；唯一的出路是重启程序。
• 触发条件说人话：在切片刚要启动的那一瞬间出了岔子 —— 数据库被别的进程短暂占住（database is locked）、磁盘出错，或者配置里有个坏值。此刻「运行中」这一行已经提交进库，工作线程却还没起来；出错时的回滚是空操作，回滚不掉已经提交的东西。本地地形这条路上还有一步要另开一条数据库连接去读配置表，正是最容易在这个窗口里抛出来的地方。
• 现在两条管线都把「写下运行中」推到线程登记之后：中间任何一步出错，任务直接判失败、可以重新开始，而不是变成一具删不掉的僵尸。

本地地形的「层级」那一格不再把话藏在悬停提示里

• 上面说的那个「基准层级」限定词，原本只写在鼠标悬停里。触摸设备上悬停根本不存在、键盘也够不着，而 0 - 14 和 0 - 14 长得一模一样 —— 用户连「这里有话要说」都看不出来。现在限定词写进文字本身。

几处小的

• 状态值不认识的时候，徽章不会再静默失灵。 任务状态或样式如果是 constructor、__proto__、toString 这类值（手改过库，或者将来新增一个状态忘了登记），前端查表会取到 JavaScript 对象自带的成员，而不是落到兜底分支：徽章的 class 变成 bg-function Object() { [native code] }（一颗无色徽章）、文字变成一段函数源码、地图上任务矩形的描边色变成 undefined 于是边框直接消失 —— 三样都不报错。涉及的四张查表现在只认自己登记过的键。
• 档位配置填错时，报错点名的是配置键。 接口调用方没传 quality 时，校验的是配置值，报错却写成 quality ('ultra') must be one of —— 指着一个用户从来没提交过的字段。现在报的是 terrain_quality_preset。
• 给排障的人：切片日志里那行 chose_grid 不能按「全 grid = 山地」读。 这条读法只在 triangulator='auto' 下成立；应用侧固定用规则网格，chose_grid 无条件等于渲染总数，与地形是什么样毫无关系，照那条读法会把每一批 DEM 都判成山地。三处注释都补上了这个限定（日志行本身没动，它一直印着 triangulator=）。另外，「用 CLI 复现生产切片」那条说明补全了：只加 --triangulator grid 不够，还要 --tile-size 65（CLI 默认 17、生产是 65），顶点密度差 4 倍，体积 / 耗时 / 三角形数照样对不上，等于没复现。

验证

• 本版全量测试 2035 项通过 / 3 项跳过（开发机 Linux；跳过的只在特定平台上有意义）。上一版发布时是 1930 项。
• 这一轮修的每个问题都配了一条会变红的用例，而且都是先在未修的实现上跑一遍、确认它确实失败，再修、再跑绿 —— 避免写出「怎么改都绿」的空断言。本轮这样逐个做过的变异超过 40 个。
• 上面那两条「静默产出错数据」以及框选、底图、Esc 这几条，另外用无头浏览器驱动真实服务端复验过：改之前的错误行为逐条复现，改之后逐条消失。
• 顺带补上了四处「测试看着有、其实抓不到」的洞 —— 其中一组用例断言的是测试文件里手抄的一份实现副本，把真实代码改坏四种花样它都不会红。
• 前端那几条另外逐个做了变异验证：把对应的错误一个一个改回去，盯着断言真的变红。详情面板这批 12 个变异；上一版给面板新增的三个 HTML 转义点补登记用例，6 个变异（那三处转义原本删掉，全量测试照样全绿）。
• 三处注释订正另做了「零可执行改动」的证明：把源码的文档字符串剥掉之后比对语法树，而不是靠眼睛看 diff。

---

通用说明

• 下载安装：从下方 Assets 下载对应平台压缩包（terraforge-windows.zip / terraforge-linux.tar.gz / terraforge-macos.tar.gz），解压即用，无需安装 Python 环境。
• 下载体积：每个平台仍包含 167 MB 的全球底图分卷（自 v0.2.8 起）。
• 首次运行：启动可执行文件后，浏览器访问 http://localhost:5000 ；代理、并发、缓存管理等在「配置」页修改。
• 历史版本：完整更新历史见仓库 CHANGELOG.md。
• 使用文档：见仓库 README.md 与 docs/guides/QUICKSTART.md。