# 维护指南

## 临时文件和缓存清理

### 概述

项目运行过程中会产生以下临时文件和缓存：

**Python 缓存**：
- `__pycache__/` - Python 字节码缓存目录
- `*.pyc`、`*.pyo`、`*.pyd` - Python 编译文件

**临时文件**：
- `docs/feishu_doc.md` - 飞书文档转换临时文件
  - ⚠️ **重要**：此文件在每次生成测试用例前会自动清空
  - **原因**：防止读取到上一次任务留下的旧内容
  - **流程**：清空 → 转换飞书文档 → 读取新内容
- `output/temp/` - 临时输出目录
  - `feishu_doc.md` - 飞书文档备份
  - `custom_events_config.json` - 临时配置文件

**系统文件**：
- `.DS_Store` - macOS 系统文件
- `*.tmp`、`*.temp` - 其他临时文件

---

## 清理工具

### 基本使用

```bash
# 清理所有临时文件和缓存
python3 scripts/clean_temp.py

# 预览将要删除的文件（不实际删除）
python3 scripts/clean_temp.py --dry-run

# 仅清理 Python 缓存
python3 scripts/clean_temp.py --cache-only

# 仅清理临时文件
python3 scripts/clean_temp.py --temp-only

# 清理测试用例输出（保留标准案例：高级房限时任务.md/xmind）
python3 scripts/clean_temp.py --testcase

# 清理所有测试用例（包括标准案例）
python3 scripts/clean_temp.py --testcase --no-keep-standard
```

### 输出示例

```
============================================================
📦 开始清理临时文件和缓存
📂 项目目录: /path/to/testcase_generation
============================================================

🧹 清理 Python 缓存文件...
   ✓ scripts/__pycache__/ (2个文件, 24.3 KB)

🧹 清理临时文件...
   ✓ docs/feishu_doc.md (1.3 KB)
   ✓ output/temp/feishu_doc.md (1.4 KB)
   ✓ .DS_Store (10.0 KB)

============================================================
✅ 清理完成:
   - 清理文件数: 7
   - 释放空间: 44.7 KB
============================================================
```

### 清理测试用例输出

**场景**：生成了多个测试用例后，想要清理历史文件，但保留标准案例作为格式参考。

**推荐用法**：
```bash
# 清理所有测试用例，保留标准案例（高级房限时任务.md/xmind）
python3 scripts/clean_temp.py --testcase

# 预览将要删除的测试用例
python3 scripts/clean_temp.py --testcase --dry-run

# 清理所有测试用例（包括标准案例）
python3 scripts/clean_temp.py --testcase --no-keep-standard
```

**标准案例**：
- `高级房限时任务.md` - Markdown 格式标准
- `高级房限时任务.xmind` - XMind 格式标准

**保留原因**：这两个文件是生成测试用例时的**唯一格式标准**，必须保留作为参照。

---

## 自动清理

### 在工作流程中集成

**方案1：生成前自动清理**

```python
# 在生成脚本开头添加
from scripts.clean_temp import TempCleaner

# 清理临时文件
cleaner = TempCleaner()
cleaner.clean_temp_files()
```

**方案2：生成后自动清理**

```python
# 在生成脚本结尾添加
try:
    # 生成逻辑
    generate_testcases()
finally:
    # 无论成功失败都清理临时文件
    cleaner.clean_temp_files()
```

**方案3：定期清理**

```bash
# 添加到 crontab（每天凌晨2点清理）
0 2 * * * cd /path/to/testcase_generation && python3 scripts/clean_temp.py
```

---

## Git 忽略配置

项目已配置 `.gitignore` 忽略以下文件：

```gitignore
# Python 缓存
__pycache__/
*.py[cod]

# 临时文件
output/temp/
docs/feishu_doc.md

# 系统文件
.DS_Store
```

**验证忽略规则**：

```bash
# 查看被忽略的文件
git status --ignored

# 强制添加被忽略的文件（不推荐）
git add -f <file>
```

---

## 清理策略

### 何时需要清理

