# ftcmap-web

**Repository Path**: wangyi-tech/ftcmap-web

## Basic Information

- **Project Name**: ftcmap-web
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FTC Base 前端工程

FTC Base 前端是基于若依（RuoYi）3.9.2 Vue3 版本扩展的前后端分离管理端工程。项目在保留若依后台管理能力的基础上，新增首页一张图、二维/三维地图场景、地图服务目录、AI 地图助手和 MCP 接口管理等前端能力，可配合 FTC Base 后端作为政企管理系统、空间信息系统和智能化业务应用的前端底座。

## 代码地址

代码仓库地址：`https://gitee.com/zhangdongchuang/ftc-base.git`

- 前端代码：`web` 分支
- 后端代码：`server` 分支

```bash
# 克隆前端工程
git clone -b web https://gitee.com/zhangdongchuang/ftc-base.git ftc-base-web

# 克隆后端工程
git clone -b server https://gitee.com/zhangdongchuang/ftc-base.git ftc-base-server
```

## 平台简介

前端工程采用 Vue 3、Vite、Element Plus、Pinia、Vue Router、Axios 等技术栈，并集成 Leaflet、Cesium、Esri Leaflet、ECharts 等地图和可视化能力。系统以若依 3.9.2 的用户权限体系、菜单路由体系和后台管理页面为基础，扩展了面向地图场景的一张图首页和面向自然语言操作的 AI 智能交互入口。

核心扩展包括：

- 一张图首页：支持二维 Leaflet 与三维 Cesium 场景，提供底图切换、图层目录、图层显隐、图层定位、地图标记、测量、清空标绘、坐标展示等能力。
- 地图服务管理：提供地图服务目录维护页面，支持 XYZ、TMS、Google XYZ、OGC WMS、OGC WMTS、ArcGIS 切片、ArcGIS 动态服务、glTF/glb 模型、3D Tileset 等服务配置。
- AI 智能交互：提供地图智能助手前端入口，支持流式响应展示、规则兜底动作执行、对话上下文展示和受控地图动作分发。
- MCP 接口管理：提供 MCP 工具、页面、绑定关系、执行方式、参数 Schema、启停状态和扫描刷新结果的管理界面。
- 平台基础能力：保留用户、角色、菜单、部门、岗位、字典、参数、通知公告、日志审计、在线用户、定时任务、服务监控、缓存监控、数据监控、表单构建、代码生成、接口文档等通用后台页面。

## 系统截图

系统截图统一放在 `docs/screenshots` 目录下，README 使用相对路径引用，便于在 Gitee、GitLab、GitHub 等代码平台直接预览。当前截图覆盖首页一张图、地图服务、AI 地图助手、MCP 接口管理、大模型配置以及若依基础权限管理页面。

| 页面 | 截图文件 | 说明 |
| :--- | :--- | :--- |
| 首页一张图 | `docs/screenshots/首页一张图.png` | 展示系统主工作台、二维/三维一张图、图层目录、底图切换、地图工具和右侧 AI 地图助手入口。 |
| 地图服务管理 | `docs/screenshots/地图服务管理.png` | 展示地图服务目录维护、服务类型、服务地址、场景模式、显示状态和服务配置管理能力。 |
| MCP 接口管理 | `docs/screenshots/MCP接口管理.png` | 展示 MCP 工具清单、所属页面、工具类型、执行方式、工具状态以及扫描同步后的工具管理结果。 |
| AI 地图助手 | `docs/screenshots/AI地图助手.png` | 展示首页地图中的自然语言交互、AI 对话结果、工具调用过程以及地图动作执行效果。 |
| 大模型配置 | `docs/screenshots/大模型配置.png` | 展示系统参数中的 AI 能力开关、接口地址、模型名称、密钥、温度和超时等运行参数配置。 |
| 用户管理 | `docs/screenshots/用户管理.png` | 展示用户查询、用户列表、部门组织树、用户状态、导入导出和新增编辑等基础权限管理能力。 |
| 角色管理 | `docs/screenshots/角色管理.png` | 展示角色查询、角色列表、权限字符、数据权限、启停状态和授权操作等角色权限能力。 |
| 菜单管理 | `docs/screenshots/菜单管理.png` | 展示菜单树、路由配置、组件路径、权限标识、图标和菜单启停状态等动态菜单管理能力。 |

### 地图与智能化能力

#### 首页一张图

首页一张图是系统的主工作台，集成地图场景、图层目录、地图工具、坐标信息和 AI 地图助手入口，用于承载空间数据查看、图层管理和智能化地图操作。

![首页一张图](docs/screenshots/首页一张图.png)

#### 地图服务管理

地图服务管理用于维护前端一张图可加载的空间服务资源，支持按服务类型、场景模式、服务地址和显示状态管理地图底图、业务图层、三维模型等服务配置。

![地图服务管理](docs/screenshots/地图服务管理.png)

#### AI 地图助手

