{"repo": "at-kiri/gis-practice", "files": {"README.md": {"d6d47e0a5d25368a2aeec1930d9656f68b8355de": {"t": 1785746602.8292162, "n": 18252, "h": "858218d16671a0b6", "c": "# 京津冀城市综合防灾应急管理系统\n\n基于 **Vue3 + SuperMap iClient (MapboxGL) + SpringBoot + FastAPI + LangGraph** 的 GIS 应急管理平台，集成多源空间数据可视化、空间分析、网络分析、AI 智能问答等能力。\n\n> 课程：GIS 工程应用实践 ｜ 数据处理：SuperMap iDesktopX 2025 ｜ 服务发布：SuperMap iServer 11i\n\n---\n\n## 一、功能模块\n\n系统按顶部导航分为 **5 大模块**：\n\n### 1. 数字大屏 `/new-big-screen`\n**气象灾害监测大屏**（NewBigScreenView），面向值班人员实时监控天气态势。\n- **KPI 指标卡**：大风强度（级）、降雨深度（mm）、温度（℃）、湿度（%），超阈值自动高亮警告\n- **气象趋势图**：过去 24h 风力/降雨/温度折线图\n- **系统状态**：实时时钟、运行状态指示灯\n\n### 2. 二维地图 `/`\n**系统核心主页面**（HomeView + SmMapViewer），集成 GIS 操作、数据管理与 AI 问答。左侧 NavSidebar 提供功能入口：\n\n#### 2.1 基础 GIS 操作（左侧工具栏，地图内嵌组件）\n| 功能 | 组件 | 说明 |\n|------|------|------|\n| 地图工具 | MapToolbar | 全幅显示、放大、缩小、平移 |\n| 鹰眼视图 | MapOverview | 小地图概览，拖拽快速定位 |\n| 量算工具 | MapMeasure | 距离量算、面积量算 |\n| 图层管理 | LayerManager | 控制各图层显隐与透明度 |\n| 空间查询 | SpatialQuery | 绘制点/矩形/圆查询 POI，结果标绘 + 属性弹窗 |\n| 专题检索 | FeatureSearch | 关键字搜索地物、行政级别（省/县/乡镇）分级检索 |\n| 缓冲区与叠置分析 | SpatialAnalysis | 缓冲区辐射范围分析、土地利用叠置分析 |\n| 网络分析 | NetworkAnalysis | 最短路径分析、服务区分析（基于长春路网数据） |\n\n#### 2.2 数据库 CRUD 管理（NavSidebar → \"数据库\"分组 → 独立路由页面）\n| 功能 | 路由 | 页面 | 表 |\n|------|------|------|----|\n| 预警主表 | `/warn-info` | WarnInfoView | `tb_warn_info` — 气象灾害预警录入/编辑/查询/删除 |\n| 协同处置 | `/coord-response` | CoordResponseView | `tb_coord_response` — 协同叫应记录管理 |\n| 物资调度 | `/supply-dispatch` | SupplyDispatchView | `tb_supply_dispatch` — 应急物资调度管理 |\n\n#### 2.3 AI 应急助手（AgentChatPanel 浮动面板，HomeView 内嵌）\n- **多 Agent 协同架构**：Coordinator 调度器 → 意图分类 → 任务规划 → 4 个子 Agent（search / analysis / route / knowledge）顺序执行 → 流式汇总输出\n- **12+ 工具**：feature_search / spatial_query / buffer_analysis / dual_buffer_analysis / overlay_analysis / shortest_path / service_area / fly_to_location / online_route_planning / mock_nearby_resources + Pareto 多目标优化 + ACO 蚁群路径分配\n- **RAG 知识库**：5 篇应急预案文档（地震/火灾/洪水/医疗救援/综合预案），FAISS 向量检索\n- **双模式**：单一意图 → 单 Agent（低延迟）；混合意图 → Coordinator 多 Agent 编排\n- **前端渲染**：工具返回的 GeoJSON 自动叠加到地图，受灾点红色标记，支援点琥珀色标记\n\n### 3. 三维洪水模拟 `/flood-simulation`\n**Cesium 3D 场景**（FloodSimulationView），演示积石山区域洪水淹没过程。\n- 淹没参数调节：高度（m）/ 速度（m/s）\n- 控制：开始模拟 / 暂停继续 / 重置\n- 实时水位动态上升效果\n\n### 4. 监测-预警-联动 `/data-dashboard`\n（原\"数据大屏\"改造，半屏面板布局：左侧地图 + 右侧页签切换）\n- **分级地图**（DashboardMap）：县级行政区灾害标记着色，点击选中目标县域\n- **气象监控**（WeatherPanel → 右侧\"气象监控\"页签）：实时气象数据（风力/降雨/温度/湿度）\n- **AHP 灾情评估**（DisasterDetailPanel → 右侧\"灾情评估\"页签）：选定县域的多指标层次分析评估\n- **一键救援**：在灾情评估面板触发 → 弹出缓冲区分析弹窗（BufferAnalysisModal）→ 确定后弹出 5 步救援调度弹窗（RoutePlanningModal）\n\n### 5. 地震指挥 `/earthquake-command`\n**地震应急指挥专页**（EarthquakeCommandView），面向地震场景的一站式指挥。\n- **震情概览**：区域、震级、时间、位置、应急等级（I~IV 级），盲区预警/未应答/物资缺口实时滚动\n- **组织层级树**：国家 → 京津冀联合指挥部 → 地市 → 区县 → 乡镇，折叠/展开\n- **AHP-DDI 灾情评估**：8 指标（地震强度/震源深度/人口密度/建筑脆弱性/道路通达性/医疗容量/物资储备/次生灾害风险），层次分析法计算 → 4 级划分\n- **双缓冲区分析**：受灾圈（小半径）+ 支援圈（大半径），按灾害等级动态调整半径\n- **救援调度**：5 步流程（建队伍→医疗→物资→交通→避难），4 路彩色路径渲染\n- **Pareto 多目标优化 + ACO 蚁群路径分配**：在距离与容量之间找 Pareto 最优解，ACO 多车路径分配\n\n---\n\n## 二、技术栈\n\n| 层 | 技术 |\n|----|------|\n| 前端 | Vue 3.5 + Vite 8 + Ant Design Vue 4 + Ant Design Vue Icons 7 + MapboxGL 1.13 + `@supermap/iclient-mapboxgl` 11.1 + Cesium + Pinia 3 + Vue Router 4 + Axios 1.7 + markdown-it 14 |\n| 后端（业务） | SpringBoot 3.4 + MyBatis 3 + MySQL 8（Java 17） |\n| 后端（Agent） | FastAPI + LangGraph + LangChain + DeepSeek-V3.2（硅基流动）+ FAISS |\n| GIS 服务 | SuperMap iServer 11i（地图/数据/空间分析/网络分析服务） |\n| 数据 | Jingjin.udbx / World.udbx / Changchun.udbx（iServer 自带样本数据） |\n\n---\n\n## 三、目录结构\n\n```\nGIS-Practice/\n├── frontend/                  # Vue3 前端\n│   ├── src/\n│   │   ├── components/\n│   │   │   ├── dashboard/        # 数据大屏组件（DashboardMap, WeatherPanel, DisasterDetailPanel, BufferAnalysisModal, RoutePlanningModal）\n│   │   │   ├── earthquake/       # 地震应急组件（BufferZoneLayer, SupportPointLayer, RescueDispatchPanel）\n│   │   │   ├── agent/            # Agent 聊天组件（ChatMessage, ToolCallCard）\n│   │   │   ├── SmMapViewer.vue   # 核心地图组件\n│   │   │   ├── NavSidebar.vue    # 导航侧边栏（GIS 工具组 + \"数据库\"分组 CRUD 入口）\n│   │   │   ├── AgentChatPanel.vue# AI 聊天面板\n│   │   │   ├── MapToolbar.vue    # 地图工具栏\n│   │   │   ├── MapOverview.vue   # 鹰眼组件\n│   │   │   ├── MapMeasure.vue    # 量算组件\n│   │   │   ├── LayerManager.vue  # 图层管理\n│   │   │   ├── FeatureSearch.vue # 专题检索\n│   │   │   ├── SpatialQuery.vue  # 空间查询\n│   │   │   ├── SpatialAnalysis.vue # 缓冲区与叠置分析\n│   │   │   └── NetworkAnalysis.vue # 网络分析\n│   │   ├── views/             # 页面视图（对应顶部导航 5 大模块 + CRUD 子页）\n│   │   │   ├── NewBigScreenView.vue    # 【数字大屏】气象灾害监测大屏\n│   │   │   ├── HomeView.vue            # 【二维地图】核心地图页（GIS + Agent）\n│   │   │   ├── FloodSimulationView.vue # 【三维洪水模拟】Cesium 3D 淹没模拟\n│   │   │   ├── DataDashboardView.vue   # 【监测-预警-联动】综合监测评估\n│   │   │   ├── EarthquakeCommandView.vue # 【地震指挥】地震应急指挥专页\n│   │   │   ├── WarnInfoView.vue        # 【二维地图→数据库】预警主表 CRUD\n│   │   │   ├── CoordResponseView.vue   # 【二维地图→数据库】协同处置 CRUD\n│   │   │   └── SupplyDispatchView.vue  # 【二维地图→数据库】物资调度 CRUD\n│   │   ├── router/index.js  # 路由配置（9 条路由）\n│   │   ├── stores/           # Pinia 状态管理（map.js / agent.js）\n│   │   ├── composables/      # Vue composables（useShortestPath）\n│   │   └── utils/\n│   │       ├── request.js        # axios 封装\n│   │       ├── map.js            # 地图工具函数\n│   │       ├── ahp.js            # 通用 AHP 层次分析法\n│   │       ├── earthquakeAhp.js  # 地震 AHP-DDI 灾情评估\n│   │       ├── haversine.js      # 球面距离计算\n│   │       ├── circlePolygon.js  # 圆形 Polygon 生成\n│   │       ├── mockData.js       # 模拟数据生成\n│   │       ├── earthquakeNaming.js # 地震命名规则\n│   │       ├── generateEarthquakePoints.js # 地震点数据生成\n│   │       └── agent/\n│   │           ├── sse.js            # SSE 连接管理\n│   │           ├── markdown.js       # Markdown 渲染\n│   │           ├── mapRenderer.js    # GeoJSON 地图渲染\n│   │           └── changchunBasemap.js # 长春底图配置\n│   ├── composables/         # Vue composables（useShortestPath）\n│   ├── public/data/         # 静态地理数据（roads.geojson, buildings.geojson）\n│   └── vite.config.js       # 含 /iserver /api /agent-api 三组 proxy\n│\n├── backend/                   # SpringBoot 业务后端（CRUD + 健康检查）\n│   └── src/main/\n│       ├── java/com/gis/emergency/\n│       │   ├── controller/  # REST API（Health / WarnInfo / CoordResponse / SupplyDispatch）\n│       │   ├── service/     # 业务逻辑层\n│       │   ├── mapper/      # MyBatis 注解式 Mapper\n│       │   ├── entity/      # 实体类（WarnInfo / CoordResponse / SupplyDispatch）\n│       │   ├── common/      # 统一响应 R.java\n│       │   ├── config/      # CORS、全局异常处理、App 配置\n│       │   └── util/        # CoordConverter 坐标转换\n│       └── resources/\n│           ├── application.yml  # 数据库 + iServer 配置\n│           ├── schema.sql       # 建表脚本（启动自动执行，幂等）\n│           └── data.sql         # 种子数据（18 条，INSERT IGNORE）\n│\n├── agent-backend/             # FastAPI Agent 后端（AI 智能问答）\n│   ├── app/\n│   │   ├── agent/             # LangGraph 多 Agent 编排\n│   │   │   ├── coordinator.py    # Coordinator 主调度：意图→规划→代码级路由→子 Agent→汇总\n│   │   │   ├── graph.py          # 单 Agent 引擎（ReAct 模式，11 GIS 工具 + 2 算法工具）\n│   │   │   ├── state.py          # 状态管理\n│   │   │   ├── nodes/\n│   │   │   │   ├── intent.py     # 意图分类节点\n│   │   │   │   ├── planner.py    # 任务规划节点\n│   │   │   │   └── summarize.py  # 结果汇总节点（流式输出）\n│   │   │   ├── sub_agents/       # 4 个子 Agent（search/analysis/route/knowledge）\n│   │   │   └── tools/\n│   │   │       ├── gis_tools.py  # 11 个 GIS 工具（feature_search/spatial_query/buffer_analysis/dual_buffer_analysis/overlay_analysis/shortest_path/service_area/fly_to_location/online_route_planning/mock_nearby_resources）\n│   │   │       ├── algo_tools.py # 2 个算法工具（Pareto 多目标优化 + ACO 蚁群多车路径分配）\n│   │   │       └── rag_tools.py  # RAG 检索工具\n│   │   ├── api/                 # FastAPI 路由（agent / rag）\n│   │   ├── services/            # LLM / RAG / iServer / Session 客户端\n│   │   ├── schemas/             # Pydantic 模型（ToolResult）\n│   │   └── config.py            # 配置读取（.env 优先）\n│   ├── data/knowledge/          # RAG 知识库源文档（5 篇应急预案 markdown）\n│   ├── .env.example             # 环境变量模板（含 API Key 配置说明）\n│   └── requirements.txt\n│\n├── openspec/                    # OpenSpec 设计文档（proposal/design/spec/tasks/checklist）\n│   └── changes/\n│       ├── project-foundation/          # 项目基础框架\n│       ├── spatial-query/               # 空间查询\n│       ├── thematic-search/             # 专题检索\n│       ├── spatial-analysis/            # 缓冲区与叠置分析\n│       ├── 20260626-multi-agent-gis/    # AI 多智能体系统\n│       ├── 20260626-data-dashboard/     # 数据大屏\n│       ├── 20260702-db-crud-module/     # 数据库 CRUD 模块\n│       └── 20260705-earthquake-rescue-refactor/ # 地震应急指挥重构\n├── .trae/                      # Trae IDE 规则、技能、工作流、知识库\n├── project-brief.md            # 项目概要\n└── AGENTS.md                   # AI Agent 入口导航\n```\n\n---\n\n## 四、运行环境要求\n\n| 软件 | 版本 | 用途 |\n|------|------|------|\n| JDK | 17+ | SpringBoot 后端 |\n| Maven | 3.8+ | 后端构建 |\n| Node.js | 18+ | 前端构建 |\n| npm | 9+ | 前端依赖 |\n| Python | 3.10+ | Agent 后端 |\n| MySQL | 8.0+ | 业务数据存储 |\n| SuperMap iServer | 11i (11.3.0) | GIS 服务 |\n| SuperMap iDesktopX | 2025（可选） | 数据处理/制图 |\n\n---\n\n## 五、启动前配置\n\n系统涉及 **5 个服务**（含数据库），按以下顺序配置和启动：iServer → MySQL → SpringBoot 后端 → FastAPI Agent 后端 → Vue 前端。\n\n### 5.1 SuperMap iServer 配置（端口 8090）\n\niServer 提供 GIS 数据服务、地图服务、空间分析、网络分析能力，是前端地图和 Agent 工具的数据源。\n\n#### 1) 安装并启动 iServer\n\n- 安装路径示例：`D:\\SuperMap\\SuperMapiServer11i\\`\n- 启动：进入 `bin/` 目录运行 `startup.bat`，浏览器访问 `http://localhost:8090/iserver`\n- 首次启动需设置管理员账号\n\n#### 2) 确认样本数据存在\n\niServer 11i 自带以下样本数据，位于 `D:\\SuperMap\\SuperMapiServer11i\\samples\\data\\`：\n\n| 数据文件 | 路径 | 用途 |\n|---------|------|------|\n| 京津冀数据 | `City\\Jingjin.udbx` | 基础地图、空间查询、缓冲区分析 |\n| 世界底图 | `World\\World.udbx` | 底图 |\n| 长春路网 | `NetworkAnalyst\\Changchun.udbx` | 网络分析（最短路径/服务区） |\n\n#### 3) 发布/确认服务\n\niServer 默认在 `webapps\\iserver\\WEB-INF\\iserver-services-samples.xml` 中预配置了以下服务，**首次启动后通常已自动发布**，请在 iServer 管理页面「服务」列表中确认存在：\n\n| 服务名 | 类型 | 用途 |\n|--------|------|------|\n| `map-jingjin` | 地图服务 | 京津冀地图展示 |\n| `data-jingjin` | 数据服务 | 要素查询（POI、行政区域等） |\n| `spatialanalyst-sample` | 空间分析服务 | 缓冲区分析、叠置分析 |\n| `transportationanalyst-sample` | 交通网络分析服务 | 最短路径、服务区分析 |\n\n若服务未自动发布，可在 iServer 管理页面「服务 → 创建服务」中基于上述数据源手动发布。\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8090/iserver/services`，应能看到上述服务列表。\n\n---\n\n### 5.2 MySQL 数据库配置（端口 3306）\n\n#### 1) 安装并启动 MySQL 8\n\n确保 MySQL 服务已启动，并能以 root 账号登录：\n\n```bash\nmysql -u root -p\n```\n\n#### 2) 修改后端数据库账号密码\n\n打开 `backend/src/main/resources/application.yml`，修改第 10–12 行：\n\n```yaml\nspring:\n  datasource:\n    url: jdbc:mysql://localhost:3306/emergency_db?createDatabaseIfNotExist=true&useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true\n    username: root           # ← 改为你的 MySQL 用户名\n    password: t821777        # ← 改为你的 MySQL 密码\n    driver-class-name: com.mysql.cj.jdbc.Driver\n```\n\n说明：\n- `createDatabaseIfNotExist=true`：首次启动时自动创建 `emergency_db` 数据库，无需手动建库\n- `serverTimezone=Asia/Shanghai`：时区配置，必须保留\n\n#### 3) 执行 SQL（建表 + 种子数据）\n\n**方式 A（推荐，自动执行）**：保持 `application.yml` 中以下配置不变：\n\n```yaml\nspring:\n  sql:\n    init:\n      mode: always                              # 每次启动都执行\n      schema-locations: classpath:schema.sql    # 建表（IF NOT EXISTS，幂等）\n      data-locations: classpath:data.sql        # 种子数据（INSERT IGNORE，幂等）\n      continue-on-error: false\n```\n\n启动 SpringBoot 后端时，`schema.sql`（建 3 张表）和 `data.sql`（插入 18 条种子数据）会**自动执行**，无需手动操作。\n\n**方式 B（手动执行）**：如需提前建表，可在 MySQL 客户端中执行：\n\n```bash\n# 登录 MySQL\nmysql -u root -p\n\n# 在 MySQL 命令行中执行\nCREATE DATABASE IF NOT EXISTS emergency_db DEFAULT CHARACTER SET utf8mb4;\nUSE emergency_db;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/schema.sql;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/data.sql;\nEXIT;\n```\n\n> 若已通过方式 A 自动建表，**不要再手动执行**，否则 `INSERT IGNORE` 会因主键已存在而跳过（无害但冗余）。\n\n#### 4) 数据表说明\n\n| 表名 | 说明 | 主键 |\n|------|------|------|\n| `tb_warn_info` | 气象灾害预警主表 | `warn_id` |\n| `tb_coord_response` | 协同叫应处置表 | `response_id` |\n| `tb_supply_dispatch` | 应急物资调度总表 | `dispatch_id` |\n\n---\n\n### 5.3 SpringBoot 业务后端配置（端口 8080）\n\n#### 1) 检查 iServer 配置\n\n`application.yml` 第 33–41 行已配置 iServer 服务地址，若你的 iServer 不在 `localhost:8090`，请修改：\n\n```yaml\niserver:\n  base-url: http://localhost:8090\n  data-service: data-jingjin\n  datasource: Jingjin\n  map-service: map-jingjin\n  map-name: 京津地区地图\n  spatial-service: spatialanalyst-sample\n  transport-service: transportationanalyst-sample\n```\n\n#### 2) 构建并启动\n\n```bash\ncd backend\nmvn clean package -DskipTests\njava -jar target/emergency-backend-0.0.1-SNAPSHOT.jar\n```\n\n或在 IDE 中直接运行 `EmergencyApplication.java`。\n\n#### 3) 验证\n\n浏览器访问 `http://localhost:8080/api/health`，应返回：\n\n```json\n{ \"code\": 200, \"message\": \"success\", \"data\": \"京津冀城市综合防灾应急管理系统后端运行正常\" }\n```\n\n---\n\n### 5.4 FastAPI Agent 后端配置（端口 8001）\n\nAgent 后端依赖 **大模型 API Key** 才能运行 AI 问答功能。\n\n#### 1) 创建 Python 虚拟环境并安装依赖\n\n```bash\ncd agent-backend\npython -m venv venv\n# Windows\nvenv\\Scripts\\activate\n# macOS/Linux\nsource venv/bin/activate\n\npip install -r requirements.txt\n```\n\n#### 2) 配置 API Key（必须）\n\n复制环境变量模板：\n\n```bash\ncp .env.example .env\n```\n\n编辑 `agent-backend/.env`，填入你的 API Key：\n\n```dotenv\n# LLM API 配置（硅基流动 SiliconFlow）\n# 注册地址：https://siliconflow.cn/  注册后在「API 密钥」页面创建 Key\n# 注意：变量名虽为 DEEPSEEK_API_KEY，实际填入的是硅基流动的 API Key\nDEEPSEEK_API_KEY=sk-your-siliconflow-api-key-here    # ← 改为你的真实 Key\nDEEPSEEK_BASE_URL=https://api.siliconflow.cn/v1\nDEEPSEEK_MODEL=deepseek-ai/DeepSeek-V3.2\n\n# iServer 配置（默认本机，无需修改）\nISERVER_URL=http://localhost:8090\n\n# 后端配置\nHOST=0.0.0.0\nPORT=8001\n\n# RAG 配置（与 LLM 共用 API Key，留空则自动回退到 DEEPSEEK_API_KEY）\nEMBEDDING_BASE_URL=https://api.siliconflow.cn/v1\nEMBEDDING_MODEL=BAAI/bge-m3\n```\n\n> **关于 API Key**：本项目使用硅基流动（SiliconFlow）提供的 `deepseek-ai/DeepSeek-V3.2` 模型，性价比高。注册硅基流动账号后在「API 密钥」页面创建 Key，填入 `DEEPSEEK_API_KEY`。Embedding 模型 `BAAI/bge-m3` 与 LLM 共用同一 Key，无需额外申请。\n\n#### 3) 启动\n\n```bash\n# 确保在 agent-backend/ 目录且已激活虚拟环境\npython -m app.main\n```\n\n或使用 uvicorn 热重载：\n\n```bash\nuvicorn app.main:app --host 0.0.0.0 --port 8001 --reload\n```\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8001/api/health`，应返回：\n\n```json\n{ \"status\": \"ok\", \"service\": \"gis-agent-backend\" }\n```\n\n启动日志中应看到 `RAG 知识库就绪：5 个文档已索引`（首次启动会自动构建 FAISS 向量库）。\n\n---\n\n### 5.5 Vue 前端配置（端口 5173）\n\n#### 1) 安装依赖\n\n```bash\ncd frontend\nnpm install\n```\n\n#### 2) 确认 Vite proxy 配置\n\n`vite.config.js` 已配置三组代理，默认无需修改：\n\n| 前缀 | 转发到 | 用途 |\n|------|--------|------|\n| `/iserver` | `http://localhost:8090` | iServer GIS 服务 |\n| `/api` | `http://localhost:8080` | SpringBoot 业务后端（CRUD 接口） |\n| `/agent-api` | `http://localhost:8001`（重写为 `/api`） | FastAPI Agent 后端（AI 问答接口） |\n\n若你的后端服务端口不同，请修改 `vite.config.js` 中对应的 `target`。\n\n#### 3) 启动\n\n```bash\nnpm run dev\n```\n\n浏览器访问 `http://localhost:5173`。\n\n#### 4) 前端路由一览（对应顶部导航 5 大模块 + CRUD 子页）\n\n| 导航分组 | 路由路径 | 页面 | 说明 |\n|----------|----------|------|------|\n| **数字大屏** | `/new-big-screen` | NewBigScreenView | 气象灾害监测大屏（KPI + 趋势图） |\n| **二维地图** | `/` | HomeView | 核心地图页（GIS 操作 + NavSidebar + AI 助手） |\n| | `/warn-info` | WarnInfoView | 预警主表 CRUD（NavSidebar → 数据库） |\n| | `/coord-response` | CoordResponseView | 协同处置 CRUD（NavSidebar → 数据库） |\n| | `/supply-dispatch` | SupplyDispatchView | 物资调度 CRUD（NavSidebar → 数据库） |\n| **三维洪水模拟** | `/flood-simulation` | FloodSimulationView | Cesium 3D 淹没模拟 |\n| **监测-预警-联动** | `/data-dashboard` | DataDashboardView | 综合监测评估（地图 + 灾情 + 气象） |\n| **地震指挥** | `/earthquake-command` | EarthquakeCommandView | 地震应急指挥专页 |\n\n---\n\n## 六、启动顺序速查\n\n| 顺序 | 服务 | 端口 | 启动命令 | 启动条件 |\n|------|------|------|---------|---------|\n| 1 | SuperMap iServer | 8090 | `bin/startup.bat` | 已安装并发布样本服务 |\n| 2 | MySQL | 3306 | 系统服务 | 已创建 root 账号或修改 `application.yml` |\n| 3 | SpringBoot 后端 | 8080 | `mvn spring-boot:run` | iServer + MySQL 已启动 |\n| 4 | FastAPI Agent 后端 | 8001 | `python -m app.main` | iServer 已启动 + `.env` 已配置 Key |\n| 5 | Vue 前端 | 5173 | `npm run dev` | 上述后端均已启动 |\n\n> **可选**：若不使用 AI 问答功能，可跳过第 4 步（FastAPI Agent 后端），其余模块（地图、CRUD、空间分析）仍可正常使用。\n\n---\n\n## 七、常见问题\n\n### Q1：前端打开后地图空白？\n- 检查 iServer 是否启动：访问 `http://localhost:8090/iserver`\n- 检查浏览器控制台是否有 `/iserver` 请求 404，确认服务名与 `application.yml` 一致\n\n### Q2：后端启动报数据库连接失败？\n- 确认 MySQL 服务已启动\n- 确认 `application.yml` 中 `username` / `password` 与本机 MySQL 一致\n- 确认 URL 中 `createDatabaseIfNotExist=true` 参数存在（首次启动需自动建库）\n\n### Q3：数据表未自动创建？\n- 检查 `application.yml` 中 `spring.sql.init.mode` 是否为 `always`\n- 检查 `schema.sql` / `data.sql` 是否在 `src/main/resources/` 下\n- 查看启动日志是否有 SQL 执行错误\n\n### Q4：Agent 聊天无响应或报 401？\n- 确认 `agent-backend/.env` 中 `DEEPSEEK_API_KEY` 已填写真实 Key\n- 确认 Key 余额充足（硅基流动账户）\n- 确认 `DEEPSEEK_BASE_URL` 为 `https://api.siliconflow.cn/v1`（非 DeepSeek 官方地址）\n\n### Q5：RAG 知识库初始化失败？\n- 首次启动会调用 Embedding API 构建向量库，需联网且 API Key 有效\n- 失败为非致命错误，Agent 仍可运行（仅失去知识库检索能力）\n- 重新启动时会自动重试\n\n### Q6：网络分析模块无结果？\n- 确认 `transportationanalyst-sample` 服务已在 iServer 发布\n- 确认长春路网数据 `Changchun.udbx` 存在\n- 网络分析使用长春市数据，起终点需在长春市范围内\n\n### Q7：端口被占用？\n- 8080 / 8001 / 5173 / 8090 任一被占用都会导致启动失败\n- 使用 `netstat -ano | findstr <端口>` 查看占用进程\n- 修改对应配置文件中的端口号（注意同步更新 `vite.config.js` 的 proxy target）\n\n---\n\n## 八、开发规范\n\n- AI 编码规范：见 [`.trae/rules/coding_guidelines.md`](.trae/rules/coding_guidelines.md)\n- 前端规范：见 [`.trae/rules/frontend_rules.md`](.trae/rules/frontend_rules.md)\n- 项目规范：见 [`.trae/rules/project_rules.md`](.trae/rules/project_rules.md)\n- Git 提交规范：`<type>: <描述>`，type 包括 `feat / fix / refactor / docs / style / chore`\n- 设计文档：`openspec/changes/<change-id>/` 下按 proposal → design → spec → tasks → checklist 组织\n- 单元测试：`frontend/src/utils/__tests__/` 下存放置工具函数单元测试（Vitest），含 earthquakeAhp / haversine / earthquakeNaming / generateEarthquakePoints 测试\n\n---\n\n## 九、安全说明\n\n- 本项目为课程设计，**不涉及用户认证**，前后端 API 均为公开访问\n- `application.yml` 中 MySQL 密码为明文（课设阶段可接受，生产环境应使用配置中心或环境变量）\n- `agent-backend/.env` 已在 `.gitignore` 中忽略，不会提交 API Key 到 Git 仓库\n- iServer 服务地址使用相对路径，通过 Vite proxy 转发，避免跨域\n\n---\n\n## 十、文档索引\n\n| 文档 | 说明 |\n|------|------|\n| [AGENTS.md](AGENTS.md) | AI Agent 入口导航 |\n| [project-brief.md](project-brief.md) | 项目概要：技术栈、数据资源、功能模块 |\n| `.trae/docs/workflows.md` | 角色工作流、协作流程 |\n| `openspec/changes/` | 各功能模块的设计文档与验收清单 |\n| `.trae/knowledge/INDEX.md` | 项目知识库全景图 |\n\n---\n\n## 十一、文档与实现差异说明\n\n本项目的设计文档（包括 `project-brief.md`、`openspec/changes/` 下的 proposal/design/spec/tasks/checklist、`.trae/knowledge/` 中的知识库等）反映的是**开发初期或阶段性方案设计**，并非最终实现的逐字描述。\n\n在实际开发与测试过程中，部分功能会因以下原因与原始文档产生差异：\n\n- 测试验证中发现问题后对接口字段、参数命名、业务逻辑的调整\n- 依赖库版本升级或 API 行为变化导致的实现细节调整\n- 针对 SuperMap iServer / DeepSeek / LangGraph 等外部服务的兼容性适配\n- 性能优化、Bug 修复过程中的代码重构\n\n> **若本文档（README）或其他设计文档与实际系统行为存在不一致，请以实际代码和运行系统为准。**\n\n如需了解某模块的最新实现，建议直接查阅对应的源码：\n\n- 前端组件实现：`frontend/src/components/` 与 `frontend/src/views/`\n- 后端接口实现：`backend/src/main/java/com/gis/emergency/`\n- Agent 工具实现：`agent-backend/app/agent/tools/` 与 `agent-backend/app/agent/sub_agents/`\n- 配置文件（反映真实运行参数）：`backend/src/main/resources/application.yml`、`agent-backend/.env.example`\n"}, "2aa4a0ed3e777c966e7bf0d2788a9548c2db50dd": {"t": 1785766214.307667, "n": 18252, "h": "858218d16671a0b6", "c": "# 京津冀城市综合防灾应急管理系统\n\n基于 **Vue3 + SuperMap iClient (MapboxGL) + SpringBoot + FastAPI + LangGraph** 的 GIS 应急管理平台，集成多源空间数据可视化、空间分析、网络分析、AI 智能问答等能力。\n\n> 课程：GIS 工程应用实践 ｜ 数据处理：SuperMap iDesktopX 2025 ｜ 服务发布：SuperMap iServer 11i\n\n---\n\n## 一、功能模块\n\n系统按顶部导航分为 **5 大模块**：\n\n### 1. 数字大屏 `/new-big-screen`\n**气象灾害监测大屏**（NewBigScreenView），面向值班人员实时监控天气态势。\n- **KPI 指标卡**：大风强度（级）、降雨深度（mm）、温度（℃）、湿度（%），超阈值自动高亮警告\n- **气象趋势图**：过去 24h 风力/降雨/温度折线图\n- **系统状态**：实时时钟、运行状态指示灯\n\n### 2. 二维地图 `/`\n**系统核心主页面**（HomeView + SmMapViewer），集成 GIS 操作、数据管理与 AI 问答。左侧 NavSidebar 提供功能入口：\n\n#### 2.1 基础 GIS 操作（左侧工具栏，地图内嵌组件）\n| 功能 | 组件 | 说明 |\n|------|------|------|\n| 地图工具 | MapToolbar | 全幅显示、放大、缩小、平移 |\n| 鹰眼视图 | MapOverview | 小地图概览，拖拽快速定位 |\n| 量算工具 | MapMeasure | 距离量算、面积量算 |\n| 图层管理 | LayerManager | 控制各图层显隐与透明度 |\n| 空间查询 | SpatialQuery | 绘制点/矩形/圆查询 POI，结果标绘 + 属性弹窗 |\n| 专题检索 | FeatureSearch | 关键字搜索地物、行政级别（省/县/乡镇）分级检索 |\n| 缓冲区与叠置分析 | SpatialAnalysis | 缓冲区辐射范围分析、土地利用叠置分析 |\n| 网络分析 | NetworkAnalysis | 最短路径分析、服务区分析（基于长春路网数据） |\n\n#### 2.2 数据库 CRUD 管理（NavSidebar → \"数据库\"分组 → 独立路由页面）\n| 功能 | 路由 | 页面 | 表 |\n|------|------|------|----|\n| 预警主表 | `/warn-info` | WarnInfoView | `tb_warn_info` — 气象灾害预警录入/编辑/查询/删除 |\n| 协同处置 | `/coord-response` | CoordResponseView | `tb_coord_response` — 协同叫应记录管理 |\n| 物资调度 | `/supply-dispatch` | SupplyDispatchView | `tb_supply_dispatch` — 应急物资调度管理 |\n\n#### 2.3 AI 应急助手（AgentChatPanel 浮动面板，HomeView 内嵌）\n- **多 Agent 协同架构**：Coordinator 调度器 → 意图分类 → 任务规划 → 4 个子 Agent（search / analysis / route / knowledge）顺序执行 → 流式汇总输出\n- **12+ 工具**：feature_search / spatial_query / buffer_analysis / dual_buffer_analysis / overlay_analysis / shortest_path / service_area / fly_to_location / online_route_planning / mock_nearby_resources + Pareto 多目标优化 + ACO 蚁群路径分配\n- **RAG 知识库**：5 篇应急预案文档（地震/火灾/洪水/医疗救援/综合预案），FAISS 向量检索\n- **双模式**：单一意图 → 单 Agent（低延迟）；混合意图 → Coordinator 多 Agent 编排\n- **前端渲染**：工具返回的 GeoJSON 自动叠加到地图，受灾点红色标记，支援点琥珀色标记\n\n### 3. 三维洪水模拟 `/flood-simulation`\n**Cesium 3D 场景**（FloodSimulationView），演示积石山区域洪水淹没过程。\n- 淹没参数调节：高度（m）/ 速度（m/s）\n- 控制：开始模拟 / 暂停继续 / 重置\n- 实时水位动态上升效果\n\n### 4. 监测-预警-联动 `/data-dashboard`\n（原\"数据大屏\"改造，半屏面板布局：左侧地图 + 右侧页签切换）\n- **分级地图**（DashboardMap）：县级行政区灾害标记着色，点击选中目标县域\n- **气象监控**（WeatherPanel → 右侧\"气象监控\"页签）：实时气象数据（风力/降雨/温度/湿度）\n- **AHP 灾情评估**（DisasterDetailPanel → 右侧\"灾情评估\"页签）：选定县域的多指标层次分析评估\n- **一键救援**：在灾情评估面板触发 → 弹出缓冲区分析弹窗（BufferAnalysisModal）→ 确定后弹出 5 步救援调度弹窗（RoutePlanningModal）\n\n### 5. 地震指挥 `/earthquake-command`\n**地震应急指挥专页**（EarthquakeCommandView），面向地震场景的一站式指挥。\n- **震情概览**：区域、震级、时间、位置、应急等级（I~IV 级），盲区预警/未应答/物资缺口实时滚动\n- **组织层级树**：国家 → 京津冀联合指挥部 → 地市 → 区县 → 乡镇，折叠/展开\n- **AHP-DDI 灾情评估**：8 指标（地震强度/震源深度/人口密度/建筑脆弱性/道路通达性/医疗容量/物资储备/次生灾害风险），层次分析法计算 → 4 级划分\n- **双缓冲区分析**：受灾圈（小半径）+ 支援圈（大半径），按灾害等级动态调整半径\n- **救援调度**：5 步流程（建队伍→医疗→物资→交通→避难），4 路彩色路径渲染\n- **Pareto 多目标优化 + ACO 蚁群路径分配**：在距离与容量之间找 Pareto 最优解，ACO 多车路径分配\n\n---\n\n## 二、技术栈\n\n| 层 | 技术 |\n|----|------|\n| 前端 | Vue 3.5 + Vite 8 + Ant Design Vue 4 + Ant Design Vue Icons 7 + MapboxGL 1.13 + `@supermap/iclient-mapboxgl` 11.1 + Cesium + Pinia 3 + Vue Router 4 + Axios 1.7 + markdown-it 14 |\n| 后端（业务） | SpringBoot 3.4 + MyBatis 3 + MySQL 8（Java 17） |\n| 后端（Agent） | FastAPI + LangGraph + LangChain + DeepSeek-V3.2（硅基流动）+ FAISS |\n| GIS 服务 | SuperMap iServer 11i（地图/数据/空间分析/网络分析服务） |\n| 数据 | Jingjin.udbx / World.udbx / Changchun.udbx（iServer 自带样本数据） |\n\n---\n\n## 三、目录结构\n\n```\nGIS-Practice/\n├── frontend/                  # Vue3 前端\n│   ├── src/\n│   │   ├── components/\n│   │   │   ├── dashboard/        # 数据大屏组件（DashboardMap, WeatherPanel, DisasterDetailPanel, BufferAnalysisModal, RoutePlanningModal）\n│   │   │   ├── earthquake/       # 地震应急组件（BufferZoneLayer, SupportPointLayer, RescueDispatchPanel）\n│   │   │   ├── agent/            # Agent 聊天组件（ChatMessage, ToolCallCard）\n│   │   │   ├── SmMapViewer.vue   # 核心地图组件\n│   │   │   ├── NavSidebar.vue    # 导航侧边栏（GIS 工具组 + \"数据库\"分组 CRUD 入口）\n│   │   │   ├── AgentChatPanel.vue# AI 聊天面板\n│   │   │   ├── MapToolbar.vue    # 地图工具栏\n│   │   │   ├── MapOverview.vue   # 鹰眼组件\n│   │   │   ├── MapMeasure.vue    # 量算组件\n│   │   │   ├── LayerManager.vue  # 图层管理\n│   │   │   ├── FeatureSearch.vue # 专题检索\n│   │   │   ├── SpatialQuery.vue  # 空间查询\n│   │   │   ├── SpatialAnalysis.vue # 缓冲区与叠置分析\n│   │   │   └── NetworkAnalysis.vue # 网络分析\n│   │   ├── views/             # 页面视图（对应顶部导航 5 大模块 + CRUD 子页）\n│   │   │   ├── NewBigScreenView.vue    # 【数字大屏】气象灾害监测大屏\n│   │   │   ├── HomeView.vue            # 【二维地图】核心地图页（GIS + Agent）\n│   │   │   ├── FloodSimulationView.vue # 【三维洪水模拟】Cesium 3D 淹没模拟\n│   │   │   ├── DataDashboardView.vue   # 【监测-预警-联动】综合监测评估\n│   │   │   ├── EarthquakeCommandView.vue # 【地震指挥】地震应急指挥专页\n│   │   │   ├── WarnInfoView.vue        # 【二维地图→数据库】预警主表 CRUD\n│   │   │   ├── CoordResponseView.vue   # 【二维地图→数据库】协同处置 CRUD\n│   │   │   └── SupplyDispatchView.vue  # 【二维地图→数据库】物资调度 CRUD\n│   │   ├── router/index.js  # 路由配置（9 条路由）\n│   │   ├── stores/           # Pinia 状态管理（map.js / agent.js）\n│   │   ├── composables/      # Vue composables（useShortestPath）\n│   │   └── utils/\n│   │       ├── request.js        # axios 封装\n│   │       ├── map.js            # 地图工具函数\n│   │       ├── ahp.js            # 通用 AHP 层次分析法\n│   │       ├── earthquakeAhp.js  # 地震 AHP-DDI 灾情评估\n│   │       ├── haversine.js      # 球面距离计算\n│   │       ├── circlePolygon.js  # 圆形 Polygon 生成\n│   │       ├── mockData.js       # 模拟数据生成\n│   │       ├── earthquakeNaming.js # 地震命名规则\n│   │       ├── generateEarthquakePoints.js # 地震点数据生成\n│   │       └── agent/\n│   │           ├── sse.js            # SSE 连接管理\n│   │           ├── markdown.js       # Markdown 渲染\n│   │           ├── mapRenderer.js    # GeoJSON 地图渲染\n│   │           └── changchunBasemap.js # 长春底图配置\n│   ├── composables/         # Vue composables（useShortestPath）\n│   ├── public/data/         # 静态地理数据（roads.geojson, buildings.geojson）\n│   └── vite.config.js       # 含 /iserver /api /agent-api 三组 proxy\n│\n├── backend/                   # SpringBoot 业务后端（CRUD + 健康检查）\n│   └── src/main/\n│       ├── java/com/gis/emergency/\n│       │   ├── controller/  # REST API（Health / WarnInfo / CoordResponse / SupplyDispatch）\n│       │   ├── service/     # 业务逻辑层\n│       │   ├── mapper/      # MyBatis 注解式 Mapper\n│       │   ├── entity/      # 实体类（WarnInfo / CoordResponse / SupplyDispatch）\n│       │   ├── common/      # 统一响应 R.java\n│       │   ├── config/      # CORS、全局异常处理、App 配置\n│       │   └── util/        # CoordConverter 坐标转换\n│       └── resources/\n│           ├── application.yml  # 数据库 + iServer 配置\n│           ├── schema.sql       # 建表脚本（启动自动执行，幂等）\n│           └── data.sql         # 种子数据（18 条，INSERT IGNORE）\n│\n├── agent-backend/             # FastAPI Agent 后端（AI 智能问答）\n│   ├── app/\n│   │   ├── agent/             # LangGraph 多 Agent 编排\n│   │   │   ├── coordinator.py    # Coordinator 主调度：意图→规划→代码级路由→子 Agent→汇总\n│   │   │   ├── graph.py          # 单 Agent 引擎（ReAct 模式，11 GIS 工具 + 2 算法工具）\n│   │   │   ├── state.py          # 状态管理\n│   │   │   ├── nodes/\n│   │   │   │   ├── intent.py     # 意图分类节点\n│   │   │   │   ├── planner.py    # 任务规划节点\n│   │   │   │   └── summarize.py  # 结果汇总节点（流式输出）\n│   │   │   ├── sub_agents/       # 4 个子 Agent（search/analysis/route/knowledge）\n│   │   │   └── tools/\n│   │   │       ├── gis_tools.py  # 11 个 GIS 工具（feature_search/spatial_query/buffer_analysis/dual_buffer_analysis/overlay_analysis/shortest_path/service_area/fly_to_location/online_route_planning/mock_nearby_resources）\n│   │   │       ├── algo_tools.py # 2 个算法工具（Pareto 多目标优化 + ACO 蚁群多车路径分配）\n│   │   │       └── rag_tools.py  # RAG 检索工具\n│   │   ├── api/                 # FastAPI 路由（agent / rag）\n│   │   ├── services/            # LLM / RAG / iServer / Session 客户端\n│   │   ├── schemas/             # Pydantic 模型（ToolResult）\n│   │   └── config.py            # 配置读取（.env 优先）\n│   ├── data/knowledge/          # RAG 知识库源文档（5 篇应急预案 markdown）\n│   ├── .env.example             # 环境变量模板（含 API Key 配置说明）\n│   └── requirements.txt\n│\n├── openspec/                    # OpenSpec 设计文档（proposal/design/spec/tasks/checklist）\n│   └── changes/\n│       ├── project-foundation/          # 项目基础框架\n│       ├── spatial-query/               # 空间查询\n│       ├── thematic-search/             # 专题检索\n│       ├── spatial-analysis/            # 缓冲区与叠置分析\n│       ├── 20260626-multi-agent-gis/    # AI 多智能体系统\n│       ├── 20260626-data-dashboard/     # 数据大屏\n│       ├── 20260702-db-crud-module/     # 数据库 CRUD 模块\n│       └── 20260705-earthquake-rescue-refactor/ # 地震应急指挥重构\n├── .trae/                      # Trae IDE 规则、技能、工作流、知识库\n├── project-brief.md            # 项目概要\n└── AGENTS.md                   # AI Agent 入口导航\n```\n\n---\n\n## 四、运行环境要求\n\n| 软件 | 版本 | 用途 |\n|------|------|------|\n| JDK | 17+ | SpringBoot 后端 |\n| Maven | 3.8+ | 后端构建 |\n| Node.js | 18+ | 前端构建 |\n| npm | 9+ | 前端依赖 |\n| Python | 3.10+ | Agent 后端 |\n| MySQL | 8.0+ | 业务数据存储 |\n| SuperMap iServer | 11i (11.3.0) | GIS 服务 |\n| SuperMap iDesktopX | 2025（可选） | 数据处理/制图 |\n\n---\n\n## 五、启动前配置\n\n系统涉及 **5 个服务**（含数据库），按以下顺序配置和启动：iServer → MySQL → SpringBoot 后端 → FastAPI Agent 后端 → Vue 前端。\n\n### 5.1 SuperMap iServer 配置（端口 8090）\n\niServer 提供 GIS 数据服务、地图服务、空间分析、网络分析能力，是前端地图和 Agent 工具的数据源。\n\n#### 1) 安装并启动 iServer\n\n- 安装路径示例：`D:\\SuperMap\\SuperMapiServer11i\\`\n- 启动：进入 `bin/` 目录运行 `startup.bat`，浏览器访问 `http://localhost:8090/iserver`\n- 首次启动需设置管理员账号\n\n#### 2) 确认样本数据存在\n\niServer 11i 自带以下样本数据，位于 `D:\\SuperMap\\SuperMapiServer11i\\samples\\data\\`：\n\n| 数据文件 | 路径 | 用途 |\n|---------|------|------|\n| 京津冀数据 | `City\\Jingjin.udbx` | 基础地图、空间查询、缓冲区分析 |\n| 世界底图 | `World\\World.udbx` | 底图 |\n| 长春路网 | `NetworkAnalyst\\Changchun.udbx` | 网络分析（最短路径/服务区） |\n\n#### 3) 发布/确认服务\n\niServer 默认在 `webapps\\iserver\\WEB-INF\\iserver-services-samples.xml` 中预配置了以下服务，**首次启动后通常已自动发布**，请在 iServer 管理页面「服务」列表中确认存在：\n\n| 服务名 | 类型 | 用途 |\n|--------|------|------|\n| `map-jingjin` | 地图服务 | 京津冀地图展示 |\n| `data-jingjin` | 数据服务 | 要素查询（POI、行政区域等） |\n| `spatialanalyst-sample` | 空间分析服务 | 缓冲区分析、叠置分析 |\n| `transportationanalyst-sample` | 交通网络分析服务 | 最短路径、服务区分析 |\n\n若服务未自动发布，可在 iServer 管理页面「服务 → 创建服务」中基于上述数据源手动发布。\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8090/iserver/services`，应能看到上述服务列表。\n\n---\n\n### 5.2 MySQL 数据库配置（端口 3306）\n\n#### 1) 安装并启动 MySQL 8\n\n确保 MySQL 服务已启动，并能以 root 账号登录：\n\n```bash\nmysql -u root -p\n```\n\n#### 2) 修改后端数据库账号密码\n\n打开 `backend/src/main/resources/application.yml`，修改第 10–12 行：\n\n```yaml\nspring:\n  datasource:\n    url: jdbc:mysql://localhost:3306/emergency_db?createDatabaseIfNotExist=true&useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true\n    username: root           # ← 改为你的 MySQL 用户名\n    password: t821777        # ← 改为你的 MySQL 密码\n    driver-class-name: com.mysql.cj.jdbc.Driver\n```\n\n说明：\n- `createDatabaseIfNotExist=true`：首次启动时自动创建 `emergency_db` 数据库，无需手动建库\n- `serverTimezone=Asia/Shanghai`：时区配置，必须保留\n\n#### 3) 执行 SQL（建表 + 种子数据）\n\n**方式 A（推荐，自动执行）**：保持 `application.yml` 中以下配置不变：\n\n```yaml\nspring:\n  sql:\n    init:\n      mode: always                              # 每次启动都执行\n      schema-locations: classpath:schema.sql    # 建表（IF NOT EXISTS，幂等）\n      data-locations: classpath:data.sql        # 种子数据（INSERT IGNORE，幂等）\n      continue-on-error: false\n```\n\n启动 SpringBoot 后端时，`schema.sql`（建 3 张表）和 `data.sql`（插入 18 条种子数据）会**自动执行**，无需手动操作。\n\n**方式 B（手动执行）**：如需提前建表，可在 MySQL 客户端中执行：\n\n```bash\n# 登录 MySQL\nmysql -u root -p\n\n# 在 MySQL 命令行中执行\nCREATE DATABASE IF NOT EXISTS emergency_db DEFAULT CHARACTER SET utf8mb4;\nUSE emergency_db;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/schema.sql;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/data.sql;\nEXIT;\n```\n\n> 若已通过方式 A 自动建表，**不要再手动执行**，否则 `INSERT IGNORE` 会因主键已存在而跳过（无害但冗余）。\n\n#### 4) 数据表说明\n\n| 表名 | 说明 | 主键 |\n|------|------|------|\n| `tb_warn_info` | 气象灾害预警主表 | `warn_id` |\n| `tb_coord_response` | 协同叫应处置表 | `response_id` |\n| `tb_supply_dispatch` | 应急物资调度总表 | `dispatch_id` |\n\n---\n\n### 5.3 SpringBoot 业务后端配置（端口 8080）\n\n#### 1) 检查 iServer 配置\n\n`application.yml` 第 33–41 行已配置 iServer 服务地址，若你的 iServer 不在 `localhost:8090`，请修改：\n\n```yaml\niserver:\n  base-url: http://localhost:8090\n  data-service: data-jingjin\n  datasource: Jingjin\n  map-service: map-jingjin\n  map-name: 京津地区地图\n  spatial-service: spatialanalyst-sample\n  transport-service: transportationanalyst-sample\n```\n\n#### 2) 构建并启动\n\n```bash\ncd backend\nmvn clean package -DskipTests\njava -jar target/emergency-backend-0.0.1-SNAPSHOT.jar\n```\n\n或在 IDE 中直接运行 `EmergencyApplication.java`。\n\n#### 3) 验证\n\n浏览器访问 `http://localhost:8080/api/health`，应返回：\n\n```json\n{ \"code\": 200, \"message\": \"success\", \"data\": \"京津冀城市综合防灾应急管理系统后端运行正常\" }\n```\n\n---\n\n### 5.4 FastAPI Agent 后端配置（端口 8001）\n\nAgent 后端依赖 **大模型 API Key** 才能运行 AI 问答功能。\n\n#### 1) 创建 Python 虚拟环境并安装依赖\n\n```bash\ncd agent-backend\npython -m venv venv\n# Windows\nvenv\\Scripts\\activate\n# macOS/Linux\nsource venv/bin/activate\n\npip install -r requirements.txt\n```\n\n#### 2) 配置 API Key（必须）\n\n复制环境变量模板：\n\n```bash\ncp .env.example .env\n```\n\n编辑 `agent-backend/.env`，填入你的 API Key：\n\n```dotenv\n# LLM API 配置（硅基流动 SiliconFlow）\n# 注册地址：https://siliconflow.cn/  注册后在「API 密钥」页面创建 Key\n# 注意：变量名虽为 DEEPSEEK_API_KEY，实际填入的是硅基流动的 API Key\nDEEPSEEK_API_KEY=sk-your-siliconflow-api-key-here    # ← 改为你的真实 Key\nDEEPSEEK_BASE_URL=https://api.siliconflow.cn/v1\nDEEPSEEK_MODEL=deepseek-ai/DeepSeek-V3.2\n\n# iServer 配置（默认本机，无需修改）\nISERVER_URL=http://localhost:8090\n\n# 后端配置\nHOST=0.0.0.0\nPORT=8001\n\n# RAG 配置（与 LLM 共用 API Key，留空则自动回退到 DEEPSEEK_API_KEY）\nEMBEDDING_BASE_URL=https://api.siliconflow.cn/v1\nEMBEDDING_MODEL=BAAI/bge-m3\n```\n\n> **关于 API Key**：本项目使用硅基流动（SiliconFlow）提供的 `deepseek-ai/DeepSeek-V3.2` 模型，性价比高。注册硅基流动账号后在「API 密钥」页面创建 Key，填入 `DEEPSEEK_API_KEY`。Embedding 模型 `BAAI/bge-m3` 与 LLM 共用同一 Key，无需额外申请。\n\n#### 3) 启动\n\n```bash\n# 确保在 agent-backend/ 目录且已激活虚拟环境\npython -m app.main\n```\n\n或使用 uvicorn 热重载：\n\n```bash\nuvicorn app.main:app --host 0.0.0.0 --port 8001 --reload\n```\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8001/api/health`，应返回：\n\n```json\n{ \"status\": \"ok\", \"service\": \"gis-agent-backend\" }\n```\n\n启动日志中应看到 `RAG 知识库就绪：5 个文档已索引`（首次启动会自动构建 FAISS 向量库）。\n\n---\n\n### 5.5 Vue 前端配置（端口 5173）\n\n#### 1) 安装依赖\n\n```bash\ncd frontend\nnpm install\n```\n\n#### 2) 确认 Vite proxy 配置\n\n`vite.config.js` 已配置三组代理，默认无需修改：\n\n| 前缀 | 转发到 | 用途 |\n|------|--------|------|\n| `/iserver` | `http://localhost:8090` | iServer GIS 服务 |\n| `/api` | `http://localhost:8080` | SpringBoot 业务后端（CRUD 接口） |\n| `/agent-api` | `http://localhost:8001`（重写为 `/api`） | FastAPI Agent 后端（AI 问答接口） |\n\n若你的后端服务端口不同，请修改 `vite.config.js` 中对应的 `target`。\n\n#### 3) 启动\n\n```bash\nnpm run dev\n```\n\n浏览器访问 `http://localhost:5173`。\n\n#### 4) 前端路由一览（对应顶部导航 5 大模块 + CRUD 子页）\n\n| 导航分组 | 路由路径 | 页面 | 说明 |\n|----------|----------|------|------|\n| **数字大屏** | `/new-big-screen` | NewBigScreenView | 气象灾害监测大屏（KPI + 趋势图） |\n| **二维地图** | `/` | HomeView | 核心地图页（GIS 操作 + NavSidebar + AI 助手） |\n| | `/warn-info` | WarnInfoView | 预警主表 CRUD（NavSidebar → 数据库） |\n| | `/coord-response` | CoordResponseView | 协同处置 CRUD（NavSidebar → 数据库） |\n| | `/supply-dispatch` | SupplyDispatchView | 物资调度 CRUD（NavSidebar → 数据库） |\n| **三维洪水模拟** | `/flood-simulation` | FloodSimulationView | Cesium 3D 淹没模拟 |\n| **监测-预警-联动** | `/data-dashboard` | DataDashboardView | 综合监测评估（地图 + 灾情 + 气象） |\n| **地震指挥** | `/earthquake-command` | EarthquakeCommandView | 地震应急指挥专页 |\n\n---\n\n## 六、启动顺序速查\n\n| 顺序 | 服务 | 端口 | 启动命令 | 启动条件 |\n|------|------|------|---------|---------|\n| 1 | SuperMap iServer | 8090 | `bin/startup.bat` | 已安装并发布样本服务 |\n| 2 | MySQL | 3306 | 系统服务 | 已创建 root 账号或修改 `application.yml` |\n| 3 | SpringBoot 后端 | 8080 | `mvn spring-boot:run` | iServer + MySQL 已启动 |\n| 4 | FastAPI Agent 后端 | 8001 | `python -m app.main` | iServer 已启动 + `.env` 已配置 Key |\n| 5 | Vue 前端 | 5173 | `npm run dev` | 上述后端均已启动 |\n\n> **可选**：若不使用 AI 问答功能，可跳过第 4 步（FastAPI Agent 后端），其余模块（地图、CRUD、空间分析）仍可正常使用。\n\n---\n\n## 七、常见问题\n\n### Q1：前端打开后地图空白？\n- 检查 iServer 是否启动：访问 `http://localhost:8090/iserver`\n- 检查浏览器控制台是否有 `/iserver` 请求 404，确认服务名与 `application.yml` 一致\n\n### Q2：后端启动报数据库连接失败？\n- 确认 MySQL 服务已启动\n- 确认 `application.yml` 中 `username` / `password` 与本机 MySQL 一致\n- 确认 URL 中 `createDatabaseIfNotExist=true` 参数存在（首次启动需自动建库）\n\n### Q3：数据表未自动创建？\n- 检查 `application.yml` 中 `spring.sql.init.mode` 是否为 `always`\n- 检查 `schema.sql` / `data.sql` 是否在 `src/main/resources/` 下\n- 查看启动日志是否有 SQL 执行错误\n\n### Q4：Agent 聊天无响应或报 401？\n- 确认 `agent-backend/.env` 中 `DEEPSEEK_API_KEY` 已填写真实 Key\n- 确认 Key 余额充足（硅基流动账户）\n- 确认 `DEEPSEEK_BASE_URL` 为 `https://api.siliconflow.cn/v1`（非 DeepSeek 官方地址）\n\n### Q5：RAG 知识库初始化失败？\n- 首次启动会调用 Embedding API 构建向量库，需联网且 API Key 有效\n- 失败为非致命错误，Agent 仍可运行（仅失去知识库检索能力）\n- 重新启动时会自动重试\n\n### Q6：网络分析模块无结果？\n- 确认 `transportationanalyst-sample` 服务已在 iServer 发布\n- 确认长春路网数据 `Changchun.udbx` 存在\n- 网络分析使用长春市数据，起终点需在长春市范围内\n\n### Q7：端口被占用？\n- 8080 / 8001 / 5173 / 8090 任一被占用都会导致启动失败\n- 使用 `netstat -ano | findstr <端口>` 查看占用进程\n- 修改对应配置文件中的端口号（注意同步更新 `vite.config.js` 的 proxy target）\n\n---\n\n## 八、开发规范\n\n- AI 编码规范：见 [`.trae/rules/coding_guidelines.md`](.trae/rules/coding_guidelines.md)\n- 前端规范：见 [`.trae/rules/frontend_rules.md`](.trae/rules/frontend_rules.md)\n- 项目规范：见 [`.trae/rules/project_rules.md`](.trae/rules/project_rules.md)\n- Git 提交规范：`<type>: <描述>`，type 包括 `feat / fix / refactor / docs / style / chore`\n- 设计文档：`openspec/changes/<change-id>/` 下按 proposal → design → spec → tasks → checklist 组织\n- 单元测试：`frontend/src/utils/__tests__/` 下存放置工具函数单元测试（Vitest），含 earthquakeAhp / haversine / earthquakeNaming / generateEarthquakePoints 测试\n\n---\n\n## 九、安全说明\n\n- 本项目为课程设计，**不涉及用户认证**，前后端 API 均为公开访问\n- `application.yml` 中 MySQL 密码为明文（课设阶段可接受，生产环境应使用配置中心或环境变量）\n- `agent-backend/.env` 已在 `.gitignore` 中忽略，不会提交 API Key 到 Git 仓库\n- iServer 服务地址使用相对路径，通过 Vite proxy 转发，避免跨域\n\n---\n\n## 十、文档索引\n\n| 文档 | 说明 |\n|------|------|\n| [AGENTS.md](AGENTS.md) | AI Agent 入口导航 |\n| [project-brief.md](project-brief.md) | 项目概要：技术栈、数据资源、功能模块 |\n| `.trae/docs/workflows.md` | 角色工作流、协作流程 |\n| `openspec/changes/` | 各功能模块的设计文档与验收清单 |\n| `.trae/knowledge/INDEX.md` | 项目知识库全景图 |\n\n---\n\n## 十一、文档与实现差异说明\n\n本项目的设计文档（包括 `project-brief.md`、`openspec/changes/` 下的 proposal/design/spec/tasks/checklist、`.trae/knowledge/` 中的知识库等）反映的是**开发初期或阶段性方案设计**，并非最终实现的逐字描述。\n\n在实际开发与测试过程中，部分功能会因以下原因与原始文档产生差异：\n\n- 测试验证中发现问题后对接口字段、参数命名、业务逻辑的调整\n- 依赖库版本升级或 API 行为变化导致的实现细节调整\n- 针对 SuperMap iServer / DeepSeek / LangGraph 等外部服务的兼容性适配\n- 性能优化、Bug 修复过程中的代码重构\n\n> **若本文档（README）或其他设计文档与实际系统行为存在不一致，请以实际代码和运行系统为准。**\n\n如需了解某模块的最新实现，建议直接查阅对应的源码：\n\n- 前端组件实现：`frontend/src/components/` 与 `frontend/src/views/`\n- 后端接口实现：`backend/src/main/java/com/gis/emergency/`\n- Agent 工具实现：`agent-backend/app/agent/tools/` 与 `agent-backend/app/agent/sub_agents/`\n- 配置文件（反映真实运行参数）：`backend/src/main/resources/application.yml`、`agent-backend/.env.example`\n"}, "cd09f0faac05f2a69b6b376178ea02cc9ce244d5": {"t": 1785766215.8611352, "n": 12110, "h": "7aeee3f9a8346225", "c": "# 京津冀城市综合防灾应急管理系统\n\n基于 **Vue3 + SuperMap iClient (MapboxGL) + SpringBoot + FastAPI + LangGraph** 的 GIS 应急管理平台，集成多源空间数据可视化、空间分析、网络分析、AI 智能问答等能力。\n\n> 课程：GIS 工程应用实践 ｜ 数据处理：SuperMap iDesktopX 2025 ｜ 服务发布：SuperMap iServer 11i\n\n---\n\n## 一、功能模块\n\n| 模块 | 说明 |\n|------|------|\n| 基本地图功能 | 全幅显示、缩放平移、鹰眼、距离/面积量算、图层管理 |\n| 空间查询 | 按绘制范围（点/矩形/圆）查询 POI，结果标绘与属性弹窗 |\n| 专题检索 | 关键字查询、行政级别（省/县/乡镇）分级检索 |\n| 缓冲区与叠置分析 | 辐射范围分析、土地利用叠置分析 |\n| 网络分析 | 最短路径分析、服务区分析（基于长春路网数据） |\n| 三维洪水模拟 | 3D 场景淹没分析展示 |\n| 数据看板 | 气象灾害预警、协同叫应、物资调度三表 CRUD 管理 |\n| AI 应急助手 | 多 Agent 协同的空间问答（Coordinator + 4 子 Agent + 11 GIS 工具 + RAG 知识库） |\n| 地震应急指挥 | AHP-DDI 8 指标灾情评估（录入 → 计算 → 4 级划分），双缓冲区分析（按等级动态半径），5 步救援调度（消防/医疗/物资/避难 4 路彩色路径） |\n\n---\n\n## 二、技术栈\n\n| 层 | 技术 |\n|----|------|\n| 前端 | Vue 3.5 + Vite 8 + Ant Design Vue 4 + MapboxGL + `@supermap/iclient-mapboxgl` 11 + Pinia + Vue Router |\n| 后端（业务） | SpringBoot 3.4 + MyBatis 3 + MySQL 8（Java 17） |\n| 后端（Agent） | FastAPI + LangGraph + LangChain + DeepSeek-V3.2（硅基流动）+ FAISS |\n| GIS 服务 | SuperMap iServer 11i（地图/数据/空间分析/网络分析服务） |\n| 数据 | Jingjin.udbx / World.udbx / Changchun.udbx（iServer 自带样本数据） |\n\n---\n\n## 三、目录结构\n\n```\nGIS-Practice/\n├── frontend/              # Vue3 前端\n│   ├── src/\n│   │   ├── components/\n│   │   │   ├── dashboard/    # 数据大屏组件（DisasterDetailPanel, BufferAnalysisModal 等）\n│   │   │   ├── earthquake/   # 地震应急组件（BufferZoneLayer, SupportPointLayer, RescueDispatchPanel）\n│   │   │   ├── ...\n│   │   ├── views/         # 页面视图（含 DataDashboardView 数据大屏、EarthquakeCommandView 地震指挥）\n│   │   ├── router/        # 路由配置（/data-dashboard 数据大屏等）\n│   │   ├── stores/        # Pinia 状态管理（map / agent）\n│   │   └── utils/         # 工具函数（request, earthquakeAhp, circlePolygon, haversine 等）\n│   ├── composables/       # Vue composables（useShortestPath 路径规划）\n│   └── vite.config.js     # 含 /iserver /api /agent-api 三组 proxy\n│\n├── backend/               # SpringBoot 业务后端（CRUD + 健康检查）\n│   └── src/main/\n│       ├── java/com/gis/emergency/\n│       │   ├── controller/  # REST API（WarnInfo / CoordResponse / SupplyDispatch）\n│       │   ├── service/     # 业务层\n│       │   ├── mapper/      # MyBatis 注解式 Mapper\n│       │   ├── entity/      # 实体类\n│       │   └── config/      # CORS、全局异常处理\n│       └── resources/\n│           ├── application.yml  # 数据库 + iServer 配置\n│           ├── schema.sql       # 建表脚本（启动自动执行，幂等）\n│           └── data.sql         # 种子数据（启动自动执行，INSERT IGNORE）\n│\n├── agent-backend/         # FastAPI Agent 后端（AI 智能问答）\n│   ├── app/\n│   │   ├── agent/         # LangGraph 多 Agent 编排\n│   │   │   ├── coordinator.py  # Coordinator 调度\n│   │   │   ├── sub_agents/     # 4 个子 Agent（search/analysis/route/knowledge）\n│   │   │   └── tools/          # 11 个 GIS 工具 + 算法工具\n│   │   ├── api/           # FastAPI 路由\n│   │   ├── services/      # LLM / RAG / iServer 客户端\n│   │   └── config.py      # 配置读取（.env 优先）\n│   ├── data/knowledge/    # RAG 知识库源文档（应急预案等 markdown）\n│   ├── .env.example       # 环境变量模板（含 API Key 配置说明）\n│   └── requirements.txt\n│\n├── openspec/              # OpenSpec 设计文档（proposal/design/spec/tasks/checklist）\n├── .trae/                 # Trae IDE 规则、技能、工作流、知识库\n├── project-brief.md       # 项目概要\n└── AGENTS.md              # AI Agent 入口导航\n```\n\n---\n\n## 四、运行环境要求\n\n| 软件 | 版本 | 用途 |\n|------|------|------|\n| JDK | 17+ | SpringBoot 后端 |\n| Maven | 3.8+ | 后端构建 |\n| Node.js | 18+ | 前端构建 |\n| npm | 9+ | 前端依赖 |\n| Python | 3.10+ | Agent 后端 |\n| MySQL | 8.0+ | 业务数据存储 |\n| SuperMap iServer | 11i (11.3.0) | GIS 服务 |\n| SuperMap iDesktopX | 2025（可选） | 数据处理/制图 |\n\n---\n\n## 五、启动前配置\n\n系统涉及 **5 个服务**（含数据库），按以下顺序配置和启动：iServer → MySQL → SpringBoot 后端 → FastAPI Agent 后端 → Vue 前端。\n\n### 5.1 SuperMap iServer 配置（端口 8090）\n\niServer 提供 GIS 数据服务、地图服务、空间分析、网络分析能力，是前端地图和 Agent 工具的数据源。\n\n#### 1) 安装并启动 iServer\n\n- 安装路径示例：`D:\\SuperMap\\SuperMapiServer11i\\`\n- 启动：进入 `bin/` 目录运行 `startup.bat`，浏览器访问 `http://localhost:8090/iserver`\n- 首次启动需设置管理员账号\n\n#### 2) 确认样本数据存在\n\niServer 11i 自带以下样本数据，位于 `D:\\SuperMap\\SuperMapiServer11i\\samples\\data\\`：\n\n| 数据文件 | 路径 | 用途 |\n|---------|------|------|\n| 京津冀数据 | `City\\Jingjin.udbx` | 基础地图、空间查询、缓冲区分析 |\n| 世界底图 | `World\\World.udbx` | 底图 |\n| 长春路网 | `NetworkAnalyst\\Changchun.udbx` | 网络分析（最短路径/服务区） |\n\n#### 3) 发布/确认服务\n\niServer 默认在 `webapps\\iserver\\WEB-INF\\iserver-services-samples.xml` 中预配置了以下服务，**首次启动后通常已自动发布**，请在 iServer 管理页面「服务」列表中确认存在：\n\n| 服务名 | 类型 | 用途 |\n|--------|------|------|\n| `map-jingjin` | 地图服务 | 京津冀地图展示 |\n| `data-jingjin` | 数据服务 | 要素查询（POI、行政区域等） |\n| `spatialanalyst-sample` | 空间分析服务 | 缓冲区分析、叠置分析 |\n| `transportationanalyst-sample` | 交通网络分析服务 | 最短路径、服务区分析 |\n\n若服务未自动发布，可在 iServer 管理页面「服务 → 创建服务」中基于上述数据源手动发布。\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8090/iserver/services`，应能看到上述服务列表。\n\n---\n\n### 5.2 MySQL 数据库配置（端口 3306）\n\n#### 1) 安装并启动 MySQL 8\n\n确保 MySQL 服务已启动，并能以 root 账号登录：\n\n```bash\nmysql -u root -p\n```\n\n#### 2) 修改后端数据库账号密码\n\n打开 `backend/src/main/resources/application.yml`，修改第 10–12 行：\n\n```yaml\nspring:\n  datasource:\n    url: jdbc:mysql://localhost:3306/emergency_db?createDatabaseIfNotExist=true&useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true\n    username: root           # ← 改为你的 MySQL 用户名\n    password: t821777        # ← 改为你的 MySQL 密码\n    driver-class-name: com.mysql.cj.jdbc.Driver\n```\n\n说明：\n- `createDatabaseIfNotExist=true`：首次启动时自动创建 `emergency_db` 数据库，无需手动建库\n- `serverTimezone=Asia/Shanghai`：时区配置，必须保留\n\n#### 3) 执行 SQL（建表 + 种子数据）\n\n**方式 A（推荐，自动执行）**：保持 `application.yml` 中以下配置不变：\n\n```yaml\nspring:\n  sql:\n    init:\n      mode: always                              # 每次启动都执行\n      schema-locations: classpath:schema.sql    # 建表（IF NOT EXISTS，幂等）\n      data-locations: classpath:data.sql        # 种子数据（INSERT IGNORE，幂等）\n      continue-on-error: false\n```\n\n启动 SpringBoot 后端时，`schema.sql`（建 3 张表）和 `data.sql`（插入 18 条种子数据）会**自动执行**，无需手动操作。\n\n**方式 B（手动执行）**：如需提前建表，可在 MySQL 客户端中执行：\n\n```bash\n# 登录 MySQL\nmysql -u root -p\n\n# 在 MySQL 命令行中执行\nCREATE DATABASE IF NOT EXISTS emergency_db DEFAULT CHARACTER SET utf8mb4;\nUSE emergency_db;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/schema.sql;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/data.sql;\nEXIT;\n```\n\n> 若已通过方式 A 自动建表，**不要再手动执行**，否则 `INSERT IGNORE` 会因主键已存在而跳过（无害但冗余）。\n\n#### 4) 数据表说明\n\n| 表名 | 说明 | 主键 |\n|------|------|------|\n| `tb_warn_info` | 气象灾害预警主表 | `warn_id` |\n| `tb_coord_response` | 协同叫应处置表 | `response_id` |\n| `tb_supply_dispatch` | 应急物资调度总表 | `dispatch_id` |\n\n---\n\n### 5.3 SpringBoot 业务后端配置（端口 8080）\n\n#### 1) 检查 iServer 配置\n\n`application.yml` 第 33–41 行已配置 iServer 服务地址，若你的 iServer 不在 `localhost:8090`，请修改：\n\n```yaml\niserver:\n  base-url: http://localhost:8090\n  data-service: data-jingjin\n  datasource: Jingjin\n  map-service: map-jingjin\n  map-name: 京津地区地图\n  spatial-service: spatialanalyst-sample\n  transport-service: transportationanalyst-sample\n```\n\n#### 2) 构建并启动\n\n```bash\ncd backend\nmvn clean package -DskipTests\njava -jar target/emergency-backend-0.0.1-SNAPSHOT.jar\n```\n\n或在 IDE 中直接运行 `EmergencyApplication.java`。\n\n#### 3) 验证\n\n浏览器访问 `http://localhost:8080/api/health`，应返回：\n\n```json\n{ \"code\": 200, \"message\": \"success\", \"data\": \"京津冀城市综合防灾应急管理系统后端运行正常\" }\n```\n\n---\n\n### 5.4 FastAPI Agent 后端配置（端口 8001）\n\nAgent 后端依赖 **大模型 API Key** 才能运行 AI 问答功能。\n\n#### 1) 创建 Python 虚拟环境并安装依赖\n\n```bash\ncd agent-backend\npython -m venv venv\n# Windows\nvenv\\Scripts\\activate\n# macOS/Linux\nsource venv/bin/activate\n\npip install -r requirements.txt\n```\n\n#### 2) 配置 API Key（必须）\n\n复制环境变量模板：\n\n```bash\ncp .env.example .env\n```\n\n编辑 `agent-backend/.env`，填入你的 API Key：\n\n```dotenv\n# LLM API 配置（硅基流动 SiliconFlow）\n# 注册地址：https://siliconflow.cn/  注册后在「API 密钥」页面创建 Key\n# 注意：变量名虽为 DEEPSEEK_API_KEY，实际填入的是硅基流动的 API Key\nDEEPSEEK_API_KEY=sk-your-siliconflow-api-key-here    # ← 改为你的真实 Key\nDEEPSEEK_BASE_URL=https://api.siliconflow.cn/v1\nDEEPSEEK_MODEL=deepseek-ai/DeepSeek-V3.2\n\n# iServer 配置（默认本机，无需修改）\nISERVER_URL=http://localhost:8090\n\n# 后端配置\nHOST=0.0.0.0\nPORT=8001\n\n# RAG 配置（与 LLM 共用 API Key，留空则自动回退到 DEEPSEEK_API_KEY）\nEMBEDDING_BASE_URL=https://api.siliconflow.cn/v1\nEMBEDDING_MODEL=BAAI/bge-m3\n```\n\n> **关于 API Key**：本项目使用硅基流动（SiliconFlow）提供的 `deepseek-ai/DeepSeek-V3.2` 模型，性价比高。注册硅基流动账号后在「API 密钥」页面创建 Key，填入 `DEEPSEEK_API_KEY`。Embedding 模型 `BAAI/bge-m3` 与 LLM 共用同一 Key，无需额外申请。\n\n#### 3) 启动\n\n```bash\n# 确保在 agent-backend/ 目录且已激活虚拟环境\npython -m app.main\n```\n\n或使用 uvicorn 热重载：\n\n```bash\nuvicorn app.main:app --host 0.0.0.0 --port 8001 --reload\n```\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8001/api/health`，应返回：\n\n```json\n{ \"status\": \"ok\", \"service\": \"gis-agent-backend\" }\n```\n\n启动日志中应看到 `RAG 知识库就绪：5 个文档已索引`（首次启动会自动构建 FAISS 向量库）。\n\n---\n\n### 5.5 Vue 前端配置（端口 5173）\n\n#### 1) 安装依赖\n\n```bash\ncd frontend\nnpm install\n```\n\n#### 2) 确认 Vite proxy 配置\n\n`vite.config.js` 已配置三组代理，默认无需修改：\n\n| 前缀 | 转发到 | 用途 |\n|------|--------|------|\n| `/iserver` | `http://localhost:8090` | iServer GIS 服务 |\n| `/api` | `http://localhost:8080` | SpringBoot 业务后端 |\n| `/agent-api` | `http://localhost:8001`（重写为 `/api`） | FastAPI Agent 后端 |\n\n若你的后端服务端口不同，请修改 `vite.config.js` 中对应的 `target`。\n\n#### 3) 启动\n\n```bash\nnpm run dev\n```\n\n浏览器访问 `http://localhost:5173`。\n\n---\n\n## 六、启动顺序速查\n\n| 顺序 | 服务 | 端口 | 启动命令 | 启动条件 |\n|------|------|------|---------|---------|\n| 1 | SuperMap iServer | 8090 | `bin/startup.bat` | 已安装并发布样本服务 |\n| 2 | MySQL | 3306 | 系统服务 | 已创建 root 账号或修改 `application.yml` |\n| 3 | SpringBoot 后端 | 8080 | `mvn spring-boot:run` | iServer + MySQL 已启动 |\n| 4 | FastAPI Agent 后端 | 8001 | `python -m app.main` | iServer 已启动 + `.env` 已配置 Key |\n| 5 | Vue 前端 | 5173 | `npm run dev` | 上述后端均已启动 |\n\n> **可选**：若不使用 AI 问答功能，可跳过第 4 步（FastAPI Agent 后端），其余模块（地图、CRUD、空间分析）仍可正常使用。\n\n---\n\n## 七、常见问题\n\n### Q1：前端打开后地图空白？\n- 检查 iServer 是否启动：访问 `http://localhost:8090/iserver`\n- 检查浏览器控制台是否有 `/iserver` 请求 404，确认服务名与 `application.yml` 一致\n\n### Q2：后端启动报数据库连接失败？\n- 确认 MySQL 服务已启动\n- 确认 `application.yml` 中 `username` / `password` 与本机 MySQL 一致\n- 确认 URL 中 `createDatabaseIfNotExist=true` 参数存在（首次启动需自动建库）\n\n### Q3：数据表未自动创建？\n- 检查 `application.yml` 中 `spring.sql.init.mode` 是否为 `always`\n- 检查 `schema.sql` / `data.sql` 是否在 `src/main/resources/` 下\n- 查看启动日志是否有 SQL 执行错误\n\n### Q4：Agent 聊天无响应或报 401？\n- 确认 `agent-backend/.env` 中 `DEEPSEEK_API_KEY` 已填写真实 Key\n- 确认 Key 余额充足（硅基流动账户）\n- 确认 `DEEPSEEK_BASE_URL` 为 `https://api.siliconflow.cn/v1`（非 DeepSeek 官方地址）\n\n### Q5：RAG 知识库初始化失败？\n- 首次启动会调用 Embedding API 构建向量库，需联网且 API Key 有效\n- 失败为非致命错误，Agent 仍可运行（仅失去知识库检索能力）\n- 重新启动时会自动重试\n\n### Q6：网络分析模块无结果？\n- 确认 `transportationanalyst-sample` 服务已在 iServer 发布\n- 确认长春路网数据 `Changchun.udbx` 存在\n- 网络分析使用长春市数据，起终点需在长春市范围内\n\n### Q7：端口被占用？\n- 8080 / 8001 / 5173 / 8090 任一被占用都会导致启动失败\n- 使用 `netstat -ano | findstr <端口>` 查看占用进程\n- 修改对应配置文件中的端口号（注意同步更新 `vite.config.js` 的 proxy target）\n\n---\n\n## 八、开发规范\n\n- AI 编码规范：见 [`.trae/rules/coding_guidelines.md`](.trae/rules/coding_guidelines.md)\n- 前端规范：见 [`.trae/rules/frontend_rules.md`](.trae/rules/frontend_rules.md)\n- 项目规范：见 [`.trae/rules/project_rules.md`](.trae/rules/project_rules.md)\n- Git 提交规范：`<type>: <描述>`，type 包括 `feat / fix / refactor / docs / style / chore`\n- 设计文档：`openspec/changes/<change-id>/` 下按 proposal → design → spec → tasks → checklist 组织\n\n---\n\n## 九、安全说明\n\n- 本项目为课程设计，**不涉及用户认证**，前后端 API 均为公开访问\n- `application.yml` 中 MySQL 密码为明文（课设阶段可接受，生产环境应使用配置中心或环境变量）\n- `agent-backend/.env` 已在 `.gitignore` 中忽略，不会提交 API Key 到 Git 仓库\n- iServer 服务地址使用相对路径，通过 Vite proxy 转发，避免跨域\n\n---\n\n## 十、文档索引\n\n| 文档 | 说明 |\n|------|------|\n| [AGENTS.md](AGENTS.md) | AI Agent 入口导航 |\n| [project-brief.md](project-brief.md) | 项目概要：技术栈、数据资源、功能模块 |\n| `.trae/docs/workflows.md` | 角色工作流、协作流程 |\n| `openspec/changes/` | 各功能模块的设计文档与验收清单 |\n| `.trae/knowledge/INDEX.md` | 项目知识库全景图 |\n\n---\n\n## 十一、文档与实现差异说明\n\n本项目的设计文档（包括 `project-brief.md`、`openspec/changes/` 下的 proposal/design/spec/tasks/checklist、`.trae/knowledge/` 中的知识库等）反映的是**开发初期或阶段性方案设计**，并非最终实现的逐字描述。\n\n在实际开发与测试过程中，部分功能会因以下原因与原始文档产生差异：\n\n- 测试验证中发现问题后对接口字段、参数命名、业务逻辑的调整\n- 依赖库版本升级或 API 行为变化导致的实现细节调整\n- 针对 SuperMap iServer / DeepSeek / LangGraph 等外部服务的兼容性适配\n- 性能优化、Bug 修复过程中的代码重构\n\n> **若本文档（README）或其他设计文档与实际系统行为存在不一致，请以实际代码和运行系统为准。**\n\n如需了解某模块的最新实现，建议直接查阅对应的源码：\n\n- 前端组件实现：`frontend/src/components/` 与 `frontend/src/views/`\n- 后端接口实现：`backend/src/main/java/com/gis/emergency/`\n- Agent 工具实现：`agent-backend/app/agent/tools/` 与 `agent-backend/app/agent/sub_agents/`\n- 配置文件（反映真实运行参数）：`backend/src/main/resources/application.yml`、`agent-backend/.env.example`\n"}, "967182bd069f753eed78bcc66568bb6fcdd959e7": {"t": 1785766218.7333386, "n": 11673, "h": "506dd6739147dabf", "c": "# 京津冀城市综合防灾应急管理系统\n\n基于 **Vue3 + SuperMap iClient (MapboxGL) + SpringBoot + FastAPI + LangGraph** 的 GIS 应急管理平台，集成多源空间数据可视化、空间分析、网络分析、AI 智能问答等能力。\n\n> 课程：GIS 工程应用实践 ｜ 数据处理：SuperMap iDesktopX 2025 ｜ 服务发布：SuperMap iServer 11i\n\n---\n\n## 一、功能模块\n\n| 模块 | 说明 |\n|------|------|\n| 基本地图功能 | 全幅显示、缩放平移、鹰眼、距离/面积量算、图层管理 |\n| 空间查询 | 按绘制范围（点/矩形/圆）查询 POI，结果标绘与属性弹窗 |\n| 专题检索 | 关键字查询、行政级别（省/县/乡镇）分级检索 |\n| 缓冲区与叠置分析 | 辐射范围分析、土地利用叠置分析 |\n| 网络分析 | 最短路径分析、服务区分析（基于长春路网数据） |\n| 三维洪水模拟 | 3D 场景淹没分析展示 |\n| 数据看板 | 气象灾害预警、协同叫应、物资调度三表 CRUD 管理 |\n| AI 应急助手 | 多 Agent 协同的空间问答（Coordinator + 4 子 Agent + 11 GIS 工具 + RAG 知识库） |\n\n---\n\n## 二、技术栈\n\n| 层 | 技术 |\n|----|------|\n| 前端 | Vue 3.5 + Vite 8 + Ant Design Vue 4 + MapboxGL + `@supermap/iclient-mapboxgl` 11 + Pinia + Vue Router |\n| 后端（业务） | SpringBoot 3.4 + MyBatis 3 + MySQL 8（Java 17） |\n| 后端（Agent） | FastAPI + LangGraph + LangChain + DeepSeek-V3.2（硅基流动）+ FAISS |\n| GIS 服务 | SuperMap iServer 11i（地图/数据/空间分析/网络分析服务） |\n| 数据 | Jingjin.udbx / World.udbx / Changchun.udbx（iServer 自带样本数据） |\n\n---\n\n## 三、目录结构\n\n```\nGIS-Practice/\n├── frontend/              # Vue3 前端\n│   ├── src/\n│   │   ├── components/    # 功能组件（地图、Agent 聊天、分析面板等）\n│   │   ├── views/         # 页面视图（路由级别）\n│   │   ├── router/        # 路由配置\n│   │   ├── stores/        # Pinia 状态管理（map / agent）\n│   │   └── utils/         # 工具函数（请求、SSE、地图渲染等）\n│   └── vite.config.js     # 含 /iserver /api /agent-api 三组 proxy\n│\n├── backend/               # SpringBoot 业务后端（CRUD + 健康检查）\n│   └── src/main/\n│       ├── java/com/gis/emergency/\n│       │   ├── controller/  # REST API（WarnInfo / CoordResponse / SupplyDispatch）\n│       │   ├── service/     # 业务层\n│       │   ├── mapper/      # MyBatis 注解式 Mapper\n│       │   ├── entity/      # 实体类\n│       │   └── config/      # CORS、全局异常处理\n│       └── resources/\n│           ├── application.yml  # 数据库 + iServer 配置\n│           ├── schema.sql       # 建表脚本（启动自动执行，幂等）\n│           └── data.sql         # 种子数据（启动自动执行，INSERT IGNORE）\n│\n├── agent-backend/         # FastAPI Agent 后端（AI 智能问答）\n│   ├── app/\n│   │   ├── agent/         # LangGraph 多 Agent 编排\n│   │   │   ├── coordinator.py  # Coordinator 调度\n│   │   │   ├── sub_agents/     # 4 个子 Agent（search/analysis/route/knowledge）\n│   │   │   └── tools/          # 11 个 GIS 工具 + 算法工具\n│   │   ├── api/           # FastAPI 路由\n│   │   ├── services/      # LLM / RAG / iServer 客户端\n│   │   └── config.py      # 配置读取（.env 优先）\n│   ├── data/knowledge/    # RAG 知识库源文档（应急预案等 markdown）\n│   ├── .env.example       # 环境变量模板（含 API Key 配置说明）\n│   └── requirements.txt\n│\n├── openspec/              # OpenSpec 设计文档（proposal/design/spec/tasks/checklist）\n├── .trae/                 # Trae IDE 规则、技能、工作流、知识库\n├── project-brief.md       # 项目概要\n└── AGENTS.md              # AI Agent 入口导航\n```\n\n---\n\n## 四、运行环境要求\n\n| 软件 | 版本 | 用途 |\n|------|------|------|\n| JDK | 17+ | SpringBoot 后端 |\n| Maven | 3.8+ | 后端构建 |\n| Node.js | 18+ | 前端构建 |\n| npm | 9+ | 前端依赖 |\n| Python | 3.10+ | Agent 后端 |\n| MySQL | 8.0+ | 业务数据存储 |\n| SuperMap iServer | 11i (11.3.0) | GIS 服务 |\n| SuperMap iDesktopX | 2025（可选） | 数据处理/制图 |\n\n---\n\n## 五、启动前配置\n\n系统涉及 **5 个服务**（含数据库），按以下顺序配置和启动：iServer → MySQL → SpringBoot 后端 → FastAPI Agent 后端 → Vue 前端。\n\n### 5.1 SuperMap iServer 配置（端口 8090）\n\niServer 提供 GIS 数据服务、地图服务、空间分析、网络分析能力，是前端地图和 Agent 工具的数据源。\n\n#### 1) 安装并启动 iServer\n\n- 安装路径示例：`D:\\SuperMap\\SuperMapiServer11i\\`\n- 启动：进入 `bin/` 目录运行 `startup.bat`，浏览器访问 `http://localhost:8090/iserver`\n- 首次启动需设置管理员账号\n\n#### 2) 确认样本数据存在\n\niServer 11i 自带以下样本数据，位于 `D:\\SuperMap\\SuperMapiServer11i\\samples\\data\\`：\n\n| 数据文件 | 路径 | 用途 |\n|---------|------|------|\n| 京津冀数据 | `City\\Jingjin.udbx` | 基础地图、空间查询、缓冲区分析 |\n| 世界底图 | `World\\World.udbx` | 底图 |\n| 长春路网 | `NetworkAnalyst\\Changchun.udbx` | 网络分析（最短路径/服务区） |\n\n#### 3) 发布/确认服务\n\niServer 默认在 `webapps\\iserver\\WEB-INF\\iserver-services-samples.xml` 中预配置了以下服务，**首次启动后通常已自动发布**，请在 iServer 管理页面「服务」列表中确认存在：\n\n| 服务名 | 类型 | 用途 |\n|--------|------|------|\n| `map-jingjin` | 地图服务 | 京津冀地图展示 |\n| `data-jingjin` | 数据服务 | 要素查询（POI、行政区域等） |\n| `spatialanalyst-sample` | 空间分析服务 | 缓冲区分析、叠置分析 |\n| `transportationanalyst-sample` | 交通网络分析服务 | 最短路径、服务区分析 |\n\n若服务未自动发布，可在 iServer 管理页面「服务 → 创建服务」中基于上述数据源手动发布。\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8090/iserver/services`，应能看到上述服务列表。\n\n---\n\n### 5.2 MySQL 数据库配置（端口 3306）\n\n#### 1) 安装并启动 MySQL 8\n\n确保 MySQL 服务已启动，并能以 root 账号登录：\n\n```bash\nmysql -u root -p\n```\n\n#### 2) 修改后端数据库账号密码\n\n打开 `backend/src/main/resources/application.yml`，修改第 10–12 行：\n\n```yaml\nspring:\n  datasource:\n    url: jdbc:mysql://localhost:3306/emergency_db?createDatabaseIfNotExist=true&useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true\n    username: root           # ← 改为你的 MySQL 用户名\n    password: t821777        # ← 改为你的 MySQL 密码\n    driver-class-name: com.mysql.cj.jdbc.Driver\n```\n\n说明：\n- `createDatabaseIfNotExist=true`：首次启动时自动创建 `emergency_db` 数据库，无需手动建库\n- `serverTimezone=Asia/Shanghai`：时区配置，必须保留\n\n#### 3) 执行 SQL（建表 + 种子数据）\n\n**方式 A（推荐，自动执行）**：保持 `application.yml` 中以下配置不变：\n\n```yaml\nspring:\n  sql:\n    init:\n      mode: always                              # 每次启动都执行\n      schema-locations: classpath:schema.sql    # 建表（IF NOT EXISTS，幂等）\n      data-locations: classpath:data.sql        # 种子数据（INSERT IGNORE，幂等）\n      continue-on-error: false\n```\n\n启动 SpringBoot 后端时，`schema.sql`（建 3 张表）和 `data.sql`（插入 18 条种子数据）会**自动执行**，无需手动操作。\n\n**方式 B（手动执行）**：如需提前建表，可在 MySQL 客户端中执行：\n\n```bash\n# 登录 MySQL\nmysql -u root -p\n\n# 在 MySQL 命令行中执行\nCREATE DATABASE IF NOT EXISTS emergency_db DEFAULT CHARACTER SET utf8mb4;\nUSE emergency_db;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/schema.sql;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/data.sql;\nEXIT;\n```\n\n> 若已通过方式 A 自动建表，**不要再手动执行**，否则 `INSERT IGNORE` 会因主键已存在而跳过（无害但冗余）。\n\n#### 4) 数据表说明\n\n| 表名 | 说明 | 主键 |\n|------|------|------|\n| `tb_warn_info` | 气象灾害预警主表 | `warn_id` |\n| `tb_coord_response` | 协同叫应处置表 | `response_id` |\n| `tb_supply_dispatch` | 应急物资调度总表 | `dispatch_id` |\n\n---\n\n### 5.3 SpringBoot 业务后端配置（端口 8080）\n\n#### 1) 检查 iServer 配置\n\n`application.yml` 第 33–41 行已配置 iServer 服务地址，若你的 iServer 不在 `localhost:8090`，请修改：\n\n```yaml\niserver:\n  base-url: http://localhost:8090\n  data-service: data-jingjin\n  datasource: Jingjin\n  map-service: map-jingjin\n  map-name: 京津地区地图\n  spatial-service: spatialanalyst-sample\n  transport-service: transportationanalyst-sample\n```\n\n#### 2) 构建并启动\n\n```bash\ncd backend\nmvn clean package -DskipTests\njava -jar target/emergency-backend-0.0.1-SNAPSHOT.jar\n```\n\n或在 IDE 中直接运行 `EmergencyApplication.java`。\n\n#### 3) 验证\n\n浏览器访问 `http://localhost:8080/api/health`，应返回：\n\n```json\n{ \"code\": 200, \"message\": \"success\", \"data\": \"京津冀城市综合防灾应急管理系统后端运行正常\" }\n```\n\n---\n\n### 5.4 FastAPI Agent 后端配置（端口 8001）\n\nAgent 后端依赖 **大模型 API Key** 才能运行 AI 问答功能。\n\n#### 1) 创建 Python 虚拟环境并安装依赖\n\n```bash\ncd agent-backend\npython -m venv venv\n# Windows\nvenv\\Scripts\\activate\n# macOS/Linux\nsource venv/bin/activate\n\npip install -r requirements.txt\n```\n\n#### 2) 配置 API Key（必须）\n\n复制环境变量模板：\n\n```bash\ncp .env.example .env\n```\n\n编辑 `agent-backend/.env`，填入你的 API Key：\n\n```dotenv\n# LLM API 配置（硅基流动 SiliconFlow）\n# 注册地址：https://siliconflow.cn/  注册后在「API 密钥」页面创建 Key\n# 注意：变量名虽为 DEEPSEEK_API_KEY，实际填入的是硅基流动的 API Key\nDEEPSEEK_API_KEY=sk-your-siliconflow-api-key-here    # ← 改为你的真实 Key\nDEEPSEEK_BASE_URL=https://api.siliconflow.cn/v1\nDEEPSEEK_MODEL=deepseek-ai/DeepSeek-V3.2\n\n# iServer 配置（默认本机，无需修改）\nISERVER_URL=http://localhost:8090\n\n# 后端配置\nHOST=0.0.0.0\nPORT=8001\n\n# RAG 配置（与 LLM 共用 API Key，留空则自动回退到 DEEPSEEK_API_KEY）\nEMBEDDING_BASE_URL=https://api.siliconflow.cn/v1\nEMBEDDING_MODEL=BAAI/bge-m3\n```\n\n> **关于 API Key**：本项目使用硅基流动（SiliconFlow）提供的 `deepseek-ai/DeepSeek-V3.2` 模型，性价比高。注册硅基流动账号后在「API 密钥」页面创建 Key，填入 `DEEPSEEK_API_KEY`。Embedding 模型 `BAAI/bge-m3` 与 LLM 共用同一 Key，无需额外申请。\n\n#### 3) 启动\n\n```bash\n# 确保在 agent-backend/ 目录且已激活虚拟环境\npython -m app.main\n```\n\n或使用 uvicorn 热重载：\n\n```bash\nuvicorn app.main:app --host 0.0.0.0 --port 8001 --reload\n```\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8001/api/health`，应返回：\n\n```json\n{ \"status\": \"ok\", \"service\": \"gis-agent-backend\" }\n```\n\n启动日志中应看到 `RAG 知识库就绪：5 个文档已索引`（首次启动会自动构建 FAISS 向量库）。\n\n---\n\n### 5.5 Vue 前端配置（端口 5173）\n\n#### 1) 安装依赖\n\n```bash\ncd frontend\nnpm install\n```\n\n#### 2) 确认 Vite proxy 配置\n\n`vite.config.js` 已配置三组代理，默认无需修改：\n\n| 前缀 | 转发到 | 用途 |\n|------|--------|------|\n| `/iserver` | `http://localhost:8090` | iServer GIS 服务 |\n| `/api` | `http://localhost:8080` | SpringBoot 业务后端 |\n| `/agent-api` | `http://localhost:8001`（重写为 `/api`） | FastAPI Agent 后端 |\n\n若你的后端服务端口不同，请修改 `vite.config.js` 中对应的 `target`。\n\n#### 3) 启动\n\n```bash\nnpm run dev\n```\n\n浏览器访问 `http://localhost:5173`。\n\n---\n\n## 六、启动顺序速查\n\n| 顺序 | 服务 | 端口 | 启动命令 | 启动条件 |\n|------|------|------|---------|---------|\n| 1 | SuperMap iServer | 8090 | `bin/startup.bat` | 已安装并发布样本服务 |\n| 2 | MySQL | 3306 | 系统服务 | 已创建 root 账号或修改 `application.yml` |\n| 3 | SpringBoot 后端 | 8080 | `mvn spring-boot:run` | iServer + MySQL 已启动 |\n| 4 | FastAPI Agent 后端 | 8001 | `python -m app.main` | iServer 已启动 + `.env` 已配置 Key |\n| 5 | Vue 前端 | 5173 | `npm run dev` | 上述后端均已启动 |\n\n> **可选**：若不使用 AI 问答功能，可跳过第 4 步（FastAPI Agent 后端），其余模块（地图、CRUD、空间分析）仍可正常使用。\n\n---\n\n## 七、常见问题\n\n### Q1：前端打开后地图空白？\n- 检查 iServer 是否启动：访问 `http://localhost:8090/iserver`\n- 检查浏览器控制台是否有 `/iserver` 请求 404，确认服务名与 `application.yml` 一致\n\n### Q2：后端启动报数据库连接失败？\n- 确认 MySQL 服务已启动\n- 确认 `application.yml` 中 `username` / `password` 与本机 MySQL 一致\n- 确认 URL 中 `createDatabaseIfNotExist=true` 参数存在（首次启动需自动建库）\n\n### Q3：数据表未自动创建？\n- 检查 `application.yml` 中 `spring.sql.init.mode` 是否为 `always`\n- 检查 `schema.sql` / `data.sql` 是否在 `src/main/resources/` 下\n- 查看启动日志是否有 SQL 执行错误\n\n### Q4：Agent 聊天无响应或报 401？\n- 确认 `agent-backend/.env` 中 `DEEPSEEK_API_KEY` 已填写真实 Key\n- 确认 Key 余额充足（硅基流动账户）\n- 确认 `DEEPSEEK_BASE_URL` 为 `https://api.siliconflow.cn/v1`（非 DeepSeek 官方地址）\n\n### Q5：RAG 知识库初始化失败？\n- 首次启动会调用 Embedding API 构建向量库，需联网且 API Key 有效\n- 失败为非致命错误，Agent 仍可运行（仅失去知识库检索能力）\n- 重新启动时会自动重试\n\n### Q6：网络分析模块无结果？\n- 确认 `transportationanalyst-sample` 服务已在 iServer 发布\n- 确认长春路网数据 `Changchun.udbx` 存在\n- 网络分析使用长春市数据，起终点需在长春市范围内\n\n### Q7：端口被占用？\n- 8080 / 8001 / 5173 / 8090 任一被占用都会导致启动失败\n- 使用 `netstat -ano | findstr <端口>` 查看占用进程\n- 修改对应配置文件中的端口号（注意同步更新 `vite.config.js` 的 proxy target）\n\n---\n\n## 八、开发规范\n\n- AI 编码规范：见 [`.trae/rules/coding_guidelines.md`](.trae/rules/coding_guidelines.md)\n- 前端规范：见 [`.trae/rules/frontend_rules.md`](.trae/rules/frontend_rules.md)\n- 项目规范：见 [`.trae/rules/project_rules.md`](.trae/rules/project_rules.md)\n- Git 提交规范：`<type>: <描述>`，type 包括 `feat / fix / refactor / docs / style / chore`\n- 设计文档：`openspec/changes/<change-id>/` 下按 proposal → design → spec → tasks → checklist 组织\n\n---\n\n## 九、安全说明\n\n- 本项目为课程设计，**不涉及用户认证**，前后端 API 均为公开访问\n- `application.yml` 中 MySQL 密码为明文（课设阶段可接受，生产环境应使用配置中心或环境变量）\n- `agent-backend/.env` 已在 `.gitignore` 中忽略，不会提交 API Key 到 Git 仓库\n- iServer 服务地址使用相对路径，通过 Vite proxy 转发，避免跨域\n\n---\n\n## 十、文档索引\n\n| 文档 | 说明 |\n|------|------|\n| [AGENTS.md](AGENTS.md) | AI Agent 入口导航 |\n| [project-brief.md](project-brief.md) | 项目概要：技术栈、数据资源、功能模块 |\n| `.trae/docs/workflows.md` | 角色工作流、协作流程 |\n| `openspec/changes/` | 各功能模块的设计文档与验收清单 |\n| `.trae/knowledge/INDEX.md` | 项目知识库全景图 |\n\n---\n\n## 十一、文档与实现差异说明\n\n本项目的设计文档（包括 `project-brief.md`、`openspec/changes/` 下的 proposal/design/spec/tasks/checklist、`.trae/knowledge/` 中的知识库等）反映的是**开发初期或阶段性方案设计**，并非最终实现的逐字描述。\n\n在实际开发与测试过程中，部分功能会因以下原因与原始文档产生差异：\n\n- 测试验证中发现问题后对接口字段、参数命名、业务逻辑的调整\n- 依赖库版本升级或 API 行为变化导致的实现细节调整\n- 针对 SuperMap iServer / DeepSeek / LangGraph 等外部服务的兼容性适配\n- 性能优化、Bug 修复过程中的代码重构\n\n> **若本文档（README）或其他设计文档与实际系统行为存在不一致，请以实际代码和运行系统为准。**\n\n如需了解某模块的最新实现，建议直接查阅对应的源码：\n\n- 前端组件实现：`frontend/src/components/` 与 `frontend/src/views/`\n- 后端接口实现：`backend/src/main/java/com/gis/emergency/`\n- Agent 工具实现：`agent-backend/app/agent/tools/` 与 `agent-backend/app/agent/sub_agents/`\n- 配置文件（反映真实运行参数）：`backend/src/main/resources/application.yml`、`agent-backend/.env.example`\n"}, "f15f3962fe1c4c9e74851b061ecaf9a6fd792cc7": {"t": 1786068477.4336102, "n": 18252, "h": "858218d16671a0b6", "c": "# 京津冀城市综合防灾应急管理系统\n\n基于 **Vue3 + SuperMap iClient (MapboxGL) + SpringBoot + FastAPI + LangGraph** 的 GIS 应急管理平台，集成多源空间数据可视化、空间分析、网络分析、AI 智能问答等能力。\n\n> 课程：GIS 工程应用实践 ｜ 数据处理：SuperMap iDesktopX 2025 ｜ 服务发布：SuperMap iServer 11i\n\n---\n\n## 一、功能模块\n\n系统按顶部导航分为 **5 大模块**：\n\n### 1. 数字大屏 `/new-big-screen`\n**气象灾害监测大屏**（NewBigScreenView），面向值班人员实时监控天气态势。\n- **KPI 指标卡**：大风强度（级）、降雨深度（mm）、温度（℃）、湿度（%），超阈值自动高亮警告\n- **气象趋势图**：过去 24h 风力/降雨/温度折线图\n- **系统状态**：实时时钟、运行状态指示灯\n\n### 2. 二维地图 `/`\n**系统核心主页面**（HomeView + SmMapViewer），集成 GIS 操作、数据管理与 AI 问答。左侧 NavSidebar 提供功能入口：\n\n#### 2.1 基础 GIS 操作（左侧工具栏，地图内嵌组件）\n| 功能 | 组件 | 说明 |\n|------|------|------|\n| 地图工具 | MapToolbar | 全幅显示、放大、缩小、平移 |\n| 鹰眼视图 | MapOverview | 小地图概览，拖拽快速定位 |\n| 量算工具 | MapMeasure | 距离量算、面积量算 |\n| 图层管理 | LayerManager | 控制各图层显隐与透明度 |\n| 空间查询 | SpatialQuery | 绘制点/矩形/圆查询 POI，结果标绘 + 属性弹窗 |\n| 专题检索 | FeatureSearch | 关键字搜索地物、行政级别（省/县/乡镇）分级检索 |\n| 缓冲区与叠置分析 | SpatialAnalysis | 缓冲区辐射范围分析、土地利用叠置分析 |\n| 网络分析 | NetworkAnalysis | 最短路径分析、服务区分析（基于长春路网数据） |\n\n#### 2.2 数据库 CRUD 管理（NavSidebar → \"数据库\"分组 → 独立路由页面）\n| 功能 | 路由 | 页面 | 表 |\n|------|------|------|----|\n| 预警主表 | `/warn-info` | WarnInfoView | `tb_warn_info` — 气象灾害预警录入/编辑/查询/删除 |\n| 协同处置 | `/coord-response` | CoordResponseView | `tb_coord_response` — 协同叫应记录管理 |\n| 物资调度 | `/supply-dispatch` | SupplyDispatchView | `tb_supply_dispatch` — 应急物资调度管理 |\n\n#### 2.3 AI 应急助手（AgentChatPanel 浮动面板，HomeView 内嵌）\n- **多 Agent 协同架构**：Coordinator 调度器 → 意图分类 → 任务规划 → 4 个子 Agent（search / analysis / route / knowledge）顺序执行 → 流式汇总输出\n- **12+ 工具**：feature_search / spatial_query / buffer_analysis / dual_buffer_analysis / overlay_analysis / shortest_path / service_area / fly_to_location / online_route_planning / mock_nearby_resources + Pareto 多目标优化 + ACO 蚁群路径分配\n- **RAG 知识库**：5 篇应急预案文档（地震/火灾/洪水/医疗救援/综合预案），FAISS 向量检索\n- **双模式**：单一意图 → 单 Agent（低延迟）；混合意图 → Coordinator 多 Agent 编排\n- **前端渲染**：工具返回的 GeoJSON 自动叠加到地图，受灾点红色标记，支援点琥珀色标记\n\n### 3. 三维洪水模拟 `/flood-simulation`\n**Cesium 3D 场景**（FloodSimulationView），演示积石山区域洪水淹没过程。\n- 淹没参数调节：高度（m）/ 速度（m/s）\n- 控制：开始模拟 / 暂停继续 / 重置\n- 实时水位动态上升效果\n\n### 4. 监测-预警-联动 `/data-dashboard`\n（原\"数据大屏\"改造，半屏面板布局：左侧地图 + 右侧页签切换）\n- **分级地图**（DashboardMap）：县级行政区灾害标记着色，点击选中目标县域\n- **气象监控**（WeatherPanel → 右侧\"气象监控\"页签）：实时气象数据（风力/降雨/温度/湿度）\n- **AHP 灾情评估**（DisasterDetailPanel → 右侧\"灾情评估\"页签）：选定县域的多指标层次分析评估\n- **一键救援**：在灾情评估面板触发 → 弹出缓冲区分析弹窗（BufferAnalysisModal）→ 确定后弹出 5 步救援调度弹窗（RoutePlanningModal）\n\n### 5. 地震指挥 `/earthquake-command`\n**地震应急指挥专页**（EarthquakeCommandView），面向地震场景的一站式指挥。\n- **震情概览**：区域、震级、时间、位置、应急等级（I~IV 级），盲区预警/未应答/物资缺口实时滚动\n- **组织层级树**：国家 → 京津冀联合指挥部 → 地市 → 区县 → 乡镇，折叠/展开\n- **AHP-DDI 灾情评估**：8 指标（地震强度/震源深度/人口密度/建筑脆弱性/道路通达性/医疗容量/物资储备/次生灾害风险），层次分析法计算 → 4 级划分\n- **双缓冲区分析**：受灾圈（小半径）+ 支援圈（大半径），按灾害等级动态调整半径\n- **救援调度**：5 步流程（建队伍→医疗→物资→交通→避难），4 路彩色路径渲染\n- **Pareto 多目标优化 + ACO 蚁群路径分配**：在距离与容量之间找 Pareto 最优解，ACO 多车路径分配\n\n---\n\n## 二、技术栈\n\n| 层 | 技术 |\n|----|------|\n| 前端 | Vue 3.5 + Vite 8 + Ant Design Vue 4 + Ant Design Vue Icons 7 + MapboxGL 1.13 + `@supermap/iclient-mapboxgl` 11.1 + Cesium + Pinia 3 + Vue Router 4 + Axios 1.7 + markdown-it 14 |\n| 后端（业务） | SpringBoot 3.4 + MyBatis 3 + MySQL 8（Java 17） |\n| 后端（Agent） | FastAPI + LangGraph + LangChain + DeepSeek-V3.2（硅基流动）+ FAISS |\n| GIS 服务 | SuperMap iServer 11i（地图/数据/空间分析/网络分析服务） |\n| 数据 | Jingjin.udbx / World.udbx / Changchun.udbx（iServer 自带样本数据） |\n\n---\n\n## 三、目录结构\n\n```\nGIS-Practice/\n├── frontend/                  # Vue3 前端\n│   ├── src/\n│   │   ├── components/\n│   │   │   ├── dashboard/        # 数据大屏组件（DashboardMap, WeatherPanel, DisasterDetailPanel, BufferAnalysisModal, RoutePlanningModal）\n│   │   │   ├── earthquake/       # 地震应急组件（BufferZoneLayer, SupportPointLayer, RescueDispatchPanel）\n│   │   │   ├── agent/            # Agent 聊天组件（ChatMessage, ToolCallCard）\n│   │   │   ├── SmMapViewer.vue   # 核心地图组件\n│   │   │   ├── NavSidebar.vue    # 导航侧边栏（GIS 工具组 + \"数据库\"分组 CRUD 入口）\n│   │   │   ├── AgentChatPanel.vue# AI 聊天面板\n│   │   │   ├── MapToolbar.vue    # 地图工具栏\n│   │   │   ├── MapOverview.vue   # 鹰眼组件\n│   │   │   ├── MapMeasure.vue    # 量算组件\n│   │   │   ├── LayerManager.vue  # 图层管理\n│   │   │   ├── FeatureSearch.vue # 专题检索\n│   │   │   ├── SpatialQuery.vue  # 空间查询\n│   │   │   ├── SpatialAnalysis.vue # 缓冲区与叠置分析\n│   │   │   └── NetworkAnalysis.vue # 网络分析\n│   │   ├── views/             # 页面视图（对应顶部导航 5 大模块 + CRUD 子页）\n│   │   │   ├── NewBigScreenView.vue    # 【数字大屏】气象灾害监测大屏\n│   │   │   ├── HomeView.vue            # 【二维地图】核心地图页（GIS + Agent）\n│   │   │   ├── FloodSimulationView.vue # 【三维洪水模拟】Cesium 3D 淹没模拟\n│   │   │   ├── DataDashboardView.vue   # 【监测-预警-联动】综合监测评估\n│   │   │   ├── EarthquakeCommandView.vue # 【地震指挥】地震应急指挥专页\n│   │   │   ├── WarnInfoView.vue        # 【二维地图→数据库】预警主表 CRUD\n│   │   │   ├── CoordResponseView.vue   # 【二维地图→数据库】协同处置 CRUD\n│   │   │   └── SupplyDispatchView.vue  # 【二维地图→数据库】物资调度 CRUD\n│   │   ├── router/index.js  # 路由配置（9 条路由）\n│   │   ├── stores/           # Pinia 状态管理（map.js / agent.js）\n│   │   ├── composables/      # Vue composables（useShortestPath）\n│   │   └── utils/\n│   │       ├── request.js        # axios 封装\n│   │       ├── map.js            # 地图工具函数\n│   │       ├── ahp.js            # 通用 AHP 层次分析法\n│   │       ├── earthquakeAhp.js  # 地震 AHP-DDI 灾情评估\n│   │       ├── haversine.js      # 球面距离计算\n│   │       ├── circlePolygon.js  # 圆形 Polygon 生成\n│   │       ├── mockData.js       # 模拟数据生成\n│   │       ├── earthquakeNaming.js # 地震命名规则\n│   │       ├── generateEarthquakePoints.js # 地震点数据生成\n│   │       └── agent/\n│   │           ├── sse.js            # SSE 连接管理\n│   │           ├── markdown.js       # Markdown 渲染\n│   │           ├── mapRenderer.js    # GeoJSON 地图渲染\n│   │           └── changchunBasemap.js # 长春底图配置\n│   ├── composables/         # Vue composables（useShortestPath）\n│   ├── public/data/         # 静态地理数据（roads.geojson, buildings.geojson）\n│   └── vite.config.js       # 含 /iserver /api /agent-api 三组 proxy\n│\n├── backend/                   # SpringBoot 业务后端（CRUD + 健康检查）\n│   └── src/main/\n│       ├── java/com/gis/emergency/\n│       │   ├── controller/  # REST API（Health / WarnInfo / CoordResponse / SupplyDispatch）\n│       │   ├── service/     # 业务逻辑层\n│       │   ├── mapper/      # MyBatis 注解式 Mapper\n│       │   ├── entity/      # 实体类（WarnInfo / CoordResponse / SupplyDispatch）\n│       │   ├── common/      # 统一响应 R.java\n│       │   ├── config/      # CORS、全局异常处理、App 配置\n│       │   └── util/        # CoordConverter 坐标转换\n│       └── resources/\n│           ├── application.yml  # 数据库 + iServer 配置\n│           ├── schema.sql       # 建表脚本（启动自动执行，幂等）\n│           └── data.sql         # 种子数据（18 条，INSERT IGNORE）\n│\n├── agent-backend/             # FastAPI Agent 后端（AI 智能问答）\n│   ├── app/\n│   │   ├── agent/             # LangGraph 多 Agent 编排\n│   │   │   ├── coordinator.py    # Coordinator 主调度：意图→规划→代码级路由→子 Agent→汇总\n│   │   │   ├── graph.py          # 单 Agent 引擎（ReAct 模式，11 GIS 工具 + 2 算法工具）\n│   │   │   ├── state.py          # 状态管理\n│   │   │   ├── nodes/\n│   │   │   │   ├── intent.py     # 意图分类节点\n│   │   │   │   ├── planner.py    # 任务规划节点\n│   │   │   │   └── summarize.py  # 结果汇总节点（流式输出）\n│   │   │   ├── sub_agents/       # 4 个子 Agent（search/analysis/route/knowledge）\n│   │   │   └── tools/\n│   │   │       ├── gis_tools.py  # 11 个 GIS 工具（feature_search/spatial_query/buffer_analysis/dual_buffer_analysis/overlay_analysis/shortest_path/service_area/fly_to_location/online_route_planning/mock_nearby_resources）\n│   │   │       ├── algo_tools.py # 2 个算法工具（Pareto 多目标优化 + ACO 蚁群多车路径分配）\n│   │   │       └── rag_tools.py  # RAG 检索工具\n│   │   ├── api/                 # FastAPI 路由（agent / rag）\n│   │   ├── services/            # LLM / RAG / iServer / Session 客户端\n│   │   ├── schemas/             # Pydantic 模型（ToolResult）\n│   │   └── config.py            # 配置读取（.env 优先）\n│   ├── data/knowledge/          # RAG 知识库源文档（5 篇应急预案 markdown）\n│   ├── .env.example             # 环境变量模板（含 API Key 配置说明）\n│   └── requirements.txt\n│\n├── openspec/                    # OpenSpec 设计文档（proposal/design/spec/tasks/checklist）\n│   └── changes/\n│       ├── project-foundation/          # 项目基础框架\n│       ├── spatial-query/               # 空间查询\n│       ├── thematic-search/             # 专题检索\n│       ├── spatial-analysis/            # 缓冲区与叠置分析\n│       ├── 20260626-multi-agent-gis/    # AI 多智能体系统\n│       ├── 20260626-data-dashboard/     # 数据大屏\n│       ├── 20260702-db-crud-module/     # 数据库 CRUD 模块\n│       └── 20260705-earthquake-rescue-refactor/ # 地震应急指挥重构\n├── .trae/                      # Trae IDE 规则、技能、工作流、知识库\n├── project-brief.md            # 项目概要\n└── AGENTS.md                   # AI Agent 入口导航\n```\n\n---\n\n## 四、运行环境要求\n\n| 软件 | 版本 | 用途 |\n|------|------|------|\n| JDK | 17+ | SpringBoot 后端 |\n| Maven | 3.8+ | 后端构建 |\n| Node.js | 18+ | 前端构建 |\n| npm | 9+ | 前端依赖 |\n| Python | 3.10+ | Agent 后端 |\n| MySQL | 8.0+ | 业务数据存储 |\n| SuperMap iServer | 11i (11.3.0) | GIS 服务 |\n| SuperMap iDesktopX | 2025（可选） | 数据处理/制图 |\n\n---\n\n## 五、启动前配置\n\n系统涉及 **5 个服务**（含数据库），按以下顺序配置和启动：iServer → MySQL → SpringBoot 后端 → FastAPI Agent 后端 → Vue 前端。\n\n### 5.1 SuperMap iServer 配置（端口 8090）\n\niServer 提供 GIS 数据服务、地图服务、空间分析、网络分析能力，是前端地图和 Agent 工具的数据源。\n\n#### 1) 安装并启动 iServer\n\n- 安装路径示例：`D:\\SuperMap\\SuperMapiServer11i\\`\n- 启动：进入 `bin/` 目录运行 `startup.bat`，浏览器访问 `http://localhost:8090/iserver`\n- 首次启动需设置管理员账号\n\n#### 2) 确认样本数据存在\n\niServer 11i 自带以下样本数据，位于 `D:\\SuperMap\\SuperMapiServer11i\\samples\\data\\`：\n\n| 数据文件 | 路径 | 用途 |\n|---------|------|------|\n| 京津冀数据 | `City\\Jingjin.udbx` | 基础地图、空间查询、缓冲区分析 |\n| 世界底图 | `World\\World.udbx` | 底图 |\n| 长春路网 | `NetworkAnalyst\\Changchun.udbx` | 网络分析（最短路径/服务区） |\n\n#### 3) 发布/确认服务\n\niServer 默认在 `webapps\\iserver\\WEB-INF\\iserver-services-samples.xml` 中预配置了以下服务，**首次启动后通常已自动发布**，请在 iServer 管理页面「服务」列表中确认存在：\n\n| 服务名 | 类型 | 用途 |\n|--------|------|------|\n| `map-jingjin` | 地图服务 | 京津冀地图展示 |\n| `data-jingjin` | 数据服务 | 要素查询（POI、行政区域等） |\n| `spatialanalyst-sample` | 空间分析服务 | 缓冲区分析、叠置分析 |\n| `transportationanalyst-sample` | 交通网络分析服务 | 最短路径、服务区分析 |\n\n若服务未自动发布，可在 iServer 管理页面「服务 → 创建服务」中基于上述数据源手动发布。\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8090/iserver/services`，应能看到上述服务列表。\n\n---\n\n### 5.2 MySQL 数据库配置（端口 3306）\n\n#### 1) 安装并启动 MySQL 8\n\n确保 MySQL 服务已启动，并能以 root 账号登录：\n\n```bash\nmysql -u root -p\n```\n\n#### 2) 修改后端数据库账号密码\n\n打开 `backend/src/main/resources/application.yml`，修改第 10–12 行：\n\n```yaml\nspring:\n  datasource:\n    url: jdbc:mysql://localhost:3306/emergency_db?createDatabaseIfNotExist=true&useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true\n    username: root           # ← 改为你的 MySQL 用户名\n    password: t821777        # ← 改为你的 MySQL 密码\n    driver-class-name: com.mysql.cj.jdbc.Driver\n```\n\n说明：\n- `createDatabaseIfNotExist=true`：首次启动时自动创建 `emergency_db` 数据库，无需手动建库\n- `serverTimezone=Asia/Shanghai`：时区配置，必须保留\n\n#### 3) 执行 SQL（建表 + 种子数据）\n\n**方式 A（推荐，自动执行）**：保持 `application.yml` 中以下配置不变：\n\n```yaml\nspring:\n  sql:\n    init:\n      mode: always                              # 每次启动都执行\n      schema-locations: classpath:schema.sql    # 建表（IF NOT EXISTS，幂等）\n      data-locations: classpath:data.sql        # 种子数据（INSERT IGNORE，幂等）\n      continue-on-error: false\n```\n\n启动 SpringBoot 后端时，`schema.sql`（建 3 张表）和 `data.sql`（插入 18 条种子数据）会**自动执行**，无需手动操作。\n\n**方式 B（手动执行）**：如需提前建表，可在 MySQL 客户端中执行：\n\n```bash\n# 登录 MySQL\nmysql -u root -p\n\n# 在 MySQL 命令行中执行\nCREATE DATABASE IF NOT EXISTS emergency_db DEFAULT CHARACTER SET utf8mb4;\nUSE emergency_db;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/schema.sql;\nSOURCE d:/Code/AI-Code/GIS-Practice/backend/src/main/resources/data.sql;\nEXIT;\n```\n\n> 若已通过方式 A 自动建表，**不要再手动执行**，否则 `INSERT IGNORE` 会因主键已存在而跳过（无害但冗余）。\n\n#### 4) 数据表说明\n\n| 表名 | 说明 | 主键 |\n|------|------|------|\n| `tb_warn_info` | 气象灾害预警主表 | `warn_id` |\n| `tb_coord_response` | 协同叫应处置表 | `response_id` |\n| `tb_supply_dispatch` | 应急物资调度总表 | `dispatch_id` |\n\n---\n\n### 5.3 SpringBoot 业务后端配置（端口 8080）\n\n#### 1) 检查 iServer 配置\n\n`application.yml` 第 33–41 行已配置 iServer 服务地址，若你的 iServer 不在 `localhost:8090`，请修改：\n\n```yaml\niserver:\n  base-url: http://localhost:8090\n  data-service: data-jingjin\n  datasource: Jingjin\n  map-service: map-jingjin\n  map-name: 京津地区地图\n  spatial-service: spatialanalyst-sample\n  transport-service: transportationanalyst-sample\n```\n\n#### 2) 构建并启动\n\n```bash\ncd backend\nmvn clean package -DskipTests\njava -jar target/emergency-backend-0.0.1-SNAPSHOT.jar\n```\n\n或在 IDE 中直接运行 `EmergencyApplication.java`。\n\n#### 3) 验证\n\n浏览器访问 `http://localhost:8080/api/health`，应返回：\n\n```json\n{ \"code\": 200, \"message\": \"success\", \"data\": \"京津冀城市综合防灾应急管理系统后端运行正常\" }\n```\n\n---\n\n### 5.4 FastAPI Agent 后端配置（端口 8001）\n\nAgent 后端依赖 **大模型 API Key** 才能运行 AI 问答功能。\n\n#### 1) 创建 Python 虚拟环境并安装依赖\n\n```bash\ncd agent-backend\npython -m venv venv\n# Windows\nvenv\\Scripts\\activate\n# macOS/Linux\nsource venv/bin/activate\n\npip install -r requirements.txt\n```\n\n#### 2) 配置 API Key（必须）\n\n复制环境变量模板：\n\n```bash\ncp .env.example .env\n```\n\n编辑 `agent-backend/.env`，填入你的 API Key：\n\n```dotenv\n# LLM API 配置（硅基流动 SiliconFlow）\n# 注册地址：https://siliconflow.cn/  注册后在「API 密钥」页面创建 Key\n# 注意：变量名虽为 DEEPSEEK_API_KEY，实际填入的是硅基流动的 API Key\nDEEPSEEK_API_KEY=sk-your-siliconflow-api-key-here    # ← 改为你的真实 Key\nDEEPSEEK_BASE_URL=https://api.siliconflow.cn/v1\nDEEPSEEK_MODEL=deepseek-ai/DeepSeek-V3.2\n\n# iServer 配置（默认本机，无需修改）\nISERVER_URL=http://localhost:8090\n\n# 后端配置\nHOST=0.0.0.0\nPORT=8001\n\n# RAG 配置（与 LLM 共用 API Key，留空则自动回退到 DEEPSEEK_API_KEY）\nEMBEDDING_BASE_URL=https://api.siliconflow.cn/v1\nEMBEDDING_MODEL=BAAI/bge-m3\n```\n\n> **关于 API Key**：本项目使用硅基流动（SiliconFlow）提供的 `deepseek-ai/DeepSeek-V3.2` 模型，性价比高。注册硅基流动账号后在「API 密钥」页面创建 Key，填入 `DEEPSEEK_API_KEY`。Embedding 模型 `BAAI/bge-m3` 与 LLM 共用同一 Key，无需额外申请。\n\n#### 3) 启动\n\n```bash\n# 确保在 agent-backend/ 目录且已激活虚拟环境\npython -m app.main\n```\n\n或使用 uvicorn 热重载：\n\n```bash\nuvicorn app.main:app --host 0.0.0.0 --port 8001 --reload\n```\n\n#### 4) 验证\n\n浏览器访问 `http://localhost:8001/api/health`，应返回：\n\n```json\n{ \"status\": \"ok\", \"service\": \"gis-agent-backend\" }\n```\n\n启动日志中应看到 `RAG 知识库就绪：5 个文档已索引`（首次启动会自动构建 FAISS 向量库）。\n\n---\n\n### 5.5 Vue 前端配置（端口 5173）\n\n#### 1) 安装依赖\n\n```bash\ncd frontend\nnpm install\n```\n\n#### 2) 确认 Vite proxy 配置\n\n`vite.config.js` 已配置三组代理，默认无需修改：\n\n| 前缀 | 转发到 | 用途 |\n|------|--------|------|\n| `/iserver` | `http://localhost:8090` | iServer GIS 服务 |\n| `/api` | `http://localhost:8080` | SpringBoot 业务后端（CRUD 接口） |\n| `/agent-api` | `http://localhost:8001`（重写为 `/api`） | FastAPI Agent 后端（AI 问答接口） |\n\n若你的后端服务端口不同，请修改 `vite.config.js` 中对应的 `target`。\n\n#### 3) 启动\n\n```bash\nnpm run dev\n```\n\n浏览器访问 `http://localhost:5173`。\n\n#### 4) 前端路由一览（对应顶部导航 5 大模块 + CRUD 子页）\n\n| 导航分组 | 路由路径 | 页面 | 说明 |\n|----------|----------|------|------|\n| **数字大屏** | `/new-big-screen` | NewBigScreenView | 气象灾害监测大屏（KPI + 趋势图） |\n| **二维地图** | `/` | HomeView | 核心地图页（GIS 操作 + NavSidebar + AI 助手） |\n| | `/warn-info` | WarnInfoView | 预警主表 CRUD（NavSidebar → 数据库） |\n| | `/coord-response` | CoordResponseView | 协同处置 CRUD（NavSidebar → 数据库） |\n| | `/supply-dispatch` | SupplyDispatchView | 物资调度 CRUD（NavSidebar → 数据库） |\n| **三维洪水模拟** | `/flood-simulation` | FloodSimulationView | Cesium 3D 淹没模拟 |\n| **监测-预警-联动** | `/data-dashboard` | DataDashboardView | 综合监测评估（地图 + 灾情 + 气象） |\n| **地震指挥** | `/earthquake-command` | EarthquakeCommandView | 地震应急指挥专页 |\n\n---\n\n## 六、启动顺序速查\n\n| 顺序 | 服务 | 端口 | 启动命令 | 启动条件 |\n|------|------|------|---------|---------|\n| 1 | SuperMap iServer | 8090 | `bin/startup.bat` | 已安装并发布样本服务 |\n| 2 | MySQL | 3306 | 系统服务 | 已创建 root 账号或修改 `application.yml` |\n| 3 | SpringBoot 后端 | 8080 | `mvn spring-boot:run` | iServer + MySQL 已启动 |\n| 4 | FastAPI Agent 后端 | 8001 | `python -m app.main` | iServer 已启动 + `.env` 已配置 Key |\n| 5 | Vue 前端 | 5173 | `npm run dev` | 上述后端均已启动 |\n\n> **可选**：若不使用 AI 问答功能，可跳过第 4 步（FastAPI Agent 后端），其余模块（地图、CRUD、空间分析）仍可正常使用。\n\n---\n\n## 七、常见问题\n\n### Q1：前端打开后地图空白？\n- 检查 iServer 是否启动：访问 `http://localhost:8090/iserver`\n- 检查浏览器控制台是否有 `/iserver` 请求 404，确认服务名与 `application.yml` 一致\n\n### Q2：后端启动报数据库连接失败？\n- 确认 MySQL 服务已启动\n- 确认 `application.yml` 中 `username` / `password` 与本机 MySQL 一致\n- 确认 URL 中 `createDatabaseIfNotExist=true` 参数存在（首次启动需自动建库）\n\n### Q3：数据表未自动创建？\n- 检查 `application.yml` 中 `spring.sql.init.mode` 是否为 `always`\n- 检查 `schema.sql` / `data.sql` 是否在 `src/main/resources/` 下\n- 查看启动日志是否有 SQL 执行错误\n\n### Q4：Agent 聊天无响应或报 401？\n- 确认 `agent-backend/.env` 中 `DEEPSEEK_API_KEY` 已填写真实 Key\n- 确认 Key 余额充足（硅基流动账户）\n- 确认 `DEEPSEEK_BASE_URL` 为 `https://api.siliconflow.cn/v1`（非 DeepSeek 官方地址）\n\n### Q5：RAG 知识库初始化失败？\n- 首次启动会调用 Embedding API 构建向量库，需联网且 API Key 有效\n- 失败为非致命错误，Agent 仍可运行（仅失去知识库检索能力）\n- 重新启动时会自动重试\n\n### Q6：网络分析模块无结果？\n- 确认 `transportationanalyst-sample` 服务已在 iServer 发布\n- 确认长春路网数据 `Changchun.udbx` 存在\n- 网络分析使用长春市数据，起终点需在长春市范围内\n\n### Q7：端口被占用？\n- 8080 / 8001 / 5173 / 8090 任一被占用都会导致启动失败\n- 使用 `netstat -ano | findstr <端口>` 查看占用进程\n- 修改对应配置文件中的端口号（注意同步更新 `vite.config.js` 的 proxy target）\n\n---\n\n## 八、开发规范\n\n- AI 编码规范：见 [`.trae/rules/coding_guidelines.md`](.trae/rules/coding_guidelines.md)\n- 前端规范：见 [`.trae/rules/frontend_rules.md`](.trae/rules/frontend_rules.md)\n- 项目规范：见 [`.trae/rules/project_rules.md`](.trae/rules/project_rules.md)\n- Git 提交规范：`<type>: <描述>`，type 包括 `feat / fix / refactor / docs / style / chore`\n- 设计文档：`openspec/changes/<change-id>/` 下按 proposal → design → spec → tasks → checklist 组织\n- 单元测试：`frontend/src/utils/__tests__/` 下存放置工具函数单元测试（Vitest），含 earthquakeAhp / haversine / earthquakeNaming / generateEarthquakePoints 测试\n\n---\n\n## 九、安全说明\n\n- 本项目为课程设计，**不涉及用户认证**，前后端 API 均为公开访问\n- `application.yml` 中 MySQL 密码为明文（课设阶段可接受，生产环境应使用配置中心或环境变量）\n- `agent-backend/.env` 已在 `.gitignore` 中忽略，不会提交 API Key 到 Git 仓库\n- iServer 服务地址使用相对路径，通过 Vite proxy 转发，避免跨域\n\n---\n\n## 十、文档索引\n\n| 文档 | 说明 |\n|------|------|\n| [AGENTS.md](AGENTS.md) | AI Agent 入口导航 |\n| [project-brief.md](project-brief.md) | 项目概要：技术栈、数据资源、功能模块 |\n| `.trae/docs/workflows.md` | 角色工作流、协作流程 |\n| `openspec/changes/` | 各功能模块的设计文档与验收清单 |\n| `.trae/knowledge/INDEX.md` | 项目知识库全景图 |\n\n---\n\n## 十一、文档与实现差异说明\n\n本项目的设计文档（包括 `project-brief.md`、`openspec/changes/` 下的 proposal/design/spec/tasks/checklist、`.trae/knowledge/` 中的知识库等）反映的是**开发初期或阶段性方案设计**，并非最终实现的逐字描述。\n\n在实际开发与测试过程中，部分功能会因以下原因与原始文档产生差异：\n\n- 测试验证中发现问题后对接口字段、参数命名、业务逻辑的调整\n- 依赖库版本升级或 API 行为变化导致的实现细节调整\n- 针对 SuperMap iServer / DeepSeek / LangGraph 等外部服务的兼容性适配\n- 性能优化、Bug 修复过程中的代码重构\n\n> **若本文档（README）或其他设计文档与实际系统行为存在不一致，请以实际代码和运行系统为准。**\n\n如需了解某模块的最新实现，建议直接查阅对应的源码：\n\n- 前端组件实现：`frontend/src/components/` 与 `frontend/src/views/`\n- 后端接口实现：`backend/src/main/java/com/gis/emergency/`\n- Agent 工具实现：`agent-backend/app/agent/tools/` 与 `agent-backend/app/agent/sub_agents/`\n- 配置文件（反映真实运行参数）：`backend/src/main/resources/application.yml`、`agent-backend/.env.example`\n"}}}}