# 数据字典类字段显示与导出实现方式

## 1. 后端接口请求

### 1.1 批量字典查询接口

项目采用"前端预加载字典 + 本地映射"方案，后端提供批量查询接口，前端一次性获取页面所需的所有字典数据。

**接口位置**: `jeecg-boot/.../dictionary/controller/DictionaryController.java`

```java
@Operation(summary = "批量根据字典编码获取字典项")
@PostMapping(value = "/getDictBatch")
public Result<Map<String, List<Map<String, Object>>>> getDictBatch(@RequestBody List<String> dictionaryCodes) {
    return Result.OK(dictionaryItemService.getDictItemsBatch(dictionaryCodes));
}
```

- Controller 只负责参数接收和结果返回，业务逻辑在 Service 层实现
- Service 层通过 QueryWrapper 查询 `DICTIONARY_ITEM` 表，按 `OrderNo` 排序，结果封装为 `{label, value}` 格式

**请求示例**:

```
POST /system/dictionary/getDictBatch
Content-Type: application/json

["Gender", "MaritalStatus"]
```

**返回格式**（`Result` 包装后的 `result` 字段内容）:

```json
{
  "Gender": [
    { "label": "男性", "value": 1 },
    { "label": "女性", "value": 2 }
  ],
  "MaritalStatus": [
    { "label": "未婚", "value": 1 },
    { "label": "已婚", "value": 2 }
  ]
}
```

### 1.2 业务接口设计原则

业务接口（如人员列表查询）只返回字典 value（数字编码），不做 JOIN 查 label。例如人员信息接口返回
`{ gender: 1, maritalStatus: 2 }`，label 的转换由前端统一完成。这样业务接口与字典表解耦，字典变更不影响业务接口。

> **Excel 导出场景**：导出时采用"后端内存映射"方案（详见第 5 章），导出前批量查询字典，在内存中将字典值替换为中文标签，再由
> AutoPoi 写入 Excel。

---

## 2. 前端数据缓存

### 2.1 useDict 工具

**位置**: `jeecgboot-vue3/src/hooks/dictionary/useDict.ts`

`useDict` 是一个 Vue 3 composable，负责从后端批量接口加载字典数据，并维护全局响应式缓存。

#### 核心设计

- **模块级单例缓存**：使用 `reactive()` 创建模块级 `dictCache` 对象，多个组件实例共享同一份缓存，只发起一次网络请求
- **防重复请求**：当已有请求在途中时，后续调用方等待同一请求完成，完成后再次检查是否仍缺失所需字典，缺则继续发起新请求
- **响应式更新**：缓存数据加载完成后，所有依赖 `dictCache` 的 `computed` 和模板自动刷新
- **类型统一**：后端 `DictionaryItem.value` 为 `Integer`，`PersonalInfo` 中字典字段为 `String`，缓存时通过
  `String(item.value)` 统一转为字符串，确保 `<a-select>` 的 `v-model` 能正确匹配选项

#### 导出方法

| 方法                         | 用途                                 |
|----------------------------|------------------------------------|
| `getDictText(code, value)` | 根据字典编码和 value 获取对应 label，用于表格列显示   |
| `getDictOptions(code)`     | 获取 `{label, value}[]` 选项列表，用于下拉框绑定 |
| `fetchDicts()`             | 手动触发字典加载（在 `onMounted` 中自动调用）      |

`getDictText` 内部使用 `String(i.value) === String(value)` 做类型不敏感比较，兼容后端返回的数字和字符串类型混用场景。

#### 使用方式

```typescript
import { useDict } from '/@/hooks/dictionary/useDict';

const { getDictText, getDictOptions } = useDict([
  'Gender', 'MaritalStatus', 'JobSeekerCategory'
]);
```

---

## 3. 页面 input 组件实现

### 3.1 列表页搜索框

**位置**: `jeecgboot-vue3/src/views/recruitment/personal/PersonalInfoList.vue`

