# 命名优化：拟合贴合度 → 形态规则度，边界利用率 → 价格活跃度

## 一、重命名原因

### 1. 原命名的问题
- **"拟合贴合度"**：过于技术化，不够直观
- **"边界利用率"**：容易让人误以为是同一个维度的不同表述

### 2. 新命名的优势
- **"形态规则度"** (Geometry Score)：直观表达形态的几何标准性
- **"价格活跃度"** (Activity Score)：直观表达价格振荡的充分性

## 二、核心差异说明

| 维度 | 形态规则度 | 价格活跃度 |
|------|----------|----------|
| **测量对象** | 关键枢轴点（4-8个） | 全部价格（240天） |
| **测量内容** | 几何规则性 | 价格活跃度 |
| **物理意义** | 形态的**结构完整性** | 形态的**有效性/真实性** |
| **失效场景** | 形态不标准，可能是噪音 | 形态虽标准，但缺乏真实博弈 |

## 三、命名映射表

### 3.1 变量/函数命名

| 旧名称 | 新名称 | 说明 |
|--------|--------|------|
| `fitting_adherence` | `geometry_score` | 形态规则度分数 |
| `fitting_score` | `geometry_score` | 形态规则度分数（输出） |
| `boundary_utilization` | `activity_score` | 价格活跃度分数 |
| `utilization_score` | `activity_score` | 价格活跃度分数（输出） |
| `calc_fitting_adherence()` | `calc_geometry_score()` | 计算形态规则度 |
| `calc_boundary_utilization()` | `calc_activity_score()` | 计算价格活跃度 |
| `W_FITTING` | `W_GEOMETRY` | 形态规则度权重 |
| `W_UTILIZATION` | `W_ACTIVITY` | 价格活跃度权重 |
| `UTILIZATION_FLOOR` | `ACTIVITY_FLOOR` | 价格活跃度下限 |

### 3.2 优化版函数命名

| 旧名称 | 新名称 |
|--------|--------|
| `calc_fitting_adherence_numba()` | `calc_geometry_score_numba()` |
| `calc_boundary_utilization_numba()` | `calc_activity_score_numba()` |
| `calc_fitting_adherence_optimized()` | `calc_geometry_score_optimized()` |
| `calc_boundary_utilization_optimized()` | `calc_activity_score_optimized()` |

## 四、修改的文件列表

### 4.1 核心文件
1. **src/converging_triangle.py** ✅
   - 数据类字段重命名
   - 函数名称重命名
   - 函数文档字符串更新
   - 函数调用更新
   - 权重常量重命名

2. **src/converging_triangle_optimized.py** ✅
   - Numba优化函数重命名
   - 封装函数重命名
   - 批量检测函数更新
   - 返回值数组重命名

3. **src/triangle_detector_api.py** ✅
   - `StrengthComponents` 类字段更新
   - 文档字符串更新
   - 结果构建代码更新

### 4.2 脚本文件
4. **scripts/plot_converging_triangles.py** ✅
   - 导入语句更新
   - 函数调用更新
   - 变量名更新
   - 图表标题和标签更新

5. **scripts/test_full_pipeline.py** ✅
   - 导入语句更新
   - 函数覆盖更新
   - 列名更新

6. **scripts/test_optimization_comparison.py** ✅
   - 导入语句更新
   - 函数名更新

7. **scripts/generate_stock_viewer.py** ✅
   - 字段名更新

8. **scripts/README_performance_tests.md** ✅
   - 文档更新

### 4.2 数据结构变更

#### ConvergingTriangleResult (converging_triangle.py)
```python
# 旧字段
fitting_score: float = 0.0
boundary_utilization: float = 0.0

# 新字段
geometry_score: float = 0.0
activity_score: float = 0.0
```

#### StrengthComponents (triangle_detector_api.py)
```python
# 旧字段
fitting_score: float
utilization_score: float

# 新字段
geometry_score: float
activity_score: float
```

## 五、强度分组成（更新后）

```
总强度 = 价格分×50% + 收敛分×15% + 成交量分×10% + 形态规则度×10% + 价格活跃度×15%
```

| 序号 | 组成部分 | 权重 | 英文名 | 说明 |
|------|---------|------|--------|------|
| 1 | **突破幅度分** | 50% | `price_score` | 价格突破上/下沿的幅度 |
| 2 | **收敛度分** | 15% | `convergence_score` | 三角形收敛程度 |
| 3 | **成交量分** | 10% | `volume_score` | 突破时的放量程度 |
| 4 | **形态规则度** | 10% | `geometry_score` | 枢轴点到拟合线的贴合程度 |
| 5 | **价格活跃度** | 15% | `activity_score` | 价格走势对通道空间的利用程度 |

## 六、向后兼容性

### 6.1 破坏性变更
⚠️ **注意**：此次重命名是**破坏性变更**，以下代码需要更新：

1. **依赖旧字段名的代码**
```python
# 旧代码（不再工作）
result.fitting_score
result.boundary_utilization
components.fitting_score
components.utilization_score

# 新代码
result.geometry_score
result.activity_score
components.geometry_score
components.activity_score
```

2. **调用旧函数名的代码**
```python
# 旧代码（不再工作）
from converging_triangle import calc_fitting_adherence, calc_boundary_utilization

# 新代码
from converging_triangle import calc_geometry_score, calc_activity_score
```

### 6.2 迁移建议

如果你的项目中有旧代码，可以：

1. **查找替换**：全局搜索并替换旧名称
2. **检查导入**：确保导入语句使用新名称
3. **更新文档**：更新相关文档和注释
4. **测试验证**：运行测试确保功能正常

## 七、验证

### 7.1 语法检查
所有文件已通过Python语法检查：
```bash
✅ src/converging_triangle.py
✅ src/converging_triangle_optimized.py
✅ src/triangle_detector_api.py
✅ scripts/plot_converging_triangles.py
✅ scripts/test_full_pipeline.py
✅ scripts/test_optimization_comparison.py
✅ scripts/generate_stock_viewer.py
```

### 7.2 导入测试
```bash
✅ 核心函数导入成功
✅ 数据类字段验证成功
✅ Numba优化版本正常加载
```

### 7.3 修改统计
- **文件总数**: 8个
- **核心源文件**: 3个
- **脚本文件**: 5个
- **替换次数**: 约150处

## 八、后续工作建议

1. **更新可视化代码**：如果有图表显示这些指标，需要更新标签
2. **更新API文档**：更新 `triangle_api_reference.md` 中的描述
3. **更新示例代码**：更新所有示例中的字段名
4. **测试验证**：运行完整的测试套件确保功能正常

---

**修改日期**: 2026-01-29
**修改原因**: 提高命名的直观性，避免用户混淆两个指标的含义
**影响范围**: 核心API字段名和函数名