# 项目结构说明

本文档详细说明了项目的目录结构和组织方式。

## 整体结构

```
AcidMap/
├── app/                    # 主应用代码
├── docs/                   # 项目文档
├── tests/                  # 测试代码
├── scripts/                # 脚本工具
├── data/                   # 数据文件
├── migrations/             # 数据库迁移
├── ssl/                    # SSL证书
├── config.env              # 配置文件
├── environment.yml         # Conda环境配置
├── main.py                 # 应用入口
└── README.md               # 项目说明
```

## 应用代码结构 (app/)

```
app/
├── api/                    # API路由层
│   ├── raster.py          # 栅格数据API
│   ├── vector.py          # 矢量数据API
│   └── unit_grouping.py   # 单元分类API
├── services/              # 业务逻辑层
│   ├── raster_service.py  # 栅格数据服务
│   ├── vector_service.py  # 矢量数据服务
│   └── unit_grouping_service.py  # 单元分类服务
├── models/                # 数据模型
│   └── orm_models.py      # ORM模型定义
├── utils/                 # 工具函数
├── config/                # 配置管理
├── static/                # 静态文件
├── scripts/               # 应用内脚本
├── logs/                  # 日志文件
├── database.py            # 数据库连接
├── main.py                # FastAPI主应用
└── __init__.py
```

## 文档结构 (docs/)

```
docs/
├── features/              # 功能文档
│   ├── unit-grouping/     # 单元分类功能
│   │   └── README.md      # 详细说明文档
│   ├── raster-processing/ # 栅格处理功能 (待添加)
│   └── vector-processing/ # 矢量处理功能 (待添加)
├── api/                   # API文档 (待添加)
├── deployment/            # 部署文档 (待添加)
└── PROJECT_STRUCTURE.md   # 本文档
```

## 测试结构 (tests/)

```
tests/
├── unit/                  # 单元测试
├── integration/           # 集成测试
│   ├── test_unit_grouping.py  # 单元分类集成测试
│   └── test_cd_integration.py # 镉预测集成测试
└── fixtures/              # 测试数据
```

## 脚本工具结构 (scripts/)

```
scripts/
├── demos/                 # 演示脚本
│   └── unit_grouping_demo.py  # 单元分类演示
├── import_farmland_data.py    # 农田数据导入
├── db_health_check.py         # 数据库健康检查
└── import_counties.py         # 县区数据导入
```

## 目录组织原则

### 1. 按功能模块组织
- 每个主要功能模块都有对应的API、服务和文档
- 相关文件集中在一起，便于维护

### 2. 分层架构
- **API层** (app/api/): 处理HTTP请求和响应
- **服务层** (app/services/): 业务逻辑实现
- **模型层** (app/models/): 数据模型和ORM

### 3. 文档优先
- 每个功能模块都有详细的文档说明
- 文档与代码同步维护
- 使用统一的文档格式

### 4. 测试分类
- **单元测试**: 测试单个函数或类
- **集成测试**: 测试完整的功能流程
- **演示脚本**: 提供快速体验功能的方式

## 新功能集成指南

当添加新功能时，请按照以下结构组织文件：

### 1. API实现
```
app/api/your_feature.py
```

### 2. 业务逻辑
```
app/services/your_feature_service.py
```

### 3. 功能文档
```
docs/features/your-feature/
├── README.md              # 功能说明
├── api-reference.md       # API参考 (可选)
└── examples.md            # 使用示例 (可选)
```

### 4. 测试代码
```
tests/integration/test_your_feature.py
```

### 5. 演示脚本 (可选)
```
scripts/demos/your_feature_demo.py
```

### 6. 更新主文档
- 在 `README.md` 中添加功能描述
- 在 `README.md` 中添加API接口说明
- 在本文档中更新目录结构

## 文件命名规范

### 1. 文件名
- 使用小写字母和下划线
- API文件: `{feature}.py`
- 服务文件: `{feature}_service.py`
- 测试文件: `test_{feature}.py`
- 演示脚本: `{feature}_demo.py`

### 2. 目录名
- 使用小写字母和连字符
- 功能目录: `{feature-name}/`
- 文档目录: `docs/features/{feature-name}/`

### 3. 文档名
- 主文档: `README.md`
- 其他文档: `{purpose}.md` (如 `api-reference.md`)

## 最佳实践

### 1. 代码组织
- 保持各层职责清晰
- 避免循环依赖
- 使用依赖注入

### 2. 文档维护
- 代码变更时同步更新文档
- 提供完整的使用示例
- 包含错误处理说明

### 3. 测试覆盖
- 每个功能都要有集成测试
- 重要功能提供演示脚本
- 测试要能独立运行

### 4. 版本控制
- 功能相关的文件一起提交
- 使用清晰的提交信息
- 避免在主目录下堆积临时文件

## 示例：单元分类功能

单元分类功能是按照上述结构组织的一个很好的例子：

- **API**: `app/api/unit_grouping.py`
- **服务**: `app/services/unit_grouping_service.py`
- **文档**: `docs/features/unit-grouping/README.md`
- **测试**: `tests/integration/test_unit_grouping.py`
- **演示**: `scripts/demos/unit_grouping_demo.py`

这种组织方式确保了：
- 功能完整性
- 文档完备性
- 测试覆盖率
- 易于维护

## 总结

良好的项目结构能够：
- 提高开发效率
- 降低维护成本
- 方便新人上手
- 支持项目扩展

请在添加新功能时严格遵循这些组织原则和命名规范。