# ApiTrack

**Repository Path**: zypdominate/api-track

## Basic Information

- **Project Name**: ApiTrack
- **Description**: 测试埋点服务，python+flask+mysql
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-28
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ApiTrack

ApiTrack 是一个基于 Python Flask 构建的自动化测试（Action Words，即测试方法）执行追踪与统计埋点中心。它旨在收集并汇总来自不同测试平台下 API 或功能测试用例的执行数据，提供清晰的多维大盘聚合视图，以指导监控侧的测试方向和代码健康度分析。

## ✨ 核心特性

- **跨框架支持**：支持 Python (如 `pytest`) 和 Android 开发套件的测试用例自动追踪埋点信息的关联。
- **自动探针同步扫描 (`ApiScanner`)**：通过 Python `ast` 解析树和 Java 正则语法，自动拉取追踪系统的项目源码，识别具有 `@api` 或 `@AndroidAW` 装饰器的测试方法，并与本地关系型数据库完成双向同步。
- **高吞吐数据上报**：暴露标准的 RESTful 追踪接口与批量 (`batch`) 汇总上报支持。
- **调度型统计聚合 (`StatisticsCollector`)**：基于 `APScheduler` 与文件互斥锁 (`fcntl`) 实现在 Linux 节点上每日定点的各项指标（如调用频次、故障率、总执行数）全量结算与清洗。
- **可视化看板**：自带 Web 端路由（`/dashboard`），开箱直接浏览系统健康状况与各模块测试活跃度图形大屏。

## 🛠 技术栈
- **核心框架**: Python 3.9 / Flask
- **ORM 与数据库**: SQLAlchemy + PyMySQL (建议搭配 MySQL 5.7+ 或 8.0)
- **数据序列化**: Marshmallow (安全拦截、类型校验)
- **调度与任务架构**: APScheduler (Linux 环境下执行部署)

## ⚙️ 环境配置与快速部署

### 1. 代码拉取与 Python 环境准备
推荐使用虚拟环境来隔离依赖链：
```bash
git clone <repository_url> ApiTrack
cd ApiTrack

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 2. 数据库与全局配置环境
本应用依赖于环境变量或根目录下的 `.env` 文件进行配置检索。请在项目根目录创建 `.env` 文件进行覆写替换：

```env
# ==== MySQL 数据库连接池配置 ====
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=vlt_track

# ==== 全局及路径等配置 ====
SECRET_KEY=your-secure-secret-key-for-flask
DEBUG=False
# 可选：配置输出文件的绝对路径(用于额外落盘)
# OUTPUT_DATA=/path/to/data

# ==== 自动化定时任务调度器配置 ====
# 若启动后台定时任务挂载需改为 true
ENABLE_SCHEDULER=true

# ApiScanner(代码追踪自动探测及更新程序) 执行触发时间(24小时制)
API_SCANNER_TIME_HOUR=12
API_SCANNER_TIME_MIN=0

# StatisticsCollector(执行统计大盘与数据清洗) 执行时间
STATISTICS_COLLECTOR_TIME_HOUR=0
STATISTICS_COLLECTOR_TIME_MIN=0
```

### 3. 数据表映射初始化
首次部署时，建议先创建空壳 MySQL 数据库，Flask 将利用启动机制完成空表骨架搭建：
```sql
CREATE DATABASE vlt_track CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 4. 服务启停管控守护
可以直接利用项目打包好的系统操作脚本：
- **启动服务 (后台挂起)**:
  ```bash
  chmod +x start.sh
  ./start.sh
  ```
- **停止挂起服务**:
  ```bash
  chmod +x stop.sh
  ./stop.sh
  ```

> **系统化托管 (Systemd 生产推荐)**：若要随服务器开机自启或长期接管标准输出日志，可深入查看仓库提供的 [systemd_service.md](systemd_service.md) 文件学习快速注册 Linux systemd 手册。注册完成后即可使用 `sudo systemctl restart apitrack` 等常规操作。

## 🔌 API 接口概览

| 功能模块 | Method | EndPoint | 简要说明 |
| :--- | :---: | :--- | :--- |
| **新增追踪数据** | `POST` | `/api/tracking` | 由自动化平台单记录上报方法或框架成功/失败的痕迹数据 |
| **追踪数据批量上传**| `POST`| `/api/tracking/batch` | 提供给压测或跑批组件用于数组形态降低 IO 会话握手负担 |
| **主动拉起同步器** | `GET` | `/api/sync-interfaces` | 无需等待明天立刻激活一次针对 Git 更新与 Ast 分析的全量同步 |
| **基础信息检索** | `GET` | `/api/info` | 分页形式回查所有挂载在本地的测试 AW 函数清单及属性归属 |
| **应用日志追踪** | `GET` | `/api/errors` | 展示各类运行过程被记录到 `AwErrorRecord` 的错误故障回放栈 |
| **总览汇总面板** | `GET` | `/api/status` | 前端向后台回源当前累计数据情况(执行数、累计抛错率、未修量) |
| **系统视图面板** | `GET` | `/dashboard` | 直接可视化输出追踪趋势网页(使用内置 Flask Template 渲染) |

## 💻 目录解构
```text
ApiTrack/
├── app.py                     # 全局路由、REST 控制器以及初始化 Schedulers 生命周期接入点
├── config.py                  # 系统核心配置 (Environment Variables Parser)
├── models.py                  # SQLAlchemy 表实体映射 (`AwInfo`, `AwErrorRecord`, `AwOpRecord` 等)
├── schemas.py                 # 借用 Marshmallow 实现 API 参数清洗强校验规则
├── services.py                # 核心功能调度引擎 (处理入库防丢、结算执行平台增量聚合方法)
├── start.sh / stop.sh         # Linux 原生进程 Shell 启停流
├── systemd_service.md         # 生产环境 Systemctl 保活托管操作示例
├── templates/                 # UI 层：Dashboard 大全网页实现
├── tests/                     # 测试用例隔离域
└── utils/                     # 核心探针处理工具箱
    ├── api_scanner.py         # 自动化 AST / Regex 解析提取工程结构核心文件
    ├── statistics_collector.py# 挂载了 fcntl 进程防互锁的高密度定时统计基石
    ├── clone_update_repo.py   # Shell 同步自动拉取主干的克隆适配器
    └── operate_data.py        # 日志后处理落盘 IO 支持件
```