Agent/examples/auto_put_ad_mini/tools/_names.py

"""
术语与字段名常量 —— 避免字符串魔法值，保证命名单一真源。

## 背景

历史上本项目对同一概念有多种叫法（代码变量 / CSV 列名 / 文档术语各不相同），
已在 2026-04-21 重构中统一为：

| 概念 | CSV 列名（保留中文，不改） | Python 变量（全英文） | 文档术语 |
|------|--------------------------|---------------------|---------|
| 广告 7 日均值动态 ROI | `动态ROI_7日均值` | `dynamic_roi_7d` | "动态 ROI (7日均值)" |
| 广告单日动态 ROI | `动态ROI` | `dynamic_roi_daily` | "动态 ROI (单日)" |
| 渠道 P50 基准 | （计算值，无列）| `channel_roi_p50` | "渠道P50" |
| 同类裂变均值 | `tier_fission_mean` | `tier_fission_mean` | "同类均值" |

## 使用方式

```python
from tools._names import COL_DYNAMIC_ROI_7D

row.get(COL_DYNAMIC_ROI_7D)  # 代替硬编码字符串 "动态ROI_7日均值"
```

## 设计约束

- **CSV 列名不动**：保留中文列名，零破坏历史 metrics_*.csv 数据
- **Python 变量规范**：全英文短名（小写下划线），与中文术语在 reason 展示层解耦
- **禁用变量名进入 LLM reason**：所有 Python 变量名都属"内部实现"，reason 必须用中文术语
"""

# ═══════════════════════════════════════════
# CSV 列名常量（保留中文，零破坏历史数据）
# ═══════════════════════════════════════════

# 广告级动态 ROI
COL_DYNAMIC_ROI_DAILY = "动态ROI"              # 单日值
COL_DYNAMIC_ROI_7D = "动态ROI_7日均值"          # 7 日滚动均值（决策参考）

# 裂变相关
COL_T0_FISSION_COEFF = "T0裂变系数"             # 单日值
COL_T0_FISSION_COEFF_7D = "T0裂变系数_7日均值"  # 7 日滚动均值

# 护栏 B 系列用的临时列（在 validate_decisions 里注入）
COL_CHANNEL_ROI_P50 = "_channel_roi_p50"        # 带下划线前缀表示"内部临时列"

# ═══════════════════════════════════════════
# 文档术语（reason 展示层）
# ═══════════════════════════════════════════

TERM_DYNAMIC_ROI_7D = "动态 ROI (7日均值)"
TERM_CHANNEL_P50 = "渠道P50"
TERM_TIER_FISSION_MEAN = "同类均值"
TERM_PAUSE_LINE = "关停线"
TERM_BID_DOWN_LINE = "降价线"
TERM_BID_UP_LINE = "提价线"

# ═══════════════════════════════════════════
# 禁用变量名黑名单（LLM reason 里若出现则违规）
# ═══════════════════════════════════════════

FORBIDDEN_IN_REASON = [
    # 旧版 Python 变量名
    "f_roi",
    "roi_mean",
    "roi_p50",
    "channel_p50",
    "tier_roi_p50",
    # 新版 Python 变量名（Phase 2 引入后也禁止出现在 reason）
    "dynamic_roi_7d",
    "channel_roi_p50",
    # 阈值线英文名
    "pause_line",
    "bid_down_line",
    "bid_up_line",
    # 信号字段
    "bid_increased_7d",
    "creative_changed_7d",
    "roi_valid_days",
    "tier_fission_mean",
]