# ftcmap-server

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

## Basic Information

- **Project Name**: ftcmap-server
- **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 扩展的前后端分离基础平台。系统保留若依成熟的权限、安全、日志、监控、代码生成等通用能力，并在此基础上新增首页一张图、地图服务目录、二维/三维场景切换、AI 智能交互和 MCP 接口扩展能力，可作为政企管理系统、空间信息系统和智能化业务应用的基础底座。

## 代码地址

代码仓库地址：`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
```

## 平台简介

平台后端采用 Spring Boot、Spring Security、JWT、Redis、MyBatis、Druid、PageHelper 等技术，前端采用 Vue 3、Vite、Element Plus、Pinia、Vue Router，并集成 Cesium、Leaflet、Esri Leaflet 等地图能力。系统以若依 3.9.2 的用户权限体系为基础，扩展了面向地图场景的一张图应用和面向自然语言操作的 AI 智能助手。

核心扩展包括：

- 一张图首页：支持二维 Leaflet 与三维 Cesium 场景，提供图层目录、底图切换、图层显隐、图层定位、地图标记、测量、清空标绘、坐标显示等能力。
- 地图服务管理：支持目录化维护地图服务，管理 XYZ、TMS、Google XYZ、OGC WMS、OGC WMTS、ArcGIS 切片、ArcGIS 动态服务、glTF/glb 模型、3D Tileset 等服务类型，并支持二维、三维或通用场景配置。
- AI 智能交互：提供地图智能助手，支持流式响应、规则兜底解析、模型接口配置、对话历史上下文和白名单地图动作执行，可通过自然语言完成视图切换、底图切换、图层操作、地图定位、标绘清理等交互。
- MCP 接口扩展：通过 `McpToolProvider` 统一暴露工具定义，支持工具扫描、页面绑定、启停管理、参数 Schema 管理和前端/后端/外部执行器扩展。
- 平台基础能力：保留用户、角色、菜单、部门、岗位、字典、参数、通知公告、日志审计、在线用户、定时任务、服务监控、缓存监控、数据监控、表单构建、代码生成、接口文档等通用后台能力。

## 技术栈

- 后端：Java 17、Spring Boot 4.0.3、Spring Security、JWT、Redis、MyBatis、Druid、PageHelper、Fastjson2、Quartz、SpringDoc OpenAPI。
- 前端：Vue 3、Vite、Element Plus、Pinia、Vue Router、Axios、ECharts、Cesium、Leaflet、Esri Leaflet。
- 数据库：PostgreSQL 完整初始化脚本位于 `sql/ftc_base_init.sql`，已整合基础表、Quartz、行政区划、地图服务、MCP 页面和工具关系等数据库对象。
- 架构：前后端分离，后端多模块 Maven 工程，前端单独构建部署。

## 项目结构

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

ftc-base-web/ftc-base
├── src/views/index.vue                 # 首页一张图
├── src/views/home                      # 地图运行时、Leaflet/Cesium 桥接、AI 动作分发
├── src/views/system/mapService         # 地图服务管理
├── src/views/system/mcpTool            # MCP 接口管理
└── src/views/system/config             # 参数设置与 AI 助手配置
```

## 内置功能

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. 系统接口：基于 SpringDoc OpenAPI 暴露接口文档，便于接口调试和对接。
20. 首页一张图：提供二维/三维一体化地图首页，支持底图切换、图层目录、地图服务加载、图层定位、标记、测量、清空标绘、首页视角和坐标状态展示。
21. 地图服务管理：支持地图服务目录、服务类型、场景模式、服务地址、图层名称、透明度、显示状态、扩展配置、服务范围解析、服务代理和导出。
22. 行政区划定位：内置行政区划服务能力，可为地图助手提供省、市、区县等区域定位支持。
23. AI 智能交互：支持用户通过自然语言驱动地图动作，系统优先调用模型接口解析，失败时回退到规则解析，并通过前端桥接执行受控地图操作。
24. MCP 接口管理：维护 MCP 工具、页面、工具与页面关系、执行方式、参数 Schema、启停状态和扫描刷新结果，为 AI 工具调用提供统一管理入口。

## 系统截图

系统截图统一放在 `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 动作解析和 MCP 工具定义，前端承载地图场景、图层目录、地图工具、坐标信息和 AI 地图助手入口。

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

#### 地图服务管理

地图服务管理用于维护一张图可加载的空间服务资源，后端提供服务目录、服务类型、场景模式、服务地址、显示状态和扩展配置等数据维护接口。

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

#### AI 地图助手

AI 地图助手由后端完成模型配置读取、会话请求构建、流式响应输出、规则兜底解析和工具调用编排，前端负责展示对话过程并执行受控地图动作。

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

#### MCP 接口管理

MCP 接口管理用于统一维护可供 AI 调用的工具定义，后端启动时扫描 `McpToolProvider` 并同步工具、页面绑定、执行方式、参数 Schema 和启停状态。

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

#### 大模型配置

大模型配置通过系统参数维护 AI 能力运行参数，包括 AI 开关、接口地址、密钥、模型名称、温度和超时设置，后端在请求模型接口和执行规则兜底时读取这些配置。

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

### 平台基础管理

#### 用户管理

用户管理保留若依后台的组织、账号、角色和状态维护能力，后端提供用户查询、新增、修改、删除、重置密码、导入导出和数据权限控制等接口。

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

#### 角色管理

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

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

#### 菜单管理

菜单管理用于维护系统动态路由、目录菜单、按钮权限、组件路径、图标和显示状态，后端根据用户角色返回前端动态菜单和权限标识。

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

## 运行说明

### 后端

```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`。