预加载字典后，用 `<a-select>` 绑定 `getDictOptions()` 返回的选项列表，替代原来的 `<j-dict-select-tag>` 或 `<a-input>`。

```vue
<script setup lang="ts">
const { getDictOptions } = useDict(['Gender', 'JobSeekerCategory', 'JobSeekerStatus', 'DataSource']);
const genderOptions = computed(() => getDictOptions('Gender'));
const jobSeekerCategoryOptions = computed(() => getDictOptions('JobSeekerCategory'));
const jobSearchStatusOptions = computed(() => getDictOptions('JobSeekerStatus'));
const dataSourceOptions = computed(() => getDictOptions('DataSource'));
</script>

<template>
  <a-select v-model:value="queryParam.gender" placeholder="请选择性别"
            allow-clear :options="genderOptions" />
  <a-select v-model:value="queryParam.jobSeekerCategory" placeholder="请选择求职人员类别"
            allow-clear :options="jobSeekerCategoryOptions" />
  <a-select v-model:value="queryParam.jobSearchStatus" placeholder="请选择求职状态"
            allow-clear :options="jobSearchStatusOptions" />
  <a-select v-model:value="queryParam.dataSource" placeholder="请选择数据来源"
            allow-clear :options="dataSourceOptions" />
</template>
```

### 3.2 表单页编辑字段

**位置**: `jeecgboot-vue3/src/views/recruitment/personal/components/PersonalInfoForm.vue`

将字典相关的字段从 `<a-input>` 改为 `<a-select>` 下拉选择。表单页需要加载所有涉及的字典，包括列表页可能没用到但表单编辑需要的字典。

```vue
<script setup lang="ts">
const { getDictOptions } = useDict([
  'IDType', 'Gender', 'MaritalStatus', 'PoliticalStatus',
  'WorkExperience', 'HouseholdType',
  'JobSeekerCategory', 'JobSeekerStatus', 'DataSource'
]);

const idTypeOptions = computed(() => getDictOptions('IDType'));
const genderOptions = computed(() => getDictOptions('Gender'));
const maritalStatusOptions = computed(() => getDictOptions('MaritalStatus'));
const politicalStatusOptions = computed(() => getDictOptions('PoliticalStatus'));
const workExperienceOptions = computed(() => getDictOptions('WorkExperience'));
const householdTypeOptions = computed(() => getDictOptions('HouseholdType'));
const jobSeekerCategoryOptions = computed(() => getDictOptions('JobSeekerCategory'));
const jobSearchStatusOptions = computed(() => getDictOptions('JobSeekerStatus'));
const dataSourceOptions = computed(() => getDictOptions('DataSource'));
</script>

<template>
  <a-form-model-item label="性别" prop="gender">
    <a-select v-model:value="formData.gender" placeholder="请选择性别"
              allow-clear :options="genderOptions" />
  </a-form-model-item>
  <a-form-model-item label="婚姻状况" prop="maritalStatus">
    <a-select v-model:value="formData.maritalStatus" placeholder="请选择婚姻状况"
              allow-clear :options="maritalStatusOptions" />
  </a-form-model-item>
  <!-- 其他字典字段类似 -->
</template>
```

---

## 4. 数据表格显示

### 4.1 使用 bodyCell 插槽翻译字典值

**位置**: `jeecgboot-vue3/src/views/recruitment/personal/PersonalInfoList.vue`

表格列通过 `column.dataIndex` 配置为字典字段的 value 字段名，渲染时由 `bodyCell` 插槽拦截，调用 `getDictText()` 将 value
翻译为 label 显示。

