端口数据结构 (Port Dataclass)

本章节面向日常使用者，介绍 端口类型背后最常见的数据结构，帮助你理解：

这些数据在代码里该怎么初始化、读取和操作；
它们与 PortType / PortTypeHint 的对应关系；
常用属性、常用方法和典型写法；
从 porttype_help 决定端口类型之后，下一步该查什么。

建议查阅顺序：

先在端口类型 (Port Type) 中决定模块端口应该声明为哪一种 PortType。
再回到本章，查对应数据结构的初始化方式和常用方法。
如果还需要完整类签名，再继续看 API参考 (API Reference)。

与端口类型 (Port Type) 相比，这里更关注 “数据结构本身怎么用”；与 API参考 (API Reference) 相比，这里以 实用为导向，而不是完整成员列表。

快速导航

字段与表格：FieldMetadata、TableData、TableSeries、TableCollection
结果数据：UnitResult、ResultModel、SingleResult、AgentRunResult
报告打印：DocData
图表数据：PlotData
坐标系：CoordinateSystem
GDIM 平台数据：GdimTemplate

FieldMetadata

FieldMetadata 是描述 单列业务语义 的元数据类，被 TableData、TableSeries 使用。每当你向 TableData 添加字段语义（标题、单位、说明）时，都是在操作 FieldMetadata 对象。

导入路径

from gdisdk.dataclass.tables import FieldMetadata

初始化参数

FieldMetadata(
    name: str,                      # 内部字段名（必须与 DataFrame 列名一致）
    title: str | None = None,       # 显示标题，默认与 name 相同
    unit: Units | None = None,      # 单位，来自 gdisdk.dataclass.terminologies.Units
    widget_type: str | None = None, # 前端控件类型（一般不需要手动设置）
    data_format: str | None = None, # 数据格式（一般不需要手动设置）
    field_type: Literal['reserved', 'regular'] | None = None,
    description: str | None = None, # 字段说明
)

使用示例

from gdisdk.dataclass.tables import FieldMetadata, TableData
from gdisdk.dataclass.terminologies import Units
import pandas as pd

meta = FieldMetadata(name="depth", title="深度", unit=Units.METER, description="钻孔深度")

df = pd.DataFrame({"depth": [1.0, 2.5, 5.0], "soil": ["填土", "粉质粘土", "砂土"]})
table = TableData(df, name="bore_data", fields_meta=[
    FieldMetadata(name="depth", title="深度", unit=Units.METER),
    FieldMetadata(name="soil", title="土层描述"),
])

TableData

对应端口类型：PortType.TableData / PortTypeHint.TableData

TableData 是 GdiSDK 最常用的表格数据结构，继承自 pandas.DataFrame，在保留全部 pandas 功能的同时，额外维护每列的业务语义：

name：内部字段名（与 DataFrame 列名一致）；
title：显示标题；
unit：单位；
description：字段说明。

因此 TableData 不只是”有数据的表”，还是”带字段语义的表”，适合在模块之间传递、导出报告、交给 LLM 分析。

导入路径

from gdisdk.dataclass.tables import TableData, FieldMetadata

初始化参数

TableData(
    data=None,                      # 与 pd.DataFrame 相同：ndarray、dict、DataFrame 等
    index=None,                     # 行索引，与 pd.DataFrame 相同
    columns=None,                   # 列标签，与 pd.DataFrame 相同
    *,
    name: str | None = None,        # 表名称，默认自动生成 UUID
    title: str | None = None,       # 显示标题，默认与 name 相同
    description: str | None = None, # 表说明
    table_type: Literal['reserved', 'regular'] | None = None,
    fields_meta: list[FieldMetadata] | dict[str, FieldMetadata] | None = None,
)

主要属性

title_to_name -> dict[str, str]：列标题 → 列名的映射；
name_to_title -> dict[str, str]：列名 → 列标题的映射；
field_titles -> list[str]：所有列的显示标题列表；
field_names -> list[str]：所有列的内部名称列表；
fields_meta -> dict[str, FieldMetadata]：列名 → 元数据的只读映射。

常用方法

