diff --git a/suite-developer/knowledge/script-data-types.md b/suite-developer/knowledge/script-data-types.md new file mode 100644 index 0000000..8d8a741 --- /dev/null +++ b/suite-developer/knowledge/script-data-types.md @@ -0,0 +1,263 @@ +# 脚本数据类型分类规范 + +> **归属:** 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/` 目录