diff --git a/suite-developer/knowledge/script-data-types.md b/suite-developer/knowledge/script-data-types.md deleted file mode 100644 index 8d8a741..0000000 --- a/suite-developer/knowledge/script-data-types.md +++ /dev/null @@ -1,263 +0,0 @@ -# 脚本数据类型分类规范 - -> **归属：** SuiteForge 知识库 | `knowledge/script-data-types.md` -> **版本：** 1.0.0 -> **合规检测依赖：** 合规检测服务 `compliance-service` 遵守同一分类标准 - ---- - -## 1. 分类原则 - -脚本按**所处理的主要数据类型**分类，而非按业务场景分类。 - -**为什么这么分：** -- 业务场景是套件层级的组织维度（套件按业务分类） -- 数据处理能力是可复用的基础单元（脚本按数据类型分类） -- 参数规范服务（合规检测）需要根据数据类型校验参数定义 - -**一个脚本只能声明一个主输入数据类型**，但可声明多个输出数据类型。 - ---- - -## 2. 分类体系 - -### 2.1 矢量数据（Vector） - -处理几何要素数据（点、线、面），含空间参考。 - -| 子类型 | 扩展名 | MIME / 格式标识 | 说明 | -|--------|--------|-----------------|------| -| `shapefile` | `.shp` | `application/x-shapefile` | ESRI Shapefile（必须打包为 .zip 上传） | -| `geojson` | `.geojson` `.json` | `application/geo+json` | GeoJSON（RFC 7946） | -| `geopackage` | `.gpkg` | `application/geopackage+vnd.sqlite3` | OGC GeoPackage 矢量层 | -| `filegdb` | `.gdb/` | `application/x-filegdb` | ESRI File Geodatabase（目录结构） | -| `dxf` | `.dxf` | `application/dxf` | AutoCAD DXF | -| `dwg` | `.dwg` | `application/acad` | AutoCAD DWG（需许可或 ODA 库） | -| `kml` | `.kml` | `application/vnd.google-earth.kml+xml` | Google KML | -| `kmz` | `.kmz` | `application/vnd.google-earth.kmz` | Google KMZ（压缩包） | -| `gml` | `.gml` | `application/gml+xml` | OGC GML | -| `mif` | `.mif` | `application/x-mapinfo-mif` | MapInfo MIF/MID | -| `tab` | `.tab` | `application/x-mapinfo-tab` | MapInfo TAB | -| `mdb` | `.mdb` | `application/x-msaccess` | Personal GeoDatabase（.mdb 格式） | -| `geobuf` | `.geobuf` | `application/geobuf` | Mapbox Geobuf（高效二进制） | -| `flatgeobuf` | `.fgb` | `application/flatgeobuf` | FlatGeobuf（流式加载优化） | - -### 2.2 栅格数据（Raster） - -处理像素格网数据，含地理参考。 - -| 子类型 | 扩展名 | 格式标识 | 说明 | -|--------|--------|---------|------| -| `geotiff` | `.tif` `.tiff` | `image/tiff; application=geotiff` | GeoTIFF（最通用） | -| `img` | `.img` | `application/x-erdas-img` | ERDAS IMAGINE | -| `dem` | `.dem` | `application/x-usgs-dem` | USGS DEM | -| `lerc` | `.lerc` | `application/lerc` | ESRI LERC（流式压缩） | -| `mrf` | `.mrf` | `application/x-mrf` | Meta Raster Format | -| `ecw` | `.ecw` | `image/ecw` | ERDAS ECW（压缩速率优化） | -| `jp2` | `.jp2` `.j2k` | `image/jp2` | JPEG 2000（含 GeoJP2） | -| `hfa` | `.hfa` | `application/x-erdas-hfa` | ERDAS HFA / Imagine | -| `nitf` | `.ntf` `.nitf` | `application/x-nitf` | NITF（军事/情报影像） | -| `hdf` | `.hdf` `.h5` | `application/x-hdf` | HDF4/HDF5（遥感常用） | -| `netcdf` | `.nc` | `application/x-netcdf` | NetCDF（气候/海洋数据） | -| `grib` | `.grib` `.grb` `.grib2` | `application/x-grib` | GRIB/GRIB2（气象数据） | -| `cog` | `.tif` | `image/tiff; application=cog` | Cloud Optimized GeoTIFF | -| `asc` | `.asc` | `application/x-esri-asc` | ESRI ASCII Grid | -| `dtm` | `.dtm` | `application/x-dtm` | DTM（数字地形模型，常无扩展名区分） | - -### 2.3 三维点云数据（Point Cloud） - -处理三维空间离散点数据。 - -| 子类型 | 扩展名 | 格式标识 | 说明 | -|--------|--------|---------|------| -| `las` | `.las` | `application/x-las` | ASPRS LAS 1.2/1.4 | -| `laz` | `.laz` | `application/x-laz` | LASzip 压缩 | -| `e57` | `.e57` | `application/x-e57` | ASTM E57 3D | -| `ply` | `.ply` | `application/x-ply` | Stanford PLY | -| `pcd` | `.pcd` | `application/x-pcd` | Point Cloud Library PCD | -| `xyz` | `.xyz` | `text/plain; format=xyz` | 简单 XYZ 文本 | -| `terrascan` | `.bin` `.tbp` | `application/x-terrascan` | Terrasolid 专有格式 | - -### 2.4 文档数据（Document） - -处理办公文档和 PDF，含空间化或地理参照场景。 - -| 子类型 | 扩展名 | 格式标识 | 说明 | -|--------|--------|---------|------| -| `pdf` | `.pdf` | `application/pdf` | PDF（含空间 PDF / GeoPDF） | -| `docx` | `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | Word 文档 | -| `xlsx` | `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | Excel 工作簿（表格数据归表格类） | -| `pptx` | `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` | PowerPoint | -| `wps` | `.wps` | `application/x-wps` | WPS 文字 | -| `et` | `.et` | `application/x-wps-et` | WPS 表格 | -| `dps` | `.dps` | `application/x-wps-dps` | WPS 演示 | -| `rtf` | `.rtf` | `application/rtf` | Rich Text Format | -| `odt` | `.odt` | `application/vnd.oasis.opendocument.text` | ODF 文本 | - -### 2.5 表格数据（Tabular） - -处理结构化表格，常用于空间化前期（地理编码、坐标对 -> 点要素）。 - -| 子类型 | 扩展名 | 格式标识 | 说明 | -|--------|--------|---------|------| -| `csv` | `.csv` | `text/csv` | CSV | -| `tsv` | `.tsv` `.tab` | `text/tab-separated-values` | TSV | -| `xls` | `.xls` | `application/vnd.ms-excel` | Excel 97-2003 | -| `xlsx` | `.xlsx`（表格场景） | 同上 | Excel 作为纯表格源 | -| `dbf` | `.dbf` | `application/x-dbf` | dBase/FoxPro | -| `parquet` | `.parquet` | `application/x-parquet` | Apache Parquet（列存，地理时空大数据） | -| `feather` | `.feather` | `application/x-feather` | Apache Feather / Arrow IPC | -| `json` | `.json`（非 GeoJSON） | `application/json` | 普通结构化 JSON（含坐标对） | -| `xml` | `.xml`（非 GML） | `application/xml` | 普通 XML | - -### 2.6 影像媒体（Image/Media） - -处理非地理参照的普通图片或视频，常作为地理信息提取的输入源。 - -| 子类型 | 扩展名 | 格式标识 | 说明 | -|--------|--------|---------|------| -| `jpeg` | `.jpg` `.jpeg` | `image/jpeg` | JPEG | -| `png` | `.png` | `image/png` | PNG | -| `bmp` | `.bmp` | `image/bmp` | BMP | -| `tiff` | `.tif` `.tiff`（非 GeoTIFF） | `image/tiff` | 普通 TIFF | -| `webp` | `.webp` | `image/webp` | WebP | -| `heic` | `.heic` | `image/heic` | HEIC（iPhone 图像） | -| `mp4` | `.mp4` | `video/mp4` | MP4 视频（无人机视频地理配准） | -| `avi` | `.avi` | `video/x-msvideo` | AVI | - -### 2.7 压缩打包（Archive） - -打包成单个容器上传的批量数据入口。 - -| 子类型 | 扩展名 | 格式标识 | 说明 | -|--------|--------|---------|------| -| `zip` | `.zip` | `application/zip` | ZIP | -| `tar` | `.tar` | `application/x-tar` | TAR | -| `targz` | `.tar.gz` `.tgz` | `application/gzip` | Gzip 压缩 tar | -| `tarxz` | `.tar.xz` | `application/x-xz` | XZ 压缩 tar 包 | -| `7z` | `.7z` | `application/x-7z-compressed` | 7-Zip | -| `rar` | `.rar` | `application/vnd.rar` | RAR | -| `gzip` | `.gz` | `application/gzip` | 单文件 gzip | - -### 2.8 空间数据库（Spatial Database） - -直接连接数据库作为数据源。 - -| 子类型 | 描述 | 连接方式 | -|--------|------|---------| -| `postgis` | PostgreSQL + PostGIS 空间数据库 | 连接字符串 `postgresql://user:pass@host/db` | -| `spatialite` | SpatiaLite 嵌入式数据库 | `.sqlite` 文件 | -| `sqlserver` | SQL Server + 空间扩展 | JDBC 连接串 | -| `oracle` | Oracle Spatial | JDBC 连接串 + SDO_GEOMETRY | -| `mysql` | MySQL + GIS 扩展 | 连接字符串 | - -### 2.9 API / 流数据（Streaming） - -通过网络接口实时获取或推送数据。 - -| 子类型 | 说明 | 协议/标准 | -|--------|------|----------| -| `ogc-features` | OGC API - Features | HTTP API / JSON-FG | -| `ogc-tiles` | OGC API - Tiles | HTTP API / TileJSON | -| `ogc-coverages` | OGC API - Coverages | HTTP API / CoverageJSON | -| `wfs` | WFS 服务 | OGC WFS 3.0 | -| `wms` | WMS 服务 | OGC WMS | -| `wmts` | WMTS 服务 | OGC WMTS 瓦片服务 | -| `tms` | TMS（Tile Map Service） | URL 模板 `{z}/{x}/{y}.pbf` | -| `mvt` | Mapbox Vector Tile | `application/vnd.mapbox-vector-tile` | -| `rest-api` | 通用 REST API 响应 | HTTP JSON | -| `mqtt` | MQTT 流式数据 | MQTT Topic 订阅 | - ---- - -## 3. 数据类型映射规则 - -### 3.1 主类型（high-level） - -脚本声明 `data_type` 时，必须指定一个主分类： - -``` -data_type: "<主分类>/<子类型>" -``` - -示例： -```yaml -data_type: "vector/geojson" -data_type: "raster/geotiff" -data_type: "pointcloud/las" -data_type: "document/pdf" -``` - -### 3.2 输入输出声明 - -脚本通过 `params_schema` 和 `output_schema` 声明输入输出的数据类型： - -```yaml -params_schema: - type: object - properties: - input_file: - type: string - data_type: "vector/geojson" # ← 标注入参数据类型 - desc: "输入矢量数据" - buffer_distance: - type: number - desc: "缓冲区半径（米）" - -output_schema: - type: object - properties: - result_file: - type: string - data_type: "vector/geojson" # ← 标注出参数据类型 - desc: "缓冲区结果" -``` - -### 3.3 合规检测规则 - -合规检测服务使用以下规则校验脚本： - -1. **主类型必须属于上述分类** — 不支持的分类返回 `invalid_data_type` -2. **输入数据类型与脚本声明的 `data_type` 必须兼容** — 子类型属于主类型即可 -3. **跨子类型兼容性规则**： - - `vector/*` ⊆ `vector`（统一主类即可，子类互转合规检测不校验） - - `raster/*` ⊆ `raster` -4. **链式脚本的数据类型传递**：脚本 B 的输入数据类型必须与前序脚本 A 的输出数据类型匹配（同一主类即可） - ---- - -## 4. 参数模板映射 - -合规检测服务根据数据类型推荐参数模板： - -| 主类型 | 默认模板 | 可配置模板 | -|--------|---------|-----------| -| `vector` | `vector-input`（文件路径 + 坐标系 + 编码） | `vector-batch`, `vector-stream` | -| `raster` | `raster-input`（文件路径 + 波段 + CRS） | `raster-multiband`, `raster-pyramid` | -| `pointcloud` | `pointcloud-input`（文件路径 + 坐标精度） | `pointcloud-filter`, `pointcloud-tile` | -| `document` | `document-input`（文件路径 + 解析选项） | `document-extract`, `document-convert` | -| `tabular` | `tabular-input`（文件路径 + 分隔符 + 编码） | `tabular-batch`, `tabular-join` | -| `image` | `image-input`（文件路径 + 格式） | `image-batch`, `image-ocr` | -| `archive` | `archive-input`（压缩包路径 + 解压规则） | `archive-extract`, `archive-repack` | -| `spatialdb` | `spatialdb-input`（连接串 + 查询 + 表名） | 无 | -| `streaming` | `api-input`（URL + 认证 + 请求参数） | 无 | - ---- - -## 5. 新增数据类型流程 - -当平台需要支持新的数据类型时，更新此文件并重新发布到 SuiteForge 知识库： - -1. 确定主分类归属（或创建新主分类） -2. 定义子类型标识符、扩展名、格式标识 -3. 编写对应的参数模板（合规检测服务端） -4. 更新此文件（SuiteForge 知识库） -5. 通知合规检测服务更新模板注册表 - ---- - -## 6. 参考实现 - -- **合规检测服务**：`compliance-service` 校验时，数据类型列表由 `TYPE_REGISTRY` 提供 -- **脚本元数据结构**：参考[脚本开发指南](../script-dev-guide.md) -- **参数模板**：存储在合规检测服务的 `templates/` 目录