AI 地图助手支持通过自然语言驱动地图操作，前端展示对话过程、响应内容和工具调用结果，并将后端解析出的动作分发到地图桥接模块执行。

![AI 地图助手](docs/screenshots/AI地图助手.png)

#### MCP 接口管理

MCP 接口管理用于统一维护可供 AI 调用的工具定义，包含工具名称、页面绑定、执行方式、参数 Schema、工具状态和扫描刷新结果，为前端地图动作与后端工具编排提供管理入口。

![MCP 接口管理](docs/screenshots/MCP接口管理.png)

#### 大模型配置

大模型配置通过系统参数维护 AI 能力运行参数，包括 AI 开关、接口地址、密钥、模型名称、温度和超时设置，便于在不修改前端代码的情况下调整智能助手运行环境。

![大模型配置](docs/screenshots/大模型配置.png)

### 平台基础管理

#### 用户管理

用户管理保留若依后台的组织、账号、角色和状态维护能力，支持按部门树筛选用户，并提供新增、修改、删除、重置密码、导入导出等常用管理操作。

![用户管理](docs/screenshots/用户管理.png)

#### 角色管理

角色管理用于维护系统角色、权限字符、显示顺序、状态和授权关系，是菜单权限、按钮权限和数据权限控制的核心入口。

![角色管理](docs/screenshots/角色管理.png)

#### 菜单管理

菜单管理用于维护系统动态路由、目录菜单、按钮权限、组件路径、图标和显示状态，前端根据后端菜单权限生成对应的导航和页面访问控制。

![菜单管理](docs/screenshots/菜单管理.png)

## 技术栈

- 核心框架：Vue 3、Vite、Vue Router、Pinia。
- UI 与交互：Element Plus、Element Plus Icons、Sass、vuedraggable、splitpanes。
- 网络请求：Axios、Fetch Stream。
- 地图能力：Leaflet、Cesium、Esri Leaflet、vite-plugin-cesium。
- 图表与编辑：ECharts、Vue Quill、js-beautify。
- 工程化：npm、Vite 多环境构建、SVG 图标自动加载、Gzip 压缩插件。
- 配套后端：Java 17、Spring Boot、Spring Security、JWT、Redis、MyBatis、PostgreSQL。

## 项目结构

```text
ftc-base-web/ftc-base
├── src/api                         # 前端接口封装
├── src/assets                      # 静态资源、样式、图标
├── src/components                  # 通用组件
├── src/layout                      # 后台管理布局
├── src/router                      # 静态路由和动态路由装配
├── src/store                       # Pinia 状态管理
├── src/utils                       # 请求、权限、缓存、下载等工具
├── src/views/index.vue             # 首页一张图入口
├── src/views/home                  # 地图运行时、Leaflet/Cesium 桥接、AI 动作分发
├── src/views/system/mapService     # 地图服务管理
├── src/views/system/mcpTool        # MCP 接口管理
├── src/views/system/config         # 参数设置与 AI 助手配置
├── vite.config.js                  # Vite 构建和开发代理配置
├── .env.development                # 开发环境变量
├── .env.staging                    # 测试环境变量
└── .env.production                 # 生产环境变量
```

配套后端工程结构参考后端 README：

```text
ftc-base-server/ftc-base
├── ruoyi-admin       # 后端启动模块，接口控制器、AI 地图助手、MCP 工具提供器
├── ruoyi-common      # 通用工具、核心领域对象、MCP 定义
├── ruoyi-framework   # 安全、配置、Web、缓存等框架能力
├── ruoyi-system      # 系统管理、地图服务、MCP 工具和页面管理等业务模块
├── ruoyi-quartz      # 定时任务模块
├── ruoyi-generator   # 代码生成模块
└── sql               # 数据库完整初始化脚本
```

## 内置功能

