refactor: 重构项目结构，将geo_tools重命名为app并更新相关引用

- 将主包名从geo_tools改为app - 更新所有模块中的引用路径 - 迁移并更新测试用例 - 添加项目规则文档 - 保持原有功能不变，仅进行结构调整
2026-04-12 19:49:56 +08:00
parent fcb8e1f255
commit db51d41aef
41 changed files with 4132 additions and 808 deletions
--- a/项目分析报告.md
+++ b/项目分析报告.md
@@ -0,0 +1,260 @@
+# Geo-Tools 项目分析报告
+
+## 1. 项目概览
+
+Geo-Tools 是一个专业的地理信息数据处理工具库，基于 geopandas、shapely、fiona 等开源地理空间库，提供了统一、简洁的 API 接口，简化地理空间数据处理流程。
+
+- **核心价值**：为地理空间数据处理提供标准化、高效的工具集
+- **应用场景**：科学研究、GIS 分析、土地利用规划、农业分析等
+- **技术特点**：统一数据读写接口、丰富的空间分析功能、坐标系转换支持
+
+## 2. 目录结构
+
+项目采用模块化设计，清晰分离核心功能、IO 操作、分析工具和辅助功能。主要目录结构如下：
+
+```
+geo_tools/
+├── app/                  # 主应用目录
+│   ├── analysis/         # 空间分析模块
+│   │   ├── spatial_ops.py # 空间叠加与邻域分析
+│   │   └── stats.py       # 空间统计工具
+│   ├── config/           # 配置模块
+│   ├── core/             # 核心地理处理层
+│   │   ├── geometry.py   # 几何运算工具
+│   │   ├── projection.py # 坐标系转换
+│   │   ├── raster.py     # 栅格数据处理
+│   │   └── vector.py     # 矢量数据处理
+│   ├── io/               # 数据读写模块
+│   │   ├── readers.py    # 数据读取
+│   │   └── writers.py    # 数据写入
+│   └── utils/            # 工具模块
+│       ├── config.py     # 配置工具
+│       ├── logger.py     # 日志工具
+│       └── validators.py # 数据验证
+├── data/                 # 数据目录
+│   └── sample/           # 示例数据
+├── scripts/              # 脚本目录
+│   └── 其他工具/         # 特定领域工具脚本
+├── tests/                # 测试目录
+└── pyproject.toml        # 项目配置文件
+```
+
+## 3. 核心功能模块
+
+### 3.1 数据读写（IO）
+
+**功能描述**：提供统一的矢量数据读取接口，支持多种格式的数据读写。
+
+**支持格式**：
+- Shapefile (.shp)
+- GeoJSON (.geojson / .json)
+- GeoPackage (.gpkg)
+- File Geodatabase (.gdb) 
+- KML / KMZ
+- FlatGeobuf (.fgb)
+- CSV（含 WKT 或 经纬度列）
+
+**核心方法**：
+- `read_vector()`：统一的矢量数据读取入口
+- `read_gdb()`：读取 Esri File Geodatabase
+- `read_gpkg()`：读取 GeoPackage 文件
+- `read_csv_points()`：从 CSV 读取点数据
+- `list_gdb_layers()`：列出 GDB 中所有图层
+
+### 3.2 几何处理（Core）
+
+**功能描述**：基于 Shapely 提供几何对象的创建、操作和分析功能。
+
+**核心功能**：
+- **几何有效性**：验证和修复几何对象
+- **基础几何运算**：缓冲区、质心、边界框、凸包
+- **集合运算**：交集、并集、差集、对称差集
+- **空间关系判断**：包含、在内部、相交、距离计算
+
+**核心方法**：
+- `is_valid_geometry()`：判断几何对象是否有效
+- `fix_geometry()`：尝试修复无效几何
+- `buffer_geometry()`：对几何对象执行缓冲区运算
+- `intersect()/union()/difference()`：几何集合运算
+- `contains()/within()/intersects()`：空间关系判断
+
+### 3.3 坐标系转换（Core）
+
+**功能描述**：基于 pyproj 提供坐标系信息查询和投影转换功能。
+
+**核心功能**：
+- CRS 信息查询
+- 坐标点批量转换
+- 矢量数据重投影
+- 自动推荐适合的投影 CRS
+
+**核心方法**：
+- `get_crs_info()`：获取 CRS 的基本信息
+- `transform_coordinates()`：批量转换坐标点
+- `reproject_gdf()`：将 GeoDataFrame 重投影到目标坐标系
+- `suggest_projected_crs()`：根据经纬度自动推荐投影 CRS
+
+### 3.4 空间分析（Analysis）
+
+**功能描述**：提供空间叠加、邻域分析和空间统计功能。
+
+**核心功能**：
+- **空间叠加**：缓冲区叠加、图层叠加
+- **邻域分析**：最近邻分析
+- **位置选择**：按空间关系选择要素
+- **空间统计**：面积加权均值、属性汇总、点计数
+
+**核心方法**：
+- `buffer_and_overlay()`：缓冲区后执行叠置分析
+- `nearest_features()`：找到最近的要素
+- `select_by_location()`：按位置关系选择要素
+- `area_weighted_mean()`：计算面积加权均值
+- `summarize_attributes()`：属性统计汇总
+- `count_by_polygon()`：统计面要素内的点数量
+
+## 4. 技术架构与依赖
+
+### 4.1 核心依赖
+
+| 依赖库 | 版本要求 | 用途 |
+|-------|---------|------|
+| geopandas | >=0.14 | 地理空间数据处理核心库 |
+| shapely | >=2.0 | 几何对象操作 |
+| fiona | >=1.9 | 矢量数据读写 |
+| pyproj | >=3.6 | 坐标系转换 |
+| pandas | >=2.0 | 数据处理 |
+| numpy | >=1.24 | 数值计算 |
+| pydantic | >=2.0 | 数据验证 |
+| pydantic-settings | >=2.0 | 配置管理 |
+| python-dotenv | >=1.0 | 环境变量管理 |
+
+### 4.2 可选依赖
+
+| 依赖组 | 包含库 | 用途 |
+|-------|-------|------|
+| dev | pytest, black, isort, flake8, mypy | 测试和代码质量工具 |
+| notebook | jupyter, matplotlib, contextily, folium | 交互式分析和可视化 |
+| raster | rasterio, xarray, rio-cogeo | 栅格数据处理 |
+
+### 4.3 技术架构
+
+项目采用分层架构设计：
+
+1. **底层依赖层**：基于 geopandas、shapely、fiona 等核心库
+2. **核心处理层**：提供几何运算、坐标系转换等基础功能
+3. **IO 层**：统一数据读写接口，支持多种格式
+4. **分析层**：提供空间分析和统计功能
+5. **工具层**：提供配置、日志、验证等辅助功能
+6. **应用层**：通过脚本和 API 接口供用户使用
+
+## 5. 业务定位与应用场景
+
+### 5.1 业务定位
+
+Geo-Tools 定位为专业的地理信息数据处理工具库，主要服务于以下场景：
+
+- **科学研究**：为地理空间相关研究提供数据处理和分析工具
+- **GIS 专业人员**：简化日常工作流程，提高处理效率
+- **土地利用规划**：支持空间分析和统计功能
+- **农业分析**：如耕作层厚度栅格制作、面积加权均值计算等
+
+### 5.2 应用场景
+
+从项目中的脚本和功能来看，主要应用场景包括：
+
+1. **数据格式转换**：在不同地理数据格式之间转换
+2. **空间分析**：缓冲区分析、叠加分析、邻域分析
+3. **空间统计**：面积加权均值、属性汇总、点计数
+4. **坐标系管理**：不同坐标系之间的转换和管理
+5. **农业分析**：如耕作层厚度分析、区域面积统计
+
+### 5.3 典型工作流
+
+1. **数据读取**：从各种格式读取地理空间数据
+2. **数据校验**：验证几何有效性和坐标系信息
+3. **数据处理**：几何运算、坐标系转换
+4. **空间分析**：执行叠加分析、邻域分析等
+5. **统计计算**：计算面积加权均值、属性汇总等
+6. **结果输出**：将处理结果写入各种格式
+
+## 6. 核心 API/类/函数
+
+### 6.1 数据读写 API
+
+| 函数名 | 功能描述 | 参数说明 | 返回值 |
+|-------|---------|---------|-------|
+| `read_vector()` | 统一的矢量数据读取入口 | path: 数据路径<br>layer: 图层名<br>crs: 目标坐标系 | GeoDataFrame |
+| `read_gdb()` | 读取 Esri File Geodatabase | gdb_path: GDB 路径<br>layer: 图层名 | GeoDataFrame |
+| `list_gdb_layers()` | 列出 GDB 中所有图层 | gdb_path: GDB 路径 | list[str] |
+| `write_vector()` | 统一的矢量数据写入 | gdf: GeoDataFrame<br>path: 输出路径 | None |
+
+### 6.2 几何处理 API
+
+| 函数名 | 功能描述 | 参数说明 | 返回值 |
+|-------|---------|---------|-------|
+| `is_valid_geometry()` | 判断几何对象是否有效 | geom: 几何对象 | bool |
+| `fix_geometry()` | 尝试修复无效几何 | geom: 几何对象 | BaseGeometry |
+| `buffer_geometry()` | 对几何对象执行缓冲区运算 | geom: 几何对象<br>distance: 缓冲距离 | BaseGeometry |
+| `intersect()/union()/difference()` | 几何集合运算 | geom_a, geom_b: 几何对象 | BaseGeometry |
+
+### 6.3 坐标系转换 API
+
+| 函数名 | 功能描述 | 参数说明 | 返回值 |
+|-------|---------|---------|-------|
+| `get_crs_info()` | 获取 CRS 的基本信息 | crs_input: CRS 输入 | dict |
+| `transform_coordinates()` | 批量转换坐标点 | xs, ys: 坐标序列<br>source_crs: 源 CRS<br>target_crs: 目标 CRS | (list[float], list[float]) |
+| `reproject_gdf()` | 将 GeoDataFrame 重投影 | gdf: GeoDataFrame<br>target_crs: 目标 CRS | GeoDataFrame |
+| `suggest_projected_crs()` | 自动推荐投影 CRS | lon, lat: 经纬度 | str |
+
+### 6.4 空间分析 API
+
+| 函数名 | 功能描述 | 参数说明 | 返回值 |
+|-------|---------|---------|-------|
+| `buffer_and_overlay()` | 缓冲区后执行叠置分析 | source: 源图层<br>distance: 缓冲距离<br>target: 目标图层 | GeoDataFrame |
+| `nearest_features()` | 找到最近的要素 | source: 查询图层<br>target: 被查询图层<br>k: 最近邻数量 | GeoDataFrame |
+| `select_by_location()` | 按位置关系选择要素 | source: 源图层<br>selector: 选择图层<br>predicate: 空间谓词 | GeoDataFrame |
+| `area_weighted_mean()` | 计算面积加权均值 | gdf: GeoDataFrame<br>value_col: 值列名<br>group_col: 分组列名 | pd.Series 或 pd.DataFrame |
+
+## 7. 技术亮点与优势
+
+1. **统一的数据读写接口**：支持多种格式，简化数据输入输出流程
+2. **丰富的几何运算功能**：基于 Shapely 提供全面的几何操作
+3. **智能的坐标系管理**：自动推荐适合的投影 CRS，简化坐标系转换
+4. **强大的空间分析能力**：支持缓冲区分析、叠加分析、邻域分析等
+5. **灵活的空间统计功能**：面积加权均值、属性汇总、点计数等
+6. **良好的错误处理**：提供友好的错误信息，便于调试
+7. **模块化设计**：清晰的代码结构，便于维护和扩展
+8. **完善的文档**：详细的函数文档和示例代码
+
+## 8. 潜在应用领域
+
+1. **土地利用规划**：分析土地利用类型、面积统计
+2. **农业分析**：耕作层厚度分析、农田面积计算
+3. **环境监测**：生态区域分析、污染源影响范围评估
+4. **城市规划**：基础设施布局、服务范围分析
+5. **交通规划**：路线分析、站点服务范围
+6. **灾害评估**：灾害影响范围分析、风险评估
+7. **市场分析**：商业网点覆盖范围、人口分布分析
+
+## 9. 项目发展建议
+
+1. **增强栅格数据处理能力**：目前栅格处理是可选依赖，可考虑增强其功能
+2. **添加更多空间分析算法**：如空间插值、网络分析等
+3. **开发可视化工具**：集成更多可视化功能，便于结果展示
+4. **提供更多领域特定工具**：针对不同领域开发专用工具
+5. **完善测试覆盖**：增加更多测试用例，提高代码质量
+6. **优化性能**：对大型数据集的处理性能进行优化
+7. **提供更多示例**：增加不同领域的应用示例
+
+## 10. 总结
+
+Geo-Tools 是一个功能强大、设计合理的地理信息数据处理工具库，基于成熟的开源地理空间库，提供了统一、简洁的 API 接口，简化了地理空间数据的处理流程。
+
+该项目的核心价值在于：
+- 提供了标准化的地理空间数据处理工具
+- 支持多种数据格式的读写
+- 提供丰富的空间分析和统计功能
+- 简化了坐标系管理和转换
+- 为不同领域的地理空间分析提供了基础工具
+
+Geo-Tools 不仅是一个实用的工具库，也是学习地理空间数据处理的良好资源，通过模块化的设计和清晰的文档，为用户提供了一个易于使用和扩展的地理信息处理框架。