一、时间：4.7-4.18

二、工作目标：项目框架搭建以及规范化流程

本次开发的核心目标为：实现历史地名时间地图的核心功能，打通“数据获取-清洗转换-前端展示”的完整链路，实现不同历史时期地名的地图联动显示，同时为后续“联动历史人物一生的轨迹”功能预留接口、做好铺垫。

三、详细内容

（一）数据获取：源头数据采集与格式转换

本次开发的核心数据源来自哈佛大学Dataverse平台的公开数据集，具体操作如下：

1. 数据源下载：访问数据集地址【https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/WW1PD6】，下载目标文件《v6_time_pref_pts_gbk_xian80.zip》，该压缩包包含了完整的历史地名数据，涵盖地名拼音、中文名、繁体名、经纬度坐标、存在时间、行政类型、治所变迁等关键元数据，为地图可视化提供了核心支撑。

2. 格式转换：由于原始数据为Shapefile格式，无法直接用于前端开发，因此使用QGIS工具对数据进行格式转换——将Shapefile文件导入QGIS，再导出为SQLite数据库格式，重点提取数据库中的county_name表，该表包含了所有需要的地名相关字段，为后续数据清洗工作提供了结构化的数据基础。

（二）数据清洗：Python脚本开发与数据优化

为确保数据符合前端可视化需求，编写Python脚本对MySQL中的county_name表数据进行深度清洗、合并与格式转换，核心代码及流程如下：

1. 环境配置与依赖引入

引入pymysql（用于连接MySQL数据库）、json(用于生成GeoJSON文件)、collections.defaultdict（用于数据分组）等依赖，配置数据库连接信息（主机、用户名、密码、数据库名称等），定义输出文件路径（historical_places.geojson）。

2. 核心功能函数开发

• fetch_data_from_mysql()：从MySQL数据库的county_name表中读取所有原始数据，通过SQL语句查询所需字段（包括ogc_fid、name_py、name_ch、x_coor、y_coor、beg_yr、end_yr等），并按地名拼音和起始年份排序，确保数据有序性。

• merge_time_periods(records)：合并同一地名的多个连续或重叠时间段，处理NULL值异常，对于重叠或相邻的时间段，取结束年份的最大值，并合并治所变迁等相关信息，避免数据冗余。

• group_by_place(records)：按“地名拼音+经纬度坐标”作为唯一标识分组，因为部分地名（如河曲县）因治所迁移存在多个不同坐标的记录，需分开处理，确保同一地点不同时期的坐标信息不混淆。

• generate_geojson(places)：将清洗后的地名数据转换为符合前端地图要求的GeoJSON格式，过滤坐标无效的数据，处理年份合理性（限定在中国历史合理范围：前3000年-1950年），构建包含完整元数据的Feature对象，最终生成FeatureCollection格式的GeoJSON文件。

• generate_time_index(features)：生成时间索引文件（time_index.json），按年份记录对应存在的地名ID，根据时间跨度选择不同的索引策略（跨度超过500年只记录起止年份，正常跨度记录所有中间年份），用于前端时间轴滑块的快速过滤，提升交互性能。

• main()：主函数，串联整个数据清洗流程，从数据库读取数据、合并时间段、生成GeoJSON和时间索引，输出数据统计信息（地名类型分布、时间范围等），确保流程可追溯、可复用。

3. 数据清洗成果

通过脚本运行，成功过滤无效数据，合并重复时间段，生成两个核心文件：historical_places.geojson（包含所有有效历史地名的地理数据和元数据）和time_index.json（时间索引文件），包含总共条数据10522条，为前端地图加载和交互提供了高效、规范的数据支持，historical_places.geojson格式形如（coordinates为经纬度）：

  {

      "type": "Feature",

      "geometry": {

        "type": "Point",

        "coordinates": [

          113.061,

          33.8711

        ]

      },

      "properties": {

        "id": 3537,

        "name_py": "Zhongxing Xian",

        "name_ch": "中兴县",

        "name_ft": "中興縣",

        "pres_loc": "今河南宝丰",

        "type_py": "Xian",

        "type_ch": "县",

        "lev_rank": "6",

        "start_year": 705,

        "end_year": 705,

        "beg_rule": "",

        "end_rule": "",

        "beg_chg_ty": "",

        "end_chg_ty": "",

        "obj_type": "POINT",

        "sys_id": 82989,

        "geo_src": "FROM_FD",

        "compiler": "",

        "gecomplr": "",

        "ent_date": ""

      }

    },

（三）前端开发：地图可视化与交互功能实现

 基于Vue3 + Element Plus + 高德地图API，完成前端代码开发、配置及菜单整合，核心内容包括 数据服务封装、地图组件开发、交互功能实现及样式优化，具体如下：

