# tsbs_analytics

**Repository Path**: jesse_yang/tsbs_analytics

## Basic Information

- **Project Name**: tsbs_analytics
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-06-25
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TSBS Analytics 评分系统与聚合计算说明

## 一、项目概述

TSBS Analytics 是一个用于时间序列基准测试（TSBS）结果的自动评分、聚合和可视化系统。该系统通过对比实际测试数据与基准值，计算性能得分，支持多组数据的聚合统计，并提供 Web 接口进行数据查看和分析。

主要功能：
- 数据加载和过滤（支持按分支、规模、集群、工作线程、执行类型、查询次数等维度筛选）
- 分组聚合统计
- 性能评分计算
- Web 前端展示（表格、图表）
- API 接口支持

## 二、安装与设置

### 2.1 环境要求
- Python 3.8+
- Flask
- Pandas
- NumPy
- 其他依赖：见 requirements.txt（如果不存在，可根据 app.py 生成）

### 2.2 安装步骤
1. 克隆仓库：
   ```
   git clone <repository_url>
   cd tsbs_analytics
   ```

2. 创建虚拟环境并安装依赖：
   ```
   python -m venv venv
   source venv/bin/activate
   pip install flask pandas numpy
   ```

3. 配置基准值文件（位于 config/ 目录）：
   - master_config.json：主基准配置
   - enterprise_config.json：企业版基准
   - opensource_config.json：开源版基准
   - master_secondary_config.json：次基准配置

4. 运行应用：
   ```
   python app.py
   ```
   访问 http://localhost:5000

## 三、评分体系原理

本系统用于对时间序列基准测试结果进行自动评分和对比，核心思想是：
- 通过对比“实际测试数据”与“基准值”之间的偏差，量化性能一致性。
- 采用加权复合评分，兼顾中心趋势和离散程度。

### 3.1 评分维度与权重
- **中心趋势（70%）**
  - 均值（50%）
  - 中位数（20%）
- **离散程度（30%）**
  - 标准差（20%）
  - 极差（10%）

### 3.2 单项评分公式
对于每个维度，计算偏差率：

    偏差率 = |实际值 - 基准值| / 基准值 × 100%

得分规则：
- 偏差率 ≤ 10%：得100分
- 偏差率 > 10%：得分 = 100 - (偏差率 - 10) × 1
- 得分最低为0分

### 3.3 综合评分公式

    综合得分 = 均值得分 × 0.5 + 中位数得分 × 0.2 + 标准差得分 × 0.2 + 极差得分 × 0.1

注意：如果某些指标缺失，系统会动态调整权重，并使用可用数据的估计值。

## 四、聚合统计流程与算法

实际测试中，同一配置下可能有多组性能数据。为保证评分准确，聚合流程如下：

### 4.1 分组维度
- 分支（branch）
- 规模（scale）
- 集群（cluster）
- 工作线程（worker）
- 执行类型（phase）
- 查询类型（query_type）

### 4.2 聚合算法
- **均值**：所有测试的均值取平均
- **中位数**：所有测试的中位数取中位数（更稳健）
- **标准差**：
  - 优先使用原始数据中的stddev_ms列的平均值
  - 如果没有stddev_ms列，则使用均值的变异度计算（后备方案）
- **极差**：所有测试的最小值和最大值之差

> 注：如果缺少某项数据，则用可用数据的合理估算（如用均值代替中位数等）

## 五、90分下限处理逻辑

- 系统不再强制将综合得分提升到90分。
- 若综合得分低于90分，前端会显示实际分数，并用“✗”标记为“不通过”。
- 评分结果结构中包含`is_passed`字段，便于前端和接口判断。

# 六、基准值更新
```
python3 scripts/update_baseline_from_source.py -s 2025-06-01 -e 2025-06-03 -b master --mode threshold
```
-s: 设置起始时间
-e: 设置结束时间
-b: 基准值分支名
--mode： 计算模式，默认threshold 求上限阈值，可选mean 求平均值

## 七、历史基准值功能

### 7.1 功能概述

系统支持保存和管理历史基准值，用户可以：
- 为master、enterprise、opensource三种类型保存历史基准值
- 选择不同时间的历史基准值进行数据对比分析
- 管理历史版本（查看、加载、删除）
- 计算结果始终以当前选择的基准值为准

### 7.2 文件结构

历史基准值采用目录结构存储：
```
config/
├── master_config.json          # Master当前基准值
├── enterprise_config.json      # 企业版当前基准值  
├── opensource_config.json      # 开源版当前基准值
└── history/                    # 历史版本目录
    ├── master/                 # Master历史版本
    │   ├── 2025-01-15.json
    │   ├── 2025-01-20.json
    │   └── ...
    ├── enterprise/             # 企业版历史版本
    │   ├── 2025-01-15.json
    │   └── ...
    └── opensource/             # 开源版历史版本
        ├── 2025-01-15.json
        └── ...
```

### 7.3 使用方法

#### 主界面使用
1. 在数据分析主界面，选择"基准值类型"（master/enterprise/opensource）
2. 选择"基准值版本"：
   - "当前版本"：使用最新的基准值
   - "历史版本 (日期)"：使用指定日期的历史基准值
3. 点击"应用筛选"进行数据对比分析

#### 基准值管理界面
1. 访问对应的基准值配置页面（/master、/enterprise、/opensource）
2. 配置或修改基准值
3. 点击"保存基准值"更新当前版本
4. 点击"保存为历史版本"将当前配置保存为历史版本
5. 点击"历史版本管理"查看、加载或删除历史版本

### 7.4 API接口

#### 获取历史版本日期列表
```
GET /api/baseline-dates/{baseline_type}
```
参数：baseline_type = master|enterprise|opensource

#### 获取指定日期的基准值
```
GET /api/baseline/{baseline_type}/{date}
```
参数：
- baseline_type = master|enterprise|opensource
- date = YYYY-MM-DD 或 current

#### 保存历史基准值
```
POST /api/baseline/{baseline_type}/{date}
```
请求体：基准值配置JSON

#### 删除历史基准值
```
DELETE /api/baseline/{baseline_type}/{date}
```

### 7.5 数据兼容性

- 保持现有配置文件格式不变，确保向后兼容
- 历史版本文件采用相同的数据结构
- 如果历史版本不存在，自动fallback到当前版本
- 支持版本间的无缝切换

### 7.6 动态版本选择功能

系统支持根据选择的基准值类型动态更新基准值版本列表：

#### 功能特点
- **实时更新**：当用户切换基准值类型时，基准值版本下拉框会自动更新
- **准确显示**：每种基准值类型只显示其对应的历史版本文件
- **用户友好**：无需刷新页面，切换即时生效

#### 技术实现
- 前端使用jQuery和Select2组件实现动态交互
- 通过AJAX调用`/api/baseline-dates/{baseline_type}`获取对应的历史版本列表
- 支持Select2的`select2:select`和标准`change`事件
- 异步加载确保用户体验流畅

#### 版本对应关系
- **Master基准值**: 显示`config/history/master/`目录下的所有历史版本
- **企业发版基准值**: 显示`config/history/enterprise/`目录下的所有历史版本
- **开源发版基准值**: 显示`config/history/opensource/`目录下的所有历史版本

### 7.7 显示模式规则

- **Master基准值**：仅支持`百分比显示`，前端自动锁定为百分比且禁用切换；后端也强制按百分比计算。
- **Master评分基准值**：仅支持`评分显示`，前端自动锁定为评分且禁用切换；后端也强制按评分计算。
- **企业发版/开源发版基准值**：可在`百分比显示`与`评分显示`之间自由切换。