AcidMap/docs/PROJECT_STRUCTURE.md

项目结构说明

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

整体结构

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

这种组织方式确保了：

• 功能完整性
• 文档完备性
• 测试覆盖率
• 易于维护

总结

良好的项目结构能够：

• 提高开发效率
• 降低维护成本
• 方便新人上手
• 支持项目扩展

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