元数据操作

get_field_metadata(key: str) -> FieldMetadata 按字段名或标题获取列元数据；key 既可以是列名也可以是列标题。
update_field_metadata(field_name: str, title=None, unit=None, description=None) -> None 更新指定列的元数据，保持字段名不变。
update_fields_metadata(value: list[FieldMetadata] | list[dict]) -> None 批量更新元数据。

列选择与重命名

select_by_titles(*titles) -> TableData 按列标题选列，返回包含所选列且保留元数据的新 TableData。
convert_to_field_names(fields=None) -> list[str] 将标题或名称（或混合）转换为统一的字段名列表；fields 为 None 时返回所有字段名。
convert_to_field_titles(fields=None) -> list[str] 同上，但转换目标为标题。
rename_columns_to_titles(inplace: bool = True) -> TableData | None 将所有列名替换为其显示标题，便于导出给用户查看。
rename_columns(mapper=None, **kwargs) -> TableData 重命名列时同步维护元数据映射，用法与 pd.DataFrame.rename 相同。

数据获取

get(key, default=None) 按列名或列标题获取列（返回 TableSeries），找不到时返回 default。

聚合与统计（保留元数据）

groupby(by=None, axis=0, ...) -> _TableDataGroupBy 分组操作，by 既可以是字段名也可以是标题；返回支持 .mean()、.sum()、.agg() 等的分组对象。
value_counts(subset=None, normalize=False, sort=True, ascending=False, dropna=True) -> TableSeries 统计去重后的值频次，subset 支持字段名或标题。
describe(percentiles=None, include=None, exclude=None, **kwargs) -> TableData 生成描述性统计，保留元数据。

排序与索引

sort_values(by: str | list[str], ascending=True, inplace=False, ...) -> TableData 按值排序，by 支持字段名或标题。
reset_index(drop=False, inplace=False, ...) -> TableData 重置索引，同时为新增列创建元数据。
drop(labels=None, axis=0, index=None, columns=None, **kwargs) -> TableData 删除行或列，同步维护元数据。
drop_duplicates(subset=None, keep='first', inplace=False, ...) -> TableData 去除重复行，subset 支持字段名或标题。
duplicated(subset=None, keep='first') -> pd.Series 标记重复行，subset 支持字段名或标题。

填充与类型转换

fillna(value=None, method=None, ...) -> TableData 填充缺失值，保留元数据。
astype(dtype, copy=True, errors='raise') -> TableData 类型转换，保留元数据。

合并与拼接

merge(right, how='inner', on=None, left_on=None, right_on=None, ...) -> TableData 合并两张表，保留双方的字段元数据。
concat(tables: list[TableData], ignore_index=False, ...) -> TableData (classmethod) 纵向拼接多张 TableData，合并各自的元数据。
append_table(other: TableData, ignore_index=True, **kwargs) -> TableData 追加另一张表的行，保留元数据。

导出与序列化

export_doc_context(precision: int | dict | None = None, datetime_format: str | dict | None = None) -> dict 将表格导出为适合报告模板或 LLM Prompt 使用的字典；precision 控制数值精度，datetime_format 控制日期格式。
prepare_for_json(inplace: bool = False) -> TableData | None 将 NaN、Inf 等 JSON 不兼容的值替换为 None，为序列化做准备。
serialize() -> dict 将 TableData 序列化为可存储/传输的字典。
deserialize(data_dict: dict) -> TableData (classmethod) 从序列化字典还原 TableData。

使用示例

import pandas as pd
from gdisdk.dataclass.tables import TableData, FieldMetadata
from gdisdk.dataclass.terminologies import Units

# 方式一：从 DataFrame 构造，同时指定字段元数据
df = pd.DataFrame({"depth": [1.0, 2.5], "soil": ["填土", "粉质粘土"]})
table = TableData(
    df,
    name="bore_layer",
    title="钻孔分层表",
    fields_meta=[
        FieldMetadata(name="depth", title="深度", unit=Units.METER),
        FieldMetadata(name="soil", title="土层名称"),
    ],
)

# 按标题选列
sub = table.select_by_titles("深度")

