@taichina/map-sdk 1.0.0

package/README.md

@@ -0,0 +1,169 @@
+# teee-map-sdk
+
+基于 [maplibre-gl](https://maplibre.org/) 封装的铁路 GIS 业务地图 SDK，面向太昌 GIS 业务流提供开箱即用的地图初始化、图层管理、要素状态控制、加密瓦片及离线包支持。
+
+## 安装
+
+```bash
+npm install
+git submodule update --init --recursive
+```
+
+## 快速开始
+
+```typescript
+import { TeeeMap } from "teee-map-sdk";
+
+const teeeMap = new TeeeMap("map-container");
+
+// CTC 施工推演图
+teeeMap.createCTCMap("ST-001", "https://tiles.example.com/{z}/{x}/{y}", [
+  "track",
+  "signal",
+  "switch",
+]);
+
+// 获取底层 maplibre 实例
+const map = teeeMap.getMap();
+```
+
+## 引入方式
+
+```html
+<!-- UMD -->
+<script src="teee-sdk/teee-map-sdk.umd.js"></script>
+<script>
+  const map = new TeeeMapSDK.TeeeMap("map");
+</script>
+```
+
+```typescript
+// ES Module
+import { TeeeMap } from "teee-map-sdk";
+```
+
+## API
+
+### 构造函数
+
+```typescript
+new TeeeMap(container: string | HTMLElement, mbtileDbClient?: any)
+```
+
+| 参数 | 说明 |
+|------|------|
+| `container` | DOM 元素 ID 或 HTMLElement |
+| `mbtileDbClient` | 可选。SQLite 客户端（需具备 `prepare` / `get` / `free` 方法），传入后启用 `mbtiles://` 协议 |
+
+### 地图创建方法
+
+| 方法 | 说明 |
+|------|------|
+| `createCTCMap(stcode, url, layers)` | CTC 施工推演 / 站场平面图 |
+| `createCTCEncryptedMap(stcode, url, layers)` | 加密 CTC 图 |
+| `createGraphMap(stcode, url, layers)` | 普通站场平面图 |
+| `createGraphEncryptedMap(stcode, url, layers)` | 加密平面图 |
+| `createGeomMap(stcode, url, layers)` | 地理图（EPSG:4326 / 4490） |
+| `createGeomEncryptedMap(stcode, url, layers)` | 加密地理图 |
+| `createRasterMap(url)` | 影像 / 栅格底图 |
+| `createEncryptedRasterMap(url)` | 加密栅格图 |
+| `createRSWPMap(url)` | 人员定位图（栅格 + GeoJSON） |
+| `createRAGEMap(url, subUrl, code)` | 信息所综合业务图 |
+| `createMbtilesMap(url, layers)` | MBTiles 离线包 |
+
+### 数据源管理
+
+| 方法 | 说明 |
+|------|------|
+| `addGeoJsonSource(id, data?)` | 添加 GeoJSON 源 |
+| `addVectorTileSource(id, url)` | 添加矢量瓦片源 |
+| `addRasterTileSource(id, url)` | 添加栅格瓦片源 |
+| `updateGeoJsonSource(id, data)` | 更新 GeoJSON 数据 |
+| `removeSource(id)` | 移除数据源 |
+
+### 图层管理
+
+| 方法 | 说明 |
+|------|------|
+| `addGeoJsonLayer(layerId, sourceId, type?, paint?, layout?)` | 添加 GeoJSON 图层 |
+| `updateLayerStyle(id, paint)` | 动态修改图层 paint 样式 |
+| `removeLayer(id)` | 移除图层 |
+
+### 要素状态管理（CTC 业务）
+
+| 方法 | 说明 |
+|------|------|
+| `stashAllFeature()` | 缓存当前视口全部要素（首次 idle 自动执行） |
+| `updateFeatureState(code, state)` | 更新要素状态，如封锁、停电、选中等 |
+| `initCTCFeatureState(feature)` | 为单个要素初始化 CTC 业务状态 |
+
+```typescript
+teeeMap.updateFeatureState("DG-102", {
+  state: "1",     // 股道封锁
+  select: true,   // 选中
+});
+```
+
+### 交互事件
+
+```typescript
+teeeMap.onFeatureClick("layer-id", (feature, lngLat) => {
+  console.log(feature.properties.code);
+});
+```
+
+### 绘制工具
+
+地图 `load` 完成后，`drawTool` 会自动挂载：
+
+```typescript
+const draw = teeeMap.drawTool;
+draw.changeMode("polygon");        // 切换绘制模式
+draw.onFinish((geojson) => {...}); // 绑定完成回调
+draw.clear();                      // 清空画布
+```
+
+### 其他
+
+| 方法 | 说明 |
+|------|------|
+| `getMap()` | 获取底层 `maplibregl.Map` 实例 |
+| `getMapConfigs()` | 获取当前 `MapForgeConfig` |
+| `destroy()` | 销毁地图实例 |
+
+### LayerType
+
+```typescript
+type LayerType =
+  | "background" | "track" | "track_circuit"
+  | "signal" | "switch" | "switch_loc"
+  | "bumper" | "insulation" | "label" | "prevention";
+```
+
+## 构建
+
+```bash
+npm run build          # 输出到 teee-sdk/
+```
+
+## 项目结构
+
+```
+├── src/
+│   ├── index.ts          # SDK 入口，导出 TeeeMap
+│   ├── teee-map/         # 核心 SDK（git 子模块，含详细设计文档）
+│   └── map-const/        # 地图常量 & 枚举（git 子模块）
+├── teee-sdk/             # 构建产物（.es.js / .umd.js / .css）
+├── SDK/                  # 示例 HTML 页面 + SDK 副本
+├── vite.config.ts        # Vite library mode 配置
+└── tsconfig.json
+```
+
+核心 SDK 采用工厂模式：[MapForge](src/teee-map/map-forge/) 生成配置 → [SourceFactory](src/teee-map/source/) 生成数据源 → [LayerFactory](src/teee-map/layers/) 生成图层 → [ToolFactory](src/teee-map/utils/) 注册交互工具。详见 [src/teee-map/DESIGN.md](src/teee-map/DESIGN.md)。
+
+## 依赖
+
+- **maplibre-gl** ^5.24.0 — 地图渲染引擎
+- **pako** ^2.1.0 — MBTiles Gzip 解压
+- **@watergis/maplibre-gl-terradraw** ^1.13.1 — 绘制工具
+- **TypeScript** ^6.0.3 / **Vite** ^8.0.10（开发依赖）

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@taichina/map-sdk",
+  "version": "1.0.0",
+  "description": "基于 GIS 的铁路业务地图 SDK。",
+  "type": "module",
+  "main": "./teee-sdk/teee-map-sdk.umd.js",
+  "module": "./teee-sdk/teee-map-sdk.es.js",
+  "types": "./teee-sdk/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./teee-sdk/index.d.ts",
+      "import": "./teee-sdk/teee-map-sdk.es.js",
+      "require": "./teee-sdk/teee-map-sdk.umd.js",
+      "default": "./teee-sdk/teee-map-sdk.es.js"
+    },
+    "./teee-sdk/*": "./teee-sdk/*"
+  },
+  "files": [
+    "teee-sdk"
+  ],
+  "scripts": {
+    "build": "vite build && node -e \"require('fs').copyFileSync('src/types/public-api.d.ts', 'teee-sdk/index.d.ts')\"",
+    "update-submodule": "git submodule update --remote --merge",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "gis",
+    "railway",
+    "map"
+  ],
+  "author": "gengar_chhkkk",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "maplibre-gl": "^5.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "maplibre-gl": "^5.24.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10"
+  },
+  "dependencies": {
+    "@turf/bbox": "^7.0.0",
+    "@watergis/maplibre-gl-terradraw": "^1.13.1",
+    "pako": "^2.1.0"
+  }
+}