1. 数据服务封装（historicalPlaceServ.ts）

封装前端数据请求相关函数，实现从public目录直接加载静态GeoJSON和时间索引文件，无需依赖后端接口，降低部署复杂度，核心函数包括：

• getGeoJsonData()：加载historical_places.geojson文件，返回标准化的响应格式，包含成功/失败状态、数据及提示信息，处理加载异常场景。

• getTimeIndex()：加载time_index.json文件，用于前端时间轴的快速过滤，同样返回标准化响应。

• getPlaceIdsByYear(year)：根据传入的年份，通过时间索引找到最接近的年份对应的地名ID列表，提升时间过滤效率。

• getPlaceDetailFromGeoJson(placeId, geojsonData)：从GeoJSON数据中根据地名ID查询详情，无需后端请求，提升响应速度。

2. 地图组件开发（HistoricalMap.vue）

组件采用高德地图API（v2.0版本），实现历史地名的可视化 展示、交互功能及DeepSeek AI智能问答集成，核心功能及代码逻辑如下：

（1）高德地图初始化：配置高德地图密钥（AMAP_KEY）和安全码（AMAP_SECURITY_CODE），加载地图脚本，初始化地图实例，设置地图中心（[108, 35]）、缩放级别（默认5级）、地图样式及交互权限（支持拖拽、缩放、滚轮缩放等）；

（2）地名标记渲染：根据GeoJSON数据，为每个历史地名创建自定义标记（按行政区划类型设置不同颜色，如郡为橙色、县为蓝色），标记大小随地图缩放级别动态调整，缩放级别≥7时显示地名标签，避免重叠；

（3）时间轴联动：基于时间索引文件，实现时间轴滑块（公元前800年-公元1912年），支持年份跳转、朝代快速切换，滑块移动时实时过滤当前年份存在的地名，更新地图标记显示；

（4）筛选与搜索：实现地名类型筛选（支持全选、取消全选）、地名搜索（支持中文、拼音），搜索结果可点击跳转至对应地名在地图上的位置；

（5）地名详情弹窗：点击地图标记，弹出详情弹窗，展示地名拼音、类型、存在时间、所属朝代、当前位置等信息；

（6）DeepSeek AI智能问答集成：

   ① 组件集成：在前端页面添加可移动、可缩放的AI问答面板，采用古风配色，与整体页面风格  统一，支持关闭、清空聊天记录、查看历史问答等操作；

  ② 核心功能：通过调用aiServ.ts中的sendChatMessage函数，与DeepSeek模型交互，支持两种提问方式——快捷提问（预设4个高频问题：当前时期重大历史事件、著名历史人物、历史典故、朝代更迭）和自定义输入提问；

  ③ 场景适配：AI问答可获取当前地图上下文（当前历史时期、选中地名），精准回答与当前场景相关的问题；点击地名详情弹窗中的AI按钮，可直接提问该地名的重大事件、著名人物等内容；

  ④ 历史记录：支持本地存储AI问答历史，可查看、恢复、删除历史记录，最多保存50条，确保用户体验连贯；

（7）核心代码逻辑：通过Vue3的响应式数据管理地图状态、AI面板状态，监听地图缩放、拖拽、时间轴变化等事件，实现各功能模块的联动，确保交互流畅。

3. 样式优化与响应式适配

设计分层布局（左侧搜索面板、底部时间轴、右侧图例），确保地图可视区域最大化；采用半透明毛玻璃效果的控制面板，兼顾美观与地图可见性；适配移动端设备，在小屏幕下自动调整控件位置和尺寸，确保交互流畅。

4. 接口与类型定义

定义HistoricalPlace、TimeIndexItem、MapConfig等接口，规范数据类型，确保前后端数据交互一致性，避免类型错误，提升代码可维护性。

5. 菜单配置

将历史地图模块整合到前端项目菜单中，确保模块可正常访问，与项目其他功能模块衔接顺畅，形成完整的项目结构。

四）AI服务封装（aiServ.ts）

封装DeepSeek AI交互相关函数，实现前端与DeepSeek模型的通信，为HistoricalMap.vue组件提供AI问答支持，核心函数如下：

sendChatMessage：接收用户提问、当前上下文及历史聊天记录，调用DeepSeek API，发送请求并返回模型响应结果，处理请求异常（如服务不可用），确保AI问答功能稳定运行。

四、开发流程

本阶段严格遵循规范化流程，分6个阶段推进，确保开发进度、质量可控，具体流程如下：

1. 需求梳理与规划（4.7-4.8）：明确项目核心目标、功能模块（数据获取、清洗、前端可视化、AI集成），划分开发任务，制定每日开发计划，确定技术栈（Python、Vue3、高德地图API、DeepSeek AI）。