```vue
<BasicTable @register="registerTable">
  <template v-slot:bodyCell="{ column, text }">
    <template v-if="column.dataIndex === 'gender'">
      {{ getDictText('Gender', text) }}
    </template>
    <template v-else-if="column.dataIndex === 'jobSeekerCategory'">
      {{ getDictText('JobSeekerCategory', text) }}
    </template>
    <template v-else-if="column.dataIndex === 'jobSearchStatus'">
      {{ getDictText('JobSeekerStatus', text) }}
    </template>
    <template v-else-if="column.dataIndex === 'dataSource'">
      {{ getDictText('DataSource', text) }}
    </template>
    <!-- 非字典字段不做处理 -->
  </template>
</BasicTable>
```

### 4.2 处理逻辑

1. 表格从业务接口获取原始数据，字典字段只包含 value（如 `{ gender: 1 }`）
2. JeecgBoot 的 `BasicTable` 渲染时，`bodyCell` 插槽的 `text` 参数即为原始 value
3. 通过 `column.dataIndex` 识别哪个列是字典字段
4. 调用对应的 `getDictText('字典编码', text)` 从缓存中查找匹配项
5. 匹配成功显示 label，匹配失败回退显示原始 value

---

## 5. Excel 导出字典映射（后端内存映射方案）

### 5.1 方案说明

Excel 导出由后端直接生成文件，不经过前端映射。采用"后端内存映射"方案：

- 导出前通过 `IDictionaryItemService.getDictItemsBatch()` 批量查询导出涉及的所有字典
- 构建 `Map<字典编码, Map<value, label>>` 快速查找结构
- 遍历导出数据，将实体中字典字段的 value 值替换为对应的中文 label
- 替换完成后交由 AutoPoi 框架写入 Excel

### 5.2 职责划分

字典翻译的业务逻辑不在 Controller 中实现，而是提取到 Service 层，遵循分层架构原则：

| 层级             | 职责                                 | 文件                             |
|----------------|------------------------------------|--------------------------------|
| **Controller** | 参数接收、查询条件组装、选中数据过滤、ModelAndView 构建 | `PersonalInfoController.java`  |
| **Service**    | 批量查询字典、构建 value→label 映射、遍历替换实体字段值 | `PersonalInfoServiceImpl.java` |

### 5.3 Controller 层代码

**位置**: `jeecg-boot/.../personal/controller/PersonalInfoController.java`（`exportXls` 方法）

Controller 只负责请求处理和视图构建，字典翻译逻辑委托给 Service：

```java
@RequiresPermissions("personal:personal_info:exportXls")
@RequestMapping(value = "/exportXls")
public ModelAndView exportXls(HttpServletRequest request, PersonalInfo personalInfo) {
    // Step.1 组装查询条件
    QueryWrapper<PersonalInfo> queryWrapper = QueryGenerator.initQueryWrapper(personalInfo, request.getParameterMap());
    LoginUser sysUser = (LoginUser) SecurityUtils.getSubject().getPrincipal();

    // 过滤选中数据
    String selections = request.getParameter("selections");
    if (oConvertUtils.isNotEmpty(selections)) {
        List<String> selectionList = Arrays.asList(selections.split(","));
        queryWrapper.in("id", selectionList);
    }

    // Step.2 获取导出数据并进行字典值→标签内存映射（业务逻辑委托给 Service）
    List<PersonalInfo> exportList = personalInfoService.translateDictFields(
            service.list(queryWrapper), EXPORT_DICT_FIELD_MAP);

    // Step.3 AutoPoi 导出Excel（此时字典字段已替换为中文标签）
    ModelAndView mv = new ModelAndView(new JeecgEntityExcelView());
    String title = "个人基本信息表";
    mv.addObject(NormalExcelConstants.FILE_NAME, title);
    mv.addObject(NormalExcelConstants.CLASS, PersonalInfo.class);
    ExportParams exportParams = new ExportParams(title + "报表", "导出人:" + sysUser.getRealname(), title, ExcelType.XSSF);
    mv.addObject(NormalExcelConstants.PARAMS, exportParams);
    mv.addObject(NormalExcelConstants.DATA_LIST, exportList);

    String exportFields = "fullName,gender,birthDate,education,householdLocation,currentResidence,jobSeekerCategory,contactPhone,jobSearchStatus,dataSource";
    mv.addObject(NormalExcelConstants.EXPORT_FIELDS, exportFields);
    return mv;
}
```