**必须清理**：
- 🔴 发现磁盘空间不足时
- 🔴 Python 升级后（清理旧版本缓存）
- 🔴 遇到导入错误时（可能是缓存问题）

**建议清理**：
- 🟡 每周定期清理一次
- 🟡 完成大型任务后
- 🟡 切换分支前

**可选清理**：
- 🟢 每次生成前（确保环境干净）
- 🟢 每次生成后（释放空间）

### 安全性说明

**清理工具只会删除**：
- Python 自动生成的缓存文件
- 明确标记为临时的文件
- 系统自动生成的文件

**不会删除**：
- ✅ 用户创建的脚本
- ✅ 配置文件
- ✅ 测试用例输出（`testcase_output/`）
- ✅ 数数看板配置（`output/dashboards/`）
- ✅ 文档和示例

---

## 故障排查

### 问题1：清理后脚本无法运行

**症状**：`ImportError: No module named ...`

**原因**：可能误删了重要文件

**解决**：
```bash
# 恢复所有 Python 文件
git checkout -- *.py

# 重新安装依赖
pip3 install -r requirements.txt
```

### 问题2：临时文件无法删除

**症状**：`Permission denied`

**解决**：
```bash
# 检查文件权限
ls -la docs/feishu_doc.md

# 修改权限
chmod 644 docs/feishu_doc.md

# 重新清理
python3 scripts/clean_temp.py
```

### 问题3：清理后 Git 状态异常

**症状**：`git status` 显示大量删除

**解决**：
```bash
# 查看被删除的文件
git status

# 如果是临时文件，更新 .gitignore
echo "docs/feishu_doc.md" >> .gitignore

# 恢复重要文件
git checkout -- <important_file>
```

---

## 最佳实践

### 1. 定期清理

```bash
# 每周一次
python3 scripts/clean_temp.py

# 或添加到工作流程
alias clean="cd /path/to/testcase_generation && python3 scripts/clean_temp.py"
```

### 2. 预览再清理

```bash
# 先预览
python3 scripts/clean_temp.py --dry-run

# 确认无误后清理
python3 scripts/clean_temp.py
```

### 3. 分类清理

```bash
# 只清理缓存（更安全）
python3 scripts/clean_temp.py --cache-only

# 只清理临时文件
python3 scripts/clean_temp.py --temp-only
```

### 4. 版本控制

```bash
# 确保 .gitignore 正确配置
git check-ignore -v docs/feishu_doc.md

# 查看忽略的文件
git status --ignored
```

---

## 手动清理

如果清理脚本不可用，可以手动清理：

```bash
# 清理 Python 缓存
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type f -name "*.pyc" -delete

# 清理临时文件
rm -f docs/feishu_doc.md
rm -rf output/temp/*

# 清理系统文件
find . -name ".DS_Store" -delete
```

**⚠️ 警告**：手动清理时请谨慎，确认路径正确后再执行。

---

## 扩展

### 自定义清理规则

编辑 `scripts/clean_temp.py`，在 `clean_temp_files()` 方法中添加：

```python
def clean_temp_files(self):
    """清理临时文件"""
    # ... 现有代码 ...

    # 添加自定义清理规则
    custom_patterns = [
        "*.backup",
        "*.bak",
        "debug_*.log"
    ]
    for pattern in custom_patterns:
        for file in self.base_dir.rglob(pattern):
            if file.is_file():
                self._remove_file(file, "自定义临时文件")
```

### 集成到 Git Hooks

创建 `.git/hooks/pre-commit`：

```bash
#!/bin/bash
# 提交前自动清理临时文件

cd "$(git rev-parse --show-toplevel)/skills/testing/data_testing/testcase_generation"
python3 scripts/clean_temp.py --temp-only --quiet

exit 0
```

---

## 相关文档

- **[配置规则参考](04-config-reference.md)** - 脚本使用说明
- **[问题排查指南](03-troubleshooting.md)** - 常见问题解决
- **[SKILL.md](../SKILL.md)** - 主入口文档