# 单元分类功能集成说明

## 功能概述

单元分类功能已成功集成到项目中，提供基于点位数据的单元h_xtfx值计算功能。该功能使用反距离加权插值算法，根据五万亩调查数据中的点位信息来计算各单元的土壤环境质量类别(h_xtfx)。

## 核心算法

### 分类逻辑
- **优先保护类**: 数值映射为 1
- **安全利用类**: 数值映射为 2  
- **严格管控类**: 数值映射为 3

### 计算规则
1. **无严格管控类点位时**:
   - 优先判断某类别占比是否≥80%，是则直接采用该类别
   - 否则对优先保护类和安全利用类点位进行反距离加权插值
   
2. **存在严格管控类点位时**:
   - 对所有点位（包括严格管控类）进行反距离加权插值

### 插值结果分类
- ≤ 1.5: 优先保护类
- 1.5 < x ≤ 2.5: 安全利用类
- > 2.5: 严格管控类

## API接口

### 核心功能接口

#### 1. 获取所有单元的h_xtfx分类结果
```http
GET /api/unit-grouping/h_xtfx
```

**响应示例:**
```json
{
  "success": true,
  "data": {
    "1": "优先保护类",
    "2": "安全利用类",
    "3": null,
    "4": "严格管控类"
  },
  "statistics": {
    "total_units": 1000,
    "units_with_data": 856,
    "units_without_data": 144,
    "category_distribution": {
      "优先保护类": 324,
      "安全利用类": 432,
      "严格管控类": 100
    },
    "point_distribution": {
      "优先保护类": 1200,
      "安全利用类": 800,
      "严格管控类": 150
    }
  }
}
```

#### 2. 获取统计信息
```http
GET /api/unit-grouping/statistics
```

#### 3. 获取特定单元的h_xtfx值
```http
GET /api/unit-grouping/unit/{unit_id}
```

### ORM功能接口

#### 4. 获取点位统计信息（ORM）
```http
GET /api/unit-grouping/points/statistics
```

**响应示例:**
```json
{
  "success": true,
  "total_points": 2150,
  "distribution": {
    "优先保护类": {
      "count": 1200,
      "percentage": 55.81
    },
    "安全利用类": {
      "count": 800,
      "percentage": 37.21
    },
    "严格管控类": {
      "count": 150,
      "percentage": 6.98
    }
  }
}
```

#### 5. 批量获取单元信息（ORM）
```http
GET /api/unit-grouping/units/batch?unit_ids=1&unit_ids=2&unit_ids=3
```

**响应示例:**
```json
{
  "success": true,
  "total_requested": 3,
  "total_found": 2,
  "data": [
    {
      "gid": 1,
      "BSM": "440200001",
      "PXZQMC": "广东省",
      "CXZQMC": "韶关市",
      "SUM_NYDTBM": 1234.56,
      "Shape_Area": 987654.32
    }
  ]
}
```

#### 6. 按区域获取点位数据（ORM）
```http
GET /api/unit-grouping/points/by-area?area_name=乐昌市
```

**响应示例:**
```json
{
  "success": true,
  "area_name": "乐昌市",
  "total_points": 125,
  "h_xtfx_distribution": {
    "优先保护类": 80,
    "安全利用类": 35,
    "严格管控类": 10
  },
  "data": [
    {
      "id": 1,
      "dwmc": "LC001",
      "xmc": "乐昌市",
      "zmc": "乐城街道",
      "cmc": "某村",
      "h_xtfx": "优先保护类",
      "lat": 25.123456,
      "lon": 113.654321,
      "ph": 6.5
    }
  ]
}
```

#### 7. 获取数据库摘要信息（ORM）
```http
GET /api/unit-grouping/database/summary
```

**响应示例:**
```json
{
  "success": true,
  "summary": {
    "total_units": 1000,
    "total_points": 2150,
    "points_with_h_xtfx": 2150,
    "h_xtfx_categories": 3,
    "point_distribution": {
      "优先保护类": 1200,
      "安全利用类": 800,
      "严格管控类": 150
    }
  }
}
```

