modules.readers 模块帮助

本章节包含 modules.readers 包中常用「数据读取」模块的使用说明和示例，例如：

Excel / CSV / 文本 / 数据库等不同数据源的读取模块
针对 GDIM 或特定业务格式的专用读取模块

CsvReader

模块简介与适用场景

CsvReader 用于读取 .csv 文件。file 参数既支持本地路径（str | Path），也支持 GDIM 文件服务返回的文件描述（dict，内部会校验为 GdimMinIOFile 并先下载到工作目录）。
它既可以输出表格数据 OutputTable，也可以从 CSV 的表头/说明行提取字段说明，输出适合下游 LLM 模块使用的 OutputSchema。
典型适用场景：
- 将外部导出的 CSV（如仪器数据、统计结果、第三方表格）作为 Pipeline 的数据源；
- 在 GDIM 前端让用户选择 CSV 文件，并将文件描述直接传给 CsvReader.file 后读取；
- 通过 usecols / dtype 只读取关键列并指定类型，避免后续处理出现类型不一致；
- 对于常见中文编码的 CSV 文件，使用 encoding="auto" 自动识别编码；
- 当 CSV 前几行包含“字段名 + 字段说明”时，可直接生成结构化 schema 文本，供提示词或智能问答模块使用；
- 当第三行（或 unit_row 指定行）为物理单位、且单位不一定在平台 Units 枚举内时，可将 check_units=False，使非空单位单元格原样写入 schema 中的方括号标注（如 [自定义单位]），而不做合法性校验、也不触发数据质量告警。

端口说明

输入端口 - （无）：该模块主要通过参数 file / sep / encoding 等提供输入配置；其中 file 可为本地路径，也可为 GDIM 文件服务文件描述 dict
输出端口 - OutputTable：输出读取到的表格（TableData）；当 output_mode="table" 或 "both" 时写入；若 file=None 则为 None - OutputSchema：输出 CSV 列 schema 对应的 ResultModel``（单字段 Pydantic 模型，**不是** ``TableData）。模型只有一个属性，名称由 schema_field_name 指定（默认 "fields"），值为从 CSV 表头行拼出的**纯文本**列说明，适合注入 PromptTemplate 等 LLM 模块。文本由 name_row``（字段名）、``description_row``（可选说明）、``unit_row``（可选单位）三行组装，每列一行，例如 ``- depth: 钻孔深度 [m]。当 output_mode="schema" 或 "both" 时写入；若 file=None 则为 None

快速上手示例：读取 CSV 表格

from gdisdk.modules.readers import CsvReader

reader = CsvReader(mname="ReadCsv")
reader.file = "example.csv"
reader.sep = ","          # 分隔符，默认 ","
reader.encoding = "auto"  # 自动识别编码（推荐用于中文 CSV）
reader.output_mode = "table"

table = reader.execute()
df = reader.OutputTable.data.dataframe  # 如需 pandas DataFrame，可从 TableData 取出

快速上手示例：读取 CSV schema

from gdisdk.modules.readers import CsvReader

reader = CsvReader(
    mname="ReadCsvSchema",
    file="example.csv",
    output_mode="schema",
    name_row=0,           # 第 1 行是字段名
    description_row=1,    # 第 2 行是字段说明；如果没有说明行可设为 None
    unit_row=2,           # 第 3 行是物理单位；如果没有单位行可设为 None
    schema_field_name="fields",
)

reader.execute()
schema = reader.OutputSchema.data
schema_text = schema.fields   # 纯文本，可直接用于提示词占位符 {fields}

# 输出示例：
# Table: example
# Fields:
# - 孔号: 钻孔编号
# - 深度: 钻孔深度 [m]
# - 孔压: 孔隙水压力 [kPa]

快速上手示例：读取 GDIM 文件服务上的 CSV

from gdisdk.modules.readers import CsvReader

# gdim_file 一般由 GDIM 前端文件选择器或上游模块直接提供
# 不建议手写这个 dict；应直接使用平台返回的完整文件描述
gdim_file = {
    "success": True,
    "fileId": "your-file-id",
    "fileUrl": "/minio/preview/your-file-id",
    "originalFilename": "监测数据.csv",
    "filename": "monitor.csv",
    "size": 1024,
    "contentType": "text/csv",
    "objectId": None,
    "objectType": None,
    "message": None,
    "thFileUrl": None,
    "thFilename": None,
    "thSize": None,
    "downloadUrl": "/minio/download/your-file-id",
    "host": "https://your-gdim-host/api/",
}

