# 代码组织规范

## 📁 目录结构规范

### 核心原则
**禁止在根目录直接放置代码文件！** 所有代码必须按功能分类放入对应目录。

---

## 📂 目录定义

### 1. 提取器 (extractors/)

```
extractors/
├── current/           # 当前使用的提取器
│   ├── fusion/        # PC融合版提取器
│   │   └── extractor_fusion_complete.py
│   └── llm/           # LLM提取器
│       └── llm_extractor_dashscope.py
├── archive/           # 归档的旧版提取器
│   └── extractor_suc5.py (等)
└── utils/             # 提取器工具模块
    └── chunker.py
```

**规则**：
- 新提取器默认放入 `current/` 对应子目录
- 废弃提取器移入 `archive/`
- 通用工具放入 `utils/`

---

### 2. 文档 (docs/)

```
docs/
├── changelogs/        # 变更日志
├── reports/           # 报告文档
├── plans/             # 计划文档
├── analysis/          # 分析文档
└── guides/            # 指南文档
```

**规则**：
- 所有 `.md` 文件必须分类存放
- 根目录仅保留 `README.md` 和索引文件

---

### 3. 脚本 (scripts/)

```
scripts/
├── shell/             # Shell脚本
├── utils/             # Python工具脚本
├── extractors/        # 提取器脚本 (v7-v12系列)
└── tests/             # 测试脚本
```

**规则**：
- `.sh` 文件放入 `shell/`
- 工具类脚本放入 `utils/`
- 版本化提取器放入 `extractors/`

---

### 4. 源代码 (src/)

```
src/
├── rag/
│   ├── extractors/    # RAG集成提取器
│   ├── advanced/      # 高级功能
│   └── agentic/       # Agent功能
├── llm/               # LLM模块
├── memory/            # 记忆模块
└── db/                # 数据库模块
```

**规则**：
- 按功能模块组织
- 保持现有 `src/rag/extractors/` 结构

---

### 5. 数据 (data/)

```
data/
├── rule_bases/        # 规则库
├── samples/           # 样本数据
└── output/            # 输出数据
```

**规则**：
- 规则库文件放入 `rule_bases/`
- 不要混放代码和数据

---

### 6. 测试 (tests/)

```
tests/
├── unit/              # 单元测试
├── integration/       # 集成测试
└── fixtures/          # 测试数据
```

**规则**：
- 测试文件统一放此处
- 不要分散在根目录

---

### 7. 配置 (config/)

```
config/
├── nginx.conf
├── prometheus.yml
└── settings.yaml
```

**规则**：
- 配置文件集中管理
- 环境配置使用 `.env` 或 `config/`

---

## 🚫 禁止事项

### 根目录禁止放置
- ❌ 提取器文件 (`extractor_*.py`)
- ❌ 测试文件 (`test_*.py`)
- ❌ Shell脚本 (`*.sh`)
- ❌ 文档文件 (`*.md`，除README外)
- ❌ 工具脚本 (`*.py` 工具)

### 根目录允许保留
- ✅ `README.md` - 项目说明
- ✅ `LICENSE` - 许可证
- ✅ `.gitignore` - Git忽略配置
- ✅ `requirements.txt` - 依赖文件
- ✅ `pyproject.toml` - 项目配置
- ✅ `DOCS_INDEX.md` - 文档索引
- ✅ `EXTRACTORS_INDEX.md` - 提取器索引
- ✅ 核心入口文件（软链接）

---

## ✅ 新代码放置流程

### 步骤1：确定代码类型
| 代码类型 | 目标目录 |
|---------|---------|
| 新提取器 | `extractors/current/{fusion,llm,utils}/` |
| 文档 | `docs/{changelogs,reports,plans,analysis,guides}/` |
| Shell脚本 | `scripts/shell/` |
| Python工具 | `scripts/utils/` |
| 测试 | `tests/` |
| RAG提取器 | `src/rag/extractors/` |
| 规则库 | `data/rule_bases/` |

### 步骤2：创建文件
```bash
# 示例：创建新提取器
touch extractors/current/fusion/extractor_new_v1.py

# 示例：创建新文档
touch docs/guides/NEW_FEATURE_GUIDE.md

# 示例：创建新工具
touch scripts/utils/new_utility.py
```

### 步骤3：更新索引
- 更新 `DOCS_INDEX.md`（如添加文档）
- 更新 `EXTRACTORS_INDEX.md`（如添加提取器）

### 步骤4：创建软链接（可选）
```bash
# 如果需要在根目录快速访问
ln -s extractors/current/fusion/extractor_new_v1.py extractor_new.py
```

---

## 🔍 代码审查检查项

提交代码前检查：
- [ ] 代码文件不在根目录
- [ ] 文件放在正确的功能目录
- [ ] 已更新相关索引文档
- [ ] 没有重复文件
- [ ] 导入路径正确

---

## 📋 目录索引维护

### 必须维护的索引文件
1. `DOCS_INDEX.md` - 文档索引
2. `EXTRACTORS_INDEX.md` - 提取器索引

### 更新时机
- 新增/删除文档时更新 `DOCS_INDEX.md`
- 新增/归档提取器时更新 `EXTRACTORS_INDEX.md`

---

## 📝 示例

### 示例1：添加新提取器
```bash
# 1. 创建文件
touch extractors/current/fusion/extractor_v13.py

# 2. 编辑代码
# ... 实现提取器 ...

# 3. 更新索引
echo "- extractor_v13.py - v13提取器" >> EXTRACTORS_INDEX.md

# 4. 可选：创建软链接
ln -s extractors/current/fusion/extractor_v13.py extractor_v13.py
```

### 示例2：添加新文档
```bash
# 1. 创建文件
touch docs/guides/V13_USAGE.md

# 2. 编辑文档
# ... 编写文档 ...

# 3. 更新索引
echo "- V13_USAGE.md" >> DOCS_INDEX.md
```

---

## ⚠️ 遗留文件处理

根目录当前遗留文件（待处理）：
- `add_more_rules.py` → `scripts/utils/`
- `entity_disambiguation_prompt.py` → `src/rag/` 或归档
- `entity_disambiguation_system.py` → **保留**（核心功能）
- `extract_complete_sentence.py` → `extractors/archive/`
- `extractor_pc_based.py` → **保留**（有依赖）
- `prompt_v2_revised.py` → `scripts/utils/` 或归档
- `quick_validate.py` → `scripts/utils/`
- `rule_base_complete.py` → `data/rule_bases/`
- `rule_base_loader.py` → `data/rule_bases/`

---

*规范制定时间：2026-04-12*
*维护者：xialab的幸运星*