1. 用户管理：维护系统用户、所属部门、岗位、角色、状态、密码和导入导出等信息。
2. 角色管理：维护角色权限、菜单权限、按钮权限和数据范围，支持按机构划分数据权限。
3. 菜单管理：维护目录、菜单、按钮、路由、组件、图标、权限标识和显示状态。
4. 部门管理：维护组织机构树，支持公司、部门、小组等多级结构，为数据权限提供组织基础。
5. 岗位管理：维护用户岗位信息，用于用户任职和业务分工配置。
6. 字典管理：维护系统固定枚举类数据，支持字典类型和字典数据管理。
7. 参数设置：维护系统运行参数，并扩展地图智能助手配置，包括 AI 开关、接口地址、接口密钥、模型名称、采样温度和超时设置。
8. 通知公告：维护系统通知、公告发布和展示内容。
9. 个人中心：支持用户资料维护、头像上传和密码修改。
10. 操作日志：记录系统操作行为、请求参数、返回结果、耗时和异常信息，支持查询和导出。
11. 登录日志：记录用户登录、退出和异常登录信息，支持查询、清空和解锁。
12. 在线用户：查看当前在线用户，并支持会话强退。
13. 定时任务：维护 Quartz 任务、Cron 表达式、执行策略、并发控制和任务日志。
14. 服务监控：查看服务器 CPU、内存、JVM、磁盘、系统参数等运行状态。
15. 缓存监控：查看 Redis 基础信息、命令统计、内存消耗和缓存键列表。
16. 数据监控：集成 Druid 监控页面，查看数据库连接池和 SQL 执行情况。
17. 表单构建：通过拖拽组件生成表单页面代码，提升简单页面开发效率。
18. 代码生成：根据数据库表生成后端、前端、Mapper、SQL 等代码，支持预览、下载和导入。
19. 系统接口：集成后端 OpenAPI/Swagger 页面，便于接口调试和对接。
20. 首页一张图：提供二维/三维一体化地图首页，支持底图切换、图层目录、地图服务加载、图层定位、标记、测量、清空标绘、首页视角和坐标状态展示。
21. 地图服务管理：支持地图服务目录、服务类型、场景模式、服务地址、图层名称、透明度、显示状态、扩展配置、服务范围解析、服务代理和导出。
22. AI 智能交互：支持用户通过自然语言驱动地图动作，前端接收后端解析结果并通过地图桥接模块执行受控操作。
23. MCP 接口管理：维护 MCP 工具、页面、工具与页面关系、执行方式、参数 Schema、启停状态和扫描刷新结果，为 AI 工具调用提供统一管理入口。

## 运行说明

### 环境要求

- Node.js：建议使用 Node.js 18 或以上版本。
- npm：项目已提交 `package-lock.json`，推荐使用 npm 安装依赖。
- 后端服务：开发环境默认代理到 `VITE_BACKEND_URL`，本地未配置时使用 `http://localhost:8080`。
- 地图服务：`VITE_MAP_PROXY_URL`、`VITE_3DMODEL_URL`、`VITE_TDT_TOKEN` 均为部署环境配置项，开源代码不内置第三方密钥或私有服务地址。

### 前端启动

```bash
cd ftc-base-web/ftc-base
npm install
npm run dev
```

开发服务由 Vite 启动，默认访问地址以终端输出为准。后端接口通过 `VITE_APP_BASE_API` 和 `vite.config.js` 中的代理配置转发。

### 前端构建

```bash
# 构建测试环境
npm run build:stage

# 构建生产环境
npm run build:prod
```

构建产物默认输出到 `dist` 目录，可用于 Nginx、网关或其他静态资源服务部署。

### 后端启动

```bash
cd ftc-base-server/ftc-base
mvn clean package
mvn -pl ruoyi-admin spring-boot:run
```

后端启动类为 `com.ruoyi.RuoYiApplication`，主要配置文件位于 `ruoyi-admin/src/main/resources`。数据库初始化脚本参考后端工程 `sql/ftc_base_init.sql`。

## 前后端接口约定

- 开发环境接口前缀由 `.env.development` 中的 `VITE_APP_BASE_API` 控制。
- Vite 代理默认将业务接口转发到 `VITE_BACKEND_URL`。
- `/map-proxy` 用于地图服务代理，目标地址由 `VITE_MAP_PROXY_URL` 配置。
- `/3dmodel` 用于三维模型静态服务代理，目标地址由 `VITE_3DMODEL_URL` 配置。
- Swagger、Druid、文件上传下载等页面和接口沿用若依前后端分离约定。
- 登录鉴权使用后端返回的 Token，前端通过请求拦截器统一携带认证信息。

## 地图与 AI 扩展说明

### 地图服务

地图服务数据由后端 `system/mapService` 接口提供，前端通过 `src/views/system/mapService` 维护服务目录，并在首页一张图中按服务类型加载到二维或三维场景。

常见服务类型包括：

- `xyz`、`tms`、`google_xyz`
- `ogc_wms`、`ogc_wmts`
- `arcgis_tile`、`arcgis_dynamic`
- `gltf`、`glb`、`3d_tileset`

### AI 地图助手

AI 地图助手前端入口位于首页一张图，相关接口封装在 `src/api/system/mapAssistant.js`。前端支持流式读取后端响应，并将可执行动作分发到 `src/views/home/mapBridge` 下的桥接模块。

### MCP 前端执行器

当 MCP 工具的 `executorType` 为 `frontend` 时，前端需要根据后端返回的 `executorTarget` 执行对应动作。当前地图桥接执行逻辑主要位于：

```text
src/views/home/mapBridge
├── assistantDispatcher.js        # AI/MCP 动作分发
├── leafletBridge.js              # 二维地图桥接
├── cesiumBridge.js               # 三维地图桥接
├── shared.js                     # 通用动作定义
└── cesiumMcpBridge               # Cesium MCP 命令集合
```

新增前端执行动作时，建议先在后端 MCP 工具定义中明确 `toolName`、`executorType`、`executorTarget` 和参数 Schema，再在前端桥接模块中实现对应动作处理，确保工具定义、页面绑定和前端执行逻辑一致。