# 解析表格结构

`POST` `/api/knowledge/document/parseTableStructure`

读取已上传的 Excel/CSV 文件的列名和示例数据，作为后续配置导入映射的依据。预分析可能调用模型推断列映射，会产生知识编译用量，但不触发文档导入或语义树生成。新上传文件仅需ossKey，知识库、原始文件名及稳定文档用量身份由后端恢复。兼容显式libraryId/documentUsageId，提供时必须与上传记录一致；fileName不覆盖上传记录。升级前无上传记录的文件启用计费时仍需提供libraryId，或重新上传。表头行号 headerRow 默认 1、数据起始行号 dataStartRow 默认 2，适用于绝大多数标准模板。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| libraryId | integer | 否 | 可选目标知识库ID；新上传文件由后端恢复，提供时必须一致；历史无记录文件启用计费时需提供 |
| documentUsageId | string | 否 | 可选文档用量身份；新上传文件由后端维护，提供时必须一致；历史请求仍可沿用预分析返回值 |
| fileName | string | 否 | 可选原始文件名；以服务端上传记录为准，历史无记录时用于预分析用量展示 |
| ossKey | string | 是 | 已上传文件的 OSS Key，由 /document/upload 接口返回 |
| headerRow | integer | 否 | 表头所在行号（从 1 开始），不传时默认 1 |
| dataStartRow | integer | 否 | 数据起始行号（从 1 开始），不传时默认 2 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |