CLAUDE.md — 天璇 (TianXuan) 系统

项目概览
天璇 是一个 TLS 加密流量数据分析与实体画像系统，基于 Django + Polars + scikit-learn + Three.js 构建，支持从 CSV 导入、实体检测、聚合、聚类、特征提取到 3D 可视化的全自动离线分析流水线。

- 版本: v2.0.0beta
- 运行方式: 离线桌面应用，内置 Python 3.12 运行时，双击 run.bat 即可启动，无需安装任何依赖。
- 数据存储: SQLite (WAL 模式) + 内存缓存
- 分支策略: 后续所有改动直接提交到 main 分支，并推送到远程仓库 https://gitea.cattysteve.top/HJQ/tianxuan。

核心模块
| 模块 | 功能 |
|------|------|
| analysis/data_loader.py | CSV 加载、合并、列名规范化、GeoIP 解析 |
| analysis/entity_detector.py | 基于列名关键词和唯一值比率的实体列自动检测 |
| analysis/entity_aggregator.py | 按实体分组计算流量统计、TLS特征、时间模式等 |
| analysis/tool_registry.py | 12 个 MCP 工具注册（145KB） |
| simple_analysis/ | 新增的“简单分析”模块，独立 Django App，提供上传→筛选→聚类→地图可视化一站式工作流 |
| templates/ | 传统功能页面（仪表盘、上传、手动分析、LLM分析、3D地球等） |
| data/ | 离线 GeoIP 数据库 (GeoLite2-City.mmdb、GeoLite2-ASN.mmdb)、自定义 IP 数据 geoip_data.txt |

项目结构要点
天璇/
├── analysis/                 # 主分析 App
├── simple_analysis/          # 简单分析 App (新增)
│   ├── views.py              # API 视图 (upload, filter, cluster, edges)
│   ├── urls.py               # 路由 /simple/
│   ├── templates/simple_analysis/
│   │   └── simple_analysis.html  # 单页应用
│   └── static/
├── config/
│   ├── config.yaml           # 全局配置（含 API Key、参数）
│   └── loader.py
├── data/
│   ├── GeoLite2-City.mmdb    # 130MB，城市级 GeoIP
│   ├── GeoLite2-ASN.mmdb     # 9.5MB，ASN 数据库
│   └── geoip_data.txt        # 补充 IP 地理位置
├── runtime/python/           # 嵌入式 Python 3.12 运行时
├── db.sqlite3                # 主数据库
├── main.py / manage.py
└── run.bat

当前开发焦点：简单分析模块 (v3)
目标：构建一个完全离线、高性能的网络流量 IP 通信社区发现与可视化工具。
工作流（4 步）：
1. 上传与预筛选：拖拽上传 CSV，支持高级筛选器（AND/OR/NOT 树状表达式），上传时立即过滤以减少内存占用。
2. 高级手动筛选：可视化布尔表达式编辑器，对已加载数据进一步精筛。
3. 网络聚类：基于 IP 通信图进行社区发现：
   - 提取所有唯一 :ips / :ipd 作为节点。
   - 先按 /24 子网分组，子网内部使用 HDBSCAN (haversine 距离) 二次聚类。
   - 最终每个节点（IP）获得一个 cluster_id。
4. 地图可视化与交互：
   - 离线地图：使用 Leaflet + 离线瓦片缓存（leaflet-offline），无网络时回退到本地低级别瓦片。
   - 节点按簇着色，支持 Canvas 渲染器和聚类插件优化性能。
   - 点击节点展示：IP、运营商、组织、城市、关联对端IP、host/text 等。
   - 点击边（IP 间连线）展示：通信次数、总流量、首次/末次北京时间、时间规律。
   - 导出点表/边表 CSV。

重要技术约定
- 列名规范化：所有 CSV 列名通过 normalize_columns() 处理成小写+下划线格式，内部使用标准列名（如 src_ip, dst_ip, cnam 等）。
- GeoIP：完全抛弃 CSV 中自带经纬度（:ips.latd 等），所有坐标均使用离线 GeoLite2-City.mmdb 解析。
- 时间处理：原始时间戳/时间列统一转为北京时间 (UTC+8) 展示。
- 内存管理：上传后的数据保存在内存缓存（_cache dict），以 session_id（12位 hex）索引，无持久化。
- 性能要求：i7-10700 + 8GB RAM，十万级 IP 节点需在 1 分钟内完成聚类，内存占用 <2GB。

前端注意事项
- 所有静态资源（Leaflet, Chart.js, Three.js 等）必须本地托管，确保离线可用。
- 地图瓦片离线方案必须实现：在线时缓存 OSM 瓦片到 IndexedDB，离线时使用缓存或内置低级别瓦片。
- 按钮必须防重复点击，操作栏固定在顶部，调试信息面板实时显示。
- 需修复 Cannot set properties of null 类 DOM 操作错误。

API 端点 (简单分析)
| 方法 | 路径 | 作用 |
|------|------|------|
| GET | /simple/ | 主页面 |
| POST | /simple/upload/ | 上传文件 + 预设筛选 + GeoIP 解析 |
| POST | /simple/filter/advanced/ | 树状高级筛选 |
| GET | /simple/column-values/ | 列 Top 50 唯一值（供下拉菜单） |
| POST | /simple/cluster/ | 执行网络聚类 |
| GET | /simple/cluster/<label>/ | 簇详情 |
| POST | /simple/edges/ | 获取边关系 |

已知问题与待办
- [ ] 离线地图瓦片缓存机制完善（目前仅低级别内置）。
- [ ] 边渲染时坐标查找需使用节点真实坐标，而非簇中心近似。
- [ ] 大数据量时地图标记性能优化（可换用 WebGL 渲染器）。
- [ ] 预设筛选器与 Step 2 筛选器 UI 统一为同一个高级筛选组件。

开发命令
- 启动开发服务器：python manage.py runserver
- 运行测试：python manage.py test simple_analysis
- 生成要求：pip freeze > requirements.txt (注意剔除内部路径)

提交规范
- 直接提交到 main 分支，git push origin main。
- 提交信息格式：feat: xxx / fix: xxx / refactor: xxx，简要描述改动。

---
最后更新: 2026-07-24
维护者: 天璇开发团队