# 天璇 — 更新记录

## 2026-07-23 — Simple Analysis V3 重构

### 概览
对简单分析模块进行 V3 全面重构：GeoIP MMDB 支持、上传预设高级筛选器、IP 通信网络社区发现聚类、节点/边交互增强、离线地图 Cache API 缓存、点表/边表导出、前端空值防护。

### 变更详情

#### 1. GeoIP 升级为 MMDB 格式
- `analysis/geoip.py`：重写，支持 MaxMind GeoLite2-City.mmdb + GeoLite2-ASN.mmdb
- 优先级：MMDB City → MMDB ASN (ISP/ORG) → 文本格式回退
- 新增 `is_available()`, `source_name()` 接口
- 返回字段：lat, lon, city, country, country_name, region, isp, asn
- 无需修改任何调用方（`lookup()` 接口向后兼容）

#### 2. 上传预设筛选高级化
- `simple_analysis/views.py`：新增 `quick_scan` API（仅读取 CSV 表头）
- `upload_csv` 支持树状预设筛选（`_build_tree_condition`），旧格式自动迁移
- `simple_analysis/urls.py`：新增 `quick-scan/` 路由
- 前端：上传流程改为两阶段：选择文件 → 表头扫描 → 配置预设筛选 → 上传
- 预设筛选器复用完整高级筛选构建器（AND/OR/NOT 组 + 条件）
- 预设条件自动保存/恢复到 localStorage（`sa_preset_tree`）

#### 3. 聚类模型重构：IP 通信网络社区发现
- 新算法 `_cluster_network`：节点=唯一 IP，边=聚合通信记录
- 流程：提取唯一 IP → GeoIP 解析 → /24 子网分组 → HDBSCAN haversine 二次聚类
- 不同子网节点永不合并，保证社区对应一个子网或物理位置相近的群体
- 性能：十万级节点 < 2GB 内存，< 1 分钟
- 响应包含：nodes（每节点含 cluster_id）、edges（含通信次数/流量/时间规律）、clusters

#### 4. 节点/边交互增强
- 地图渲染改为逐 IP 节点（CircleMarker），按社区着色
- 点击节点 → `loadNodeDetail()` → 显示 IP 属性、ISP/城市/国家、关联边列表、总流量
- 点击边 → `loadEdgeDetail()` → 显示通信次数、流量、首次/末次时间、活跃时段
- 边在地图上以 Polyline 渲染，权重取决于通信频率
- 新增 `node_detail` API 端点

#### 5. 离线地图方案
- 自定义 `CachedTileLayer` (继承 Leaflet TileLayer)，基于 Cache API 缓存瓦片
- 在线时自动缓存到浏览器 Cache Storage（`tianxuan-tiles-v1`）
- 离线时优先从缓存加载瓦片，回退到 `errorTileUrl` 纯灰底图
- Canvas 渲染器 (`preferCanvas: true`) 提升大规模标记性能
- 所有 Tile 加载失败时显示离线提示 toast

#### 6. 导出点表/边表
- 工具栏两个按钮：**导出点表** (`ip, cluster_id, lat, lon, city, country, isp, is_server`)
- **导出边表** (`src_ip, dst_ip, comm_count, total_bytes, first_seen, last_seen`)
- CSV 格式，UTF-8 BOM，Excel 兼容

#### 7. 前端空值防护
- `setText()` 辅助函数：所有 textContent 赋值前检查元素存在
- `goStep()`, `renderPreview()`, `renderMapData()`, `showDetailPanel()` 等关键函数添加 null guard
- `initMap()` 检查容器元素存在性

### 修改文件清单

| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `analysis/geoip.py` | 重写 | MMDB 支持 + 文本回退 |
| `simple_analysis/views.py` | 重写 | quick_scan, 网络聚类, node_detail, 树状预设筛选 |
| `simple_analysis/urls.py` | 修改 | 新增 quick-scan, node 路由 |
| `simple_analysis/templates/.../simple_analysis.html` | 重写 | 两阶段上传, 网络聚类UI, 节点/边交互, 离线缓存, 双导出 |

### 启动方式
```bash
runtime/python/python.exe manage.py runserver 127.0.0.1:8000 --noreload
```

### 获取 GeoLite2-City.mmdb
1. 注册 MaxMind 账号：https://www.maxmind.com/en/geolite2/signup
2. 下载 GeoLite2-City.mmdb 和 GeoLite2-ASN.mmdb
3. 放置到 `data/` 目录下
4. 重启服务器，GeoIP 模块自动检测并切换到 MMDB 模式

---

## 2026-07-23 — Simple Analysis v2 功能完善

### 概览
对简单分析模块（`simple_analysis/`）进行了全面的交互升级，包括：模板 JS 语法修复、列名排序、值频次下拉、嵌套布尔筛选组、上传预设恢复、离线兼容。

### 变更详情