### 5.4 Service 层实现

**位置**: `jeecg-boot/.../personal/service/IPersonalInfoService.java`（接口声明）

```java
/**
 * 导出时对字典字段进行值→标签的内存映射翻译
 *
 * @param list         待导出的数据列表
 * @param fieldDictMap 字段名→字典编码 的映射关系
 * @return 字典字段已替换为中文标签的数据列表
 */
List<PersonalInfo> translateDictFields(List<PersonalInfo> list, Map<String, String> fieldDictMap);
```

**位置**: `jeecg-boot/.../personal/service/impl/PersonalInfoServiceImpl.java`（实现）

```java
@Service
public class PersonalInfoServiceImpl extends ServiceImpl<PersonalInfoMapper, PersonalInfo>
        implements IPersonalInfoService {

    @Autowired
    private IDictionaryItemService dictionaryItemService;

    @Override
    public List<PersonalInfo> translateDictFields(List<PersonalInfo> list, Map<String, String> fieldDictMap) {
        // 批量查询导出涉及的所有字典数据
        List<String> dictCodes = new ArrayList<>(fieldDictMap.values());
        Map<String, List<Map<String, Object>>> dictData = dictionaryItemService.getDictItemsBatch(dictCodes);

        // 构建 value→label 快速查找映射: Map<字典编码, Map<value, label>>
        Map<String, Map<String, String>> valueLabelMap = new HashMap<>();
        for (Map.Entry<String, List<Map<String, Object>>> entry : dictData.entrySet()) {
            Map<String, String> valueToLabel = new HashMap<>();
            for (Map<String, Object> item : entry.getValue()) {
                valueToLabel.put(String.valueOf(item.get("value")), String.valueOf(item.get("label")));
            }
            valueLabelMap.put(entry.getKey(), valueToLabel);
        }

        // 遍历导出数据，将字典字段的值替换为对应的中文标签
        for (PersonalInfo info : list) {
            for (Map.Entry<String, String> fieldEntry : fieldDictMap.entrySet()) {
                String fieldName = fieldEntry.getKey();
                String dictCode = fieldEntry.getValue();
                Map<String, String> mapping = valueLabelMap.get(dictCode);
                if (mapping == null) continue;

                switch (fieldName) {
                    case "gender":
                        if (info.getGender() != null)
                            info.setGender(mapping.getOrDefault(info.getGender(), info.getGender()));
                        break;
                    case "jobSeekerCategory":
                        if (info.getJobSeekerCategory() != null)
                            info.setJobSeekerCategory(mapping.getOrDefault(info.getJobSeekerCategory(), info.getJobSeekerCategory()));
                        break;
                    case "jobSearchStatus":
                        if (info.getJobSearchStatus() != null)
                            info.setJobSearchStatus(mapping.getOrDefault(info.getJobSearchStatus(), info.getJobSearchStatus()));
                        break;
                    case "dataSource":
                        if (info.getDataSource() != null)
                            info.setDataSource(mapping.getOrDefault(info.getDataSource(), info.getDataSource()));
                        break;
                }
            }
        }
        return list;
    }
}
```

### 5.5 字段映射配置

**位置**: `PersonalInfoController.java`（类级别常量）

```java
/**
 * 导出字段与字典编码的映射关系：entity字段名 → 字典编码
 * 用于导出时自动将字典值翻译为中文标签
 */
private static final Map<String, String> EXPORT_DICT_FIELD_MAP = new LinkedHashMap<>();

static {
    EXPORT_DICT_FIELD_MAP.put("gender", "Gender");
    EXPORT_DICT_FIELD_MAP.put("jobSeekerCategory", "JobSeekerCategory");
    EXPORT_DICT_FIELD_MAP.put("jobSearchStatus", "JobSeekerStatus");
    EXPORT_DICT_FIELD_MAP.put("dataSource", "DataSource");
}
```