reader = CsvReader(
    mname="ReadCsvFromGdimFile",
    file=gdim_file,
    encoding="auto",
    output_mode="table",
)

reader.execute()
table = reader.OutputTable.data

参数说明

CsvReader 参数一览
参数名	类型	默认值	说明
`file`	`str \| Path \| dict \| None`	`None`	CSV 文件来源。传本地路径时直接读取本机文件；传 `dict` 时会先按 `GdimMinIOFile` 校验，并根据 `downloadUrl` / `host` 从 GDIM 文件服务下载到工作目录后再读取；为 `None` 时不读取并输出 `None`。
`sep`	`str`	`,`	分隔符（如 `,`, `"\t"` 等）。
`encoding`	`str \| None`	`"auto"`	文件编码； `"auto"` 会自动尝试常见编码并选择可解码的编码。
`header`	`int \| list[int] \| str \| None`	`"infer"`	表头行配置： `"infer"` 自动推断； `0` 表示第一行为列名； `None` 表示无表头（列名为 0,1,2…）； `[0,1]` 支持多级表头。
`index_col`	`int \| str \| list[int] \| list[str] \| None`	`None`	指定作为索引的列。
`usecols`	`list[int] \| list[str] \| None`	`None`	只读取指定列（可用列序号或列名）。
`dtype`	`dict[str, str] \| str \| None`	`None`	指定数据类型（可为单一类型或按列指定类型字典），用于避免类型推断误差。
`skiprows`	`int \| list[int] \| None`	`None`	跳过行：可为跳过前 N 行的 `int`，或指定要跳过的行号列表（0-indexed）。
`nrows`	`int \| None`	`None`	读取行数上限（用于大文件抽样/加速）。
`na_values`	`str \| list[str] \| dict[str, str \| list[str]] \| None`	`None`	额外识别为缺失值的字符串（支持按列指定）。
`output_mode`	`Literal["table", "schema", "both"]`	`"table"`	控制输出模式： `"table"` 只输出 `OutputTable`； `"schema"` 只输出 `OutputSchema`，且不会加载整张表； `"both"` 同时输出表格和 schema。
`name_row`	`int`	`0`	读取 schema 时，字段名所在的原始 CSV 行号（从 0 开始计数）。仅在输出 `OutputSchema` 时使用。
`description_row`	`int \| None`	`1`	读取 schema 时，字段说明所在的原始 CSV 行号（从 0 开始计数）；若 CSV 没有说明行，设为 `None`。仅在输出 `OutputSchema` 时使用。
`unit_row`	`int \| None`	`2`	读取 schema 时，各列物理单位所在的原始 CSV 行号（从 0 开始计数），默认第三行；无单位行、或行号超出文件时可设为 None``（与 ``description_row 行为一致）。仅在输出 `OutputSchema` 时使用。
`check_units`	`bool`	`True`	是否校验单位字符串与 `gdi.dataclass.terminologies.Units` 的匹配。 True``（默认）：仅识别到的标准单位会写入 schema（如 ``[m]），未知单位会发出 `GDIDataQualityWarning` 且该列不带单位标注； `False`：不校验，非空单位单元格按原文放入方括号（如 `[my unit]`）。
`schema_field_name`	`str`	`"fields"`	`OutputSchema` 中承载 schema 纯文本的 ResultModel 字段名。默认可通过 `schema.fields` 访问；若下游 `PromptTemplate` 占位符为 `{columns}` 等，可改为对应名称（如 `"columns"`、`"schema"`）。

schema 输出格式说明

OutputSchema 输出的是一个 ResultModel 实例（内部为单字段 Pydantic BaseModel），不是 TableData，也不包含 CSV 数据行本身。
模型仅有一个字符串字段，字段名等于 schema_field_name``（默认 ``"fields"），值为可直接注入提示词的纯文本摘要。
典型用法：将 OutputSchema 连到 PromptTemplate.InputValues，使模板中的 {fields}``（或与 ``schema_field_name 同名的占位符）自动填入列说明。
文本格式大致如下：

