# 限制文件规则

本规则定义了项目中需要保护的文件和目录，这些文件不应被直接修改或删除。

## 禁止修改的文件

### 模型文件

- `**/*.cbm` - CatBoost 模型文件
- `**/*.pth` - PyTorch 模型检查点
- `**/best_model.pth` - 最佳模型文件
- `main/train/best_model.pth`

### 预测结果文件

- `**/predictions_*.tsv` - 预测结果文件
- `main/train/predictions_test.tsv`
- `main/train/predictions_train.tsv`
- `main/train/predictions.tsv`
- `main/train/test1.tsv`
- `main/train/test2.tsv`
- `predictions_test.tsv`

### 配置文件

- `.env` - 环境变量配置
- `.gitignore` - Git 忽略规则

## 禁止直接编辑的目录

### 模型训练输出目录

- `main/train/` - 模型训练输出目录
  - 所有 `.pth` 文件
  - 所有 `.tsv` 预测结果
  - 所有 `.ipynb` 分析报告（需要时可通过 Jupyter 编辑）

### 数据文件目录

- `main/data/` - 数据文件目录
  - 所有 `.ipynb` 数据处理笔记本（需通过 Jupyter 编辑）
  - `update/` 子目录下的文件

### 模型文件

- `my_catboost_model.cbm` - CatBoost 训练好的模型

## 只读数据目录

以下目录包含只读数据，处理时需要特别注意：

```python
# 正确的读取方式
def load_data(filename):
    data = pd.read_hdf(filename, key="data")  # 使用 pandas 读取 HDF5
    return data

# 错误的写入方式 - 不要修改源数据
def process_data(filename):
    data = pd.read_hdf(filename, key="data")
    data.to_hdf(filename, key="data")  # 禁止！会覆盖源数据
```

## Jupyter Notebook 规则

### 允许的操作

- 在 `main/data/` 和 `main/train/` 目录下编辑 `.ipynb` 文件
- 运行 Notebook 进行数据分析
- 添加新的分析单元

### 禁止的操作

- 直接修改生成的模型文件
- 手动修改预测结果文件

## 保护机制

### 临时文件

临时计算产生的中间文件（如带前缀 `_` 的列）应在函数结束时清理：

```python
def get_factor(df):
    old_columns = df.columns.tolist()[:]
    
    # 临时计算
    df["_temp_calc"] = df["close"] / df["open"]
    
    # 清理临时列
    cols_to_drop = ["_temp_calc"]
    df.drop(columns=cols_to_drop, inplace=True, errors="ignore")
    
    new_columns = [col for col in df.columns.tolist()[:] if col not in old_columns]
    return df, new_columns
```

### 模型文件保护

模型文件只能通过训练脚本生成，禁止手动修改：

```python
# 正确：使用训练脚本
# python main/train/train_model.py

# 禁止：直接编辑模型文件
# 任何对 .pth, .cbm 文件的手动编辑都是不允许的
```

## 环境变量

以下环境变量在 `.env` 中定义，禁止硬编码：

- 数据库连接信息
- API 密钥
- 路径配置

如需使用这些变量，应通过 `os.getenv()` 或 `python-dotenv` 读取：

```python
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("API_KEY")
```

## 相关规则文件

读取限制规则已移至独立文件 [`restricted_reads.md`](restricted_reads.md)，包含禁止读取 config 文件和 JSON 文件的详细规则。