# 按字段名或标题获取元数据
meta = table.get_field_metadata("depth")   # 等价于 get_field_metadata("深度")

# 导出报告上下文（保留 2 位小数）
ctx = table.export_doc_context(precision=2)

TableSeries

对应端口类型：PortType.TableSeries / PortTypeHint.TableSeries

TableSeries 是 TableData 的单列版本，继承自 pandas.Series，额外维护该列的 FieldMetadata。常见来源：

从 TableData 中用 table.get("列名") 或 table["列名"] 取出一列；
某些模块明确将输出定义为单列序列。

导入路径

from gdisdk.dataclass.tables import TableSeries, FieldMetadata

主要属性

field_meta -> FieldMetadata：当前列的完整元数据对象；
unit -> Units：单位（可读写）；
description -> str：字段说明（可读写）。

常用方法

rename(*args, **kwargs) -> TableSeries 重命名时同步维护元数据的 name 字段。
map(arg, na_action=None) -> TableSeries 应用映射函数，尽量保留元数据。
serialize() -> dict 序列化为字典。
deserialize(data_dict: dict) -> TableSeries (classmethod) 从字典还原 TableSeries。

TableCollection

对应端口类型：PortType.TableCollection / PortTypeHint.TableCollection

TableCollection 管理 多张相互关联的 ``TableData``，额外维护：

哪张是主表（main_table）；
哪些是子表（sub_tables）；
主表与子表的关联主键（primary_key）。

导入路径

from gdisdk.dataclass.tables import TableCollection

初始化参数

TableCollection(
    name: str | None = None,        # 集合名称
    title: str | None = None,       # 显示标题，默认与 name 相同
    description: str | None = None, # 说明
)

常用方法

添加与获取

add_table(table: TableData, main_table: bool = False, primary_key: str | None = None, sub_table: bool = False, parent_table: str | None = None) -> None 向集合中加入一张表，同时声明其角色： main_table=True 表示这是主表；sub_table=True 表示这是子表， parent_table 指定关联的主表名，primary_key 指定关联主键列名。
get_table(key: str) -> TableData | None 按表名或表标题获取某张表。
remove_table(key: str) -> None 按表名删除某张表。
table_names -> list[str] (property) 所有表的内部名称列表。
table_titles -> list[str] (property) 所有表的显示标题列表。

关系查询

get_main_tables() -> list[str] 返回所有主表名称。
get_sub_tables(main_table_name: str | None = None) -> list[str] 返回某主表的所有子表名称；不传参则返回所有子表。
get_primary_key(main_table_name: str | None = None) -> str | None 返回某主表与其子表之间的关联主键列名。

操作

rename_columns_to_titles() -> None 将集合内所有表的列名替换为标题。
copy() -> TableCollection 深拷贝整个集合。

导出与序列化

export_doc_context(...) -> dict 将多表按关系导出为适合模板打印和 LLM 使用的结构化字典。
serialize() -> dict 序列化。
deserialize(data_dict: dict) -> TableCollection (classmethod) 反序列化。

使用示例

from gdisdk.dataclass.tables import TableCollection, TableData, FieldMetadata
import pandas as pd

main_df = pd.DataFrame({"bore_id": ["K1", "K2"], "depth": [20.0, 15.0]})
main_table = TableData(main_df, name="bore_info", title="钻孔一览")

sub_df = pd.DataFrame({"bore_id": ["K1", "K1", "K2"], "soil": ["填土", "粉土", "砂土"]})
sub_table = TableData(sub_df, name="bore_layer", title="钻孔分层")

coll = TableCollection(name="bore_project", title="钻探数据")
coll.add_table(main_table, main_table=True, primary_key="bore_id")
coll.add_table(sub_table, sub_table=True, parent_table="bore_info")

UnitResult

UnitResult 是 SingleResult 中每一项结果的容器，继承自 pydantic.BaseModel。

导入路径

from gdisdk.dataclass.results import UnitResult

字段