Table: <文件名（不含扩展名）>
Fields:
- <字段名>: <字段说明> [<单位>]
- <字段名>: <字段说明>
- <字段名>

各部分的来源：
- Table: ...：取自 CSV 文件名（stem）；
- 字段名：来自 name_row 对应行的各列单元格；
- 字段说明：来自 description_row；若该行不存在或 description_row=None，则只输出 - 字段名；
- 单位：来自 unit_row，以方括号附在字段行末尾，如 [m]、[kPa]。
如果某列没有对应说明，则仅输出字段名（及可选的单位标注）。
当 description_row 超出文件行数或设为 None 时，模块仍会输出字段名列表，但不附带字段说明。
当配置了 unit_row 且该行存在有效单元格时，字段行会在 schema 中附带单位方括号，例如 - depth: 钻孔深度 [m]。 check_units=True``（默认）时只接受能匹配 ``Units 的单位，未知单位会发出 GDIDataQualityWarning 并省略该列单位； check_units=False 时不校验，非空单位按原字符串写入方括号（如 [my unit]）。

上传 GDIM 前检查

是否需要特别处理：当读取的 CSV 文件需要由 GDIM 前端上传、选择或在平台运行时提供时，是。
必须检查：
- 不要再依赖本机绝对路径或仅本地存在的相对路径；上传后的推荐方式是由前端传入 GDIM 文件描述，并直接赋给 file；
- 模板建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``dict``） 提供，这是上传后的推荐方式。
建议检查：
- encoding 优先设为 "auto"，减少中文 CSV 编码不一致导致的读取失败；
若遗漏，常见现象：
- 本地调试可正常读取固定路径文件，但上传 GDIM 后报“文件不存在”；
- 文件能下载，但因编码出现乱码。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import CsvReader

pipeline = PipeLine(app_name="ReadCsvDemo", app_title="读取CSV示例")

read_csv = CsvReader("ReadCsv")
read_csv.file = "example.csv"
read_csv.encoding = "auto"
read_csv.output_mode = "both"
read_csv.name_row = 0
read_csv.description_row = 1

pipeline.add_module(read_csv)
pipeline.run()

table = read_csv.OutputTable.data
schema = read_csv.OutputSchema.data
schema_text = schema.fields   # 纯文本列 schema，可传给 PromptTemplate

更多信息

GdimTableReader

模块简介与适用场景

GdimTableReader 用于从 GDIM 项目中读取一个或多个数据表，输出为 TableCollection``（多表集合），并可额外指定其中一张表输出为 ``TableData。
当读取结果为空时，可通过 empty_error_type 控制行为；其中 "create_empty_table" 会按模板元数据创建一个空的 TableData，而不是直接跳过该表。
典型适用场景：
- 在 Pipeline 的起点从 GDIM 拉取业务表（如「剖面数据表」「钻孔表」「地层表」等）；
- 只读取关键字段（减少网络与内存开销），并在后续模块中进行筛选、统计、绘图；
- 按模板关系自动读取主表及相关子表（ auto_detect_related_tables=True ）；
- 关闭自动识别关联表时，用手动指定的主表、子表与主键字段组装 TableCollection 的层级信息（ auto_detect_related_tables=False 配合 main_table_name / sub_table_names / primary_key ）。

端口说明

输入端口 - InputToken：鉴权与项目定位信息 (token, proj_id, host)。若 Pipeline 已通过 pipeline.update_gdim_state(token=..., proj_id=..., host=...) 配置 gdim_state，模块会从 Pipeline 自动取 token（及项目、host 等），此时该端口可以不连接，否则由本端口传入。
输出端口 - OutputTables：读取到的多表集合（TableCollection） - OutputTable：从 OutputTables 中选出的单表（TableData），由 output_table_name 指定；未指定时默认取集合中的第一张表；若指定了名称但该表不在集合中，则可能为 None

快速上手示例：读取指定表与字段

from gdisdk.modules.readers import GdimTableReader

