From cdd7613d53350bb10f6b16b0dc89e8dc9ae64a53 Mon Sep 17 00:00:00 2001 From: gaozheng Date: Thu, 25 Jun 2026 22:20:43 +0800 Subject: [PATCH] =?UTF-8?q?docs(api):=20vtk-3d-openapi=20=E5=AF=B9?= =?UTF-8?q?=E9=BD=90=E5=AE=9E=E6=B5=8B=E5=AE=9E=E7=8E=B0(0.6.1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按客户端实测口径修正文档偏差: - DsPage: 行在 data.list(非 data.value)+total;补注与 structNode/exception 用 data.value 的差异 - DsRow: 从5字段扩为实测解析全字段——name(=类型名,JSON键是name非typeName)/dsTypeCode/createTime/ sourceShowParentId(+parentId回退)/structParentId/structParentConfType/properties(泛型JSON,数组或对象)/ file;ddCode 是通用 dd 码(非仅 voxel/slice),data/page 返回各类 dsObject - data/page 描述补实测:行在list/返回各类ds/classifyType==1走file·page/**业务字段值(含装置arrayType)不在行上** (装置属测线脚本配置)→ 类型筛选改按 typeName/dsTypeCode 范围筛 - registerSlice 描述补:客户端 mock 当前 projectId 为空,接真后端需补 nav.currentProjectId 未变(已与实现一致):VoxelGenerateRequest/SliceGenerateRequest/SliceSpec/VolumeBuildParams/DsPageRequest/ StructNode(L)/ExceptionList(均 data.value) --- docs/api/vtk-3d-openapi.json | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/docs/api/vtk-3d-openapi.json b/docs/api/vtk-3d-openapi.json index 36f7fd0..7a6e0fb 100644 --- a/docs/api/vtk-3d-openapi.json +++ b/docs/api/vtk-3d-openapi.json @@ -2,7 +2,7 @@ "openapi": "3.0.3", "info": { "title": "Geopro3 三维视图 API（三维体 / 切片 / 异常 三件套）", - "version": "0.6.0-draft", + "version": "0.6.1-draft", "description": "VTK 三维视图后端接口。归属结构(2026-06-24 修订)：**GS/项目根/TM → 三维体(dd_voxel) → 切片(dd_slice)**(三维体生成位置由用户在生成对话框选择,默认单GS挂该GS/跨GS挂项目根,可改为项目内任意 GS/TM；源数据集与归属解耦)，异常挂在三维体上(remarkSourceId=三维体 dsObjectId)。\n\n**总原则：实体无关的契约一律复用存量；只为各自特有、存量装不下的部分扩展。**\n- 三维体/切片对后端 = 纯元数据 dsObject：增删改查/属性复用存量 dsObject 面，各加 1 个登记端点；体素字节/切面数据全在客户端(算+存+取+渲染)，后端零数据端点。\n- 异常复用整套存量 /business/exception 端点(端点不限实体类型，三维体 id 直接塞 remarkSourceId)；**异常体(consortium)分组也是存量已有**(consortiumId/Name/Type)。3D 仅扩展两处：location 加 worldPts+plane(三维几何)、加截图(R88)。\n\n响应统一信封 `{ code:int, msg:string, data:object|array }`，code==200 成功；列表/集合放 data.value。\n\n依赖前提：异常 remarkSourceId 指向三维体，须等三维体登记出真 dsObjectId 后，3D 异常才能接真端点。" }, "servers": [ @@ -34,7 +34,7 @@ "post": { "tags": ["dsObject-reuse"], "summary": "[复用] 分页查询某父节点下的数据集行", - "description": "存量端点(loadRowsAsync)。查三维体：structParentId=生成位置节点 id(GS/项目根/TM)、structParentConfType=1或2；查某三维体下切片：structParentId=该三维体 dsObjectId。返回行 ddCode=dd_voxel / dd_slice。", + "description": "存量端点(loadRowsAsync)。查三维体：structParentId=生成位置节点 id(GS/项目根/TM)、structParentConfType=1或2；查某三维体下切片：structParentId=该三维体 dsObjectId。\n\n**实测口径(2026-06-25)**：①行在 `data.list`(非 data.value)；②返回项目结构下**各类** dsObject(文件/网格/反演/三维体/切片/异常…)，行 ddCode 非仅 voxel/slice；③客户端用 classifyType==1 时改打 `/business/dsObject/file/page`(文件型)，否则 `data/page`；④**行不返回业务字段值**(properties 为文件元数据或 null)，**装置类型(arrayType) 不在 data/page 行上**——它属测线脚本配置(ScriptInfoVO)，故客户端「类型筛选」改按行自带的 typeName/dsTypeCode 范围筛，而非 arrayType。", "operationId": "dsObjectDataPage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DsPageRequest" } } } }, "responses": { @@ -114,7 +114,7 @@ "post": { "tags": ["slice-new"], "summary": "[新增] 登记切片记录", - "description": "在所属三维体下登记一条 dd_slice dsObject(名称 + 三点位姿写入 attachedParameters.slicePose)，返回新 dsObjectId。只建记录、不触发后端计算——切面据「体+位姿」在客户端重采样渲染。", + "description": "在所属三维体下登记一条 dd_slice dsObject(名称 + 三点位姿写入 attachedParameters.slicePose)，返回新 dsObjectId。只建记录、不触发后端计算——切面据「体+位姿」在客户端重采样渲染。\n\n**实测(2026-06-25)**：客户端 mock 仓储无项目上下文，当前打印的请求体 projectId 为空；接真后端前客户端需补 nav.currentProjectId()。其余字段(volumeDsId/name/axis/三点/colorScaleId)与本 schema 一致。", "operationId": "registerSlice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SliceGenerateRequest" } } } }, "responses": { @@ -311,17 +311,32 @@ } }, "DsPage": { - "type": "object", "description": "分页结果", - "properties": { "total": { "type": "integer" }, "value": { "type": "array", "items": { "$ref": "#/components/schemas/DsRow" } } } + "type": "object", "description": "分页结果。**注意**：data/page 的行在 `data.list`（不是 data.value），与 structNode/exception 等集合用 data.value 不同（实测客户端按 data.list 解析）。", + "properties": { "total": { "type": "integer" }, "list": { "type": "array", "items": { "$ref": "#/components/schemas/DsRow" } } } }, "DsRow": { - "type": "object", "description": "数据集行(列表/树节点)", + "type": "object", + "description": "数据集行(data/page 通用 dsObject 行；客户端 parseDsRows 实测口径)。data/page 返回项目结构下**各类** dsObject(文件/网格/反演/三维体/切片/异常…)，非仅三维体/切片。", "required": ["id", "ddCode"], "properties": { - "id": { "type": "string" }, "dsName": { "type": "string" }, - "ddCode": { "type": "string", "enum": ["dd_voxel", "dd_slice"] }, - "typeName": { "type": "string", "example": "三维体" }, - "parentId": { "type": "string", "nullable": true, "description": "三维体=生成位置节点 id(GS/项目根/TM)；切片=所属三维体 dsObjectId" } + "id": { "type": "string" }, + "dsName": { "type": "string", "description": "数据集名" }, + "name": { "type": "string", "example": "电阻率反演数据", "description": "**数据集类型名**(客户端映射为 typeName；注意 JSON 键是 name，非 typeName)。类型筛选即按此值的范围筛。" }, + "ddCode": { "type": "string", "description": "通用 dd 码：dd_voxel/dd_slice/dd_anomaly/dd_section/dd_inversion_data/dd_grid/dd_file 等(非仅 voxel/slice)" }, + "dsTypeCode": { "type": "string", "nullable": true, "description": "数据集类型代码(如 'ERT platform inversion data'；分段按它归类，typeName 缺失时筛选回退它)" }, + "createTime": { "type": "string", "nullable": true, "description": "创建时间(列表副标题/时间筛选用)" }, + "sourceShowParentId": { "type": "string", "nullable": true, "description": "显示树父(派生数据挂源数据下)；客户端 parentId 优先取它，缺则回退 parentId" }, + "parentId": { "type": "string", "nullable": true, "description": "sourceShowParentId 的回退" }, + "structParentId": { "type": "string", "nullable": true, "description": "结构归属父(项目根/GS/TM)——分段树据此把 ds 挂到 GS/TM 容器下" }, + "structParentConfType": { "type": "integer", "nullable": true, "description": "结构父配置类型：1=GS/项目根 2=TM" }, + "properties": { + "description": "字段值(泛型 JSON)。**两种形态都可能**：数组 [{confFieldId,value}] 或对象 {confFieldId:value}；文件型 ds 此处可能是文件元数据；派生数据可能为 null。**实测 data/page 多不返回业务字段值(装置/采集时间等)，故装置类型不在此**。", + "nullable": true + }, + "file": { + "type": "object", "nullable": true, "description": "文件型 ds 的文件信息", + "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size": { "type": "integer" } } + } } }, "DsObjectDetail": {