kingoftech-v01/tracking-project

# Phone Number 分析器 一个用于分析国际电话号码的小型 Python 工具。给定任意 E.164 号码（例如 `+14155552671`），该工具将报告： - **国家**和**地区**（来自 Google 的 `libphonenumber`，通过 `phonenumbers` 库） - **网络运营商**名称（在数据库有数据的情况下） - **可能的时区**（IANA 名称，如 `America/Los_Angeles`） - **大致 GPS 坐标**——通过 [OpenCage Geocoding API](https://opencagedata.com/) 对地区名称进行地理编码解析 - **交互式 HTML 地图**——使用 [Folium](https://python-visualization.github.io/folium/) 生成并在默认浏览器中自动打开 所有这些功能通过一个简单的 [Tkinter](https://docs.python.org/3/library/tkinter.html) 桌面 GUI 呈现。 ## 项目布局 ``` tracking-project/ ├── phone_analyzer.py # Pure business logic: analyze_number, generate_map, │ # api_key_from_env, PhoneAnalysis dataclass ├── app.py # Tkinter GUI: PhoneAnalyzerApp class + main() ├── tests/ │ ├── test_analyzer.py # Tests for phone_analyzer.py (100 % coverage) │ └── test_app.py # Tests for app.py (100 % coverage, headless-safe) ├── requirements.txt # Runtime dependencies (pinned) ├── requirements-dev.txt # Dev dependencies: pytest, ruff, mypy └── pyproject.toml # Tool configuration (ruff, mypy, pytest, coverage) ``` ## 安装 ``` git clone https://github.com/kingoftech-v01/tracking-project.git cd tracking-project pip install -r requirements.txt ``` 运行时依赖： | Package | Version | Purpose | |---------|---------|---------| | `phonenumbers` | 8.13.45 | 号码解析、地理编码、运营商、时区查询 | | `opencage` | 2.4.0 | 正向地理编码（地区名称 → GPS 坐标） | | `folium` | 0.17.0 | HTML 地图生成 | Tkinter 是 Python 标准库的一部分——在大多数平台上无需额外安装。 在最小化的 Linux 安装中，您可能需要运行 `apt install python3-tk`。 ## 配置 OpenCage API 密钥从 `OPENCAGE_KEY` 环境变量中读取。 如果未设置该变量，则跳过地理编码，纬度/经度 字段将为空（不生成地图）。 1. 在 创建一个免费账户并复制您的 API 密钥。 2. 在运行程序之前导出它： ``` export OPENCAGE_KEY=your_api_key_here ``` 或者内联传递它以进行一次性运行： ``` OPENCAGE_KEY=your_api_key_here python app.py ``` ## 用法 ``` python app.py ``` 在 GUI 窗口中： 1. 输入带有国家代码的完整国际电话号码 （例如 `+14155552671`）。 2. 点击 **Analyze**。 3. 结果面板将显示国家、地区、运营商、时区，以及 （如果地理编码成功）坐标和已保存地图的路径。 地图 HTML 文件也会在默认浏览器中自动打开。 ## 示例输出 ``` Country : United States Region : California Carrier : AT&T Wireless Timezones : America/Los_Angeles Latitude : 36.7783 Longitude : -119.4179 Map saved : phone_location.html ``` ## 运行测试 安装开发依赖： ``` pip install -r requirements-dev.txt ``` 运行包含分支覆盖率的完整测试套件： ``` pytest --cov=. --cov-report=term-missing ``` 所有测试都是自包含的——不需要真实的 API 密钥、网络访问或 显示器。外部 I/O（OpenCage、Folium、Tkinter）已被模拟。 ## 代码检查和类型检查 ``` ruff check . # style and security lint mypy phone_analyzer.py app.py # strict static type checking ``` ## 限制 - **仅为大致位置**——坐标指向国家行政区划的地理 中心，而非任何真实设备的位置。 - **无实时跟踪**——该工具无法确定电话在任意给定时刻的位置。 - **运营商数据缺失**——`phonenumbers` 运营商数据库 不完整；许多号码返回空字符串。 - **仅供教育使用**——未经用户同意，请勿使用此工具查询号码。 ## 贡献 1. Fork 该仓库并创建一个功能分支。 2. 为任何新逻辑编写测试；覆盖率阈值为 100%。 3. 运行 `ruff check .` 和 `mypy phone_analyzer.py app.py`——两者必须 以零错误通过。 4. 提交一个 Pull Request，并清晰描述更改内容。

标签：API集成, E.164, Folium, Geocoding, libphonenumber, OpenCage, Pytest, Python, Tkinter, 二进制发布, 单元测试, 可观测性, 国际号码, 地图绘制, 地理位置, 开源工具, 无后门, 时区查询, 桌面GUI, 电话号码分析, 电话归属地查询, 运营商识别, 逆向工具