# 信号热力图（`heatmap`）

`wifisec heatmap` 把终端变成一张可交互的无线勘测平面图：你用方向键把光标移动到"我现在站的位置"，按空格触发一轮真实扫描，把目标 AP 的信号强度钉进格子。网格按 dBm 分级着色，未采样区域做 IDW 插值连成热力面，右侧实时列出周边 AP 与风险徽章。这是 NetSpot/Ekahau 这类商业走位勘测（site survey）工具的终端版——**全部数据来自真实扫描，零模拟**。

| 能力 | 实现 |
|:---|:---|
| 信号热力 | 网格每格 2 字符宽，ANSI 256 色按 5 级 dBm 渲染 |
| 覆盖插值 | IDW（1/d² 加权），半径硬上限，宁可留白不编造 |
| AP 位置 | 最强采样格标 `@@`，作为 AP 方位粗估计 |
| 信道/风险 | 右侧面板逐 AP 列出信道、加密、风险徽章（复用 wids 安全等级口径） |
| 平面图 | 可选 ASCII 平面图文件作背景，未采样处透出墙体字符 |
| 落盘 | 退出自动保存 JSON（每目标一个文件），可复测可归档 |

## 获取二进制

```bash
go install github.com/ctkqiang/wifisec/cmd/wifisec@latest
```

其他获取方式见仓库 README。

## 1. 用法

```bash
wifisec heatmap                  # 默认目标 = 信号最强的 AP
wifisec heatmap 'MyWiFi'         # 指定目标 SSID
wifisec heatmap 'MyWiFi' 平面图.txt   # 叠加 ASCII 平面图背景
```

需要交互式终端（检测 stdin/stdout 都是 TTY，管道/重定向会直接拒绝）。平面图是普通文本文件：一字符对应一格，墙画 `#`、门留空，随你习惯。

## 2. 操作

| 按键 | 动作 |
|:---|:---|
| `↑↓←→` 或 `hjkl` | 移动光标（你站的位置） |
| `空格` / `回车` | 在当前格采样（触发一轮真实扫描，约 2-4 秒） |
| `Tab` | 切换目标 AP（每个目标的网格独立） |
| `x` | 清除当前格采样（按错的后悔药） |
| `s` | 立即保存 JSON |
| `q` / `Ctrl-C` | 退出：自动保存并打印统计 |

## 3. 读图

```text
 wifisec heatmap · 目标 MyWiFi · 采样 12 格 · 目标 1/8
 ▓▓=光标  ██=精确采样  ▒▒=IDW插值  @@=AP方位估计
 ■<-80 ■-80 ■-70 ■-60 ■≥-50 dBm
```

颜色从红（<-80 dBm 死角）到绿（≥-50 dBm 极好）共五级，口径：`-50/-60/-70/-80` 分界——对齐行业漫游阈值惯例（-70 dBm 以下 roaming 开始犹豫，-80 以下语音开始卡）。

## 4. 原理与诚实边界

**RSSI 物理**：信号是负值，越接近 0 越强。自由空间距离翻倍约 -6dB，穿一堵墙 -3~-12dB。

**IDW 插值**：未采样格取半径内全部采样点的 1/d² 加权平均，半径 = (列数+行数)/6，硬上限 12 格。超过半径一律留白——隔墙衰减不遵守 1/d²，远距离插值是在编造覆盖，宁可空着。

**AP 方位**：取信号最强的采样格标记 `@@`。单点最强≠AP 精确坐标，但走位勘测场景下"哪边信号强 AP 就在哪边"足够指导排查。

**目标匹配**：macOS 未授权定位时系统隐藏 BSSID，目标匹配退化为按 SSID（同名多 AP 取最强读数）；授权后按 BSSID 精确锁定。

## 5. 落盘格式

```json
{
  "ssid": "MyWiFi", "bssid": "AA:BB:...", "cols": 40, "rows": 20,
  "cells": {"4,3": -55, "7,9": -80},
  "plan": ["####", "#  #"],
  "started_at": "…", "saved_at": "…"
}
```

`cells` 键为 `"行,列"`，值为 dBm。文件名 `heatmap-<SSID>-<时间戳>.json`，当前目录生成。

## 6. 排错

| 现象 | 原因 | 处理 |
|:---|:---|:---|
| "需要交互式终端" | 在管道/重定向里运行 | 直接在终端跑 |
| "终端窗口太小" | 网格 <20×8 | 拉大窗口或关闭面板（窄终端自动隐藏） |
| 按空格状态行"本轮不可见" | 目标走出覆盖或扫描抖动 | 走近 AP 重采；持续不可见说明覆盖洞本身就是结论 |
| 方向键不灵 | 极少数终端不发标准转义 | 用 hjkl（vi 键位永远可用） |
| macOS 全程 BSSID 为 `-` | 未授权定位 | 系统设置 → 隐私与安全性 → 定位服务 → wifisec |

## 7. 法律红线

勘测记录的是信号元数据（RSSI/信道/加密方式），不触碰任何通信内容。即便如此，平面图 + 信号指纹的组合足以推断他人场所的内部布局与设备位置——只在自有场所或已获书面授权的环境使用，数据依法留存、不用于测绘第三方场所。