UnitResult(
    name: str,                       # 内部 key（必填）
    value: float | int | str | bool | list | None,  # 结果值（必填）
    title: str | None = None,        # 显示标题，默认与 name 相同
    unit: Units = Units.UNITLESS,    # 单位
    description: str | None = None, # 补充说明
)

使用示例

from gdisdk.dataclass.results import UnitResult
from gdisdk.dataclass.terminologies import Units

item = UnitResult(name="bearing_capacity", title="地基承载力", value=180.0, unit=Units.KPA)

ResultModel

对应端口类型：PortType.ResultModel / PortTypeHint.ResultModel

ResultModel 是当前推荐的结构化结果数据类型。它继承自 pydantic.BaseModel，用于表达 字段结构明确、希望长期维护的结果对象。

与 SingleResult 相比，ResultModel 更适合新模块和新端口设计：

字段定义写在类上，结构更清晰；
自带 Pydantic 类型校验、默认值和序列化能力；
仍然保留 title / unit / description 等结果元数据；
同样支持 convert_to_table_data()、export_doc_context() 等结果导出能力。

如果你只是临时透传一个松散的 JSON 字典，可以继续使用 JsonObject；如果你在兼容历史模块，则可能仍会遇到 SingleResult。

导入路径

from pydantic import Field

from gdisdk.dataclass.results import ResultModel, UnitField

定义方式

ResultModel 有两种定义方式，根据字段结构是否在开发时已知来选择。

方式一：静态类继承（字段结构已知时）

ResultModel 一般不是直接“传参数构造一个空壳类”，而是 先定义一个结果模型子类，再实例化该子类。

from pydantic import Field
from gdisdk.dataclass.results import ResultModel, UnitField
from gdisdk.dataclass.terminologies import Units

class BearingCapacityResult(ResultModel):
    bearing_capacity: float = UnitField(title="承载力特征値", unit=Units.KPA, description="修正后的承载力")
    safety_factor: float = UnitField(title="安全系数")
    note: str = Field(default="", title="备注", description="补充说明")

result = BearingCapacityResult(
    bearing_capacity=180.0,
    safety_factor=2.1,
    note="建议采用天然基础",
)

方式二：``from_dict``（字段在运行时才确定）

当字段名和数量在运行时才能确定时，可以使用 ResultModel.from_dict() 方法动态构建并返回一个 ResultModel 实例。它内部封装了 Pydantic 的 create_model，使你无需接触任何 Pydantic 内部 API。

**简单用法**（仅传入字段名和値）：

from gdisdk.dataclass.results import ResultModel

result = ResultModel.from_dict(
    {"bearing_capacity": 180.0, "safety_factor": 2.1, "note": "建议采用天然基础"},
)

**携带字段元数据**（标题、单位等）：

from gdisdk.dataclass.results import ResultModel, UnitField
from gdisdk.dataclass.terminologies import Units

result = ResultModel.from_dict(
    {"bearing_capacity": 180.0, "safety_factor": 2.1},
    model_name="BearingResult",
    fields_meta={
        "bearing_capacity": UnitField(title="承载力特征値", unit=Units.KPA),
        "safety_factor":    UnitField(title="安全系数"),
    },
)

Note

from_dict 返回的实例类型是 ResultModel 的动态子类，字段没有 IDE 自动补全支持。如果字段结构已知，优先用方式一（静态类继承）。

两种方式的对比与选型

维度	静态类继承	`from_dict` 动态构建
字段结构	开发时确定，写在类定义里	运行时才确定（来自外部数据、配置或上游端口）
IDE 支持	完整的自动补全与类型检查	无自动补全（字段是动态生成的）
元数据（单位/标题/描述）	通过 `UnitField` / `Field` 完整声明	通过 `fields_meta` 参数传入（可选）
可复用性	高；类可在多处引用	低；每次运行都生成新类，一般不跨模块复用
典型场景	模块的固定输出结构（推荐用于绝大多数自定义模块）	通用聚合/合并模块，如 `MergeResultModels`
推荐度	✅ 首选	仅在动态字段不可避免时使用

主要属性