# 最小可运行：直接在模块上指定 token / proj_id（无需 Pipeline）
reader = GdimTableReader(
    mname="ReadTables",
    token="你的GDIM Token",
    proj_id="你的GDIM项目ID",
    host=None,   # 可选；None 时使用默认 host 或 pipeline.gdim_state.host
)

# 只读一张表的指定字段（key 可以写表名或表标题，value 可以写字段名或字段标题，系统会自动识别）
reader.table_fields = {
    "剖面数据表": ["剖面编号", "x_coordinate", "y_coordinate"],
}

# 指定 OutputTable 要输出哪张表（未指定时默认取读取到的第一张表）
reader.output_table_name = "剖面数据表"

tables = reader.execute()
one_table = reader.OutputTable.data

参数说明

GdimTableReader 参数一览
参数名	类型	默认值	说明
`table_fields`	`dict[str, list[str]] \| list[str] \| str \| None`	`None`	需要读取的表/字段配置。为 `None` 时读取全部表的全部字段；为 `str/list` 时读取指定表全部字段；为 `dict` 时可指定表与字段（表与字段支持用「name」或「title」，系统会自动识别）。
`format_dict`	`dict[str, dict[str, str]] \| None`	`None`	字段格式化配置（按表维度指定字段格式），用于在读取后对数据类型/格式进行统一处理。
`auto_detect_related_tables`	`bool`	`True`	是否基于模板结构自动识别关联表。为 `True` 时会忽略 `main_table_name` / `sub_table_names` / primary_key``（且要求 ``gdim=True；若为 `False` 且本参数为 `True` 会报错）。
`main_table_name`	`str \| None`	`None`	主表的内部名或表标题（系统自动识别）。仅当 `auto_detect_related_tables=False` 时生效，用于标记 `TableCollection` 中的主表及解析 `primary_key`。
`sub_table_names`	`list[str] \| None`	`None`	子表内部名或表标题列表（系统自动识别）。仅当 `auto_detect_related_tables=False` 时生效。
`primary_key`	`str \| None`	`None`	主表上用于层级的关键字段，可为字段内部名或字段标题（系统自动识别）。仅当 `auto_detect_related_tables=False` 且已设置 `main_table_name` 时参与解析。
`primary_key_values`	`dict[str, int \| float \| str] \| None`	`None`	子表过滤用的父表主键值：键为表名（或业务上的子表标识，与 `get_table_data` 约定一致），值为对应主键取值；用于有父子关系时只拉取某一父记录下的子表数据。仅 `gdim=True` 时有效。
`keep_gdim_id`	`bool`	`False`	是否保留输出表中的 `gdim_id` 列（仅 `gdim=True` 时生效）。该列主要用于后续更新 GDIM 中已有的数据。
`table_collection_name`	`str \| None`	`None`	输出 `TableCollection` 的 ``name``（集合元数据）。
`table_collection_title`	`str \| None`	`None`	输出 `TableCollection` 的 `title`。
`table_collection_description`	`str \| None`	`None`	输出 `TableCollection` 的 `description`。
`missing_error_type`	`Literal["error","warning","gdi_warning"]`	`"error"`	表/字段缺失时的处理策略：抛错、控制台警告、或在 GDIM 中以 `GDIWarning` 形式提示。
`empty_error_type`	`Literal["warning","gdi_warning","create_empty_table"]`	`"warning"`	读取到空表时的处理策略：`"warning"` / `"gdi_warning"` 会提示后跳过该表；`"create_empty_table"` 会按模板结构创建空的 `TableData` 并继续输出。若 `table_fields` 以 `dict` 指定了字段，生成的空表还会裁剪到本次请求的字段集合，保证空表 schema 与正常读取时一致。
`output_table_name`	`str \| None`	`None`	`OutputTable` 端口要输出的表名/表标题（与 `TableCollection.get_table` 的查找规则一致）；为 `None` 时默认取集合中第一张表；名称在集合中不存在时 `OutputTable` 为 `None`。
`gdim`	`bool`	`True`	若数据平台为原老版本系统 GBIM，则设置该值为 `False`。
`token / proj_id / host`	`str \| None` 等	`None`	构造函数中可直接传入鉴权信息：`token`、`proj_id`、host``（``host 为 `None` 时使用默认地址）。若未传入，则由 `pipeline.gdim_state` 或 `InputToken` 提供。注意：若在构造函数中设置了 proj_id``（赋给 ``self.proj_id），其优先级高于 `InputToken` 与 Pipeline 上的 `proj_id`；若希望通过 `InputToken` 切换项目，则不要在构造函数里写死 `proj_id`。