## 项目文件结构

```
app/
├── api/
│   └── unit_grouping.py          # API接口定义
├── services/
│   └── unit_grouping_service.py  # 业务逻辑服务
├── models/
│   └── orm_models.py             # 数据模型(已存在)
└── main.py                       # 主应用(已更新)
```

## 使用步骤

### 1. 安装依赖
确保已安装所需的Python包：
```bash
# 使用conda环境
conda env create -f environment.yml
conda activate your_env_name

# 或使用pip（如果有requirements.txt）
pip install shapely
```

### 2. 启动服务
```bash
# 在项目根目录下运行
uvicorn main:app --reload

# 或使用演示脚本
python scripts/demos/unit_grouping_demo.py
```

### 3. 访问API文档
打开浏览器访问: `http://localhost:8000/docs`

### 4. 测试功能
```bash
# 运行集成测试
python tests/integration/test_unit_grouping.py
```

## 数据模型

### 输入数据
- **unit_ceil表**: 单元几何数据
  - `gid`: 单元ID
  - `geom`: 几何信息
  
- **fifty_thousand_survey_data表**: 五万亩调查数据
  - `id`: 点位ID
  - `geom`: 点位几何信息
  - `h_xtfx`: 土壤环境质量类别

### 输出数据
- 单元ID到h_xtfx分类的映射
- 统计信息（总数、分布等）

## ORM vs SQL 对比

### 使用ORM的优势

1. **类型安全**: 编译时检查，减少运行时错误
2. **代码可维护性**: 更加Pythonic，易于理解和维护
3. **自动化功能**: 
   - 自动处理连接管理
   - 自动类型转换
   - 自动防SQL注入
4. **查询优化**: SQLAlchemy自动优化查询
5. **关系映射**: 自动处理表间关系

### 代码对比示例

**传统SQL方式:**
```python
# 原始SQL查询
unit_query = text("SELECT gid, ST_AsBinary(geom) as geom FROM unit_ceil")
unit_result = self.db_session.execute(unit_query)
unit_rows = unit_result.fetchall()
```

**ORM方式:**
```python
# 使用ORM查询
unit_query = self.db_session.query(
    UnitCeil.gid,
    func.ST_AsBinary(UnitCeil.geom).label('geom')
)
unit_rows = unit_query.all()
```

### 新增的ORM功能

1. **统计查询**: 使用`func.count()`和`group_by()`
2. **批量查询**: 使用`filter(Model.id.in_(ids))`
3. **条件过滤**: 使用`filter()`和`isnot(None)`
4. **结果计数**: 使用`query().count()`

## 性能考虑

1. **空间查询优化**: 使用PostGIS的空间索引来加速点位包含查询
2. **数据过滤**: 只查询有效的h_xtfx值，避免处理空值
3. **异常处理**: 对几何数据解析失败的情况进行graceful处理
4. **日志记录**: 详细的操作日志便于调试和监控
5. **ORM优化**: 
   - 延迟加载减少内存占用
   - 批量查询减少数据库往返
   - 查询缓存提高重复查询性能

## 错误处理

- 数据库连接失败
- 几何数据解析异常
- 插值计算错误
- 单元不存在等情况

所有错误都会返回适当的HTTP状态码和错误信息。

## 扩展功能

未来可以考虑添加：
1. 缓存机制以提高查询性能
2. 批量查询单元功能
3. 结果导出功能（GeoJSON、CSV等）
4. 可视化界面
5. 算法参数配置（如插值权重、阈值等）

## 注意事项

1. 确保数据库中有足够的单元和点位数据
2. 几何数据的坐标系统需要一致
3. 服务启动前确保数据库连接正常
4. 大数据量时可能需要考虑分页处理

## 相关文件

- **API实现**: `app/api/unit_grouping.py`
- **业务逻辑**: `app/services/unit_grouping_service.py`
- **集成测试**: `tests/integration/test_unit_grouping.py`
- **演示脚本**: `scripts/demos/unit_grouping_demo.py`

## 联系方式

如有问题或建议，请联系开发团队。