names -> list[str]：字段名列表，按模型定义顺序返回；
titles -> list[str]：显示标题列表；
units -> list[Units]：单位列表；
values -> list[Any]：字段值列表；
descriptions -> list[str | None]：字段说明列表；
name_values -> dict[str, Any]：按字段名组织的值字典；
title_values -> dict[str, Any]：按标题组织的值字典；
title_to_name -> dict[str, str]：标题 → 字段名映射。

常用方法

get_unit(field_name: str) -> Units 获取某个字段的单位；未设置时返回 Units.UNITLESS。
get_title(field_name: str) -> str 获取某个字段的显示标题；未设置时回退到字段名。
get_description(field_name: str) -> str | None 获取某个字段的说明文字。
get(key: str | int, default=None) -> Any 按字段名、标题或索引取值；找不到时返回 default。
convert_to_table_data(joiner: str = ',') -> TableData 将结果模型转换为一张只有一行的 TableData，并保留标题与单位元数据；列表值会用 joiner 拼接。
export_doc_context(precision=None, datetime_format=None, joiner=',') -> dict[str, Any] 导出成适合报告模板或 LLM Prompt 使用的扁平字典；precision 和 datetime_format 支持按字段名或标题分别配置。
model_dump() -> dict[str, Any] 使用标准 Pydantic API 导出普通字典。
YourResultModel.model_validate(data) -> YourResultModel (classmethod) 使用标准 Pydantic API 从字典恢复模型实例。

使用示例

from pydantic import Field
from gdisdk.dataclass.results import ResultModel, UnitField
from gdisdk.dataclass.terminologies import Units
class LayerSummary(ResultModel):
    layer_name: str = Field(title="地层名称", description="主要地层名称")
    thickness: float = UnitField(title="厚度", unit=Units.METER, description="累计厚度")
    is_soft_soil: bool = Field(default=False, title="是否软土")
result = LayerSummary(layer_name="粉质粘土", thickness=6.5, is_soft_soil=True)

print(result.get_title("thickness"))     # 厚度
print(result["地层名称"])                  # 粉质粘土
print(result.model_dump())               # {'layer_name': '粉质粘土', 'thickness': 6.5, 'is_soft_soil': True}

table = result.convert_to_table_data()
ctx = result.export_doc_context(precision={"厚度": 2})

SingleResult

对应端口类型：PortType.SingleResult / PortTypeHint.SingleResult

SingleResult 保存一组 带 key 元数据的简单结果，底层是 dict[str, UnitResult]。它仍然适合“指标类结果”这类旧接口，但主要用途已经变成 兼容历史模块和历史 Pipeline。

Warning

SingleResult 已处于逐步淘汰阶段，后续将由 ResultModel 取代。新模块和新端口设计建议优先使用 PortType.ResultModel / PortTypeHint.ResultModel； SingleResult 主要用于兼容历史模块和历史 Pipeline。

导入路径

from gdisdk.dataclass.results import SingleResult, UnitResult

初始化参数

# 方式一：传入 UnitResult 列表（保留完整元数据）
SingleResult(result: list[UnitResult])

# 方式二：传入简单字典（name -> value，无标题/单位）
SingleResult(result: dict[str, float | int | str | bool | list | None])

主要属性

result -> list[UnitResult]：以列表形式返回所有结果项；
name_values -> dict[str, value]：按字段名组织的值字典；
title_values -> dict[str, value]：按显示标题组织的值字典；
values -> list：所有结果值的列表；
names -> list[str]：所有字段名的列表；
titles -> list[str]：所有显示标题的列表；
units -> list[Units]：所有单位的列表；
title_to_name -> dict[str, str]：标题 → 字段名的映射。

常用方法

get(key: str | int, default: UnitResult | None = None) -> UnitResult | None 按字段名、显示标题或索引获取 UnitResult，找不到时返回 default。
convert_to_table_data(joiner: str = ',') -> TableData 将结果转换为一张 TableData，以便表格展示或进一步处理。
export_doc_context(precision=None, datetime_format=None, joiner=',') -> dict 导出为模板或 LLM Prompt 可直接使用的字典；列表类型的值会用 joiner 连接为字符串。
serialize() -> dict 序列化。
deserialize(data_dict: dict) -> SingleResult (classmethod) 反序列化。

