添加文档注释，方便生成技术文档

README.md

@@ -1,9 +1,6 @@
-# basic_template_not_login_front
+# xian_vue_new
-开发基本模版——前端
+西安项目前端
-# basic_template_not_login_front
+# xian_vue_new
-
-## 项目介绍
-`basic_template_not_login_front` 是一个包含前端的基础开发模板，旨在为快速搭建Web应用提供完整的技术栈支持。项目前端基于Vue 3 + TypeScript + Element Plus构建，可直接作为中小型Web项目的开发起点。
 
 ## 开发工具说明
 1. 使用vscode完成前端代码撰写

src/api/api.ts

@@ -6,29 +6,50 @@ import type { ApiResponse } from '@/types/ApiResponse'
 import type { XianHiddenDangerSpots } from '@/types/base/XianHiddenDangerSpots'
 import type { XianRiskSpots } from '@/types/base/XianRiskSpots'
 
+/**
+ * API接口统一导出对象
+ */
 export const $api = {
 
   // 加密模块
   crypto: {
-    // 获取sm2公钥
+    /**
+     * 获取SM2公钥
+     * @returns SM2公钥响应
+     */
     getSm2PublicKey: () => getSm2PublicKey(),
   },
 
   // 隐患点信息
   hiddenDangerSpots: {
-    // 获取所有基础隐患点
+    /**
+     * 获取所有基础隐患点
+     * @param disasterType - 灾害类型
+     * @returns 隐患点数据数组
+     */
     getBasePoins: (disasterType: DisasterType): Promise<ApiResponse<XianHiddenDangerSpots[]>> => getHiddenDangerBasePoints(disasterType),
 
-    // 根据id获取隐患点详情
+    /**
+     * 根据id获取隐患点详情
+     * @param id - 隐患点id
+     * @returns 隐患点详情
+     */
     getPointDetailById: (id: number): Promise<ApiResponse<XianHiddenDangerSpots>> => getHiddenDangerPointDetailById(id),
   },
 
   // 风险点信息
   riskSpots: {
-    // 获取所有基础风险点
+    /**
+     * 获取所有基础风险点
+     * @returns 风险点数据数组
+     */
     getBasePoins: (): Promise<ApiResponse<XianRiskSpots[]>> => getRiskBasePoints(),
 
-    // 根据id获取风险点详情
+    /**
+     * 根据id获取风险点详情
+     * @param id - 风险点id
+     * @returns 风险点详情
+     */
     getPointDetailById: (id: number): Promise<ApiResponse<XianRiskSpots>> => getRiskPointDetailById(id),
   },
 }

src/api/crypto.ts