开源版本不内置数据库密码、Redis 密码、JWT 密钥、AI 接口密钥等敏感配置。部署时请通过环境变量或外部配置文件设置 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD`、`REDIS_HOST`、`REDIS_PASSWORD`、`TOKEN_SECRET`、`AI_ASSISTANT_ENDPOINT`、`AI_ASSISTANT_API_KEY`、`AI_ASSISTANT_MODEL` 等参数。

### 前端

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

前端开发服务由 Vite 启动，生产构建产物用于静态资源部署。

## MCP 接口扩展方法

系统中的 MCP 接口统一通过 `McpToolProvider` 暴露工具定义。后端启动时会自动扫描所有 Spring Bean 中的 `McpToolProvider`，也可以在 MCP 接口管理页面点击“刷新接口”触发重新扫描。扫描结果会注册到数据库表 `sys_mcp_tool`，工具和页面的多对多关系会同步到 `sys_mcp_tool_page`，页面基础信息保存在 `sys_mcp_page`。

系统已内置首页地图 MCP 工具提供器 `MapBridgeMcpToolProvider`，页面标识为 `home-map`，包含 `map_bridge_execute`、`switch_view` 以及地图桥接动作工具。前端通过首页地图桥接模块执行对应动作，可支持地图视图、图层、实体、三维场景、动画、截图、标绘清理等能力扩展。

### 扩展步骤

1. 在后端模块中新增一个 Spring 组件类，推荐放在业务模块自己的 `mcp` 包下，例如 `ruoyi-admin/src/main/java/com/ruoyi/web/mcp`。
2. 实现 `com.ruoyi.common.mcp.McpToolProvider`，在 `getToolDefinitions()` 中返回当前组件提供的所有 MCP 工具。
3. 使用 `McpToolDefinition.function(pageIds, toolName, displayName, description, parametersSchema)` 创建工具定义。
4. 设置 `executorType` 和 `executorTarget`。当前常用值为：
   - `frontend`：由前端桥接执行，例如地图、页面控件、二三维场景切换。
   - `backend`：由后端业务逻辑执行。
   - `external`：由外部服务或后续扩展执行。
5. 启动系统，或在 MCP 接口管理页面点击“刷新接口”，系统会把工具注册到数据库。
6. 在 MCP 接口管理页面检查工具是否可用，并在页面管理中维护页面名称。AI 请求时会根据当前 `pageId` 查询该页面可用工具，并写入模型请求的 `tools` 参数。

### 字段约定

- `toolName` 是模型调用的函数名，必须全局唯一，格式为 `^[A-Za-z_][A-Za-z0-9_]{0,127}$`。
- `pageIds` 是工具绑定页面列表，支持一个工具绑定多个页面。传 `*` 表示全局工具，任意页面都可用。
- `displayName` 是管理页面展示名称。
- `description` 会提供给模型，用于判断什么时候调用该工具，应写清楚能力边界和参数含义。
- `parametersSchema` 是 OpenAI tools function 的 JSON Schema。请求构建时系统会根据当前页面自动约束 `pageId` 参数。
- `sortNum` 控制同一页面下工具排序。
- `enabled` 为扫描默认启停状态。已存在工具再次扫描时会保留管理页面里的人工启停状态。
- 扫描工具不存在时，系统会自动停用旧的扫描工具，不会删除历史配置。

### 样例

下面示例新增一个“导出当前页面报告”的 MCP 工具，绑定到 `home-map` 和 `onemap` 两个页面，由前端桥接处理。

```java
package com.ruoyi.web.mcp;

import java.util.LinkedHashMap;
import java.util.List;
import org.springframework.stereotype.Component;
import com.alibaba.fastjson2.JSONObject;
import com.ruoyi.common.mcp.McpToolDefinition;
import com.ruoyi.common.mcp.McpToolProvider;

@Component
public class ReportMcpToolProvider implements McpToolProvider
{
    @Override
    public List<McpToolDefinition> getToolDefinitions()
    {
        McpToolDefinition exportReport = McpToolDefinition.function(
            List.of("home-map", "onemap"),
            "export_report",
            "导出报告",
            "Export the current page report. Use this tool only when the user asks to export or download a report.",
            buildExportReportSchema()
        );
        exportReport.setExecutorType("frontend");
        exportReport.setExecutorTarget("bridge:exportReport");
        exportReport.setSortNum(100);
        exportReport.setRemark("页面报告导出 MCP 工具");
        return List.of(exportReport);
    }

    private JSONObject buildExportReportSchema()
    {
        JSONObject schema = new JSONObject(new LinkedHashMap<>());
        schema.put("type", "object");

        JSONObject properties = new JSONObject(new LinkedHashMap<>());

        JSONObject pageId = new JSONObject(new LinkedHashMap<>());
        pageId.put("type", "string");
        pageId.put("description", "Current page id.");
        properties.put("pageId", pageId);

        JSONObject format = new JSONObject(new LinkedHashMap<>());
        format.put("type", "string");
        format.put("enum", List.of("pdf", "docx"));
        format.put("description", "Report file format.");
        properties.put("format", format);

        JSONObject title = new JSONObject(new LinkedHashMap<>());
        title.put("type", "string");
        title.put("description", "Optional report title.");
        properties.put("title", title);

        schema.put("properties", properties);
        schema.put("required", List.of("pageId", "format"));
        schema.put("additionalProperties", false);
        return schema;
    }
}
```

如果工具由前端执行，需要在前端对应页面或桥接模块中处理 `executorTarget`，例如识别 `bridge:exportReport` 并执行导出逻辑。如果工具由后端执行，则保持 `executorType=backend`，并在后端工具调用分发逻辑中按 `toolName` 或 `executorTarget` 调用具体业务服务。