使用示例

from gdisdk.dataclass.results import SingleResult, UnitResult
from gdisdk.dataclass.terminologies import Units

result = SingleResult([
    UnitResult(name="fa", title="地基承载力特征值", value=180.0, unit=Units.KPA),
    UnitResult(name="depth", title="基础埋深", value=1.5, unit=Units.METER),
])

# 按标题取值
item = result.get("地基承载力特征值")
print(item.value)   # 180.0

# 导出用于报告模板
ctx = result.export_doc_context(precision=2)
# {'fa': '180.00', 'depth': '1.50'}  — key 为字段名

AgentRunResult

对应端口类型：PortType.AgentRunResult / PortTypeHint.AgentRunResult

AgentRunResult 对应的是 pydantic_ai.run.AgentRunResult 对象，用于保存一次大模型调用的 原始运行结果及其元数据。它不是面向业务语义建模的结果容器，而是面向 AI 运行链路的原始结果对象。

典型可访问的信息包括：

.output：模型返回的最终输出内容；
.all_messages()：本次运行的完整消息历史；
.new_messages()：相对于已有上下文新增的消息；
.usage()：token 使用量等调用统计信息。

适用场景：

需要保留 LLM 原始响应，而不是只保留最终文本或结构化结果；
需要查看消息历史、token 消耗、上下文追加消息等运行信息；
需要把一次调用结果继续作为后续多轮对话的上下文；
调试、审计、日志记录或性能分析。

导入路径

from pydantic_ai.run import AgentRunResult

说明

PortTypeHint.AgentRunResult 直接对应 pydantic_ai.run.AgentRunResult。通常由 LLMNode、Agent 节点或其他 AI 模块的 OutputResponse 端口输出。

选型建议

如果你只需要业务可消费的结构化结果，优先使用 ResultModel；
如果你只需要一段模型回复文本，优先使用 Text 或从 AgentRunResult.output 提取后再封装；
只有在下游确实要访问原始运行上下文和调用元数据时，再继续传递 AgentRunResult。

使用示例

from pydantic_ai.run import AgentRunResult

run_result: AgentRunResult = some_ai_module.OutputResponse

text = run_result.output
messages = run_result.all_messages()
usage = run_result.usage()

DocData

对应端口类型：PortType.DocData / PortTypeHint.DocData

DocData 是面向 文档模板打印 的专用数据结构，继承自 pydantic.BaseModel，包含两部分：

data：最终会写进文档模板的渲染数据；
doc_keys_struct：模板变量结构说明，用于配置模板 key。

通常不需要手动构造，而是由 DocDataWriter、MergeDocData 等模块自动生成。当你想排查模板变量或渲染数据时，可以使用它的导出方法。

导入路径

from gdisdk.dataclass.results import DocData

字段

DocData(
    data: dict[str, Any],           # 渲染数据：key 为模板变量名，value 为对应内容
    doc_keys_struct: dict[str, Any], # 模板 key 结构说明
)

常用方法

to_json_serializable() -> dict[str, Any] 返回可安全序列化为 JSON 的副本（将 Path 对象等转换为字符串）。
export_data_to_json(file_path: str) -> None 将渲染数据导出为 JSON 文件，便于排查内容问题。
export_keys_to_json(file_path: str) -> None 将模板 key 结构导出为 JSON 文件，便于配置模板。
export_all_to_json(file_path: str) -> None 同时导出渲染数据和 key 结构，合并为一个 JSON 文件。

PlotData

对应端口类型：PortType.PlotData / PortTypeHint.PlotData

PlotData 不是一个自定义类，而是一个 用于前端图表渲染的 JSON 字典约定。在当前实现中，它通常对应 Plotly figure 的字典形式（即 fig.to_dict() 的结构）。

主要用途：

可视化模块输出给 GDIM / Web 前端渲染；
在多个图表模块之间传递图表数据；
交给 PlotMerger 合并多个图表。

典型来源：