如需为其他字典字段添加导出翻译，只需在此映射中追加条目，并在 Service 的 `switch` 中添加对应 case 即可。

### 5.6 数据流

```
业务库数据: { gender: "1", jobSeekerCategory: "2", jobSearchStatus: "1", dataSource: "1" }
     │
     ▼  Service.translateDictFields()
     │
     ├── ① getDictItemsBatch(["Gender", "JobSeekerCategory", "JobSeekerStatus", "DataSource"])
     │
     ├── ② 构建 value→label 映射
     │    { Gender → {"1"→"男性", "2"→"女性"}, ... }
     │
     ├── ③ 遍历替换实体字段值
     │    { gender: "男性", jobSeekerCategory: "失业人员", jobSearchStatus: "待业中", dataSource: "系统录入" }
     │
     └── ④ 返回替换后的列表给 Controller
     │
     ▼  Controller → AutoPoi → Excel
     Excel 中直接显示中文标签
```

### 5.7 与前端映射方案对比

| 环节     | 前端映射方案                         | 后端内存映射方案                   |
|--------|--------------------------------|----------------------------|
| 适用场景   | 页面展示、查询表单、编辑表单                 | Excel 导出                   |
| 字典查询时机 | 页面挂载时一次性预加载                    | 导出时实时查询                    |
| 缓存方式   | `reactive()` 模块级全局缓存           | 临时 Map，导出完成后丢弃             |
| 替换方式   | `bodyCell` 插槽中 `getDictText()` | Service 层 setter 直接修改实体字段值 |
| 逻辑归属   | 前端 `useDict` composable        | 后端 Service 层               |
| 字典变更影响 | 页面刷新后生效                        | 每次导出实时查询，立即生效              |

---

## 6. 树形字典（以行政区划 XZQH 为例）

### 6.1 方案概述

对于大规模层级数据（如行政区划 44K+ 节点、职业分类 2K+ 节点），不能使用第 1~5 章的扁平字典方案一次性全量加载。
本方案采用"懒加载树 + 双字段存储"策略：

| 项目 | 说明 |
|------|------|
| **存储方案** | 实体存两个字段：叶子代码（已有列，如 `householdLocation`）+ 完整路径（新增列，如 `householdAreaName`） |
| **后端加载** | 懒加载接口 `/getDictTreeChildren`，按需加载当前展开层级的子节点 |
| **前端编辑** | `<a-tree-select>` + `loadData` 懒加载 + `labelInValue` 回显完整路径 |
| **前端回显** | 编辑时直接用已存储的完整路径文本（`householdAreaName`），无需调 API |
| **表格/详情/导出** | 直接显示 `householdAreaName` 字段，无需字典翻译 |

### 6.2 数据模型设计

数据库表中已有叶子代码列，新增完整路径文本列：

**位置**: `.docs/sql/个人信息与简历信息.sql`

```sql
ALTER TABLE PERSONAL_INFO ADD HOUSEHOLD_AREA_NAME VARCHAR(500);
COMMENT ON COLUMN PERSONAL_INFO.HOUSEHOLD_AREA_NAME IS '户口所在地完整路径（如：广东省湛江市赤坎区）';
ALTER TABLE PERSONAL_INFO ADD RESIDENCE_AREA_NAME VARCHAR(500);
COMMENT ON COLUMN PERSONAL_INFO.RESIDENCE_AREA_NAME IS '现居住地完整路径（如：广东省湛江市赤坎区）';
```

**Entity 新增字段**（位置：`PersonalInfo.java`）：