2. 数据获取与预处理（4.9-4.10）：从哈佛大学Dataverse平台采集原始数据，完成格式转换并导入MySQL数据库，整理数据台账，分析数据质量及清洗重点。

3. Python脚本开发与数据清洗（4.11-4.12）：编写数据清洗脚本，开发核心函数，完成数据过滤、合并、格式转换，生成GeoJSON和时间索引文件，验证数据有效性。

4. 前端开发（4.13-4.16）：搭建前端项目框架，封装数据服务和AI服务，开发地图组件，实现可视化、交互及AI问答功能，进行样式优化和响应式适配。

5. 测试与调试（4.17）：逐模块进行测试（数据加载、地图渲染、时间轴联动、AI问答等），排查并解决地图加载失败、交互逻辑bug、AI请求异常等问题，优化性能。

6. 规范化与整合（4.18）：整理代码、完善注释，规范文件结构，将历史地图模块整合到项目菜单，编写开发工作报告，完成项目交付准备。

本次开发（4.7-4.18）顺利完成所有既定目标，取得以下核心成果：

1. 数据成果：完成10522条历史地名数据的采集、清洗与标准化，生成historical_places.geojson（地理数据）和time_index.json（时间索引）两个核心文件，数据覆盖先秦至清朝，包含完整的地理和元数据信息。

2. 代码成果：开发Python数据清洗脚本（完整可复用）、前端Vue3组件（HistoricalMap.vue）、数据服务（historicalPlaceServ.ts）、AI服务（aiServ.ts），定义规范的接口类型，代码结构清晰、可维护性强。

3. 功能成果：

（1）核心功能：实现历史地名地图可视化，支持时间轴联动、地名筛选、搜索、详情查看，地图交互流畅，大数据量下渲染稳定；

（2）新增功能：集成DeepSeek AI智能问答，支持快捷提问、自定义提问，可结合当前历史场景精准回答，支持问答历史记录管理；

（3）适配功能：完成移动端响应式适配，确保不同设备均可正常使用；优化样式设计，提升页面美观度和用户体验。

4. 流程成果：建立规范化的开发流程，完成项目框架搭建，为后续“联动历史人物一生的轨迹”功能预留接口，奠定坚实的技术和代码基础。

六、总结

本次开发顺利完成了项目框架搭建、规范化流程落地及历史地名时间地图核心模块开发，全程围绕“数据-前端-交互-AI”的完整链路展开，核心难点及解决方法如下：

1. 核心难点一：历史数据的复杂性，同一地名因治所迁移存在多个坐标和时间段，易出现数据混淆和重复渲染。解决方法：采用“地名拼音+经纬度”双重标识进行分组合并，通过Python脚本自动化处理重复数据，确保数据唯一性。

2. 核心难点二：前端性能优化，10522条数据加载和时间轴联动易出现卡顿，时间轴滑块文字重叠。解决方法：生成时间索引文件，提升时间过滤响应速度；优化地图标记渲染逻辑，动态调整标记大小和标签显示；旋转时间轴文字、间隔显示标记，彻底解决文字重叠问题。

3. 核心难点三：DeepSeek AI功能与前端场景的适配，确保AI能获取当前地图上下文（时期、选中地名），实现精准问答。解决方法：封装上下文获取函数，将当前时期、选中地名信息融入AI提问请求，优化AI面板交互，确保与地图功能联动顺畅。

开发过程中，通过分步推进、逐模块测试的方式，及时解决了数据格式转换、地图加载异常、交互逻辑bug、AI请求异常等问题，确保了开发进度和质量。同时，规范的代码编写和流程设计，提升了代码的可维护性和可扩展性，为后续功能开发奠定了良好基础。

七、后续开发规划

4月19日起，将在本次历史地名地图模块的基础上，重点推进“联动历史人物一生的轨迹”功能开发，核心规划如下：

1. 数据补充：采集历史人物数据（姓名、生卒年份、主要活动地点、生平事迹等），与现有历史地名数据关联，建立人物-地名关联表，完成数据清洗和标准化。

2. 功能开发：在现有地图组件基础上，新增历史人物筛选、搜索功能，实现人物一生轨迹在地图上的动态展示（按时间顺序标注人物活动地点，支持轨迹播放）。

3. AI功能升级：优化DeepSeek AI问答功能，支持提问历史人物相关问题（如“李白的一生轨迹”“苏轼在宋朝的活动地点”），实现人物与地名、历史事件的联动问答。

4. 性能优化：针对新增的人物数据，优化地图渲染和数据加载逻辑，确保多数据量下交互流畅；完善响应式适配，优化移动端用户体验。

5. 功能整合与测试：将人物轨迹功能与现有模块整合，完成全流程测试，排查bug，优化细节，确保功能稳定、体验良好，最终形成“历史地名+历史人物”的完整历史地理可视化系统。