空表处理说明

当 empty_error_type="warning" 或 "gdi_warning" 时，空表会给出提示后被跳过，不会进入 OutputTables。
当 empty_error_type="create_empty_table" 时，模块会使用该表的模板元数据生成一个空的 TableData：
- 表名、标题、描述、字段元数据仍会保留；
- 若表中存在 id 列，后续仍会按 keep_gdim_id 的规则转换为 gdim_id 或删除；
- 若 table_fields 为 dict，则会仅保留本次请求的字段，避免空表比正常读取多出未请求列。

快速上手示例：空表时按模板生成空表

from gdisdk.modules.readers import GdimTableReader

reader = GdimTableReader(
    mname="ReadMaybeEmptyTable",
    token="你的GDIM Token",
    proj_id="你的GDIM项目ID",
    empty_error_type="create_empty_table",
    output_table_name="地层表",
)
reader.table_fields = {
    "地层表": ["层号", "岩土名称", "厚度"],
}

reader.execute()
table = reader.OutputTable.data

# 即使 GDIM 中这张表当前没有数据，仍会得到一个 0 行的 TableData，
# 并保留请求字段对应的 schema，便于后续模块继续运行。

在 pipeline 中的使用方式

from gdisdk.connectors import log_in
from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import GetGdimToken, GdimTableReader

pipeline = PipeLine(app_name="ReadGdimTables", app_title="读取GDIM表数据示例")

# 方式 A：在 Pipeline 上统一配置 GDIM 凭证（模块内部 get_token() 会优先使用 pipeline 的值）
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["剖面数据表", "钻孔表"]
read_tables.output_table_name = "剖面数据表"

pipeline.add_module(read_tables)

# 方式 B：用 GetGdimToken 输出到 InputToken（适合在 Pipeline 中统一鉴权/切换项目）
# get_token = GetGdimToken("GetToken", token="你的GDIM Token", proj_id="你的GDIM项目ID")
# links = get_token.OutputToken >> read_tables.InputToken
# pipe.add_links(links)

result = pipeline.run()
tables = read_tables.OutputTables.data
one_table = read_tables.OutputTable.data

更多信息

ReadGtbFile

模块简介与适用场景

ReadGtbFile 用于读取由 ExportGdimTables 导出的 .gtb 或 .xlsx 文件，并重建为可供下游继续处理的 TableCollection。
该模块适合在 “先导出 GDIM 表格文件，再由本地处理 / 人工编辑 / 外部流程生成新文件，最后重新读回 Pipeline” 的场景中使用。
读取时会恢复导出文件中的关键结构信息：
- metadata.dataTemplateId：用于标识导出文件对应的模板；
- metadata.tables：用于恢复每张表的内部名、标题和工作表名；
- metadata.tableRelations：若存在，会自动恢复主表 / 子表层级，便于后续 GdimTableWriter 按正确顺序写回。
文件中的表结构约定为：
- 第 1 行为字段标题；
- 第 2 行为字段内部名；
- 第 3 行及之后为数据行。
当 validate_template_id=True 且能取得有效的 token + proj_id 时，模块会额外校验文件模板 ID 是否与目标项目一致；若不一致，则给出 warning 并停止输出。

端口说明

输入端口 - InputToken：鉴权与项目定位信息 (token, proj_id, host)；仅当需要从 GDIM 文件服务下载文件，或要执行模板 ID 校验时需要；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取
输出端口 - OutputTables：从 .gtb / .xlsx 文件重建得到的 TableCollection

快速上手示例：读取本地导出的 GTB 文件

from gdisdk.modules.readers import ReadGtbFile

reader = ReadGtbFile(
    mname="ReadExportedTables",
    file="项目表格导出.gtb",
    validate_template_id=False,  # 仅做本地读取时可关闭模板校验
)

tables = reader.execute()
print(reader.OutputTables.data)

快速上手示例：读取 GDIM 文件服务中的导出文件

from gdisdk.modules.readers import ReadGtbFile

