# 地区三级联动表实现计划

## 目标
创建省份/城市/地区三级联动数据库表，在个人中心"所在位置"字段中使用级联选择，替代当前的静态硬编码数据。

## 当前状态分析

### 现状
- `UserInfoCard.tsx` 中的 `locationOptions` 是静态硬编码的（只包含北京、上海、广东的部分区县）
- `FUser.location` 字段是 `CharField(max_length=100)`，存储格式为 `"省/市/区"` 字符串
- IP定位API (`GetIPDataView`) 返回 `regionName` 和 `city`，但没有结构化存储
- 无地区数据库表

### 问题
- 静态数据覆盖范围有限
- 无法与IP定位数据联动
- 用户体验差（需要手动输入）

## 实现方案

### 1. 创建 Region 模型

**文件**: `c:\Users\12914\Desktop\vscode\chunyu_project\user\models.py`

```python
class Region(models.Model):
    """地区三级联动表 - 省/市/区"""
    REGION_LEVEL_CHOICES = [
        (1, '省份'),
        (2, '城市'),
        (3, '区县'),
    ]
    
    name = models.CharField(max_length=100, verbose_name='地区名称')
    code = models.CharField(max_length=20, unique=True, verbose_name='地区编码')
    level = models.IntegerField(choices=REGION_LEVEL_CHOICES, verbose_name='级别')
    parent = models.ForeignKey('self', on_delete=models.CASCADE, null=True, blank=True, related_name='children', verbose_name='上级地区')
    pinyin = models.CharField(max_length=200, blank=True, verbose_name='拼音')
    sort_order = models.IntegerField(default=0, verbose_name='排序')
    
    class Meta:
        verbose_name = '地区'
        verbose_name_plural = '地区'
        ordering = ['level', 'sort_order', 'code']
        indexes = [
            models.Index(fields=['parent', 'level']),
            models.Index(fields=['code']),
        ]
    
    def __str__(self):
        return self.name
```

### 2. 创建数据迁移文件

**文件**: `c:\Users\12914\Desktop\vscode\chunyu_project\user\migrations\0010_region.py`

迁移文件将：
- 创建 Region 表
- 包含初始数据种子命令的引用

### 3. 创建数据种子命令

**文件**: `c:\Users\12914\Desktop\vscode\chunyu_project\user\management\commands\seed_regions.py`

功能：
- 从JSON文件或内置数据导入全国省市区数据
- 支持增量更新（已存在则跳过）
- 数据来源：国家统计局行政区划代码

### 4. 创建 API 序列化器

**文件**: `c:\Users\12914\Desktop\vscode\chunyu_project\user\serializers\region_serializers.py`

```python
class RegionSerializer(serializers.ModelSerializer):
    children = serializers.SerializerMethodField()
    
    class Meta:
        model = Region
        fields = ['id', 'name', 'code', 'level', 'parent_id', 'children']
    
    def get_children(self, obj):
        children = obj.children.all()
        if children.exists():
            return RegionSerializer(children, many=True).data
        return None
```

### 5. 创建 API 视图

**文件**: `c:\Users\12914\Desktop\vscode\chunyu_project\user\views\region.py`

```python
class RegionListView(APIView):
    """获取地区级联数据"""
    permission_classes = [AllowAny]
    
    def get(self, request):
        # 只返回省级数据，前端按需加载子级
        level = request.GET.get('level', 1)
        parent_code = request.GET.get('parent_code')
        
        if parent_code:
            regions = Region.objects.filter(parent__code=parent_code)
        else:
            regions = Region.objects.filter(level=level)
        
        serializer = RegionSerializer(regions, many=True)
        return Response({'code': 200, 'data': serializer.data})
```

### 6. 注册路由

**文件**: `c:\Users\12914\Desktop\vscode\chunyu_project\user\urls.py`

添加：
```python
path('regions/', region_views.RegionListView.as_view(), name='region-list'),
```

### 7. 前端 API 请求

**文件**: `c:\Users\12914\Desktop\vscode\chunyu_project_react\src\utils\request.ts`

添加：
```typescript
const region = {
  getList: (params?: { level?: number; parent_code?: string }) =>
    request.public.get('/user/regions/', params),
};
```

### 8. 前端组件改造

**文件**: `C:\Users\12914\Desktop\vscode\chunyu_project_react\src\pages\Profile\components\UserInfoCard.tsx`

修改内容：
1. 移除静态 `locationOptions`
2. 添加 `regionOptions` 状态，从API获取省级数据
3. 改造 `Cascader` 组件为动态加载模式
4. 使用 `loadData` 属性实现按需加载子级数据
5. 保存时将地区编码数组转换为 `"省/市/区"` 格式字符串

```typescript
// 新的地区级联选择器
<Cascader
  options={regionOptions}
  loadData={async (selectedOptions) => {
    const targetOption = selectedOptions[selectedOptions.length - 1];
    targetOption.loading = true;
    const children = await region.getList({ parent_code: targetOption.code });
    targetOption.children = children;
    setRegionOptions([...regionOptions]);
  }}
  value={location}
  onChange={(v) => setLocation(v as string[])}
  placeholder="请选择地区"
  expandTrigger="hover"
  displayRender={(labels) => labels.join(" / ")}
  style={{ width: "100%" }}
/>
```

### 9. IP定位联动（可选）

登录时自动填充位置：
- 在 `_create_login_record` 中调用IP API
- 将 `regionName` 和 `city` 存入 `LoginRecord.location`
- 尝试匹配 Region 表中的地区编码

## 文件清单

| 文件 | 操作 | 说明 |
|------|------|------|
| `chunyu_project/user/models.py` | 修改 | 添加 Region 模型 |
| `chunyu_project/user/migrations/0010_region.py` | 新建 | 创建 Region 表迁移 |
| `chunyu_project/user/management/commands/seed_regions.py` | 新建 | 数据种子命令 |
| `chunyu_project/user/serializers/region_serializers.py` | 新建 | 地区序列化器 |
| `chunyu_project/user/views/region.py` | 新建 | 地区API视图 |
| `chunyu_project/user/urls.py` | 修改 | 注册地区路由 |
| `chunyu_project_react/src/utils/request.ts` | 修改 | 添加 region API |
| `chunyu_project_react/src/pages/Profile/components/UserInfoCard.tsx` | 修改 | 使用动态地区数据 |

## 验证步骤

1. 运行 `python manage.py makemigrations` 生成迁移
2. 运行 `python manage.py migrate` 执行迁移
3. 运行 `python manage.py seed_regions` 导入初始数据
4. 访问 `/api/user/regions/` 验证API返回数据
5. 打开个人中心，验证地区级联选择器正常工作
6. 保存位置后验证数据库存储格式正确

## 假设与决策

### 假设
- 前端使用 Ant Design Cascader 组件的 `loadData` 属性实现懒加载
- 初始数据来源于国家统计局行政区划代码
- Region 表数据量约为 3000+ 条（省34个、市300+、区县2800+）

### 决策
- 使用 `parent` 自关联外键实现树形结构
- API 只返回当前级别数据，前端按需加载子级
- 存储格式保持兼容：`"省/市/区"` 字符串