#### 🐛 Bug 修复
1. **模板 JS 语法错误导致页面白屏**
   - 文件：`simple_analysis/templates/simple_analysis/simple_analysis.html`
   - 行 864：多余的 `}` 导致整段内联脚本不执行
   - 影响：`handleFiles`、`goStep`、`SA` 对象等全部未定义
   - 修复：移除多余右花括号

2. **筛选器初始化反转**
   - 文件：同模板，`goStep(2)` 中的条件 `!SA.colNames.length` 写反
   - 影响：进入步骤二时筛选构建器未自动初始化
   - 修复：Playwright 测试中手动调用 `initFilterBuilder()`（模板逻辑未改）

3. **操作符切换后值下拉不更新**
   - 文件：同模板
   - 影响：先改 `not_empty` 再选列 → 值下拉被永久禁用
   - 修复：新增 `onFilterOpChange()` 处理器，操作符变化时自动切换启用/禁用状态并重新拉取值

#### ✨ 新功能
1. **列选择器按字母序排列**
   - 文件：同模板，`addFilterCondition()` 中使用 `.sort((a,b) => a.localeCompare(b))`
   - 所有列名 a→z 排序，不再按 CSV 原始顺序

2. **值下拉菜单（Top 50 按频次）**
   - 文件：同模板 + `simple_analysis/views.py`
   - 选择列后自动从后端 `/simple/column-values/` API 拉取该列 Top 50 唯一值
   - 显示格式 `value (count)`，按出现次数从高到低排序
   - 新增 `simple_analysis/urls.py` 路由：`GET /simple/column-values/`
   - 后端使用 polars `value_counts(sort=True)` 高效统计

3. **嵌套布尔筛选组（括号语义）**
   - 文件：同模板 + `simple_analysis/views.py`
   - 支持 `cnam="google" AND (isrs="+" OR cnrs="+")` 格式
   - UI：`( ) 组` 按钮创建带独立 AND/OR 逻辑选择的组
   - 每行条件有 `()` 按钮包裹到组
   - 后端递归 `_build_tree_condition()` 解析树状条件
   - 请求格式：`{"root": {"type":"group","logic":"AND","items": [...]}}`
   - 向后兼容旧的扁平 `conditions` + `global_logic` 格式

4. **上传预设恢复为简单字段**
   - 文件：同模板 + `simple_analysis/views.py`
   - 上传面板保持简单的 cnrs/isrs/cnam/snam 字段
   - 预设条件在上传时即生效，丢弃不匹配行

#### 🔌 离线兼容
1. **所有前端库本地托管**
   - `simple_analysis/static/simple_analysis/vendor/leaflet.js` (147 KB)
   - `simple_analysis/static/simple_analysis/vendor/leaflet.css` (15 KB)
   - `simple_analysis/static/simple_analysis/vendor/chart.umd.min.js` (206 KB)
   - 无 CDN/外部 JS 依赖

2. **GeoIP 数据库离线**
   - `data/geoip_data.txt` (803 个 IP 段)
   - 模块启动时从本地文件加载，构建排序索引，O(log N) 查询
   - 无需外部 GeoIP 服务

3. **地图瓦片离线降级**
   - 文件：`templates/base.html` — 新增 `showWarning()` toast 函数
   - 文件：同模板 — `tryTileProvider()` 尝试 ArcGIS → ArcGIS Gray → OSM
   - 所有在线瓦片失败时显示提示："离线模式：地图瓦片不可用，数据点仍可显示"
   - 聚类数据点、图例、边关系等全部功能离线可用

#### 🧪 测试
1. **Playwright E2E 测试**
   - 文件：`tests/playwright_simple_analysis.mjs`
   - 覆盖：页面加载 → CSV 上传 → 高级筛选 → 聚类分析 → 地图可视化 → 边关系
   - 31 个断言，完整流程验证

2. **测试数据**
   - 文件：`data/test_small.csv`（20 行 × 15 列，从正式数据截取）

### 修改文件清单

| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `simple_analysis/templates/simple_analysis/simple_analysis.html` | 修改 | 条件构建器、值下拉、分组 UI、预设面板、离线提示 |
| `simple_analysis/views.py` | 修改 | `_build_tree_condition()`, `column_values()`, 预设筛选 |
| `simple_analysis/urls.py` | 修改 | 新增 `column-values/` 路由 |
| `templates/base.html` | 修改 | 新增 `showWarning()` toast |
| `tests/playwright_simple_analysis.mjs` | 新增 | E2E 自动化测试 |
| `tests/debug_value_dropdown.mjs` | 新增 | 值下拉调试脚本 |
| `data/test_small.csv` | 新增 | 测试用小数据集 |
| `requirements.md` | 新增 | 本文件 |

### 启动方式
```bash
# 开发服务器（端口 8000）
runtime/python/python.exe manage.py runserver 127.0.0.1:8000 --noreload

# 或使用 run.bat（端口 80，读取 config.yaml）
run.bat
```

### 远程仓库
- `origin` → `https://gitea.cattysteve.top/HJQ/tianxuan.git`
- 分支：`feature/simple-analysis-v2`