LineChartPlotter、BarChartPlotter、ScatterChartPlotter 等绘图模块的 OutputPlotData；
PlotMerger 的合并结果。

适用建议：

只要目标是”前端显示图表”，就应该使用 PlotData；
如果你的数据仍然是业务表，先用 TableData，到真正绘图时再转换成 PlotData；
虽然它底层是 dict，但它表示特定的图表协议数据，不建议把它当作普通 JsonObject 来理解或复用。

CoordinateSystem

对应端口类型：PortType.CoordinateSystem / PortTypeHint.CoordinateSystem

CoordinateSystem 是 Pydantic 模型，用于在模块之间显式传递 坐标系参数，避免把空间参考信息散落在多个字符串或数字字段里。

导入路径

from gdisdk.dataclass.results import CoordinateSystem

字段

CoordinateSystem(
    name: Literal[
        'WGS84_UTM_S', 'WGS84_UTM_N',
        'CGCS2000_3', 'CGCS2000_6',
        'Xian1980_3', 'Xian1980_6',
        'Beijing1954_3', 'Beijing1954_6',
        'WGS84', 'RELATIVE_CRS',
    ] | None = None,                      # 坐标系名称
    zoneMethod: Literal['manualInput', 'autoInput'] | None = None,  # 投影分带方式
    zoneNumber: int | None = None,         # 带号
    centralMeridian: float | None = None,  # 中央子午线经度
    refPointLongitude: float | None = None, # 相对坐标系参考点经度（RELATIVE_CRS 专用）
    refPointLatitude: float | None = None,  # 相对坐标系参考点纬度
    refPointX: float | None = None,         # 参考点 X 坐标
    refPointY: float | None = None,         # 参考点 Y 坐标
    elevationDatum: str | None = None,      # 高程基准
    yAxisDirection: Literal['east', 'north'] | None = None,  # Y 轴方向
)

使用示例

from gdisdk.dataclass.results import CoordinateSystem

crs = CoordinateSystem(name="CGCS2000_3", zoneNumber=21, centralMeridian=123.0)

GdimTemplate

对应端口类型：PortType.GdimTemplate / PortTypeHint.GdimTemplate

GdimTemplate 描述 GDIM 数据模板的结构信息，核心包括各业务表的元数据、表名与标题的映射、父表/子表关系以及平台应用信息。

导入路径

from gdisdk.dataclass.gdimData import GdimTemplate

常用方法

get_table_metadata(key: str)：按表名或标题获取表结构；
get_children(table_name: str)：获取某表的所有子表名称；
get_parent(table_name: str)：获取某表的父表名称；
is_root_table(table_name: str) -> bool：判断是否为根表；
is_parent_table(table_name: str) -> bool：判断是否有子表；
is_child_table(table_name: str) -> bool：判断是否为子表。

典型适用场景

从 GDIM 读取模板定义；
根据模板动态生成读表、写表、校验逻辑；
需要理解表结构树和业务表关系时。

GdimMinIOFile

对应端口类型：PortType.GdimFile / PortTypeHint.GdimFile

GdimMinIOFile 表示 GDIM 平台中的文件对象，例如上传后的附件、图片、文档或其它资源。

导入路径

from gdisdk.dataclass.gdimData import GdimMinIOFile

字段

fileId、filename、originalFilename、contentType、size、downloadUrl

常用方法

get_download_url() -> str：获取文件的可下载链接；
get_file_url() -> str：获取文件访问链接。

典型适用场景

上传文件后在模块之间传递文件对象；
将平台中的文件结果交给下游模块；
在报告、可视化或业务流程中引用平台文件。

如何在设计模块端口时配合使用

如果你是在设计模块端口或编写 @local_function，建议按照下面的顺序判断：

先在端口类型 (Port Type) 中确定应使用哪一种 PortType；如果是新的结构化结果对象，优先考虑 ResultModel。
再回到本章，用 search_dataclass_help("ClassName") 查询该数据结构的初始化参数和常用方法。
如果需要完整成员签名，再进入 API参考 (API Reference) 中对应页面。

这样可以把”端口选型”和”数据结构使用”分开处理，文档查阅效率会更高。