```java
/** 户口所在地完整路径 */
@Excel(name = "户口所在地完整路径", width = 25)
private java.lang.String householdAreaName;

/** 现居住地完整路径 */
@Excel(name = "现居住地完整路径", width = 25)
private java.lang.String residenceAreaName;
```

### 6.3 后端接口

所有树形字典接口位于 `DictionaryController.java`，路径前缀 `/system/dictionary`。

#### 6.3.1 懒加载子节点（核心接口）

```
GET /system/dictionary/getDictTreeChildren?dictionaryCode=XZQH&parentCode=
```

- `parentCode` 为空时返回根节点（省级）
- 返回格式 `[{key, title, leaf}]`，`leaf=true` 表示叶子节点（无展开箭头）
- 通过一次批量 `SELECT DISTINCT ParentItemID` 查询判断每个子节点是否有后代，避免 N+1

**Service 实现位置**: `DictionaryItemServiceImpl.java` → `getDictTreeChildren()`

#### 6.3.2 获取完整路径

```
GET /system/dictionary/getItemFullPath?dictionaryCode=XZQH&code=440802
→ "广东省湛江市赤坎区"
```

沿 `parentItemId` 链从叶子节点向上回溯，将各层级名称拼接。

**Service 实现位置**: `DictionaryItemServiceImpl.java` → `getItemFullPath()`

#### 6.3.3 根据 code 回显名称（value→label）

```
GET /system/dictionary/loadDictItem/XZQH?key=440100,440200
→ ["广州市", "韶关市"]
```

支持逗号分隔批量查询，按 key 的原始顺序返回。

#### 6.3.4 模糊搜索（用于搜索展开）

```
GET /system/dictionary/searchDictItem?dictionaryCode=XZQH&keyword=湛江&limit=20
→ [{code, name, fullPath, ancestorCodes}, ...]
```

按 `Name LIKE '%keyword%'` 模糊匹配，附带完整路径和祖先节点 code 链。

### 6.4 前端编辑表单实现

**位置**: `jeecgboot-vue3/src/views/recruitment/personal/components/PersonalInfoForm.vue`

#### 6.4.1 模板

使用 `<a-tree-select>` 替代 `<a-input>`：

```vue
<a-tree-select
  v-model:value="householdValueObj"
  v-model:tree-expanded-keys="householdExpandedKeys"
  :tree-data="householdTreeData"
  :load-data="(node) => loadTreeChildren(node, 'householdTreeData')"
  placeholder="请选择户口所在地"
  allow-clear
  label-in-value
  @change="(val) => handleAreaChange(val, 'household')"
/>
```

关键属性：
- `label-in-value`: v-model 绑定 `{value, label}` 对象，支持自定义显示文本
- `load-data`: 展开节点时触发懒加载
- `tree-expanded-keys`: 受控展开，编辑回显时可自动展开祖先层级
- 不使用 `show-search`（内置客户端搜索无法覆盖懒加载未加载的节点）

#### 6.4.2 根节点加载

```typescript
async function loadAreaRootNodes() {
  const res = await defHttp.get({
    url: '/system/dictionary/getDictTreeChildren',
    params: { dictionaryCode: 'XZQH', parentCode: '' },
  }, { isTransformResponse: false });
  if (res.success && res.result) {
    return res.result.map((item) => ({
      key: item.key, title: item.title, value: item.key, isLeaf: item.leaf,
    }));
  }
  return [];
}

// onMounted 中调用
const rootNodes = await loadAreaRootNodes();
householdTreeData.value = rootNodes;
residenceTreeData.value = rootNodes;
```

#### 6.4.3 懒加载子节点