package/teee-sdk/index.d.ts

@@ -0,0 +1,181 @@
+import type { Map as MaplibreMap, GeoJSONFeature, LngLat, SourceSpecification } from 'maplibre-gl';
+
+/** 地图图层类型 */
+export type LayerType =
+  | 'station'
+  | 'track'
+  | 'signal'
+  | 'switch'
+  | 'switch_loc'
+  | 'insulation'
+  | 'station_track'
+  | 'platform'
+  | 'crossing'
+  | 'bridge'
+  | 'tunnel'
+  | 'culvert'
+  | 'mileage'
+  | string;
+
+/** 地图初始化参数 */
+export interface MapParams {
+  id: string;
+  source: SourceSpecification | SourceSpecification[];
+  layers?: unknown[];
+  subSourceId?: string;
+  subSource?: SourceSpecification;
+}
+
+/** 画笔工具接口 */
+export interface DrawTool {
+  changeMode(mode: string): void;
+  setOnFinish(cb: (feature: unknown) => void): void;
+  setOnChange(cb: (feature: unknown) => void): void;
+  setOnDelete(cb: (feature: unknown) => void): void;
+  setOnSelect(cb: (id: string | number) => void): void;
+}
+
+/**
+ * TeeeMap 实例对外暴露的公共接口。
+ */
+export interface TeeeMap {
+  /** 底层 maplibre-gl Map 实例 */
+  readonly map: MaplibreMap;
+
+  /** 添加 GeoJSON 数据源 */
+  addGeoJsonSource(id: string, data?: GeoJSON.GeoJSON | string): void;
+  /** 移除指定数据源 */
+  removeSource(id: string): void;
+  /** 更新 GeoJSON 数据源内容 */
+  updateGeoJsonSource(id: string, data: GeoJSON.GeoJSON | string): void;
+  /** 添加矢量瓦片数据源 */
+  addVectorTileSource(id: string, url: string): void;
+  /** 添加栅格瓦片数据源 */
+  addRasterTileSource(id: string, url: string): void;
+  /** 添加 GeoJSON 图层 */
+  addGeoJsonLayer(
+    layerId: string,
+    sourceId: string,
+    type?: 'fill' | 'line' | 'circle' | 'symbol',
+    paint?: Record<string, unknown>,
+    layout?: Record<string, unknown>,
+  ): void;
+  /** 动态更新图层 paint 样式 */
+  updateLayerStyle(id: string, paint: Record<string, unknown>): void;
+  /** 移除指定图层 */
+  removeLayer(id: string): void;
+  /** 为指定图层绑定要素点击事件 */
+  onFeatureClick(
+    layerIds: string | string[],
+    callback: (feature: GeoJSONFeature, lngLat: LngLat) => void,
+  ): void;
+
+  /** 销毁地图实例并释放资源 */
+  destroy(): void;
+  /** 初始化地图基础状态 */
+  initState(): void;
+  /** 为指定要素初始化 CTC 业务状态 */
+  initCTCFeatureState(f: GeoJSONFeature): void;
+  /** 为指定要素初始化 Graph 业务状态 */
+  initGraphFeatureState(f: GeoJSONFeature): void;
+  /** 为指定要素初始化 GeoJSON 图层业务状态 */
+  initGeoJsonFeatureState(f: GeoJSONFeature, layerType: string): void;
+  /** 初始化 GeoJSON 业务状态 */
+  initGeoJsonState(): void;
+
+  /** 更新要素业务状态 */
+  updateFeatureState(code: string | number, state: Record<string, unknown>): void;
+  /** 获取要素业务状态 */
+  getFeatureState(code: string | number): Record<string, unknown> | undefined;
+
+  /** 画笔工具实例（地图 load 后挂载） */
+  readonly drawTool?: DrawTool;
+
+  /** 创建 CTC 施工推演 / 站场平面图 */
+  createCTCMap(stcode: string, url: string, layers: LayerType[]): void;
+  /** 创建加密 CTC 施工推演 / 站场平面图 */
+  createCTCEncryptedMap(stcode: string, url: string, layers: LayerType[]): void;
+  /** 创建人员定位图（RSWP） */
+  createRSWPMap(url: string): void;
+  /** 创建普通站场平面图（Graph） */
+  createGraphMap(stcode: string, url: string, layers: LayerType[]): void;
+  /** 创建加密站场平面图（Graph） */
+  createGraphEncryptedMap(stcode: string, url: string, layers: LayerType[]): void;
+  /** 创建地理地图（Geom） */
+  createGeomMap(stcode: string, url: string, layers: LayerType[]): void;
+  /** 创建加密地理地图（Geom） */
+  createGeomEncryptedMap(stcode: string, url: string, layers: LayerType[]): void;
+  /** 创建 GeoJSON 站场图 */
+  createGeoJsonStationMap(stcode: string, url: string, layers: LayerType[]): Promise<void>;
+  /** 创建栅格影像地图 */
+  createRasterMap(url: string): void;
+  /** 创建加密栅格影像地图 */
+  createEncryptedRasterMap(url: string): void;
+  /** 创建 RAGE 地图 */
+  createRAGEMap(url: string, subUrl: string, code: string): void;
+  /** 获取 maplibre-gl Map 实例 */
+  getMap(): MaplibreMap;
+}
+
+/**
+ * 太昌业务地图 SDK 主类。
+ * 基于 maplibre-gl 封装，提供一键式地图初始化、图层管理、要素状态控制、加密瓦片及离线包支持。
+ *
+ * @example
+ * ```ts
+ * import { TeeeMap } from '@teee/map-sdk';
+ * import maplibregl from 'maplibre-gl';
+ *
+ * const teeeMap = new TeeeMap('map-container');
+ * teeeMap.createCTCMap('1234', 'https://tiles.example.com/{z}/{x}/{y}', ['station', 'track', 'signal']);
+ * ```
+ */
+export declare class TeeeMap {
+  constructor(container: string | HTMLElement);
+
+  /** 底层 maplibre-gl Map 实例 */
+  readonly map: MaplibreMap;
+
+  addGeoJsonSource(id: string, data?: GeoJSON.GeoJSON | string): void;
+  removeSource(id: string): void;
+  updateGeoJsonSource(id: string, data: GeoJSON.GeoJSON | string): void;
+  addVectorTileSource(id: string, url: string): void;
+  addRasterTileSource(id: string, url: string): void;
+  addGeoJsonLayer(
+    layerId: string,
+    sourceId: string,
+    type?: 'fill' | 'line' | 'circle' | 'symbol',
+    paint?: Record<string, unknown>,
+    layout?: Record<string, unknown>,
+  ): void;
+  updateLayerStyle(id: string, paint: Record<string, unknown>): void;
+  removeLayer(id: string): void;
+  onFeatureClick(
+    layerIds: string | string[],
+    callback: (feature: GeoJSONFeature, lngLat: LngLat) => void,
+  ): void;
+
+  destroy(): void;
+  initState(): void;
+  initCTCFeatureState(f: GeoJSONFeature): void;
+  initGraphFeatureState(f: GeoJSONFeature): void;
+  initGeoJsonFeatureState(f: GeoJSONFeature, layerType: string): void;
+  initGeoJsonState(): void;
+  updateFeatureState(code: string | number, state: Record<string, unknown>): void;
+  getFeatureState(code: string | number): Record<string, unknown> | undefined;
+
+  readonly drawTool?: DrawTool;
+
+  createCTCMap(stcode: string, url: string, layers: LayerType[]): void;
+  createCTCEncryptedMap(stcode: string, url: string, layers: LayerType[]): void;
+  createRSWPMap(url: string): void;
+  createGraphMap(stcode: string, url: string, layers: LayerType[]): void;
+  createGraphEncryptedMap(stcode: string, url: string, layers: LayerType[]): void;
+  createGeomMap(stcode: string, url: string, layers: LayerType[]): void;
+  createGeomEncryptedMap(stcode: string, url: string, layers: LayerType[]): void;
+  createGeoJsonStationMap(stcode: string, url: string, layers: LayerType[]): Promise<void>;
+  createRasterMap(url: string): void;
+  createEncryptedRasterMap(url: string): void;
+  createRAGEMap(url: string, subUrl: string, code: string): void;
+  getMap(): MaplibreMap;
+}