geohash-spatial-code-maps

Geohash 与空间代码地图最佳实践

介绍如何在 TypeScript 和 Rust 中正确实现 geohash，如何大规模查询和索引，以及如何将其应用于“将代码库视为可导航的 2D 地图”模式——把代码投影到一个平面上，使 geohash 前缀成为领域区域，你可以像浏览 Google 地图一样在其中穿行。包含 8 个类别中的 42 条规则，按影响程度排序。

适用场景

在以下情况下，请参考这些指南：

• 在 TypeScript 或 Rust 中实现或审查 geohash 编码器/解码器（位交错、base32、精度、邻居）
• 基于经纬度数据构建邻近范围／半径／边界框搜索，或将 geohash 存储为索引键（SQL B 树、Redis 有序集合）
• 调试常见的 geohash 错误——坐标轴颠倒、字母表错误、边界处的漏报、高精度下单元格偏差一位
• 将代码库（或任何抽象图）投影到 2D 平面并对其进行 geohash 编码，使前缀能够指代业务领域或功能
• 像浏览平铺地图一样浏览 geohash 数据集：按精度缩放、加载视口瓦片、按细节层级聚合、前缀聚类、深层链接

范围说明

类别 1–4、6 和 7 是教科书式的 geohash 内容，取材于权威来源（geohash 规范、davetroy/geohash-js 邻接表、Redis、Elasticsearch）。类别 5（map-）和 8（nav-）是新颖的综合成果——目前没有规范的“为代码库应用 geohash”库，因此这些规则从成熟技术（确定性图布局、Morton/Z-order 键、平铺地图分块、软件制图学）中提炼设计原则。对于何时这种模式属于过度设计，规则也会如实说明。

按优先级划分的规则类别

优先级	类别	影响	前缀	规则数
1	编码与位交错	严重	enc-	6
2	精度与单元格几何	严重	prec-	5
3	邻居与邻接	高	nbr-	5
4	邻近与范围查询	高	qry-	5
5	代码库地图式空间布局	高	map-	7
6	解码与边界框	中高	dec-	4
7	空间索引与存储	中高	idx-	5
8	导航与渲染	中	nav-	5

快速参考

1. 编码与位交错（严重）

• enc-interleave-longitude-first — 偶数位交错经度，奇数位交错纬度
• enc-base32-alphabet — 使用 geohash base32 字母表，而非 RFC 4648
• enc-integer-morton-encode — 编码为交错的 64 位整数，以提高速度并生成可排序键
• enc-binary-chop-no-float-drift — 重新计算区间中点；切勿累加浮点步长
• enc-normalize-input-domain — 限制纬度范围、环绕经度，并拒绝非有限输入
• enc-five-bit-char-boundary — 每个字符精确累积 5 位

2. 精度与单元格几何（严重）

• prec-choose-from-error-radius — 根据所需误差半径选择 geohash 长度
• prec-cells-are-not-square — 将单元格视为矩形，其长宽比会随长度变化而翻转
• prec-error-is-half-cell — 解码精度应报告为半个单元格，而非整个单元格
• prec-cells-shrink-toward-poles — 经度方向的米数需乘以 cos(纬度)
• prec-avoid-mixed-precision — 比较或存储前统一到相同精度

3. 邻居与邻接关系（HIGH）

• nbr-canonical-lookup-tables — 使用规范边界/邻居表计算邻居
• nbr-antimeridian-wrap — 在东西方向跨越反子午线环绕查找邻居
• nbr-pole-handling — 越过极点时不返回邻居
• nbr-integer-level-neighbors — 在解交错整数上计算邻居
• nbr-eight-neighbor-set — 构建完整的八邻居集合以进行邻近查询

4. 邻近与范围查询（HIGH）

• qry-search-cell-plus-neighbors — 查询单元格及其八个邻居，绝不只查询前缀
• qry-precision-from-radius — 使查询精度与搜索半径匹配
• qry-bbox-range-decomposition — 将边界框分解为覆盖范围的 geohash 区间
• qry-refine-with-haversine — 使用真实距离筛选 geohash 候选项
• qry-expand-precision-when-sparse — 对稀疏单元格移除一个前缀字符以扩大搜索范围

5. 将代码库视为地图的空间布局（HIGH）

• map-deterministic-projection — 根据结构信号将代码投影到二维空间，而非使用任意布局
• map-stable-coordinates — 确保坐标可复现且增量更新后保持稳定
• map-normalize-to-geohash-domain — 将代码平面归一化到 geohash 的纬度/经度域
• map-coupling-implies-proximity — 验证耦合的代码是否落在同一区域
• map-prefix-as-domain-region — 将 geohash 前缀视为命名的域区域
• map-precision-as-architectural-level — 将前缀长度映射到架构层级
• map-persist-coordinate-sidecar — 将文件到 geohash 的映射作为已提交的旁文件持久化

6. 解码与边界框（MEDIUM-HIGH）

• dec-decode-to-bbox — 解码为边界框，再计算中心点
• dec-symmetric-interval-reconstruction — 通过镜像编码器的区间二分过程进行解码
• dec-avoid-roundtrip-reencode — 保留原始哈希；不要先解码再重新编码
• dec-precompute-reverse-alphabet — 使用预计算的反向字母表查找表进行解码

7. 空间索引与存储（MEDIUM-HIGH）

• idx-sorted-string-range-scan — 将 geohash 存储为排序字符串，以便按前缀范围扫描
• idx-integer-sortable-key — 使用交错整数作为紧凑的可排序键
• idx-db-prefix-index — 使 Postgres 和 Redis 中的前缀查询可使用索引
• idx-range-query-from-covering-set — 将边界框查询作为覆盖集合上的范围扫描来执行
• idx-trie-hierarchical-bucketing — 使用 geohash 字典树按区域聚合

8. 导航与渲染（中）

• nav-precision-to-zoom-levels — 将地图 geohash 精度映射到缩放级别
• nav-level-of-detail-aggregation — 缩小时渲染聚合后的前缀分桶
• nav-tile-lazy-loading — 仅加载视口内的 geohash 单元格
• nav-cluster-by-prefix — 按共享前缀聚合重叠标记
• nav-breadcrumb-prefix-path — 使用 geohash 前缀作为导航状态和深层链接

如何使用

阅读各个参考文件，了解详细说明、代码示例以及“何时不应应用”的指导：

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板

规则通过 [[other-rule-slug]] 相互链接；遇到相关模式时，请按照链接查阅。若要端到端构建代码地图，主线如下：map-deterministic-projection → map-normalize-to-geohash-domain → 编码（类别 1）→ map-prefix-as-domain-region → 导航（类别 8）。

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息