```typescript
async function loadTreeChildren(treeNode, treeDataRefName) {
  // 避免重复加载
  if (treeNode.dataRef.children) return Promise.resolve();

  const res = await defHttp.get({
    url: '/system/dictionary/getDictTreeChildren',
    params: { dictionaryCode: 'XZQH', parentCode: treeNode.value },
  }, { isTransformResponse: false });

  if (res.success && res.result) {
    const children = res.result.map((item) => ({
      key: item.key, title: item.title, value: item.key, isLeaf: item.leaf,
    }));
    // 挂子节点到 a-tree-select 的 dataRef 上
    treeNode.dataRef.children = children;
    // 强制触发 Vue 响应式更新
    if (treeDataRefName === 'householdTreeData') {
      householdTreeData.value = [...householdTreeData.value];
    } else {
      residenceTreeData.value = [...residenceTreeData.value];
    }
  }
  return Promise.resolve();
}
```

> **注意**：`defHttp.get` 需传入 `{ isTransformResponse: false }`，否则框架会自动解包只返回 `data.result`，导致 `res.success` 无法判断。

#### 6.4.4 选择变更处理

```typescript
async function handleAreaChange(val, prefix) {
  if (val && val.value) {
    // 存叶子代码到已有列
    formData[`${prefix}Location`] = val.value;
    // 调 API 获取完整路径，存到新增的 areaName 列
    const res = await defHttp.get({
      url: '/system/dictionary/getItemFullPath',
      params: { dictionaryCode: 'XZQH', code: val.value },
    }, { isTransformResponse: false });
    const fullPath = res.success ? res.result : val.label;
    formData[`${prefix}AreaName`] = fullPath;
    // 更新下拉框显示为完整路径
    if (prefix === 'household') {
      householdValueObj.value = { value: val.value, label: fullPath };
    } else {
      residenceValueObj.value = { value: val.value, label: fullPath };
    }
  } else {
    // 清空
    formData[`${prefix}Location`] = '';
    formData[`${prefix}AreaName`] = '';
    // ...
  }
}
```

#### 6.4.5 编辑回显

编辑时直接从数据记录中取已存储的路径文本，**无需调 API**：

```typescript
function edit(record) {
  nextTick(() => {
    // ...赋值 formData
    householdValueObj.value = tmpData.householdLocation
      ? { value: tmpData.householdLocation, label: tmpData.householdAreaName || tmpData.householdLocation }
      : undefined;
    residenceValueObj.value = tmpData.currentResidence
      ? { value: tmpData.currentResidence, label: tmpData.residenceAreaName || tmpData.currentResidence }
      : undefined;
  });
}
```

### 6.5 表格列显示

**位置**: `jeecgboot-vue3/src/views/recruitment/personal/PersonalInfo.data.ts`

树形字典字段的 `dataIndex` 直接指向 `areaName` 列，**无需 `bodyCell` 插槽字典翻译**：

```typescript
{
  title: '户口所在地',
  align: 'center',
  dataIndex: 'householdAreaName',  // ← 直接用路径文本列，不翻译
  width: 200,
},
{
  title: '现居住地',
  align: 'center',
  dataIndex: 'residenceAreaName',
  width: 200,
},
```

### 6.6 详情弹窗显示

**位置**: `jeecgboot-vue3/src/views/recruitment/personal/components/PersonalInfoDetailModal.vue`

```vue
<a-descriptions-item label="户口所在地" :span="1">
  {{ detailData.householdAreaName || detailData.householdLocation || '-' }}
</a-descriptions-item>
<a-descriptions-item label="现居住地" :span="1">
  {{ detailData.residenceAreaName || detailData.currentResidence || '-' }}
</a-descriptions-item>
```

优先显示路径文本，无数据时回退显示叶子代码。

### 6.7 Excel 导出

**位置**: `PersonalInfoController.java` → `exportXls()`

树形字典字段已在 `PersonalInfo` Entity 上有独立的 `householdAreaName`/`residenceAreaName` 列，且标注了 `@Excel` 注解。
导出字段列表中直接包含这两个列名即可，**无需走 `translateDictFields` 字典映射**：

```java
String exportFields = "...",
    + "householdAreaName,residenceAreaName,"
    + "jobSeekerCategory,contactPhone,jobSearchStatus,dataSource";
```