@@ -3,8 +3,8 @@ import type { ApiResponse } from '@/types/ApiResponse'
 import httpInstance from '@/utils/request/http'
 
 /**
- * 获取sm2加密公钥
+ * 获取SM2加密公钥
- * @returns
+ * @returns SM2公钥响应
  */
 export const getSm2PublicKey = (): Promise<ApiResponse<Sm2PublicKeyResponse>> => {
   return httpInstance.get('/crypto/sm2/public-key')

src/api/hidden-danger-spots.ts

@@ -4,9 +4,9 @@ import type { DisasterType } from "@/types/common/DisasterType"
 import httpInstance from "@/utils/request/http"
 
 /**
- * 获取隐患点数据
+ * 获取隐患点基础数据
- * @param disasterType 灾害类型
+ * @param disasterType - 灾害类型
- * @returns 隐患点数据
+ * @returns 隐患点数据数组
  */
 export const getBasePoins = (disasterType: DisasterType): Promise<ApiResponse<XianHiddenDangerSpots[]>> => {
     return httpInstance.get('/hidden-danger-spots/base-points', {
@@ -18,7 +18,7 @@ export const getBasePoins = (disasterType: DisasterType): Promise<ApiResponse<Xi
 
 /**
  * 根据id获取隐患点详情
- * @param id 隐患点id
+ * @param id - 隐患点id
  * @returns 隐患点详情
  */
 export const getPointDetailById = (id: number): Promise<ApiResponse<XianHiddenDangerSpots>> => {

src/api/risk-spots.ts

@@ -3,8 +3,8 @@ import type { XianRiskSpots } from "@/types/base/XianRiskSpots"
 import httpInstance from "@/utils/request/http"
 
 /**
- * 获取风险点数据
+ * 获取风险点基础数据
- * @returns 风险点数据
+ * @returns 风险点数据数组
  */
 export const getBasePoins = (): Promise<ApiResponse<XianRiskSpots[]>> => {
     return httpInstance.get('/risk-spots/base-points')
@@ -12,7 +12,7 @@ export const getBasePoins = (): Promise<ApiResponse<XianRiskSpots[]>> => {
 
 /**
  * 根据id获取风险点详情
- * @param id 风险点id
+ * @param id - 风险点id
  * @returns 风险点详情
  */
 export const getPointDetailById = (id: number): Promise<ApiResponse<XianRiskSpots>> => {

src/hooks/map/useAdministrativeDivision.ts

@@ -15,7 +15,14 @@ import {
 } from '@/assets';
 import { Color } from 'cesium';
 
+/**
+ * 行政区划分相关钩子函数
+ * @returns 行政区数据、ID、颜色及透明度配置
+ */
 export const useAdministrativeDivision = () => {
+  /**
+   * 行政区GeoJSON数据数组
+   */
   const areas = [
     baQiao,
     beiLin,
@@ -31,6 +38,9 @@ export const useAdministrativeDivision = () => {
     yanTa,
     zhouZhi,
   ];
+  /**
+   * 行政区ID数组
+   */
   const areasId = [
     'baqiao',
     'beilin',
@@ -46,6 +56,9 @@ export const useAdministrativeDivision = () => {
     'yanta',
     'zhouzhi',
   ];
+  /**
+   * 行政区颜色数组
+   */
   const areasColor = [
     new Color(255 / 255, 153 / 255, 0 / 255),
     new Color(255 / 255, 51 / 255, 102 / 255),
@@ -61,7 +74,13 @@ export const useAdministrativeDivision = () => {
     new Color(255 / 255, 153 / 255, 204 / 255),
     new Color(190 / 255, 255 / 255, 232 / 255),
   ];
+  /**
+   * 区域透明度
+   */
   const areaTransparency = 0.3;
+  /**
+   * 标签透明度
+   */
   const labelTransparency = 1;
 
   return { areas, areasId, areasColor, areaTransparency, labelTransparency };

src/hooks/map/useMap.ts

@@ -3,8 +3,14 @@ import { CesiumUtilsSingleton } from '@/utils/cesium/CesiumUtils';
 import { ScreenSpaceEventType } from 'cesium';
 import type { ClickObject } from '@/types/cesium/ClickObject';
 import { useLoadingInformationStore } from '@/stores/useLoadingInformation';
+/**
+ * 地图交互相关钩子函数
+ * @returns 注册监听器和视角控制方法
+ */
 export const useMap = () => {
-  // 注册全局点击监听器
+  /**
+   * 注册全局点击监听器
+   */
   const registerAndClickOnTheListener = () => {
     CesiumUtilsSingleton.clickLayer((pickedObject: ClickObject) => {
       if (
@@ -45,7 +51,9 @@ export const useMap = () => {
     });
   };
 
-  // 注册全局滚轮监听器
+  /**
+   * 注册全局滚轮监听器
+   */
   const registerAScrollListener = () => {
     CesiumUtilsSingleton.getViewer()!.scene.canvas.addEventListener(
       'wheel',
@@ -56,12 +64,16 @@ export const useMap = () => {
     );
   };
 
-  // 当行政区超出页面时，自动拉回视角
+  /**
+   * 当行政区超出页面时，自动拉回视角
+   */
   const automaticallyAdjustThePerspective = () => {
     CesiumUtilsSingleton.outOverView();
   };
 
-  // 禁止事件
+  /**
+   * 禁止默认事件
+   */
   const prohibitedEvents = () => {
     // 禁止全局默认双击事件
     CesiumUtilsSingleton.getViewer()?.cesiumWidget.screenSpaceEventHandler.removeInputAction(

src/hooks/rain-earthquake/useHiddenPoint.ts

@@ -5,7 +5,14 @@ import {
   waterLoggingIcon,
 } from '@/assets';
 
+/**
+ * 隐患点相关钩子函数
+ * @returns 字段映射和获取灾害图标方法
+ */
 export const useHiddenPoint = () => {
+  /**
+   * 字段映射配置
+   */
   const field = {
     fieldCode: '野外编号',
     disasterName: '灾害点名称',
@@ -15,6 +22,11 @@ export const useHiddenPoint = () => {
     riskGrade: '风险等级',
   };
 
+  /**
+   * 根据灾害类型获取对应图标
+   * @param disasterType - 灾害类型
+   * @returns 图标路径
+   */
   function getDisasterIcon(disasterType?: string): string {
     switch (disasterType) {
       case '滑坡':

src/hooks/rain-earthquake/useRiskPoint.ts

@@ -1,9 +1,18 @@
 import { riskAreaIcon } from '@/assets';
 
+/**
+ * 风险点相关钩子函数
+ * @returns 信息框标题、字段映射和获取图标方法
+ */
 export const useRiskPoint = () => {
-  // 信息框标题
+  /**
+   * 信息框标题
+   */
   const informationBoxTitle = '风险区域';
 
+  /**
+   * 字段映射配置
+   */
   const field = {
     riskName: '风险区名称',
     unitCode: '统一编号',
@@ -18,6 +27,10 @@ export const useRiskPoint = () => {
     lat: '纬度',
   };
 
+  /**
+   * 获取风险点图标
+   * @returns 图标路径
+   */
   function getDisasterIcon(): string {
     return riskAreaIcon;
   }

src/hooks/rainstorm/useRainDisasterChain.ts

@@ -3,15 +3,22 @@ import type { XianHiddenDangerSpots } from '@/types/base/XianHiddenDangerSpots';
 import { HiddenPointType } from '@/types/common/DisasterType';
 import type { PaginationType } from '@/types/common/PaginationType';
 
-// 灾害链影响点列表钩子函数
+/**
+ * 暴雨灾害链影响点列表钩子函数
+ * @returns 搜索条件、表格数据、分页配置及相关方法
+ */
 export const useRainDisasterChain = () => {
-  // 搜索条件
+  /**
+   * 搜索条件
+   */
   const conditions = ref({
     tableData: '',
     hiddenPoint: HiddenPointType.LANDSLIDE,
   });
 
-  // 下拉选项
+  /**
+   * 下拉选项
+   */
   const selectOptions = [
     { value: HiddenPointType.LANDSLIDE, label: '滑坡' },
     { value: HiddenPointType.DEBRIS_FLOW, label: '泥石流' },
@@ -19,10 +26,14 @@ export const useRainDisasterChain = () => {
     { value: HiddenPointType.WATERLOGGING, label: '内涝' },
   ];
 
-  // 表格数据
+  /**
+   * 表格数据
+   */
   const tableDatas = ref<XianHiddenDangerSpots[]>([]);
 
-  // 表头
+  /**
+   * 表头配置
+   */
   const tableColumns = [
     { title: '名称', key: 'disasterName' },
     { title: '位置', key: 'position' },
@@ -30,7 +41,9 @@ export const useRainDisasterChain = () => {
     { title: '险情等级', key: 'riskGrade' },
   ];
 
-  // 分页配置
+  /**
+   * 分页配置
+   */
   const paginationConfig = ref<PaginationType>({
     currentPage: 1,
     pageSize: 10,
@@ -38,7 +51,10 @@ export const useRainDisasterChain = () => {
     totalPage: 1,
   });
 
-  // 修改条件
+  /**
+   * 修改搜索条件
+   * @param value - 新的搜索条件
+   */
   function changeConditions(value: {
     tableData: string;
     hiddenPoint: HiddenPointType;
@@ -46,7 +62,10 @@ export const useRainDisasterChain = () => {
     conditions.value = value;
   }
 
-  // 修改页码
+  /**
+   * 修改页码
+   * @param value - 新的页码
+   */
   function changeCurrentPage(value: number) {
     paginationConfig.value.currentPage = value;
   }

src/hooks/rainstorm/useRainLegend.ts

@@ -6,9 +6,14 @@ import {
   waterLoggingIcon,
 } from '@/assets';
 
-// 引入图例钩子函数
+/**
+ * 暴雨图例钩子函数
+ * @returns 图例数据列表
+ */
 export const useRainLegend = () => {
-  // 图例数据
+  /**
+   * 图例数据
+   */
   const legendList = [
     { name: '滑坡隐患点', link: landslideIcon },
     { name: '泥石流隐患点', link: debrisFlowIcon },

src/hooks/useIndex.ts

@@ -1,8 +1,15 @@
 import { useRoute } from 'vue-router';
 
+/**
+ * 首页导航相关钩子函数
+ * @returns 顶部导航映射和激活状态判断函数
+ */
 export const useIndex = () => {
   const route = useRoute();
 
+  /**
+   * 顶部导航映射配置
+   */
   const topNavMap = [
     { title: '暴雨灾害链', name: 'rainstorm', query: { identification: 1 } },
     { title: '地震灾害链', name: 'earthquake', query: { identification: 2 } },
@@ -12,7 +19,11 @@ export const useIndex = () => {
     { title: '文件管理', name: 'index', query: { identification: 6 } },
   ];
 
-  // 判断当前导航项是否激活
+  /**
+   * 判断当前导航项是否激活
+   * @param identification - 导航项标识
+   * @returns 是否为激活状态
+   */
   const isActive = (identification: number) => {
     const targetId = identification.toString();
     let currentId = route.query.identification;

src/hooks/usePointsHandle.ts

@@ -10,11 +10,12 @@ import {
 
 /**
  * 公共批量处理点钩子函数
+ * @returns 添加点的方法
  */
 export const usePointsHandle = () => {
   /**
-   * 添加点
+   * 批量添加点
-   * @param points - 点数据
+   * @param points - 点数据数组
    * @param getDisasterIcon - 获取灾害图标的函数
    * @param prefix - 前缀
    * @returns 点的ID列表

src/stores/useCryptStore.ts

@@ -1,8 +1,14 @@
 import { defineStore } from 'pinia';
 import { type Ref, ref } from 'vue';
 
+/**
+ * 加密相关状态管理
+ * @returns SM2公钥状态
+ */
 export const useCryptStore = defineStore('crypt', () => {
-  // sm2公钥
+  /**
+   * SM2公钥
+   */
   const sm2PublicKey: Ref<string> = ref('');
 
   return { sm2PublicKey };

src/stores/useLoadingInformation.ts

@@ -3,23 +3,38 @@ import { defineStore } from 'pinia';
 import { type Ref, ref } from 'vue';
 
 /**
- * 加载信息弹窗相关参数
+ * 加载信息弹窗相关状态管理
+ * @returns 点击对象、隐患点/风险点状态及相关方法
  */
 export const useLoadingInformationStore = defineStore(
   'loadingInformation',
   () => {
-    // 点击的对象
+    /**
+     * 点击的对象
+     */
     const clickObject: Ref<ClickObject> = ref({ id: '', primitive: null });
 
-    // 隐患点
+    /**
+     * 隐患点加载状态
+     */
     const loadingHiddenPointInformationStatus: Ref<boolean> = ref(false);
+    /**
+     * 隐患点ID
+     */
     const hiddenPointId: Ref<number> = ref(-1);
 
-    // 风险点
+    /**
+     * 风险点加载状态
+     */
     const loadingRiskPointInformationStatus: Ref<boolean> = ref(false);
+    /**
+     * 风险点ID
+     */
     const riskPointId: Ref<number> = ref(-1);
 
-    // 重置状态
+    /**
+     * 重置状态
+     */
     const resetStatue = () => {
       loadingHiddenPointInformationStatus.value = false;
       hiddenPointId.value = -1;
@@ -27,26 +42,65 @@ export const useLoadingInformationStore = defineStore(
       riskPointId.value = -1;
     };
 
-    // get/set方法
+    /**
+     * 获取点击对象
+     * @returns 点击对象
+     */
     const getClickObject = () => clickObject.value;
+    /**
+     * 设置点击对象
+     * @param value - 点击对象
+     */
     const setClickObject = (value: ClickObject) => {
       clickObject.value = value;
     };
+    /**
+     * 获取隐患点加载状态
+     * @returns 加载状态
+     */
     const getLoadingHiddenPointInformationStatus = () =>
       loadingHiddenPointInformationStatus.value;
+    /**
+     * 设置隐患点加载状态
+     * @param value - 加载状态
+     */
     const setLoadingHiddenPointInformationStatus = (value: boolean) => {
       loadingHiddenPointInformationStatus.value = value;
     };
+    /**
+     * 获取风险点加载状态
+     * @returns 加载状态
+     */
     const getLoadingRiskPointInformationStatus = () =>
       loadingRiskPointInformationStatus.value;
+    /**
+     * 设置风险点加载状态
+     * @param value - 加载状态
+     */
     const setLoadingRiskPointInformationStatus = (value: boolean) => {
       loadingRiskPointInformationStatus.value = value;
     };
+    /**
+     * 获取隐患点ID
+     * @returns 隐患点ID
+     */
     const getHiddenPointId = () => hiddenPointId.value;
+    /**
+     * 设置隐患点ID
+     * @param value - 隐患点ID
+     */
     const setHiddenPointId = (value: number) => {
       hiddenPointId.value = value;
     };
+    /**
+     * 获取风险点ID
+     * @returns 风险点ID
+     */
     const getRiskPointId = () => riskPointId.value;
+    /**
+     * 设置风险点ID
+     * @param value - 风险点ID
+     */
     const setRiskPointId = (value: number) => {
       riskPointId.value = value;
     };

src/stores/useViewerStore.ts

@@ -1,12 +1,25 @@
 import { defineStore } from 'pinia';
 import { type Ref, ref } from 'vue';
 
+/**
+ * Viewer加载状态管理
+ * @returns Viewer加载完成状态及相关方法
+ */
 export const useViewerStore = defineStore('viewer', () => {
-  // viewer完成状态
+  /**
+   * Viewer加载完成状态
+   */
   const viewerLoadingCompleted: Ref<boolean> = ref(false);
 
-  // get/set方法
+  /**
+   * 获取Viewer加载完成状态
+   * @returns 加载完成状态
+   */
   const getViewerLoadingCompleted = () => viewerLoadingCompleted.value;
+  /**
+   * 设置Viewer加载完成状态
+   * @param value - 加载完成状态
+   */
   const setViewerLoadingCompleted = (value: boolean) => {
     viewerLoadingCompleted.value = value;
   };

src/types/ApiResponse.ts

@@ -1,5 +1,12 @@
+/**
+ * API响应数据结构
+ * @template T - 响应数据类型
+ */
 export interface ApiResponse<T = unknown> {
+  /** 状态码 */
   code: number;
+  /** 响应消息 */
   message: string;
+  /** 响应数据 */
   data: T;
 }

src/types/base/Point.ts

@@ -1,3 +1,6 @@
+/**
+ * 点类数据接口，与点相关数据需要继承该接口
+ */
 export interface Point {
   /** 序号 */
   id?: number;
@@ -5,7 +8,7 @@ export interface Point {
   lon?: number;
   /** 纬度 */
   lat?: number;
-  /** 空间 */
+  /** 空间几何数据 */
   geom?: string;
   /** 灾害类型 */
   disasterType?: string;

src/types/base/XianHiddenDangerSpots.ts

@@ -1,28 +1,28 @@
 import type { Point } from './Point';
 
 /**
- * 地质灾害隐患点
+ * 西安市地质灾害隐患点数据接口
  */
 export interface XianHiddenDangerSpots extends Point {
   /** 野外编号 */
   fieldCode?: string;
-  /** 省 */
+  /** 省名称 */
   province?: string;
   /** 省编号 */
   provinceId?: string;
-  /** 市 */
+  /** 市名称 */
   city?: string;
   /** 市编号 */
   cityId?: string;
-  /** 县 */
+  /** 县名称 */
   county?: string;
   /** 县编号 */
   countyId?: string;
-  /** 乡镇 */
+  /** 乡镇名称 */
   village?: string;
   /** 灾害点名称 */
   disasterName?: string;
-  /** 位置 */
+  /** 位置描述 */
   position?: string;
   /** 规模等级 */
   scaleGrade?: string;

src/types/base/XianRiskSpots.ts

@@ -1,5 +1,8 @@
 import type { Point } from './Point';
 
+/**
+ * 西安市风险点数据接口
+ */
 export interface XianRiskSpots extends Point {
   /** 风险区名称 */
   riskName?: string;
@@ -7,19 +10,19 @@ export interface XianRiskSpots extends Point {
   unitCode?: string;
   /** 风险区等级 */
   riskLevel?: string;
-  /** 面积 */
+  /** 面积（平方公里） */
   area?: number;
-  /** 省 */
+  /** 省名称 */
   province?: string;
-  /** 市 */
+  /** 市名称 */
   city?: string;
-  /** 县 */
+  /** 县名称 */
   county?: string;
-  /** 乡 */
+  /** 乡名称 */
   country?: string;
-  /** 村 */
+  /** 村名称 */
   village?: string;
-  /** 位置 */
+  /** 位置描述 */
   position?: string;
   /** 居民户数（户） */
   residentCounts?: number;
@@ -29,13 +32,13 @@ export interface XianRiskSpots extends Point {
   riskProperty?: number;
   /** 常住人口（人） */
   permanentPopulation?: number;
-  /** 住房（间） */
+  /** 住房数量（间） */
   housing?: number;
   /** 巡查员姓名 */
   inspectorName?: string;
   /** 巡查员电话 */
   inspectorTele?: string;
-  /** 空间 */
+  /** 空间几何数据 */
   geom?: string;
   /** 逻辑删除标识，0未删除，1已删除 */
   isDelete?: number;

src/types/cesium/CesiumInitOptions.ts

@@ -2,44 +2,57 @@ import type { Color } from 'cesium';
 import type { GeoJsonFileType } from './GeoJsonFileType';
 
 /**
- * Cesium 公共配置选项
+ * Cesium Viewer初始化配置选项
- * 用于初始化时统一配置 Viewer 参数
  */
 export interface CesiumInitOptions {
-  containerId: string; // 容器 DOM ID
+  /** 容器DOM ID */
-  terrain?: string; // 地形服务地址（默认：Cesium 内置地形）
+  containerId: string;
+  /** 地形服务地址 */
+  terrain?: string;
 
-  shouldAnimate?: boolean; // 是否自动播放动画(默认：true)
+  /** 是否自动播放动画，默认true */
-  baseLayerPicker?: boolean; // 是否显示图层选择器（默认：false）
+  shouldAnimate?: boolean;
-  timeline?: boolean; // 是否显示时间轴（默认：false）
+  /** 是否显示图层选择器，默认false */
-  animation?: boolean; // 是否显示动画控件（默认：false）
+  baseLayerPicker?: boolean;
-  infoBox?: boolean; // 是否显示信息框（默认：false）
+  /** 是否显示时间轴，默认false */
-  navigationHelpButton?: boolean; // 是否显示导航帮助按钮（默认：false）
+  timeline?: boolean;
-  fullscreenButton?: boolean; // 是否显示全屏按钮（默认：false）
+  /** 是否显示动画控件，默认false */
-  homeButton?: boolean; // 是否显示主页按钮（默认：false）
+  animation?: boolean;
-  scene3DOnly?: boolean; // 是否3D场景（默认：false）
+  /** 是否显示信息框，默认false */
-  sceneModePicker?: boolean; // 场景模式选择器（默认：false）
+  infoBox?: boolean;
-  geocoder?: boolean; // 搜索（默认：false）
+  /** 是否显示导航帮助按钮，默认false */
+  navigationHelpButton?: boolean;
+  /** 是否显示全屏按钮，默认false */
+  fullscreenButton?: boolean;
+  /** 是否显示主页按钮，默认false */
+  homeButton?: boolean;
+  /** 是否3D场景，默认false */
+  scene3DOnly?: boolean;
+  /** 场景模式选择器，默认false */
+  sceneModePicker?: boolean;
+  /** 搜索功能，默认false */
+  geocoder?: boolean;
 
-  sceneMode?: number; // 初始场景模式（默认：3D，可选：2D=1, COLUMBUS_VIEW=2）
+  /** 初始场景模式（2D=1, COLUMBUS_VIEW=2, 3D=3），默认3D */
+  sceneMode?: number;
 
-  // 遮罩配置
+  /** 遮罩配置 */
   mark?: {
-    // 是否包含遮罩，默认false
+    /** 是否包含遮罩，默认false */
     include?: boolean;
-    // GeoJSON 数据，如果要突出显示某一区域，就传递改值
+    /** GeoJSON数据，用于突出显示某一区域 */
     geoJson?: GeoJsonFileType;
-    // 孔属于半球，默认东半球
+    /** 孔洞属于半球，默认东半球 */
     belongingHemisphere?: 'east' | 'west';
-    // 遮罩颜色，默认黑色
+    /** 遮罩颜色，默认黑色 */
     color?: Color;
-    // 边框
+    /** 边框配置 */
     border?: {
-      // 是否显示边框，默认true
+      /** 是否显示边框，默认true */
       show?: boolean;
-      // 边框颜色，默认白色
+      /** 边框颜色，默认白色 */
       color?: Color;
-      // 边框宽度，默认1
+      /** 边框宽度，默认1 */
       width?: number;
     };
   };

src/types/cesium/ClickObject.ts

@@ -1,7 +1,13 @@
 import type { Billboard } from 'cesium';
 
+/**
+ * 点击对象接口
+ */
 export interface ClickObject {
+  /** 对象ID */
   id: string;
+  /** 其他属性 */
   [key: string]: unknown;
+  /** 图元对象 */
   primitive: Billboard | null;
 }

src/types/cesium/EntityOptions.ts

@@ -2,49 +2,76 @@ import type { Cartesian3, Color } from 'cesium';
 import { HeightReference, MaterialProperty } from 'cesium';
 
 /**
- * 实体配置通用类型
+ * 实体配置选项
- * 支持点、线、面、Billboard 等基础实体
+ * 支持点、线、面、Billboard等基础实体类型
  */
 export interface EntityOptions {
-  id: string; // 实体唯一标识（必填，用于后续查询/删除）
+  /** 实体唯一标识（必填，用于后续查询/删除） */
-  position: Cartesian3 | [number, number, number]; // 位置（经纬度高程数组 或 Cartesian3）
+  id: string;
-  type: 'point' | 'polyline' | 'billboard' | 'polygon'; // 实体类型
+  /** 位置（经纬度高程数组或Cartesian3） */
-  isDefault?: boolean; // 是否为默认实体，默认值false
+  position: Cartesian3 | [number, number, number];
-  // 点配置（type='point' 时必填）
+  /** 实体类型 */
+  type: 'point' | 'polyline' | 'billboard' | 'polygon';
+  /** 是否为默认实体，默认false */
+  isDefault?: boolean;
+  /** 点配置（type='point'时必填） */
   pointOptions?: {
-    color?: Color; // 颜色（默认：红色）
+    /** 颜色，默认红色 */
-    pixelSize?: number; // 像素大小（默认：8）
+    color?: Color;
-    outlineColor?: Color; // 轮廓颜色（默认：白色）
+    /** 像素大小，默认8 */
-    outlineWidth?: number; // 轮廓宽度（默认：1）
+    pixelSize?: number;
-    heightReference?: HeightReference; // 高度参考（默认：CLAMP_TO_GROUND）
+    /** 轮廓颜色，默认白色 */
+    outlineColor?: Color;
+    /** 轮廓宽度，默认1 */
+    outlineWidth?: number;
+    /** 高度参考，默认CLAMP_TO_GROUND */
+    heightReference?: HeightReference;
   };
-  // 线配置（type='polyline' 时必填）
+  /** 线配置（type='polyline'时必填） */
   polylineOptions?: {
-    positions: Cartesian3[] | [number, number, number][]; // 线顶点数组
+    /** 线顶点数组 */
-    color?: Color; // 颜色（默认：蓝色）
+    positions: Cartesian3[] | [number, number, number][];
-    width?: number; // 线宽（默认：3）
+    /** 颜色，默认蓝色 */
-    clampToGround?: boolean; // 是否贴地（默认：false）
+    color?: Color;
+    /** 线宽，默认3 */
+    width?: number;
+    /** 是否贴地，默认false */
+    clampToGround?: boolean;
   };
-  // Billboard 配置（type='billboard' 时必填）
+  /** Billboard配置（type='billboard'时必填） */
   billboardOptions?: {
-    image: string; // 图片地址
+    /** 图片地址 */
-    scale?: number; // 缩放比例（默认：1）
+    image: string;
-    color?: Color; // 颜色（默认：白色）
+    /** 缩放比例，默认1 */
-    verticalOrigin?: number; // 垂直对齐方式（默认：CENTER）
+    scale?: number;
-    horizontalOrigin?: number; // 水平对齐方式（默认：CENTER）
+    /** 颜色，默认白色 */
-    heightReference?: HeightReference; // 高度参考（默认：CLAMP_TO_GROUND）
+    color?: Color;
+    /** 垂直对齐方式，默认CENTER */
+    verticalOrigin?: number;
+    /** 水平对齐方式，默认CENTER */
+    horizontalOrigin?: number;
+    /** 高度参考，默认CLAMP_TO_GROUND */
+    heightReference?: HeightReference;
   };
-  // 面配置（type='polygon' 时必填）
+  /** 面配置（type='polygon'时必填） */
   polygonOptions?: {
-    hierarchy: Cartesian3[] | [number, number, number][]; // 面顶点数组
+    /** 面顶点数组 */
-    // color?: Color // 颜色（默认：绿色）
+    hierarchy: Cartesian3[] | [number, number, number][];
-    outline?: boolean; // 是否显示轮廓（默认：true）
+    /** 是否显示轮廓，默认true */
-    outlineColor?: Color; // 轮廓颜色（默认：黑色）
+    outline?: boolean;
-    outlineWidth?: number; // 轮廓宽度（默认：1）
+    /** 轮廓颜色，默认黑色 */
-    height?: number; // 高度（默认：0）
+    outlineColor?: Color;
-    extrudedHeight?: number; //  extrudedHeight 高度（默认：0）
+    /** 轮廓宽度，默认1 */
-    heightReference?: HeightReference; // 高度参考（默认：CLAMP_TO_GROUND）
+    outlineWidth?: number;
-    material?: MaterialProperty; // 材质（默认：Color.WHITE）
+    /** 高度，默认0 */
+    height?: number;
+    /** 拉伸高度，默认0 */
+    extrudedHeight?: number;
+    /** 高度参考，默认CLAMP_TO_GROUND */
+    heightReference?: HeightReference;
+    /** 材质，默认Color.WHITE */
+    material?: MaterialProperty;
   };
-  attributes?: Record<string, unknown>; // 自定义属性（用于存储额外信息）
+  /** 自定义属性（用于存储额外信息） */
+  attributes?: Record<string, unknown>;
 }

src/types/cesium/GeoJsonFileType.ts

@@ -1,5 +1,10 @@
+/**
+ * GeoJSON文件类型接口
+ */
 export interface GeoJsonFileType {
+  /** 类型，固定为FeatureCollection */
   type: 'FeatureCollection';
+  /** 要素数组 */
   features: {
     geometry: {
       coordinates: number[][][][];

src/types/cesium/GeoJsonOptions.ts

@@ -1,32 +1,56 @@
 import type { Cartesian3, Color, DataSource } from 'cesium';
 import type { LabelConfig } from './LabelConfig';
 
-// 数据源：字符串路径/URL | GeoJSON对象
+/**
+ * GeoJSON数据源类型：字符串路径/URL或GeoJSON对象
+ */
 export type CustomizeGeoJsonDataSource = string | object;
 
-// 唯一配置项接口
+/**
+ * GeoJSON图层配置选项
+ */
 export interface GeoJsonOptions {
+  /** 是否显示名称 */
   showName?: boolean;
+  /** 是否为默认图层 */
   isDefault?: boolean;
+  /** 标签样式配置 */
   labelStyle?: LabelConfig;
+  /** 多边形样式配置 */
   polygonStyle?: {
+    /** 是否填充 */
     fill?: boolean;
+    /** 填充颜色 */
     fillColor?: Color;
+    /** 是否显示轮廓 */
     outline?: boolean;
+    /** 轮廓颜色 */
     outlineColor?: Color;
+    /** 轮廓宽度 */
     outlineWidth?: number;
+    /** 中心点位置 */
     center?: Cartesian3 | [number, number, number];
   };
+  /** 线样式配置 */
   polylineStyle?: {
+    /** 线宽 */
     width?: number;
+    /** 材质颜色 */
     material?: Color;
+    /** 是否贴地 */
     clampToGround?: boolean;
   };
+  /** 点样式配置 */
   pointStyle?: {
+    /** 像素大小 */
     pixelSize?: number;
+    /** 颜色 */
     color?: Color;
+    /** 轮廓颜色 */
     outlineColor?: Color;
+    /** 轮廓宽度 */
     outlineWidth?: number;
   };
+  /** 加载完成回调 */
   onComplete?: (dataSource: DataSource) => void;
 }

src/types/cesium/LabelConfig.ts

@@ -5,14 +5,26 @@ import type {
   VerticalOrigin,
 } from 'cesium';
 
+/**
+ * 标签配置接口
+ */
 export interface LabelConfig {
-  labelText?: string; // 文本，默认空白
+  /** 文本内容，默认空白 */
-  labelFont?: string; // 字体样式，默认16px "微软雅黑"
+  labelText?: string;
-  labelColor?: Color; // 标签颜色， 默认白色
+  /** 字体样式，默认16px "微软雅黑" */
-  labelSize?: number; // 字体大小，默认16
+  labelFont?: string;
-  labelOffset?: { x: number; y: number }; // 标签偏移，默认0,0
+  /** 标签颜色，默认白色 */
-  horizontalOrigin?: HorizontalOrigin; // 水平位置，默认居中
+  labelColor?: Color;
-  verticalOrigin?: VerticalOrigin; // 垂直位置，默认居中
+  /** 字体大小，默认16 */
-  backgroundColor?: Color; // 背景颜色，默认透明
+  labelSize?: number;
+  /** 标签偏移，默认{x:0, y:0} */
+  labelOffset?: { x: number; y: number };
+  /** 水平位置，默认居中 */
+  horizontalOrigin?: HorizontalOrigin;
+  /** 垂直位置，默认居中 */
+  verticalOrigin?: VerticalOrigin;
+  /** 背景颜色，默认透明 */
+  backgroundColor?: Color;
+  /** 中心点位置 */
   center?: Cartesian3 | [number, number, number];
 }

src/types/cesium/LayerConfig.ts

@@ -1,20 +1,31 @@
+/**
+ * 图层配置接口
+ */
 export interface LayerConfig {
-  id: string; // 唯一id
+  /** 唯一ID */
+  id: string;
 
-  type: 'imagery' | 'wms' | 'wmts'; // 图层类型，支持iimagery, Geoserver WMS, Geoserver WMTS
+  /** 图层类型，支持imagery、wms、wmts */
-  provider: string; // 图层提供者
+  type: 'imagery' | 'wms' | 'wmts';
-  url: string; // 图层地址
+  /** 图层提供者 */
-  layers: string; // 图层名称
+  provider: string;
+  /** 图层地址 */
+  url: string;
+  /** 图层名称 */
+  layers: string;
 
-  isDefault?: boolean; // 是否为默认图层，默认值false
+  /** 是否为默认图层，默认false */
+  isDefault?: boolean;
 
-  /**
+  /** WMTS图层样式，默认default */
-   * WMTS 图层参数
+  style?: string;
-   */
+  /** WMTS图层格式，默认image/png */
-  style?: string; // 图层样式，默认为default
+  format?: string;
-  format?: string; // 图层格式，默认为image/png
+  /** WMTS瓦片矩阵集ID，默认EPSG:4326 */
-  tileMatrixSetID?: string; // 瓦片矩阵集ID，默认为EPSG:4326
+  tileMatrixSetID?: string;
-  credit?: string; // 图层版权信息，默认为空
+  /** WMTS图层版权信息，默认空 */
+  credit?: string;
 
-  parameters?: Record<string, string>; // 图层参数
+  /** 图层参数 */
+  parameters?: Record<string, string>;
 }

src/types/cesium/PrimitiveOptions.ts

@@ -1,15 +1,29 @@
 import type { Cartesian3, Color, NearFarScalar } from 'cesium';
 
+/**
+ * Primitive图元配置选项
+ */
 export interface PrimitiveOptions {
+  /** 唯一ID */
   id: string;
+  /** 图元类型 */
   type: 'point' | 'polyline' | 'polygon' | 'billboard';
-  positions: [number, number, number][] | Cartesian3[]; // 点集合，线和面需要多个点
+  /** 点集合，线和面需要多个点 */
-  isDefault?: boolean; // 是否为默认图元，默认值false
+  positions: [number, number, number][] | Cartesian3[];
+  /** 是否为默认图元，默认false */
+  isDefault?: boolean;
+  /** 颜色 */
   color?: Color;
-  pixelSize?: number; // 点大小
+  /** 点大小 */
-  width?: number; // 线宽
+  pixelSize?: number;
-  image?: string; // 广告牌图片
+  /** 线宽 */
-  scale?: number; // 广告牌缩放
+  width?: number;
-  scaleByDistance?: NearFarScalar; // 广告牌距离衰减缩放
+  /** 广告牌图片 */
-  customProperties?: Record<string, unknown>; // 自定义属性对象
+  image?: string;
+  /** 广告牌缩放 */
+  scale?: number;
+  /** 广告牌距离衰减缩放 */
+  scaleByDistance?: NearFarScalar;
+  /** 自定义属性对象 */
+  customProperties?: Record<string, unknown>;
 }

src/types/common/DisasterType.ts

@@ -1,12 +1,23 @@
+/**
+ * 灾害类型枚举
+ */
 export enum DisasterType {
+  /** 暴雨 */
   RAINSTORM = 'rainstorm',
+  /** 地震 */
   EARTHQUAKE = 'earthquake',
 }
 
-// 隐患点类型
+/**
+ * 隐患点类型枚举
+ */
 export enum HiddenPointType {
+  /** 滑坡 */
   LANDSLIDE = '滑坡',
+  /** 泥石流 */
   DEBRIS_FLOW = '泥石流',
+  /** 内涝 */
   WATERLOGGING = '内涝',
+  /** 山洪 */
   FLASH_FLOOD = '山洪',
 }

src/types/common/PaginationType.ts

@@ -1,6 +1,13 @@
+/**
+ * 分页配置接口
+ */
 export interface PaginationType {
+  /** 当前页码 */
   currentPage: number;
+  /** 每页数量 */
   pageSize: number;
+  /** 总记录数 */
   total: number;
+  /** 总页数 */
   totalPage: number;
 }

src/types/crypto/Sm2PublicKeyResponse.ts

@@ -1,6 +1,7 @@
+/**
+ * SM2公钥响应接口
+ */
 export interface Sm2PublicKeyResponse {
-  /**
+  /** SM2公钥 */
-   * 公钥
-   */
   publicKey: string;
 }

src/utils/request/http.ts

@@ -15,6 +15,10 @@ declare module 'axios' {
   }
 }
 
+/**
+ * Axios HTTP请求实例
+ * 包含请求/响应拦截器，支持SM2/SM4加密解密
+ */
 const httpInstance = axios.create({
   baseURL: configJson.apiBaseUrl,
   timeout: 15000, // 增加超时时间

src/utils/safety/SafetyUtils.ts

@@ -12,9 +12,14 @@ const SM4_MODE = SM4.constants.ECB;
 const SM4_INPUT_ENCODING = 'utf8';
 const SM4_OUTPUT_ENCODING = 'hex';
 
+/**
+ * 安全工具类
+ * 提供SM2/SM4加密解密功能
+ */
 export const SafetyUtils = {
   /**
    * 获取SM2公钥
+   * @returns SM2公钥
    */
   getSm2PublicKey: async (): Promise<string> => {
     const cryptStore = useCryptStore();
@@ -32,7 +37,8 @@ export const SafetyUtils = {
   },
 
   /**
-   * 生成随机SM4密钥（16字节=32位十六进制字符串）
+   * 生成随机SM4密钥（16字节）
+   * @returns SM4密钥
    */
   generateSm4Key: (): string => {
     return SafetyUtils._generateRandomHex(16);
@@ -40,6 +46,9 @@ export const SafetyUtils = {
 
   /**
    * SM2非对称加密（公钥加密）
+   * @param data - 待加密数据
+   * @param publicKey - 公钥（可选）
+   * @returns 加密后的数据
    */
   sm2Encrypt: async (
     data: object | string,
@@ -65,6 +74,9 @@ export const SafetyUtils = {
 
   /**
    * SM2非对称解密（私钥解密）
+   * @param data - 待解密数据
+   * @param privateKey - 私钥
+   * @returns 解密后的数据
    */
   sm2Decrypt: async (data: string, privateKey: string): Promise<string> => {
     try {
@@ -81,6 +93,9 @@ export const SafetyUtils = {
 
   /**
    * SM4对称加密（ECB模式）
+   * @param key - 密钥
+   * @param data - 待加密数据
+   * @returns 加密后的数据
    */
   sm4Encrypt: (key: string, data: object | string): string => {
     try {
@@ -98,6 +113,9 @@ export const SafetyUtils = {
 
   /**
    * SM4对称解密（ECB模式）
+   * @param key - 密钥
+   * @param encryptedData - 待解密数据
+   * @returns 解密后的数据
    */
   sm4Decrypt: (key: string, encryptedData: string): object | string => {
     try {
@@ -121,6 +139,9 @@ export const SafetyUtils = {
 
   /**
    * 加密FormData中的普通字段
+   * @param key - 密钥
+   * @param formData - 表单数据
+   * @returns 加密后的表单数据
    */
   encryptFormData: (key: string, formData: FormData): FormData => {
     const encryptedFormData = new FormData();
@@ -141,6 +162,8 @@ export const SafetyUtils = {
 
   /**
    * 生成指定长度的随机十六进制字符串
+   * @param length - 长度
+   * @returns 随机十六进制字符串
    */
   _generateRandomHex: (length: number): string => {
     const uint8Array = new Uint8Array(length);

src/utils/utils.ts

@@ -36,6 +36,12 @@ export const Utils = {
     };
   },
 
+  /**
+   * 日期格式化函数
+   * @param format - 格式化字符串（支持YYYY、MM、DD、HH、mm、ss等）
+   * @param date - 日期对象，默认为当前时间
+   * @returns 格式化后的日期字符串
+   */
   formatDate: (format: string, date: Date = new Date()): string => {
     // 基础时间数据
     const year = date.getFullYear();