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/