`EXPORT_DICT_FIELD_MAP` 中无需添加树形字典的映射项。

### 6.8 数据流总结

```
【新增/编辑】
  用户展开树 → getDictTreeChildren 懒加载子节点
  用户选中叶子节点 → handleAreaChange
    ├─ formData.householdLocation = "440802" (存 code)
    ├─ getItemFullPath API → "广东省湛江市赤坎区"
    ├─ formData.householdAreaName = "广东省湛江市赤坎区" (存路径)
    └─ householdValueObj.label = "广东省湛江市赤坎区" (下拉框显示)
      保存 → 后端 code + 路径文本同时入库

【编辑回显】
  编辑表单 → 直接用 householdAreaName 回填 valueObj
  → 下拉框显示完整路径，零 API 调用

【表格/详情/导出】
  → 直接使用 householdAreaName 字段
  → 无需字典翻译
```

### 6.9 与普通字典方案对比

| 环节 | 普通字典（如 Gender） | 树形字典（如 XZQH） |
|------|----------------------|---------------------|
| 数据量 | 小（几条~几十条） | 大（K 级~万级） |
| 加载方式 | 前端预加载全部 | 懒加载，按需加载子节点 |
| 编辑组件 | `<a-select>` + `useDict` | `<a-tree-select>` + 自定义懒加载 |
| 存储方式 | 只存 code（如 `1`） | 存 code（`440802`）+ 路径文本（`广东省湛江市赤坎区`） |
| 表格显示 | `getDictText()` 翻译 code→label | 直接显示路径文本列 |
| 详情显示 | `getDictText()` 翻译 | 直接显示路径文本列 |
| Excel 导出 | `translateDictFields` 内存映射 | 直接导出路径文本列（`@Excel` 注解） |
| 后端接口 | `/getDictBatch` 批量查询 | `/getDictTreeChildren` 懒加载 + `/getItemFullPath` 路径解析 |

### 6.10 关键源码文件索引

| 层级 | 文件 | 说明 |
|------|------|------|
| 后端 Controller | `jeecg-boot/.../dictionary/controller/DictionaryController.java` | 6 个接口：`getDictTreeChildren`/`loadDictItem`/`getItemFullPath`/`searchDictItem`/`getDict`/`getDictBatch` |
| 后端 Service | `jeecg-boot/.../dictionary/service/IDictionaryItemService.java` | 接口声明 |
| 后端 Service Impl | `jeecg-boot/.../dictionary/service/impl/DictionaryItemServiceImpl.java` | 懒加载、路径回溯、批量检查后代等核心逻辑 |
| 后端 Entity | `jeecg-boot/.../personal/entity/PersonalInfo.java` | `householdAreaName`/`residenceAreaName` 字段 |
| 后端 Controller | `jeecg-boot/.../personal/controller/PersonalInfoController.java` | `exportFields` 包含 areaName 列 |
| 前端编辑表单 | `jeecgboot-vue3/src/views/recruitment/personal/components/PersonalInfoForm.vue` | `<a-tree-select>` + 懒加载 + 路径回显 |
| 前端表格列配置 | `jeecgboot-vue3/src/views/recruitment/personal/PersonalInfo.data.ts` | `dataIndex: 'householdAreaName'` |
| 前端详情弹窗 | `jeecgboot-vue3/src/views/recruitment/personal/components/PersonalInfoDetailModal.vue` | 直接显示 areaName 字段 |
| SQL | `.docs/sql/个人信息与简历信息.sql` | ALTER TABLE 新增 areaName 列 |
| SQL | `.docs/sql/数据字典-行政区划(XZQH).sql` | XZQH 字典数据插入脚本（44K+ 条） |
| SQL | `.docs/sql/数据字典-职业分类(ZYFL).sql` | ZYFL 字典数据插入脚本（2K+ 条） |