gdim_file = {
    "success": True,
    "fileId": "your-file-id",
    "filename": "gdim_tables.gtb",
    "originalFilename": "项目表格导出.gtb",
    "downloadUrl": "/minio/download/your-file-id",
    "host": "https://your-gdim-host/api/",
}

reader = ReadGtbFile(
    mname="ReadGtbFromGdim",
    file=gdim_file,
    token="你的GDIM Token",
    proj_id="你的GDIM项目ID",
)

reader.execute()
tables = reader.OutputTables.data

参数说明

ReadGtbFile 参数一览
参数名	类型	默认值	说明
`file`	`str \| Path \| dict \| None`	`None`	要读取的 `.gtb` / `.xlsx` 文件。支持本地路径，也支持 GDIM 文件描述 dict``（例如 ``ExportGdimTables(save_to_gdim=True) 的输出）。
`validate_template_id`	`bool`	`True`	是否校验文件中的 `dataTemplateId` 与目标 GDIM 项目的模板 ID 一致。仅在能取得有效 `token + proj_id` 时执行；不一致时会给出 warning 并停止输出。
`token`	`str \| None`	`None`	用户 token；也可通过 `InputToken` 或 `pipeline.gdim_state` 提供。
`proj_id`	`int \| str \| None`	`None`	目标 GDIM 项目 ID，用于模板 ID 校验；若设置，会覆盖 `InputToken` 或 `pipeline.gdim_state` 中的项目 ID。
`host`	`str \| None`	`None`	GDIM 平台地址。若为 `None`，则使用 `pipeline.gdim_state.host` 或环境变量默认值。

读取行为说明

当 file 为本地路径时，模块直接读取该文件。
当 file 为 GDIM 文件描述 dict 时，模块会先根据 downloadUrl / host 下载到工作目录，再执行解析。
若文件扩展名不是 .gtb 或 .xlsx，或 metadata 缺失 / 格式错误，模块会给出 GDIDataQualityWarning 并输出 None。
输出的每张 TableData 会使用字段内部名作为列名，同时把字段标题写入 name_to_title，以便兼顾程序处理与展示。

上传 GDIM 前检查

是否需要特别处理：当该模块在 GDIM 平台运行，且读取对象来自前端上传文件或需要校验目标项目模板时，是。
必须检查：
- 不要依赖仅本地存在的路径；上传后的推荐方式是由前端传入 GDIM 文件描述，并直接赋给 file；
- 文件建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``dict``） 提供，这是上传后的推荐方式。
建议检查：
- 仅在“离线查看导出结果”场景下，可将 validate_template_id 设为 False，避免因没有项目上下文而中断读取。
若遗漏，常见现象：
- 本地调试可读取固定路径文件，但上传 GDIM 后因文件路径不可见而失败；

更多信息

GdimAppDataReader

模块简介与适用场景

GdimAppDataReader 从 GDIM 数据库中读取已由其他 Pipeline 应用在平台上运行并落库的数据，反序列化后打包为 ResultModel，从端口 OutputResultModel 输出。
上游应用需在构建 Pipeline 时调用 save_data_to_db()，声明要持久化的内容（模块输出端口数据、Pipeline 本体属性、或模块计算参数）。平台执行该应用后，这些条目会按约定键名存入 GDIM；本模块按应用标题参数（app_title）定位到对应应用，再一次性取回全部已存字段。
ResultModel 中各字段的键名规则与 save_data_to_db 一致：
- "模块名@输出端口名" — 输出端口数据（如 "MyModule@OutputTable"）
- "pipeline@属性名" — Pipeline 本体上的直接属性（如 "pipeline@workspace"）；注意这与 add_attribute() 映射到模块参数的机制不同，后者需用 "模块名#参数名" 保存模块参数
- "模块名#参数名" — 模块的计算参数/属性
典型适用场景：
- 拆分应用：例如应用 A（如水腐蚀性分析）运行后把关键 TableData、阈值参数等写入 GDIM；应用 B（如报告生成）再通过 GdimAppDataReader 读回并交给 Word/图表模块；
- 本地联调：在配置好 token、proj_id``（或 Pipeline 的 ``gdim_state）的前提下，也可在脚本中读取已落库的某应用结果。

