LinkToolDocs/web/dev/dev-plan.md
2025-07-24 18:04:18 +08:00

404 lines
54 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# GIS与LLM结合Web应用开发计划
## 一、项目概述
### 项目背景与目标
本项目的提出源于传统地理信息系统GIS操作门槛高、技术壁垒显著的行业痛点。传统GIS工具通常要求用户具备专业的空间分析知识和复杂操作技能导致普通用户难以高效利用空间分析功能。为解决这一问题项目定位为“自然语言驱动的空间分析Web应用”旨在通过整合大型语言模型LLM的自然语言理解能力与GIS的空间分析工具降低空间分析的技术门槛实现地理信息处理的便捷化。
项目开发的核心背景之一是LLM与业务数据源的集成难题。由于LLM与传统数据源在技术架构上存在天然隔离以往的集成方式多为碎片化的定制化开发导致系统扩展性差、维护成本高。为此项目引入模型上下文协议MCPModel Context Protocol作为连接标准。MCP作为一种统一开放的协议能够替代传统碎片化的定制集成方式为AI系统如LLM与业务数据源包括GIS工具、第三方地图服务等提供安全的双向连接解决LLM与数据源隔离导致的集成困难问题[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]。
基于上述背景项目的核心目标是开发一个支持自然语言交互的空间分析Web应用。具体目标包括用户通过自然语言描述空间分析需求应用通过MCP协议调用空间分析工具及第三方服务如高德地图等MCP服务共同完成需求处理并将分析结果通过前端地图组件可视化展示。此外应用需支持多源数据集成与工具调用实现“自然语言输入-空间分析处理-可视化输出”的全流程闭环,最终满足用户对地理信息处理便捷化、高效化的需求。通过这一目标的实现,项目将推动空间分析工具从专业领域向大众化应用场景延伸,提升地理信息服务的普惠性。
### 团队组成与分工
为确保项目架构分层客户端UI/Host/Client层、服务端Server/Resource层的高效落地团队需采用客户端与服务端并行协作的组织模式每组配置2名成员具体分工如下
**客户端小组**
- **地图负责人**聚焦UI层实现负责基于Leaflet的地图组件开发与图层管理包括地图渲染、交互逻辑及多源数据图层的加载与控制
- **AI负责人**聚焦Host层功能负责LLM调用流程设计、工具解析逻辑开发以及基于AntDesignX的AI对话模块实现支撑用户与系统的自然语言交互。
**服务端小组**
- **常规负责人**聚焦Server/Resource层基础功能负责数据库PostgreSQL+PostGIS设计与优化、用户鉴权等管理模块开发保障数据存储与系统安全
- **AI负责人**聚焦AI服务能力构建负责MCP工具调用模块开发、LLM接口适配与集成实现AI能力与后端资源的协同调度。
**协作机制**
为支撑并行开发团队需明确关键节点输出物技术验证阶段末完成接口需求文档编制服务端基于此文档于产品原型阶段初输出API文档及Mock服务确保客户端可同步开展UI层与Host层的开发工作提升整体研发效率。
## 二、开发计划
### 项目周期与阶段划分
本项目周期总计2.5个月自2025年7月27日启动至2025年10月10日结束整体按“可行性验证→快速迭代→优化交付”的逻辑划分为三个阶段各阶段任务明确且依次递进。
**技术验证阶段**2025年7月27日至2025年8月10日约15天为项目启动后的首个阶段核心目标是完成技术可行性验证。该阶段需重点推进三项任务一是技术栈选型确定适配项目需求的开发框架、工具及平台二是关键技术可行性验证具体包括MCP协议实现、LLM与GIS功能集成机制、数据隔离方案等核心技术点的验证确保技术路径的可行性三是形成技术验证报告为后续阶段奠定基础。
**产品原型阶段**2025年8月11日至2025年8月25日约15天聚焦于快速迭代开发以输出可演示的核心功能为目标。该阶段需实现“自然语言交互→空间分析→结果可视化”的完整核心功能链路确保用户可通过自然语言输入触发GIS空间分析并将分析结果以可视化方式呈现。通过原型演示验证产品核心价值与用户交互流程的合理性。
**完善开发阶段**2025年8月26日至2025年10月10日约45天为项目的优化与交付阶段重点围绕功能扩展、性能优化、测试与部署展开。在功能层面基于原型反馈补充次要功能模块提升产品完整性在性能层面针对系统响应速度、并发处理能力、数据加载效率等进行优化同时完成全面的功能测试、兼容性测试及安全测试并部署至生产环境确保产品稳定交付。
为保障阶段目标达成各阶段间需设置明确的里程碑评审机制。例如技术验证阶段末需评审MCP协议实现方案及关键技术验证结果产品原型阶段末需通过核心功能演示评审确认功能链路的完整性与可用性确保项目按计划有序推进。
### 技术验证阶段7.27-8.10
#### 目标与任务分解
本阶段核心目标为验证关键技术可行性,明确技术栈选型与接口规范,并输出最终技术方案。任务分解如下:
**客户端技术验证**由地图负责人执行React+AntDesignX+Leaflet集成测试7.27-8.1确保前端地图组件与UI框架的兼容性同时AI负责人需完成LLM流式响应与工具解析模块原型开发验证前端与AI能力的交互机制。
**服务端技术验证**常规负责人负责Spring Boot+Spring AI+PostgreSQL含PostGIS环境搭建及GeoServer部署与配置7.28-8.2构建基础数据存储与地图服务支撑AI负责人需基于JSON-RPC 2.0实现MCP协议并完成与通义百炼/Deepseek等LLM平台的接口适配及兼容性测试8.6-8.8确保服务端与AI模型的稳定通信。
**跨团队协作任务**团队共同研究MCP官方规范https://modelcontextprotocol.io/introduction输出协议实现指南并完成基础MCP请求/响应格式开发8.3-8.5设计PostgreSQL行级安全RLS策略以确保用户数据隔离同步完成空间数据存储方案验证8.7-8.9开发GeoServer REST API客户端用于地图服务发布并协调客户端与服务端团队完成API需求文档输出及Mock服务部署8.10),保障跨模块接口一致性。
#### 交付物与评审标准
本阶段的交付物包括以下核心文档与成果,旨在全面覆盖技术验证阶段的关键技术输出与设计成果:
1. **《技术栈选型报告》**:明确项目开发所需的技术组件与架构方案,包含选型依据及可行性分析;
2. **《技术验证报告》**涵盖各核心模块如LLM集成、地图服务、MCP协议的可行性结论与验证结果
3. **《MCP协议实现指南》**详细说明多模态协作协议MCP的技术实现细节指导后续开发
4. **《数据库设计初稿》**:初步完成数据模型与存储结构设计,为数据层开发提供基础;
5. **《API需求文档客户端输出与Mock服务》**:明确客户端与服务端交互的接口规范,并提供模拟服务支持前端联调。
评审标准将从技术可行性、性能指标与功能完整性三个维度进行验证,具体包括:
1. **技术栈适配性**选型方案需满足性能要求例如Leaflet地图渲染延迟需控制在500ms以内且整体技术架构无重大风险
2. **核心功能验证**MCP协议需支持Tools/Resources/Prompts三类服务调用LLM接口需实现流式响应机制确保交互流畅性
3. **数据安全与隔离**基于行级安全RLS策略的用户数据隔离测试需通过验证确保不同用户无法访问对方数据
4. **文档完整性**API需求文档需覆盖客户端所有功能点确保接口设计与业务需求一致核心技术模块LLM集成、MCP调用、地图服务需通过综合验证确认技术路径可行。
### 产品原型阶段8.11-8.25
#### 目标与任务分解
本阶段的核心目标是交付可演示的最小原型实现“用户输入自然语言→LLM解析→调用GIS工具→结果可视化”的全流程闭环并完成核心功能开发及前后端联调。
**任务分解如下**
- **客户端**
1. UI层开发由地图负责人负责包括地图组件渲染含图层管理控件、符号化渲染及AI对话界面实现支持流式输出与历史记录其中地图组件开发周期为8.11-8.18AI对话界面实现周期为8.12-8.19
2. 功能模块开发由AI负责人负责包括Host层工具解析模块XML格式解析至MCP服务调用逻辑及Client层MCP客户端HTTP/SSE请求处理开发周期为8.15-8.22。
- **服务端**
1. AI负责人负责Server层MCP模块开发封装GIS分析工具接口与数据获取接口及地图服务封装基于GeoServer REST API实现WMS/WFS接口其中MCP服务接口开发周期为8.11-8.20地图服务封装周期为8.13-8.21
2. 常规负责人负责管理模块实现(用户登录/注册、权限控制及数据库表结构完善含RLS策略部署用户认证系统实现周期为8.16-8.23。
- **跨团队协作**
服务端需在8.15前依据客户端API需求文档完成Mock服务部署客户端需在8.20前完成与Mock服务的联调并最终在8.24-8.25期间完成客户端与服务端的接口联调。
#### 交付物与评审标准
交付物包括可运行的产品原型前端界面与后端服务、《API文档含Mock配置》《数据库表结构终稿》及联调测试报告。其中产品原型需整合客户端的地图与AI对话模块以实现前端交互与后端服务的联动API文档应涵盖MCP、地图、认证等核心接口的详细定义及Mock配置联调测试报告需记录系统集成过程中的测试结果。
评审标准涵盖功能完整性、性能指标及安全要求。功能层面原型需支持至少2个典型场景如“分析海珠区建筑密度”“规划广州塔出发路线”且核心功能流程自然语言输入→MCP调用→结果渲染需完整贯通性能指标方面自然语言解析准确率需大于80%API接口覆盖率≥90%联调测试通过率≥85%;结果呈现要求地图结果渲染正确(符号化显示分析结果);安全层面需确保用户数据隔离生效。
| 指标类别 | 具体指标 | 要求值 | 说明 |
|----------------|---------------------------|----------|----------------------------------------------------------------------|
| 功能完整性 | 核心功能流程完整性 | 100% | 自然语言输入→MCP调用→结果渲染完整贯通 |
| | 典型场景支持数量 | ≥2个 | 如“分析海珠区建筑密度”“规划广州塔出发路线” |
| 性能指标 | 自然语言解析准确率 | >80% | 用户自然语言指令解析准确度 |
| | API接口覆盖率 | ≥90% | MCP/地图/认证等核心接口覆盖程度 |
| | 联调测试通过率 | ≥85% | 系统集成测试通过率 |
| 结果呈现 | 地图渲染正确率 | 100% | 符号化显示分析结果 |
| 安全要求 | 用户数据隔离生效 | 100% | 用户间数据访问隔离机制 |
### 完善开发阶段8.26-10.10
#### 目标与任务分解
本阶段的核心目标是提升系统稳定性、完善功能覆盖、完成全面测试并实现部署上线。具体任务分解如下:
**功能扩展**
- **客户端**增加管理设置模块含MCP服务管理、模型参数配置由AI负责人负责优化地图组件符号化样式由地图负责人负责同步进行客户端交互优化实施周期为8月26日至9月10日。
- **服务端**增加日志模块与任务进度跟踪功能由常规负责人负责扩展对第三方MCP服务的支持如集成ArcGIS工具由AI负责人负责同步开展服务端性能调优实施周期为8月26日至9月15日。
**测试与优化**
- **单元测试**覆盖核心模块代码比例需达到80%以上实施周期为9月11日至9月25日。
- **集成测试**包含性能测试与安全测试其中性能测试要求并发用户数≥10时系统响应时间\<2秒安全测试需实现SQL注入防护与XSS过滤功能实施周期为9月26日至10月1日。
- **用户验收测试**验证系统功能与用户需求的一致性实施周期为10月2日至10月5日。
**部署**
- **Docker容器化打包**整合前端、后端、数据库及GeoServer服务进行统一容器化封装实施周期为9月20日至9月25日。
- **生产环境部署与文档编写**完成容器化应用的生产环境部署并编写详细的部署文档实施周期为10月6日至10月10日。
#### 交付物与验收标准
本阶段的交付物包括在生产环境中部署的Web应用最终版本包含所有功能模块、《用户手册》《开发文档》《测试报告》测试覆盖率需达到95%及以上、《Docker部署脚本》及配套的部署文档与运维手册。这些交付物需完整覆盖项目从应用使用、开发过程、测试验证到部署运维的全流程需求确保应用交付后具备可维护性与可扩展性。
验收标准需从功能完整性、系统稳定性、性能指标、用户验证及数据安全五个维度进行评估。在功能方面Web应用需覆盖所有需求点包括自然语言交互、空间分析、结果可视化及用户管理模块并满足需求文档中的具体功能要求。系统稳定性要求连续运行72小时无崩溃且无致命bug。性能指标需同时满足页面加载时间小于3秒、分析任务执行时间小于10秒、响应时间不超过2秒以及并发量不低于100的要求。用户验收测试通过率需达到100%,确保应用符合用户实际使用需求。此外,数据安全需严格遵守用户数据隔离要求,确保数据处理与存储的合规性。
| 指标类型 | 要求阈值 | 单位 |
|------------------------|----------|--------|
| 页面加载时间 | \<3 | 秒 |
| 分析任务执行时间 | \<10 | 秒 |
| 响应时间 | ≤2 | 秒 |
| 并发量 | ≥100 | 请求数 |
## 三、设计与实施方案
### 整体架构设计
#### 分层架构
本项目的分层架构设计遵循“前后端分离+分层解耦”原则,将系统划分为客户端三层与服务端两层,各层职责明确且通过标准化接口实现通信,以提升系统的可维护性与扩展性。
**客户端三层**聚焦用户交互与协议调用自上而下包括UI层、Host层与Client层。UI层基于React组件构建负责接收用户输入如GIS查询参数、LLM指令并渲染结果如地图可视化、自然语言回答实现页面的动态交互与数据展示。Host层作为核心协调者集成LLM基座与工具解析模块承担逻辑调度职能一方面管理Client层实例的生命周期、控制连接权限及执行安全策略另一方面协调AI能力与GIS工具的调用流程确保用户请求的合理分发[[2](https://blog.csdn.net/qq_44866828/article/details/146106385)]。Client层作为MCP协议的具体实现者由Host层动态创建并与服务端保持1:1连接负责按MCP协议规范发起请求、建立有状态会话、处理协议协商及消息路由支持HTTP/SSE、stdio等多种传输方式[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)][[3](https://github.com/viant/mcp)]。
**服务端两层**专注于业务逻辑处理与资源管理包含Server层与Resource层。Server层提供HTTP接口集成MCP模块、地图服务、管理模块及LLM模块通过解析Client层请求并分派给对应实现者完成业务逻辑的处理与协调[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]。Resource层作为数据与工具的底层支撑通过PostgreSQL数据库与文件系统实现数据持久化并连接第三方数据源或工具如数据库、文件系统、API服务为上层提供资源访问能力[[2](https://blog.csdn.net/qq_44866828/article/details/146106385)]。
**层间通信机制**基于清晰定义的接口实现解耦。UI层通过调用Host层的LLM请求方法触发业务流程Host层通过调用Client层的MCP执行方法完成协议转换与请求转发Client层与Server层基于JSON-RPC 2.0协议进行通信,支持认证/授权机制如OAuth 2/OIDC以保障交互安全性[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]。整体架构通过“客户端-主机-服务器”模式实现跨层协作其中Host作为协议核心协调者Client与Server通过MCP协议建立有状态会话确保上下文交换与采样协调的高效性[[4](https://cloud.tencent.com/developer/article/2541726?policyId=1004)][[5](https://blog.csdn.net/wireless_com/article/details/149377560)][[6](https://spec.modelcontextprotocol.io/specification/draft/basic/)]。
#### 核心技术栈
核心技术栈的选择以“功能适配+开发效率+性能优化”为核心原则需在满足GIS与LLM融合需求的同时确保系统稳定性与部署便捷性。具体技术组合及选型依据如下
| 层级 | 组件 | 版本/模式 | 核心功能 | 参考依据 |
|--------------|--------------------|-------------------|--------------------------------------------------------------------------|----------|
| **前端** | React | 18 | 组件化开发框架 | |
| | TypeScript | 5.2 | 类型安全开发 | |
| | Leaflet | 1.9.4 | 轻量级地理数据可视化 | |
| | AntDesignX | - | AI对话场景组件库 | |
| | JSON-RPC | 2.0 | 消息协议标准 | [[9](1)][[10](2)]|
| | HTTP传输 | Streamable | 大数据流交互(取代HTTP+SSE) | [[9](1)][[10](2)]|
| | npm | 10.5 | 依赖管理 | |
| **后端** | Spring Boot | 3.2 | 微服务框架 | |
| | Spring AI | 0.8.0 | LLM集成引擎 | [[11](3)] |
| | GeoServer | 2.23.0 | WMS/WFS地理服务 | |
| | MCP协议 | stdio/SSE/Streamable | 进程通信/长连接推送/大数据流传输 | [[12](4)][[13](5)]|
| | OAuth | 2.1 | 用户认证框架 | [[9](1)][[10](2)]|
| | Maven | 3.9 | 依赖管理 | |
| **数据存储** | PostgreSQL | 16 | 关系型数据库 | |
| | PostGIS | 3.4 | 空间数据扩展 | |
| **部署** | Docker | 26.1 | 容器化封装 | |
| | Nginx | - | 前端资源托管 | |
| | Docker Compose | - | 多容器协同部署 | |
| **扩展** | JSON-RPC批处理 | - | 提升接口调用效率 | [[9](1)][[10](2)]|
| | 多模态数据 | 文本/图像/音频 | 多类型内容支持 | [[9](1)][[10](2)]|
| | 参数自动补全 | - | 交互体验增强 | [[9](1)][[10](2)]|
> 参考依据索引:
> [1] [JSON-RPC 2.0协议规范](https://cloud.tencent.com/developer/article/2541726)
> [2] [Streamable传输模式解析](https://blog.csdn.net/wireless_com/article/details/149377560)
> [3] [Spring AI集成方案](https://blog.csdn.net/m0_64132019/article/details/147163246)
> [4] [MCP协议传输方式](https://cloud.tencent.com/developer/article/2528910)
> [5] [MCP协议规范](https://www.claudemcp.com/specification)
**前端技术栈**
采用React 18作为核心框架搭配TypeScript 5.2实现组件化开发与类型安全通过schema.ts中的TypeScript模式定义权威协议需求确保前后端数据交互的一致性[[4](https://cloud.tencent.com/developer/article/2541726?policyId=1004)][[5](https://blog.csdn.net/wireless_com/article/details/149377560)]。地图渲染采用Leaflet 1.9.4其轻量特性可高效适配地理数据可视化需求UI组件层集成AntDesignX提供AI对话场景所需的流式输出、历史记录管理等预制组件提升开发效率。通信协议基于JSON-RPC 2.0消息格式传输方式采用Streamable HTTP以支持灵活的大数据流交互取代传统HTTP+SSE模式满足LLM响应实时性要求[[4](https://cloud.tencent.com/developer/article/2541726?policyId=1004)][[5](https://blog.csdn.net/wireless_com/article/details/149377560)][[7](https://cloud.tencent.com/developer/article/2528910?frompage=seopage&policyId=20240001)]。前端依赖管理工具选用npm 10.5,确保包版本一致性与依赖解析效率。
**后端技术栈**
后端框架采用Spring Boot 3.2结合Spring AI 0.8.0简化LLM模型集成流程支持多语言SDK如Java、Python的灵活调用[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]。地理数据服务通过GeoServer 2.23.0实现提供WMS/WFS标准接口以支撑地图图层发布与空间数据查询。通信层基于MCP协议架构支持标准输入输出stdio用于本地进程间高效通信、服务器发送事件SSE实现HTTP长连接推送以及社区支持的Streamable传输模式适用于大数据流场景[[7](https://cloud.tencent.com/developer/article/2528910?frompage=seopage&policyId=20240001)][[8](https://www.claudemcp.com/specification)]。安全授权方面集成OAuth 2.1框架确保用户认证与权限控制的全面性[[4](https://cloud.tencent.com/developer/article/2541726?policyId=1004)][[5](https://blog.csdn.net/wireless_com/article/details/149377560)]。后端依赖管理采用Maven 3.9,实现依赖包的自动化构建与版本管控。
**数据存储层**
采用PostgreSQL 16作为基础数据库搭配PostGIS 3.4扩展模块提供空间数据类型如Geometry与空间索引能力支持高效的地理查询如缓冲区分析、空间叠加。该组合满足GIS应用中矢量数据存储、拓扑关系管理及复杂空间运算需求同时兼容关系型数据与空间数据的统一管理。
**容器化与部署**
通过Docker 26.1实现应用容器化封装确保开发、测试与生产环境的一致性。前端资源打包为Nginx容器镜像后端服务与数据库分别构建独立容器通过Docker Compose实现多容器协同部署简化跨环境迁移与运维流程。
**扩展支持**
技术栈支持JSON-RPC批处理请求以提升接口调用效率兼容文本、图像及音频多模态数据传输并提供参数自动补全建议功能增强用户交互体验[[4](https://cloud.tencent.com/developer/article/2541726?policyId=1004)][[5](https://blog.csdn.net/wireless_com/article/details/149377560)]。
### 数据库设计
#### 表结构设计
本系统设计6张核心数据表所有表均包含`user_id`字段以支持行级安全RLS隔离机制确保数据访问的安全性与用户数据隔离。各表结构如下
- **users用户表**:存储用户基本信息及认证数据,字段包括`id`主键PK、`username`(用户名)、`password_hash`(密码哈希)、`api_key`LLM平台访问密钥、`role`用户角色取值为admin或user、`created_at`(创建时间)。其中`id`作为唯一标识,`password_hash`保障密码存储安全,`role`字段用于权限控制。
- **conversations对话表**记录用户与LLM的对话会话信息字段包括`id`主键PK、`user_id`外键FK关联users表、`title`(对话标题)、`created_at`(创建时间)、`updated_at`(更新时间)。`user_id`实现对话数据的用户隔离,`title`便于用户识别不同对话,`updated_at`追踪对话最新活动时间。
- **conversation_messages对话消息表**:存储单轮对话消息内容,字段包括`id`主键PK、`conversation_id`外键FK关联conversations表、`role`消息角色取值为user或ai、`content`(消息内容)、`created_at`(创建时间)。通过`conversation_id`关联至具体对话,`role`区分消息发送方,`content`记录消息文本。
- **spatial_tasks空间分析任务表**管理GIS空间分析任务的生命周期字段包括`id`主键PK、`user_id`外键FK关联users表、`mcp_service`调用的MCP服务名称、`tool_name`(使用的空间分析工具名称)、`parameters`任务参数JSON格式、`status`任务状态取值为pending、running、success或failed、`result_path`(分析结果存储路径)、`created_at`(创建时间)、`updated_at`(更新时间)。`parameters`支持复杂参数结构,`status`追踪任务进度,`result_path`指向结果数据存储位置。
- **mcp_servicesMCP服务配置表**:配置外部空间分析服务的连接信息,字段包括`id`主键PK、`user_id`外键FK关联users表、`name`(服务名称)、`type`服务类型取值为Tools、Prompts或Resources、`url`(服务访问地址)、`auth_type`认证方式取值为OAuth 2.1或API Key、`config`服务配置参数JSON格式、`is_enabled`(服务启用状态)。`type`区分服务类别,`auth_type`与`config`保障服务调用的安全性与正确性。
- **map_layers地图图层表**:管理用户自定义地图图层信息,字段包括`id`主键PK、`user_id`外键FK关联users表、`name`(图层名称)、`data_source`数据源地址支持WMS或WFS协议、`style_config`图层样式配置JSON格式、`is_visible`(图层可见状态)。`data_source`指定空间数据来源,`style_config`控制图层可视化效果,`is_visible`支持图层显示切换。
为实现RLS隔离需对上述表配置访问策略。例如针对spatial_tasks表的RLS策略可定义为`CREATE POLICY user_spatial_tasks ON spatial_tasks FOR ALL USING (user_id = current_user_id());`,确保用户仅能访问自身创建的空间分析任务数据。
#### 索引与性能优化
为提升系统查询效率,需针对高频访问字段设计合理的索引策略,并结合性能优化措施保障系统响应速度。在常规字段索引设计方面,应在用户表(`users`)的`api_key`字段创建唯一索引,以加速用户身份验证过程;在对话记录表(`conversations`)中基于`user_id`构建复合索引,优化用户对话历史的查询效率;在空间分析任务表(`spatial_tasks`)中,针对`user_id`与`status`创建复合索引,同时补充对`task_id`字段的索引,以支持任务状态筛选与单任务查询场景;在地图图层表(`map_layers`)中,基于`user_id`与`is_visible`构建复合索引,提升图层可见性状态的检索速度。此外,用户表、对话记录表及空间分析任务表均需对`user_id`字段单独创建索引,进一步强化用户维度数据的查询性能。
在空间数据查询优化方面需利用PostGIS扩展提供的空间索引能力。针对`spatial_tasks`表中存储结果空间数据的字段(如`result_geom`创建GIST索引以显著加速空间关系判断、范围查询等地理操作。
性能优化措施还包括数据隔离与访问控制机制。通过启用PostgreSQL的行级安全策略RLS可实现用户数据的逻辑隔离防止跨用户数据访问同时避免因权限校验导致的性能损耗。结合上述索引策略与安全机制系统可在保障数据安全性的前提下实现高效的数据检索与空间分析处理。
### 模块功能设计
#### 客户端模块
##### UI层
UI层按功能划分子模块每个子模块实现特定组件与交互函数具体包括地图组件、AI对话模块和管理设置模块各模块基于前端技术栈实现组件渲染与用户交互。
**地图组件**基于Leaflet实现核心组件包括`MapRenderer`负责初始化Leaflet地图实例并加载WMS/WFS地理数据图层`LayerManager`提供图层管理功能,支持图层显隐控制与顺序调整,关键函数包括`toggleLayer(id)`切换指定ID图层的可见性和`reorderLayers(ids)`按ID序列重新排列图层顺序`Symbolizer`组件根据预设规则对分析结果进行符号化渲染,通过`renderResult(geom, style)`函数接收几何对象与样式参数并完成可视化呈现。
**AI对话模块**采用AntDesignX组件库构建包含三个核心组件`ChatWindow`负责展示对话气泡界面支持用户与AI的消息交互提供`addMessage(role, content)`函数添加对话内容,并支持文件上传功能;`StreamRenderer`处理LLM的流式响应通过`streamResponse(chunk)`函数实时接收并渲染响应片段;`ChatHistory`组件管理对话历史记录,提供`loadHistory(conversationId)`加载指定会话ID的历史记录和`saveHistory(conversation)`(保存当前对话内容)函数。
**管理设置模块**涵盖系统配置与用户管理功能,主要组件包括:`McpServiceManager`实现MCP服务配置的CRUD操作`ModelConfig`组件支持LLM模型管理与参数调整可配置TopP、Temperature等关键参数`UserAuth`提供用户登录与注册表单,实现身份验证功能。
##### Host层
Host层作为GIS与LLM结合Web应用的核心协调与执行层承担用户交互、LLM集成及工具调用的关键职责其核心功能围绕模块设计与跨层协调展开。
**核心模块及方法**方面Host层包含两大核心组件
- **LLM基座**:通过抽象类`LLMClient`实现不同厂商API的统一调用其核心方法`requestStream(prompt, model, params)`支持发起流式请求并返回Observable对象确保与LLM服务的高效交互。该设计旨在屏蔽底层API差异为上层应用提供标准化接口。
- **工具解析模块**:通过`ToolParser`实现LLM响应的工具调用解析与执行具体包括`parseToolCall(response)`和`executeTool(toolName, params)`方法。其中,`parseToolCall`负责从LLM响应中提取XML格式的工具调用信息如`\<tool name="arcgis:clip_analysis" params="{...}"/>`),而`executeTool`则根据解析结果调用Client层对应MCP客户端执行具体工具实现GIS功能与LLM能力的衔接[[7](https://cloud.tencent.com/developer/article/2528910?frompage=seopage&policyId=20240001)]。
在**协调与管理职责**上Host层作为容器和协调器需创建并管理多个客户端实例控制连接权限与生命周期执行安全策略及用户授权决策并处理跨客户端的上下文聚合[[4](https://cloud.tencent.com/developer/article/2541726?policyId=1004)][[5](https://blog.csdn.net/wireless_com/article/details/149377560)]。同时其需协调AI/LLM的集成与采样过程确保用户交互与后端工具调用的高效协同为应用提供统一的执行环境与安全保障。
##### Client层
Client层作为MCPMap Collaboration Protocol服务的客户端实现层需根据服务类型差异化构建客户端组件具体实现方式如下
**McpHttpClient**用于处理HTTP类MCP服务通过封装HTTP请求逻辑提供核心功能方法
- `getResource(uri)`调用Resources服务通过GET请求获取指定URI的地理空间资源数据支撑客户端资源管理能力
- `callTool(name, params)`调用Tools服务采用POST请求并遵循JSON-RPC格式传递工具名称与参数实现LLM工具调用功能
- `getPrompt(templateId, params)`调用Prompts服务根据模板ID获取预设提示模板并动态填充参数支持提示模板选择与个性化配置。
**McpSseClient**专注于处理SSEServer-Sent Events流式MCP服务核心方法为`subscribeToolProgress(toolId)`,通过建立持久化连接订阅工具执行进度通知,实现流式状态更新。
Client层需维护与服务端的1:1专属连接承担协议协商、消息路由及有状态会话管理职责确保通信链路的稳定性与数据一致性[[8](https://www.claudemcp.com/specification)]。此外该层集成资源管理、提示模板选择、工具调用等基础功能并支持多用户会话管理例如通过Cloudflare Durable Objects等技术实现会话状态的持久化存储满足多用户并发场景下的会话隔离需求[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)][[14](https://juejin.cn/post/7492809676682248219)]。
#### 服务端模块
##### Server层
Server层作为GIS与LLM结合Web应用的核心服务中枢负责处理客户端请求、协调各功能模块交互及资源调度主要包含以下核心模块及关键方法
**MCP模块**
该模块通过`McpController`实现对MCPMulti-Component Protocol请求的统一处理对外暴露接口路径`/api/mcp`,核心功能涵盖工具调用、资源查询及提示词模板管理[[7](https://cloud.tencent.com/developer/article/2528910?frompage=seopage&policyId=20240001)][[15](https://blog.csdn.net/flytoprx/article/details/148436915)]。具体方法包括:`getResources(uri, userId)`用于根据资源标识uri和用户ID查询系统资源`callTool(toolName, params, userId)`接收工具名称、参数及用户ID执行指定工具并返回处理结果`getPrompts(templateId, params)`根据模板ID和动态参数获取预定义的提示词模板支持LLM交互流程的标准化。
**地图服务模块**
基于`GeoServerClient`组件封装GeoServer REST API调用逻辑实现地理数据服务的发布与访问[[15](https://blog.csdn.net/flytoprx/article/details/148436915)]。核心方法包括:`publishLayer(layerConfig)`根据图层配置信息如数据源、样式、投影等在GeoServer中发布新图层`getWmsUrl(layerId)`根据图层唯一标识生成符合OGC标准的WMS服务URL支持客户端地图渲染。
**管理模块**
该模块负责用户生命周期管理与安全认证,包含两个核心控制器:`UserController`提供用户CRUD操作接口路径为`/api/users``AuthController`处理用户登录与注册请求,路径为`/api/auth`并基于JWTJSON Web Token实现身份鉴权[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]。通过OAuth2.1协议规范用户认证流程,确保系统访问的安全性与可控性。
**LLM模块**
通过`LLMService`组件实现对多厂商大模型API的适配与统一调用支持通义百炼、Deepseek等主流模型[[15](https://blog.csdn.net/flytoprx/article/details/148436915)]。核心方法`streamCompletion(prompt, model, userId)`支持发起流式对话请求,以响应式编程方式返回`Flux\<Chunk>`类型结果满足LLM交互过程中的实时数据传输需求提升用户体验。
Server层各模块通过标准化接口与协议如HTTP/JSON-RPC 2.0协同工作实现工具调用、地理数据服务、用户管理及LLM能力的有机整合为应用提供高效、可靠的后端支撑[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]。
##### Resource层
Resource层作为系统的数据持久化与外部服务对接核心负责管理数据存储、访问及外部交互其设计需满足数据安全性、访问灵活性及服务集成可靠性。
在**数据库访问**方面,该层通过`SpatialTaskRepository`与`UserRepository`实现结构化数据的持久化管理。其中,`SpatialTaskRepository`提供空间任务的CRUD创建、读取、更新、删除操作支持地理空间数据的高效存取`UserRepository`则专注于用户数据访问集成行级安全RLS过滤机制通过应用程序控制访问权限以保障数据安全确保用户仅能访问其权限范围内的数据[[15](https://blog.csdn.net/flytoprx/article/details/148436915)]。此类数据库交互符合资源Resources作为“可被客户端读取并用作与LLM交互的上下文数据”的核心定位支持通过参数化查询动态获取指定条件的数据例如基于用户ID或任务ID的过滤查询[[16](https://blog.csdn.net/qq_46094651/article/details/147448829)]。
**文件系统**模块通过`ResultStorage`组件管理非结构化分析结果文件采用URI风格路径设计存储路径规范为`/data/{userId}/{taskId}/`。该设计借鉴资源访问的URI路径特性支持按用户和任务维度对结果文件进行分层组织便于缓存与读取操作[[16](https://blog.csdn.net/qq_46094651/article/details/147448829)]。典型场景包括存储LLM生成的地理空间分析报告、可视化图表等客户端可通过类似REST API的GET请求访问指定路径下的文件内容。
在**第三方集成**层面Resource层通过`AmapClient`与`GeoServerManager`实现外部服务对接。`AmapClient`负责调用高德地图API获取地理编码、路径规划等基础地理服务数据`GeoServerManager`则用于管理GeoServer工作区与图层实现空间数据的发布与可视化。此类集成符合资源作为“与外部服务交互桥梁”的定位支持将第三方服务返回的结构化数据流如地图瓦片、空间分析结果转化为LLM可处理的上下文数据同时通过应用层权限控制保障外部服务调用的安全性[[14](https://juejin.cn/post/7492809676682248219)]。
综上Resource层通过数据库访问、文件系统管理及第三方集成的协同设计构建了高效、安全、可扩展的数据与服务访问体系为上层业务逻辑提供稳定的数据支撑与外部能力对接。其实现需遵循资源的只读操作特性、URI路径规范及缓存优化策略确保系统在数据密集型场景下的性能与可靠性[[16](https://blog.csdn.net/qq_46094651/article/details/147448829)]。
| 模块名称 | 组件 | 功能 | 特点/设计 |
|--------------|--------------------------|----------------------------------------------------------------------|---------------------------------------------------------------------------|
| 数据库访问 | SpatialTaskRepository | 提供空间任务的CRUD操作支持地理空间数据的高效存取 | 支持行级安全RLS过滤机制通过应用程序控制访问权限以保障数据安全 |
| | UserRepository | 用户数据访问 | |
| 文件系统 | ResultStorage | 管理非结构化分析结果文件 | 存储路径规范为`/data/{userId}/{taskId}/`,支持按用户和任务维度分层组织 |
| 第三方集成 | AmapClient | 调用高德地图API获取地理编码、路径规划等基础地理服务数据 | 将第三方服务返回的结构化数据流转化为LLM可处理的上下文数据 |
| | GeoServerManager | 管理GeoServer工作区与图层实现空间数据的发布与可视化 | |
### HTTP接口定义
#### 核心接口列表
本章节按功能模块定义HTTP接口明确路径、方法、参数及响应格式具体如下
| 模块 | 路径 | 方法 | 参数 | 响应格式 |
|-------------|---------------------------|--------|----------------------------------------------------------------------|--------------------------------------------------------------------------|
| **LLM接口** | `POST /api/llm/stream` | POST | `prompt`:对话提示文本\<br>`model`:模型名称\<br>`userId`:用户唯一标识 | Server-Sent Events格式\<br>- `chunk`:流式对话内容片段\<br>- `done`:对话结束标识 |
| **MCP工具调用** | `POST /api/mcp/tools/call` | POST | `serviceName`:服务名称\<br>`toolName`:工具名称\<br>`params`:工具参数\<br>`userId`:用户标识 | JSON对象\<br>`{success: boolean, result: any}`\<br>[[3](https://github.com/viant/mcp)][[16](https://blog.csdn.net/qq_46094651/article/details/147448829)] |
| **地图服务** | `GET /api/map/wms` | GET | `layerId`:图层标识\<br>`bbox`:边界框坐标\<br>`width`:图片宽度\<br>`height`:图片高度 | 图片流(渲染后的地图图层) |
| **用户登录** | `POST /api/auth/login` | POST | `username`:用户名\<br>`password`:密码 | JSON对象\<br>`{token: string, user: User}` |
| **对话列表** | `GET /api/conversations` | GET | `userId`:用户唯一标识 | JSON数组\<br>`[{id, title, createdAt}, ...]` |
- **LLM接口**
路径:`POST /api/llm/stream`方法POST功能提供流式对话服务。参数包括`prompt`(对话提示文本)、`model`(模型名称)、`userId`用户唯一标识。响应采用Server-Sent EventsSSE格式包含两类事件`chunk`(返回流式对话内容片段)和`done`(标识对话结束)。
- **MCP工具调用接口**
路径:`POST /api/mcp/tools/call`方法POST功能调用Tools服务执行特定工具操作。该接口基于JSON-RPC 2.0协议实现支持请求含唯一ID和方法名、响应与请求ID对应包含成功结果或错误信息及通知无ID单向消息三种消息类型[[6](https://spec.modelcontextprotocol.io/specification/draft/basic/)]。参数包括`serviceName`(服务名称)、`toolName`(工具名称)、`params`(工具执行参数)、`userId`用户唯一标识。响应格式为JSON对象`{success: boolean, result: any}`,其中`success`指示调用是否成功,`result`返回工具执行结果[[3](https://github.com/viant/mcp)][[16](https://blog.csdn.net/qq_46094651/article/details/147448829)]。
- **地图服务接口**
路径:`GET /api/map/wms`方法GET功能获取WMSWeb Map Service图层数据。参数包括`layerId`(图层唯一标识)、`bbox`(边界框坐标,格式为`minx,miny,maxx,maxy`)、`width`(图片宽度)、`height`(图片高度)。响应为图片流,直接返回渲染后的地图图层图像。
- **用户接口**
- 登录接口:路径`POST /api/auth/login`方法POST功能用户身份验证。参数包括`username`(用户名)、`password`密码。响应格式为JSON对象`{token: string, user: User}`,其中`token`为身份认证令牌,`user`为用户基本信息。
- 对话列表接口:路径`GET /api/conversations`方法GET功能获取用户历史对话列表。参数包括`userId`用户唯一标识。响应格式为JSON数组`[{id, title, createdAt}, ...]`,数组元素包含对话`id`(唯一标识)、`title`(对话标题)、`createdAt`(创建时间)。
## 四、配套讲解PPT
### PPT结构设计
本PPT遵循“认知→技术→执行”的逻辑主线采用模块化设计共分为6个核心部分各模块内容及页数规划如下
**项目概述**1-2页
该部分旨在建立听众对项目的整体认知包含三个核心要素背景层面重点阐述LLM与数据源隔离的行业痛点引出项目立项的必要性[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]目标层面明确解决上述问题的核心方向核心功能演示层面通过截图或流程图直观展示系统交互逻辑突出MCPModel Context Protocol的核心组件Resources/Prompts/Tools在功能实现中的作用[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]。
**架构设计**3-4页
以分层设计为核心展示系统的技术骨架。首先呈现5层架构图清晰标注各层职责与边界其次通过模块交互流程图详细说明数据流转路径即从UI层发起请求依次经过Host层、Client层、Server层最终与Resource层进行数据交互。该架构设计需体现MCP协议在资源隔离与交互中的关键作用同时可结合Python/Go服务器实现示例说明技术落地的可行性[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]。
**技术栈详解**5-6页
系统梳理项目技术体系分为三个维度前端、后端及DevOps技术栈列表明确各环节的工具选型关键技术点深度解析重点包括MCP协议的三类服务解决LLM与数据源隔离问题、PostgreSQL行级安全控制RLS及GeoServer REST API地理数据服务接口[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]技术选型依据说明如选择Python/Go作为服务器开发语言的性能与兼容性考量。
**开发计划**3-4页
以时间轴甘特图为主视觉元素呈现项目全周期管理。内容包括阶段任务划分如需求分析、架构设计、开发测试、部署上线、各阶段交付物清单如需求文档、架构蓝图、测试报告以及团队分工矩阵明确角色与职责。长期维护计划可参考MCP协议的更新机制即基于GitHub进行版本管理每3-6个月进行技术迭代[[17](https://milvus.io/ai-quick-reference/where-is-the-model-context-protocol-mcp-spec-maintained-and-how-often-is-it-updated)]。
**协作流程**2-3页
聚焦跨团队协同效率分两部分展开技术协作流程涵盖接口梳理、API文档生成、Mock服务联调的全链路环节确保前后端接口协调一致沟通机制明确每日站会进度同步、周评审会问题复盘与计划调整的执行规范保障信息流转高效透明。
**质量要求**2页
从标准层面保障项目交付质量包括代码规范如命名规则、注释要求、测试标准单元测试覆盖率≥80%、接口响应时间≤500ms等性能指标以及交付验收标准功能完整性、兼容性、安全性验证流程确保最终成果符合设计预期与业务需求。
### 技术培训重点
技术培训分模块设计实操内容,各模块需结合技术规范与最佳实践,确保开发能力的系统性构建:
**前端培训**聚焦用户交互与地图可视化实现核心内容包括基于React+TypeScript的项目工程化搭建重点强化组件化开发与类型安全Leaflet地图组件开发涵盖图层加载、叠加与管理逻辑实现地理数据的可视化呈现AntDesignX AI对话组件的集成与定制满足自然语言交互界面需求SSE客户端流式响应处理结合传输协议特性如SSE在实时数据推送场景的适用性确保LLM生成内容的流畅展示[[2](https://blog.csdn.net/qq_44866828/article/details/146106385)]。
**后端培训**侧重服务集成与数据安全管控具体包括Spring Boot框架与Spring AI的集成方案实现LLM模型的调用与管理基于JSON-RPC 2.0规范的MCP协议实现需明确Host/Client/Server核心组件的职责划分及交互逻辑保障跨服务通信的标准化[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)][[2](https://blog.csdn.net/qq_44866828/article/details/146106385)]PostgreSQL数据库配置结合PostGIS扩展实现空间数据存储并通过行级安全策略RLS强化数据访问控制落实安全最佳实践中的权限管理要求[[18](https://cloud.tencent.com/developer/article/2535686?policyId=1003)]GeoServer REST API的封装与调用实现地理空间服务的动态管理。
**联合培训**旨在打通前后端协作流程关键内容包含MCP协议三类服务调用的实操演练需基于功能模块分层控制设计——Resources服务由应用控制用于地理数据获取Tools服务由AI控制执行空间分析任务Prompts服务由用户控制生成定制化提示模板结合多语言SDK如TypeScript前端与Java后端的协同使用[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)][[2](https://blog.csdn.net/qq_44866828/article/details/146106385)]前后端联调环节重点训练Mock服务的配置与应用依据联调规范完成API文档验证、错误码定义及接口兼容性测试确保整体系统交互的稳定性。
培训过程中需同步强调技术选型的核心考量如MCP协议实现需评估开放性、生态支持、安全性等要素传输协议选择需结合场景特性如stdio适用于轻量交互SSE适用于流式响应以提升开发团队对技术栈的综合把控能力[[2](https://blog.csdn.net/qq_44866828/article/details/146106385)][[19](https://mcpnodes.com/)]。
### 项目要求与风险提示
项目要求是确保开发过程规范可控、成果可交付的基础,需明确技术规范、文档标准与管理流程;风险提示则需针对潜在技术瓶颈与外部依赖风险制定前瞻性应对策略,保障项目稳定性与可持续性。
**项目要求**方面需严格遵循开发流程规范与质量标准代码管理采用Git Flow工作流以实现分支策略标准化确保代码提交的可追溯性与版本控制效率文档体系需覆盖API接口文档、开发手册及用户操作指南确保团队协作与后期维护的顺畅性进度管理通过JIRA任务跟踪系统实现需求拆解、工时评估与里程碑监控保障开发节奏与交付节点可控。此外安全性与性能要求需作为核心指标纳入开发规范安全性层面需实现基于角色的权限管理、敏感数据加密传输及操作日志审计功能严格控制地理数据与用户信息的访问权限[[4](https://cloud.tencent.com/developer/article/2541726?policyId=1004)]性能层面需重点评估高并发场景下的实时响应能力如多用户同时发起空间查询请求及大规模数据交互时的系统负载能力确保地图服务响应时间≤2秒满足用户体验需求[[2](https://blog.csdn.net/qq_44866828/article/details/146106385)]。
**风险提示**需聚焦技术依赖与系统稳定性,制定分层应对方案:
- **MCP协议相关风险**作为GIS与LLM交互的核心协议其兼容性与生态成熟度直接影响集成效率。需关注协议规范每3-6个月的更新频率建立版本跟踪机制以提前适配接口变更[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]同时优先选择社区活跃度高、文档示例完善的MCP实现库降低生态依赖风险并在开发初期与协议厂商开展联合测试验证数据交互的稳定性[[2](https://blog.csdn.net/qq_44866828/article/details/146106385)]。
- **LLM接口与第三方服务风险**外部LLM API调用存在限流、延迟波动等不确定性需实现多厂商 fallback 机制如同时对接OpenAI与开源模型接口并对高频查询结果建立本地缓存以降级响应针对第三方地图服务或空间数据库需优化连接池配置与索引策略缓解高并发下的数据库性能瓶颈[[2](https://blog.csdn.net/qq_44866828/article/details/146106385)]。
- **性能与安全风险**空间分析模块在处理大规模矢量数据或复杂拓扑计算时易出现性能瓶颈需通过空间索引优化如R树、四叉树与批量任务异步处理提升效率多用户并发场景下需采用会话管理机制如Cloudflare Durable Objects的休眠/唤醒策略)避免资源泄露[[1](https://blog.csdn.net/m0_64132019/article/details/147163246)]安全层面需实施输入校验、参数过滤及传输加密TLS 1.3)等措施,并遵循最小权限原则,确保工具调用与数据访问需经用户显式批准,防范注入攻击与数据越权风险[[4](https://cloud.tencent.com/developer/article/2541726?policyId=1004)]。
通过明确项目要求与风险应对措施可系统性降低开发过程中的不确定性为GIS与LLM融合应用的稳定交付提供保障。