更详细的配置方式见运行机制 (Runtime) 中的「跨 Pipeline 数据」一节。从 ResultModel 中取单个字段时，可配合 filters）。

端口说明

输入端口 - InputToken：(token, proj_id, host)。若当前 Pipeline 已通过 pipeline.update_gdim_state(token=..., proj_id=..., host=...) 配置运行上下文，通常可不连接此端口，模块会从 Pipeline 自动获取 token。
输出端口 - OutputResultModel：反序列化后的 ResultModel；当无法解析 token、未设置 app_title、proj_id 缺失或与平台数据不匹配时可能为 None。

参数说明

GdimAppDataReader 参数一览
参数名	类型	默认值	说明
`app_title`	`str \| None`	`None`	目标应用在 GDIM 模板中的标题，须与保存数据的应用标题完全一致，且能唯一定位到一个应用（`appId`）。
`token` / `proj_id` / `host`	`str \| None` 等	`None`	鉴权与平台地址。可在构造函数传入并写入 `InputToken`；若未传，则依赖 `InputToken` 或 `pipeline.gdim_state`。`proj_id` 若在模块上显式设置，会覆盖 token 中的项目 ID。

快速上手示例：在 Pipeline 中读取另一应用保存的数据

from gdisdk.pipeline import PipeLine
from gdisdk.modules import GdimAppDataReader

pipe = PipeLine(app_name="ReportGenerate", app_title="报告生成")
pipe.update_gdim_state(token="...", proj_id="...")

reader = GdimAppDataReader(mname="ReadCorrosionApp")
reader.app_title = "水腐蚀性分析"  # 与上游应用在模板中的标题一致

pipe.add_module(reader)
pipe.run()

result_model = reader.OutputResultModel.data
if result_model is not None:
    # 键名取决于上游 save_data_to_db 的配置，例如：
    # table = result_model.get("CorrosionModule@OutputTable")

更多信息

运行机制 (Runtime)
modules.filters 模块帮助中的 GdimAppDataSelector。
API 参考 - modules 包
完整类定义与参数说明（readers）

GdimAppProjectInfoReader

模块简介与适用场景

GdimAppProjectInfoReader 用于读取 GDIM「项目信息」应用（Project Information APP）的数据，输出：
- OutputProjectInfo：项目基本信息（ ResultModel，字段会根据项目信息动态生成）；
- OutputCoordinateSystem：项目坐标系（ CoordinateSystem）。
典型适用场景：
- 在报表/成果图生成前读取工程名称、工程编号、地址等信息；
- 读取坐标系参数，为坐标转换或成果统一坐标基准提供依据（GDIM）。

端口说明

输入端口 - InputToken：鉴权与项目定位信息 (token, proj_id, host)；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取
输出端口 - OutputProjectInfo：项目信息（ResultModel，字段会根据 GDIM 项目信息动态生成） - OutputCoordinateSystem：项目坐标系（CoordinateSystem）

快速上手示例：读取项目信息与坐标系

from gdisdk.modules.readers import GdimAppProjectInfoReader

reader = GdimAppProjectInfoReader(
    mname="ReadProjectInfo",
    token="你的GDIM Token",
    proj_id="12345",
    host=None,
)

project_info = reader.execute()
coord = reader.OutputCoordinateSystem.data

参数说明

GdimAppProjectInfoReader 参数一览
参数名	类型	默认值	说明
`token / proj_id / host`	`str \| int \| None / int \| None / str \| None`	`None`	鉴权与项目定位信息。若未在模块中显式传入，模块会优先从 `pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host` 中获取；也可以通过 `InputToken` 端口传入 `(token, proj_id, host)`。
`gdim`	`bool`	`True`	若数据平台为原老版本系统 GBIM，则设置该值为 `False`。

在 pipeline 中的使用方式

from gdisdk.connectors import log_in
from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import GdimAppProjectInfoReader

pipe = PipeLine(app_name="ReadProjectInfo", app_title="读取项目信息示例")
pipe.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_info = GdimAppProjectInfoReader("ReadInfo")
pipeline.add_module(read_info)

result = pipeline.run()
info = read_info.OutputProjectInfo.data
coord = read_info.OutputCoordinateSystem.data

更多信息