OntiCards API 接口文档

文档说明

本文档描述了 OntiCards 系统的所有 API 接口，用于数据库连接、数据源管理、智能查询、数据审计等功能。

基础信息：

• 基础路径：/console/api

• Session认证：基于 Flask-Login 的 Session 认证（部分接口需要 @login_required 装饰器）

• API Key认证：基于API Key的无状态认证（适用于插件接口和外部调用）

• 认证方式：

• 请求格式：JSON（Content-Type: application/json）

• 响应格式：JSON

统一响应格式：

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

目录

1. 用户管理模块

1. API Key管理模块

1. 数据源管理模块

1. 数据卡片管理模块

1. 数据盘点模块

1. 智能查询模块

1. 数据审计模块

1. 版本更新日志模块

1. Excel字段提取模块

1. 模型配置信息管理模块

1. 历史查询模块

1. 监控中心模块

1. 系统配置模块

1. SSO单点登录模块

1. 提示词配置模块

1. 业务术语库管理模块

1. 数据治理模块 - 数据质检（第一阶段）

1. 数据治理模块 - 治理（第二阶段）

1. 用户管理模块

1.1 用户登录

接口描述： 用户登录，返回 JWT Token

请求类型： POST

接口路径： /console/api/login

是否需要登录： 否

请求参数：

请求示例：

{
  "username": "admin",
  "password": "123456"
}

返回示例：

{
  "code": 200,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

错误响应：

{
  "code": 400,
  "message": "Invalid username or password"
}

1.2 用户注册

接口描述： 新用户注册

请求类型： PUT

接口路径： /console/api/login

是否需要登录： 否

请求参数：

请求示例：

{
  "username": "newuser",
  "password": "123456"
}

返回示例：

{
  "code": 200,
  "message": "Registration successful"
}

1.3 获取当前用户信息

接口描述： 获取当前登录用户的详细信息

请求类型： GET

接口路径： /console/api/user

是否需要登录： 是

请求参数： 无

返回示例：

{
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "id": "uuid-string",
    "username": "admin",
    "nickname": "管理员",
    "avatar": "http://example.com/avatar.jpg",
    "user_group_name": "管理员组",
    "role": "admin",
    "login_at": "2025-01-20T10:30:00"
  }
}

1.4 更新当前用户信息

接口描述： 更新当前登录用户的昵称和头像

请求类型： PUT

接口路径： /console/api/user

是否需要登录： 是

请求参数：

请求示例：

{
  "nickname": "新昵称",
  "avatar": "http://example.com/new_avatar.jpg"
}

返回示例：

{
  "code": 200,
  "message": "Current user updated successfully"
}

1.5 退出登录

接口描述： 用户退出登录

请求类型： GET

接口路径： /console/api/logout

是否需要登录： 是

请求参数： 无

返回示例：

{
  "code": 200,
  "message": "Logged out successfully"
}

1.6 修改密码

接口描述： 修改用户密码

请求类型： POST

接口路径： /console/api/change_password

是否需要登录： 是

请求参数：

请求示例：

{
  "id": "uuid-string",
  "old_password": "old123",
  "new_password": "new123"
}

返回示例：

{
  "code": 200,
  "message": "Password changed successfully"
}

1.7 获取所有用户列表

接口描述： 获取系统中所有用户列表（管理员权限）

请求类型： GET

接口路径： /console/api/users/all

是否需要登录： 是

权限要求： 管理员

请求参数： 无

返回示例：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "uuid-string",
      "username": "admin",
      "nickname": "管理员",
      "avatar": "http://example.com/avatar.jpg",
      "status": "normal",
      "default_lang": "zh-CN",
      "user_group_name": "管理员组",
      "role": "admin",
      "login_at": "2025-01-20T10:30:00"
    }
  ]
}

1.8 用户管理（增删改）

接口描述： 管理员对用户进行创建、更新、删除操作

请求类型： POST / PUT / DELETE

接口路径： /console/api/users/manage

是否需要登录： 是

权限要求： 管理员

1.8.1 创建用户（POST）

请求参数：

请求示例：

{
  "username": "newuser",
  "nickname": "新用户",
  "email": "user@example.com",
  "password": "123456",
  "user_group_id": "uuid-string",
  "role": "normal"
}

1.8.2 更新用户（PUT）

请求参数：

请求示例：

{
  "id": "uuid-string",
  "nickname": "更新后的昵称",
  "role": "admin"
}

1.8.3 删除用户（DELETE）

请求参数：

请求示例：

{
  "id": "uuid-string"
}

返回示例：

{
  "code": 200,
  "message": "用户删除成功"
}

2. API Key管理模块

2.1 API Key认证说明

API Key认证方式：

API Key是一种无状态的认证方式，适用于插件接口、外部系统调用等场景。使用API Key时，不需要登录Session，只需在请求头中携带有效的API Key即可。

支持的认证头格式：

1. Authorization头（推荐）

   Authorization: <api_key>

1. Authorization头（Bearer格式）

   Authorization: Bearer <api_key>

1. X-API-Key头

   X-API-Key: <api_key>

API Key验证规则：

• API Key必须处于active状态

• API Key未过期（expires_at为空或未到期）

• API Key关联的用户必须存在且有效

• 每次成功调用后，系统会更新last_used_at字段

错误响应：

• 401 Unauthorized: 缺少API Key或API Key无效

• 403 Forbidden: API Key已禁用或已过期

2.2 查询API Key

接口描述： 查询API Key列表或单个API Key详情

请求类型： GET

接口路径： /console/api/api_keys

是否需要登录： 是

请求参数（Query）：

请求示例（查询列表）：

GET /console/api/api_keys

请求示例（查询单条）：

GET /console/api/api_keys?id=550e8400-e29b-41d4-a716-446655440000

返回示例（列表）：

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "生产环境API Key",
      "api_key": "ak_xxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "active",
      "expires_at": "2025-12-31T23:59:59+00:00",
      "last_used_at": "2025-12-29T10:30:00+00:00",
      "created_at": "2025-01-01T00:00:00+00:00",
      "updated_at": "2025-01-01T00:00:00+00:00"
    }
  ]
}

返回示例（单条）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "生产环境API Key",
    "api_key": "ak_xxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "active",
    "expires_at": "2025-12-31T23:59:59+00:00",
    "last_used_at": "2025-12-29T10:30:00+00:00",
    "created_at": "2025-01-01T00:00:00+00:00",
    "updated_at": "2025-01-01T00:00:00+00:00"
  }
}

返回字段说明：

• id: API Key唯一标识

• user_id: 所属用户ID（用于数据隔离）

• name: API Key名称/备注

• api_key: API Key明文（仅创建时和查询时返回）

• status: 状态（active=可用，disabled=已禁用）

• expires_at: 过期时间（ISO 8601格式，null表示永不过期）

• last_used_at: 最后使用时间

• created_at: 创建时间

• updated_at: 更新时间

2.3 创建API Key

接口描述： 为指定用户创建新的API Key

请求类型： POST

接口路径： /console/api/api_keys

是否需要登录： 是

请求参数：

请求示例（自动生成API Key）：

{
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "生产环境API Key",
  "expires_at": "2025-12-31T23:59:59+00:00"
}

请求示例（自定义API Key）：

{
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "测试环境API Key",
  "api_key": "ak_custom_key_12345678901234567890",
  "expires_at": null
}

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "api_key": "ak_xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

说明：

1. 如果不传api_key参数，系统会自动生成格式为ak_开头的32字符随机字符串

1. API Key创建后，api_key明文只在创建时返回一次，后续查询不会返回完整明文

1. expires_at为空或null表示永不过期

1. 创建时status默认为active

2.4 更新API Key

接口描述： 更新API Key的名称、状态或过期时间

请求类型： PUT

接口路径： /console/api/api_keys

是否需要登录： 是

请求参数：

请求示例（更新名称和状态）：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "生产环境API Key（已更新）",
  "status": "disabled"
}

请求示例（延长过期时间）：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2026-12-31T23:59:59+00:00"
}

请求示例（设为永不过期）：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "expires_at": null
}

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

重要规则：

1. expires_at只能延长，不能缩短（安全考虑）

1. 如果原本就有过期时间，新的expires_at必须晚于原过期时间

1. 可以将有过期时间的Key改为永不过期（传null）

1. status只能设为active或disabled

错误响应（尝试缩短过期时间）：

{
  "code": 400,
  "msg": "expires_at 只能延长，不能缩短",
  "data": null
}

2.5 删除API Key

接口描述： 删除指定的API Key

请求类型： DELETE

接口路径： /console/api/api_keys

是否需要登录： 是

请求参数：

请求示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

说明： 删除API Key后，使用该Key的所有请求将立即失效

3. 数据源管理模块

3.1 测试数据库连接

接口描述： 测试数据库连接是否可用

请求类型： POST

接口路径： /console/api/connect_test

是否需要登录： 是

请求参数：

数据库类型说明：

• MySQL: 需要 username, password, host, port, database

• PostgreSQL: 需要 username, password, host, port, database

• SQL Server: 需要 username, password, (dsn 或 host+port), database

• Oracle: 需要 username, password, host, port, (service_name 或 sid)

• SQLite: 需要 (sqlite_memory=true 或 sqlite_path)

• Trino: 需要 host, port, catalog, schema

• 电科金仓（KingBase）: 需要 username, password, host, port, database（基于 PostgreSQL 内核，兼容 PostgreSQL 语法）

• OceanBase（MySQL 租户模式）: 需要 username, password, host, port, database；使用 mysql+pymysql 协议，默认端口 2881

• 达梦（DMBase）: 需要 username, password, host, port, database（兼容 Oracle 语法）

💡 TIP：OceanBase 原生提供 MySQL 与 Oracle 双兼容模式，当前 API 已支持 MySQL 租户模式；Oracle 租户模式将在后续版本中支持。

请求示例（MySQL）：

{
  "connect_name": "生产库A",
  "db_type": "mysql",
  "username": "root",
  "password": "password123",
  "host": "192.168.1.100",
  "port": 3306,
  "database": "test_db"
}

返回示例：

{
  "code": 200,
  "msg": "连接成功",
  "result": {
    "database_type": "mysql",
    "database_version": "8.0.33",
    "connection": "mysql+pymysql://root:***@192.168.1.100:3306/test_db"
  }
}

错误响应：

{
  "code": 400,
  "msg": "数据库连接失败: Access denied for user",
  "result": null
}

3.2 提取数据库表结构

接口描述： 从数据库中提取表结构信息，并生成数据卡片。支持全量抽取（所有表）或指定抽取（仅特定表）。

请求类型： POST

接口路径： /console/api/extract_schema

是否需要登录： 是

请求参数：

请求示例（全量抽取）：

{
  "connect_name": "生产库A",
  "db_type": "mysql",
  "username": "root",
  "password": "password123",
  "host": "192.168.1.100",
  "port": 3306,
  "database": "test_db",
  "request_id": "req-123456"
}

请求示例（抽取指定表）：

{
  "connect_name": "生产库A",
  "db_type": "mysql",
  "username": "root",
  "password": "password123",
  "host": "192.168.1.100",
  "port": 3306,
  "database": "test_db",
  "table_names": ["customers", "orders"],
  "request_id": "req-123456"
}

返回示例：

{
  "code": 200,
  "msg": "提取成功",
  "data": {
    "insert_result": {
      "message": "success",
      "inserted": 2,
      "skipped": 0,
      "total": 2
    },
    "generated_cards": [
      {
        "id": "uuid-xxx",
        "table_name": "customers",
        "card_content": "..."
      }
    ],
    "datasource_info": {
      "id": "ds-xxx",
      "connect_name": "生产库A",
      "database_type": "mysql"
    }
  }
}

3.3 获取数据源中的表列表

接口描述： 获取数据源中的所有表和视图列表（不提取结构），用于前端展示让用户选择要抽取的表。

请求类型： POST

接口路径： /console/api/list_tables

是否需要登录： 是

请求参数：

请求示例：

{
  "connect_name": "生产库A",
  "db_type": "mysql",
  "username": "root",
  "password": "password123",
  "host": "192.168.1.100",
  "port": 3306,
  "database": "test_db"
}

成功响应：

{
  "code": 200,
  "msg": "success",
  "result": {
    "tables": [
      { "name": "customers", "type": "TABLE" },
      { "name": "orders", "type": "TABLE" },
      { "name": "products", "type": "TABLE" },
      { "name": "user_stats_view", "type": "VIEW" }
    ],
    "total": 4
  }
}

响应字段说明：

错误响应：

{
  "code": 400,
  "msg": "数据库连接失败: Access denied",
  "result": null
}

3.4 取消提取表结构

接口描述： 取消正在进行的表结构提取操作，并清理已生成的数据

请求类型： POST

接口路径： /console/api/cancel_extract_schema

是否需要登录： 是

请求参数：

请求示例：

{
  "request_id": "req-123456",
  "config": {
    "connect_name": "生产库A",
    "db_type": "mysql",
    "host": "192.168.1.100",
    "port": 3306,
    "database": "test_db"
  }
}

返回示例：

{
  "code": 200,
  "msg": "取消成功，已清理所有相关数据",
  "data": {
    "request_id": "req-123456",
    "deleted_schemas": 50,
    "deleted_cards": 50,
    "deleted_weaviate": 50,
    "deleted_datasource": 1,
    "status": "cancelled"
  }
}

3.5 获取数据源列表

接口描述： 分页获取当前用户的所有数据源列表

请求类型： GET

接口路径： /console/api/datasource_tool

是否需要登录： 是

请求参数（Query）：

请求示例：

GET /console/api/datasource_tool?page=1&page_size=20

返回示例：

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "items": [
      {
        "id": "uuid-string",
        "user_id": "uuid-string",
        "connect_name": "生产库A",
        "db_type": "mysql",
        "database_name": "test_db",
        "table_num": 50,
        "status": "available",
        "connect_info": "mysql+pymysql://root:***@192.168.1.100:3306/test_db",
        "datacard_count": 50,
        "weaviate_num": 48,
        "schemas": [
          {
            "id": "uuid-string",
            "table_name": "users",
            "db_type": "mysql",
            "database_name": "test_db",
            "db_version": "8.0",
            "is_view": false,
            "view_name": null,
            "is_filled": true,
            "catalog_type": "mysql",
            "schema_text": {
              "columns": [
                {"name": "id", "type": "int", "nullable": false, "primary_key": true},
                {"name": "name", "type": "varchar(100)", "nullable": true}
              ],
              "indexes": []
            },
            "filled_data": {
              "table_comment": "用户表",
              "business_desc": "存储系统用户信息"
            },
            "created_at": "2025-01-20T10:30:00",
            "updated_at": "2025-01-20T10:30:00"
          }
        ],
        "created_at": "2025-01-20T10:30:00",
        "updated_at": "2025-01-20T10:30:00"
      }
    ],
    "page": 1,
    "page_size": 20,
    "total": 5,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false,
    "weaviate_count": 50
  }
}

返回字段说明：

• datacard_count: 该数据源关联的数据卡片数量

• weaviate_num: 该数据源在向量库中实际存在的记录数量（用于校验同步状态）

• schema_text: 表结构详情（已解析为JSON对象，包含列信息、索引等）

• filled_data: LLM填充的业务描述信息

• schemas: 该数据源关联的表结构信息列表

• weaviate_count: 当前用户向量库中的总记录数（跨所有数据源）

3.6 更新数据源信息

接口描述： 更新数据源的连接名称、状态等信息

请求类型： PUT

接口路径： /console/api/datasource_tool/

是否需要登录： 是

路径参数：

请求参数：

请求示例：

{
  "connect_name": "更新后的连接名",
  "status": "available"
}

返回示例：

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid-string",
    "user_id": "uuid-string",
    "connect_name": "更新后的连接名",
    "db_type": "mysql",
    "database_name": "test_db",
    "table_num": 50,
    "status": "available",
    "connect_info": "mysql+pymysql://root:***@192.168.1.100:3306/test_db",
    "created_at": "2025-01-20T10:30:00",
    "updated_at": "2025-01-20T10:30:00",
    "schemas_updated": 0,
    "cards_updated": 1
  }
}

返回字段说明：

• schemas_updated: 同步更新的表结构记录数（connect_name 变更时同步）

• cards_updated: 同步更新的数据卡片记录数（connect_name 变更时同步）

3.7 删除数据源

接口描述： 删除指定的数据源及其关联的所有数据（表结构、数据卡片、向量数据、盘点数据、术语库关联等）

请求类型： DELETE

接口路径： /console/api/datasource_tool/

是否需要登录： 是

路径参数：

请求参数： 无

返回示例：

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": "uuid-string",
    "schemas_deleted": 50,
    "cards_deleted": 50,
    "term_library_links_deleted": 2,
    "inventory_jobs_deleted": 1,
    "inventory_job_results_deleted": 10,
    "table_relationships_deleted": 5,
    "table_relationship_cards_deleted": 5,
    "field_mappings_deleted": 20,
    "weaviate_count": 50,
    "weaviate_deleted": true,
    "field_index_deleted": 50
  }
}

返回字段说明：

3.8 刷新数据源

接口描述： 刷新数据源，支持快速刷新（仅测试连接并更新状态）和全量刷新（重新提取表结构并更新数据卡片）两种模式

请求类型： POST

接口路径： /console/api/datasource_tool//refresh

是否需要登录： 是

路径参数：

Query参数：

模式说明：

• quick：快速刷新，仅测试数据库连接并更新数据源状态，不重新提取表结构

• full：全量刷新，重新提取所有表结构，对比差异后更新数据卡片和向量库

3.8.1 快速刷新（quick）

请求示例：

POST /console/api/datasource_tool/uuid-string/refresh?mode=quick

返回示例：

{
  "code": 200,
  "msg": "刷新完成（quick）",
  "data": {
    "mode": "quick",
    "id": "uuid-string",
    "connect_name": "生产库A",
    "status_before": "unavailable",
    "status_after": "available",
    "database_type": "mysql",
    "database_name": "test_db",
    "database_version": "8.0.33",
    "connection": "mysql+pymysql://root:***@192.168.1.100:3306/test_db",
    "error": null
  }
}

返回字段说明：

3.8.2 全量刷新（full）

请求示例：

POST /console/api/datasource_tool/uuid-string/refresh?mode=full

返回示例：

{
  "code": 200,
  "msg": "刷新完成（full）",
  "data": {
    "mode": "full",
    "added_tables": ["new_table1"],
    "removed_tables": ["deleted_table"],
    "changed_tables": ["updated_table1", "updated_table2"],
    "unchanged_tables": 47,
    "schemas_deleted": 1,
    "cards_deleted": 1,
    "weaviate_deleted": 1,
    "cards_generated": 3,
    "total_tables": 50
  }
}

返回字段说明：

4. 数据卡片管理模块

4.1 获取数据卡片列表

接口描述： 获取当前用户的所有数据卡片，支持按数据源筛选、关键字搜索、分页

请求类型： GET

接口路径： /console/api/datacard_tool

是否需要登录： 是

请求参数（Query）：

请求示例：

GET /console/api/datacard_tool?connect_name=生产库A&q=订单&page=1&page_size=20&parse_json=true

返回示例（group_by=datasource）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total_cards": 50,
    "total_datasources": 2,
    "items": [
      {
        "datasource": {
          "connect_name": "生产库A",
          "db_type": "mysql",
          "database_name": "test_db",
          "table_num": 30,
          "status": "available",
          "connect_info_masked": "mysql+pymysql://root:***@192.168.1.100:3306/test_db"
        },
        "cards": [
          {
            "doc_id": "uuid-string",
            "table_name": "orders",
            "connect_name": "生产库A",
            "connect_info_masked": "mysql+pymysql://root:***@192.168.1.100:3306/test_db",
            "w_uuid": "uuid-string",
            "card_data": "{\"table_name\":\"orders\",\"columns\":[...]}"
          }
        ]
      }
    ]
  }
}

返回示例（group_by=flat）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total_cards": 50,
    "total_datasources": 2,
    "items": [
      {
        "doc_id": "uuid-string",
        "table_name": "orders",
        "connect_name": "生产库A",
        "w_uuid": "uuid-string",
        "card_data": "{\"table_name\":\"orders\",\"columns\":[...]}"
      }
    ],
    "page": 1,
    "page_size": 20,
    "total": 50,
    "total_pages": 3
  }
}

4.2 更新数据卡片

接口描述： 更新指定数据卡片的内容

请求类型： PUT

接口路径： /console/api/datacard_tool

是否需要登录： 是

请求参数：

请求示例：

{
  "doc_id": "uuid-string",
  "card_data": {
    "table_name": "orders",
    "table_desc": "订单表",
    "columns": [
      {
        "name": "id",
        "type": "int",
        "comment": "订单ID",
        "nullable": false
      }
    ]
  }
}

返回示例：

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "doc_id": "uuid-string",
    "w_uuid": "new-uuid-string",
    "card_data": {...},
    "_vector_ops": {
      "delete_old_ok": true,
      "old_w_uuid": "old-uuid-string",
      "new_w_uuid": "new-uuid-string"
    }
  }
}

说明： 更新数据卡片时，系统会自动更新向量数据库（Weaviate）中的向量数据。

5. 数据盘点模块

5.1 定向盘点

5.1.1 获取数据源表列表

接口描述： 获取指定数据源下的所有表，包含表的质量等级、缺失字段数等信息

请求类型： GET

接口路径： /console/api/target_inventory/tables

是否需要登录： 是

请求参数：

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "tables": [
      {
        "table_name": "orders",
        "quality_level": "low",
        "missing_fields_count": 5,
        "is_ai_filled": false
      },
      {
        "table_name": "customers",
        "quality_level": "high",
        "missing_fields_count": 0,
        "is_ai_filled": false
      }
    ]
  }
}

质量等级说明：

• low: 目标表（需要补充注释的表）

• medium: LLM填充表（已通过AI补充注释）

• high: 优质参考表（注释完整的表）

5.1.2 启动定向盘点任务

接口描述： 创建定向盘点任务，对选定的目标表进行字段注释推荐和表关系推断

请求类型： POST

接口路径： /console/api/target_inventory/run

是否需要登录： 是

请求参数：

请求示例：

{
  "datasource_id": "xxx-xxx-xxx",
  "target_tables": ["orders", "order_items"],
  "ref_tables": ["customers", "products"],
  "dict_file_id": "dict-001",
  "options": {
    "enable_profiling": true,
    "confidence_threshold": 0.7
  }
}

响应示例：

{
  "code": 200,
  "msg": "任务创建成功",
  "data": {
    "job_id": "job-xxx-xxx",
    "status": "queued",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

5.1.3 确认字段映射

接口描述： 用户确认字段注释推荐结果，保存到字段映射表

请求类型： POST

接口路径： /console/api/target_inventory/confirm

是否需要登录： 是

请求参数：

请求示例：

{
  "job_id": "job-xxx-xxx",
  "mappings": [
    {
      "source_table": "customers",
      "source_column": "customer_name",
      "target_table": "orders",
      "target_column": "cust_name",
      "mapping_type": "semantic_match",
      "confidence": 0.95
    }
  ]
}

5.1.4 确认表关系

接口描述： 用户确认表关系推断结果，保存到表关系表

请求类型： POST

接口路径： /console/api/target_inventory/confirm_relationships

是否需要登录： 是

请求参数：

请求示例：

{
  "job_id": "job-xxx-xxx",
  "relationships": [
    {
      "table_a": "orders",
      "table_b": "customers",
      "relationship_type": "foreign_key",
      "join_conditions": [
        {
          "column_a": "customer_id",
          "column_b": "id",
          "operator": "="
        }
      ],
      "cardinality": "N:1",
      "confidence": 0.98
    }
  ]
}

5.1.5 生成关系卡片

接口描述： 基于确认的表关系生成关系卡片并入库（数据库+向量库）

请求类型： POST

接口路径： /console/api/target_inventory/generate_cards

是否需要登录： 是

请求参数：

响应示例：

{
  "code": 200,
  "msg": "关系卡片生成成功",
  "data": {
    "cards_count": 5,
    "vector_indexed": true
  }
}

5.2 全域盘点

5.2.1 启动全域盘点

接口描述： 自动对数据源所有表进行关系发现，支持单数据源和多数据源模式

请求类型： POST

接口路径： /console/api/global_inventory/discover

是否需要登录： 是

请求参数：

请求示例（单数据源）：

{
  "datasource_id": "xxx-xxx-xxx",
  "schema_name": "public",
  "confidence_threshold": 0.6,
  "max_workers": 8,
  "enable_profiling": true
}

请求示例（多数据源）：

{
  "datasource_ids": ["xxx-xxx-xxx", "yyy-yyy-yyy"],
  "confidence_threshold": 0.7,
  "max_workers": 10
}

响应示例：

{
  "code": 200,
  "msg": "全域盘点完成",
  "data": {
    "success": true,
    "tables_count": 25,
    "relationships_count": 48,
    "cards_count": 25,
    "is_multi_source": false,
    "cross_source_count": 0,
    "execution_time": "125.3s"
  }
}

响应示例（多数据源）：

{
  "code": 200,
  "msg": "全域盘点完成",
  "data": {
    "success": true,
    "tables_count": 50,
    "relationships_count": 95,
    "cards_count": 50,
    "is_multi_source": true,
    "cross_source_count": 12,
    "execution_time": "256.7s"
  }
}

5.2.2 获取单表关系卡片

接口描述： 获取指定表的完整关系卡片数据

请求类型： GET

接口路径： /console/api/global_inventory/cards//

是否需要登录： 是

路径参数：

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "table_name": "orders",
    "datasource_id": "xxx-xxx-xxx",
    "relationships": [
      {
        "target_table": "customers",
        "target_datasource_id": "xxx-xxx-xxx",
        "join_conditions": [
          {
            "source_column": "customer_id",
            "target_column": "id",
            "operator": "="
          }
        ],
        "relationship_type": "foreign_key",
        "relationship_strength": 0.95,
        "cardinality": "N:1",
        "is_cross_source": false
      },
      {
        "target_table": "products",
        "target_datasource_id": "yyy-yyy-yyy",
        "join_conditions": [
          {
            "source_column": "product_code",
            "target_column": "code",
            "operator": "="
          }
        ],
        "relationship_type": "semantic_match",
        "relationship_strength": 0.82,
        "cardinality": "N:1",
        "is_cross_source": true
      }
    ],
    "related_datasource_ids": ["xxx-xxx-xxx", "yyy-yyy-yyy"],
    "has_cross_source_relations": true
  }
}

5.2.3 获取数据源所有关系卡片

接口描述： 获取指定数据源下所有表的关系卡片列表

请求类型： GET

接口路径： /console/api/global_inventory/cards/

是否需要登录： 是

路径参数：

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "datasource_id": "xxx-xxx-xxx",
    "cards": [
      {
        "table_name": "orders",
        "relationships_count": 3,
        "has_cross_source_relations": false
      },
      {
        "table_name": "customers",
        "relationships_count": 2,
        "has_cross_source_relations": true
      }
    ],
    "total_count": 25
  }
}

6. 智能查询模块

6.1 基于数据卡片的聚合查询（Session认证）

接口描述： 根据自然语言问题，智能检索相关数据卡片，生成SQL并执行查询，支持多表关联和跨数据源查询

请求类型： POST

接口路径： /console/api/query_by_datacards_agg

是否需要登录： 是

请求参数：

说明：

• 融合策略（AND/OR/PRIORITY/UNION）由系统根据自然语言问题自动推断，无需手动指定

• 查询类型（聚合/明细）由系统自动检测，无需手动指定

• 不指定数据源时，搜索当前用户的所有数据源

请求示例：

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "enable_rerank": true
}

使用数据源ID的请求示例：

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "datasource_ids": ["550e8400-e29b-41d4-a716-446655440000", "660e8400-e29b-41d4-a716-446655440001"],
  "enable_rerank": true
}

使用单个数据源ID的请求示例：

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "datasource_id": "550e8400-e29b-41d4-a716-446655440000"
}

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "clusters": [
      {
        "db_type": "mysql",
        "connect_name": "生产库A",
        "cluster_tables": [
          {
            "table_name": "orders",
            "columns": [
              {"name": "order_id", "type": "int"},
              {"name": "customer_id", "type": "varchar"},
              {"name": "amount", "type": "decimal"},
              {"name": "create_time", "type": "datetime"}
            ]
          }
        ],
        "target_sql": "SELECT o.customer_id, SUM(o.amount) as total_amount FROM orders o WHERE o.create_time >= DATE_SUB(NOW(), INTERVAL 1 MONTH) AND o.amount > 1000 GROUP BY o.customer_id",
        "rows": [
          {
            "customer_id": "C001",
            "total_amount": 5000.00
          }
        ],
        "entity_ids": ["C001"],
        "datasource_ids": ["uuid1"],
        "datasource_names": ["生产库A"],
        "table_names": ["orders"],
        "warnings": []
      }
    ],
    "merge": {
      "strategy": "SINGLE_CLUSTER",
      "entity_key": "customer_id",
      "fusion_method": "none",
      "note": "单数据源查询，无需跨源融合"
    },
    "final_rows": [
      {
        "customer_id": "C001",
        "total_amount": 5000.00
      }
    ],
    "fill_warnings": [],
    "data_cards": [
      {
        "doc_id": "uuid-string",
        "table_name": "orders",
        "database_name": "ecommerce_db",
        "connect_name": "生产库A",
        "card_content": {}
      }
    ],
    "term_rewrite": {
      "enabled": true,
      "matched_count": 1,
      "matched_terms": [
        {
          "term_name": "GMV",
          "term_definition": "商品交易总额",
          "matched_alias": "订单金额",
          "library_name": "电商术语库"
        }
      ],
      "rewritten_question": "查询最近一个月GMV（商品交易总额）大于1000的客户信息"
    }
  }
}

返回字段说明：

说明：

1. 系统首先使用向量检索找到相关的数据卡片

1. 如果启用了术语展开（enable_term_rewrite=true），会先对问题进行术语识别和改写

1. 根据数据卡片构建表结构和关系

1. 优先使用关系卡片中的JOIN条件（如果存在），提升多表查询准确率

1. 使用LLM生成SQL查询（结合关系卡片信息）

1. 执行SQL并返回结果

1. 如果涉及多个数据源，根据融合策略合并结果（利用关系信息）

关系卡片增强效果：

• JOIN条件准确率提升15-20%

• 多表查询成功率提升20-25%

• 支持跨数据源关系识别

• 显著减少笛卡尔积问题

6.2 基于数据卡片的聚合查询（API Key认证插件接口）

接口描述： 基于API Key认证的聚合查询接口，专为插件和外部系统调用设计，无需Session登录

请求类型： POST

接口路径： /console/api/query_by_datacards_agg_plugin

是否需要登录： 否（使用API Key认证）

认证方式： 在请求头中携带API Key（参见 2.1 API Key认证说明）

请求头示例：

Authorization: ak_xxxxxxxxxxxxxxxxxxxxxxxx
或
Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxxxxxx
或
X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxx

请求参数：

参数优先级说明：

• connect_name > datasource_id > datasource_ids > 不指定（搜索所有数据源）

• 当传入 connect_name 时，系统会根据该名称在用户的数据源中查找对应的数据源ID

请求示例：

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "enable_rerank": true
}

使用数据源名称的请求示例：

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "connect_name": "生产库A",
  "enable_rerank": true
}

使用数据源ID的请求示例：

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "datasource_ids": ["550e8400-e29b-41d4-a716-446655440000", "660e8400-e29b-41d4-a716-446655440001"],
  "enable_rerank": true
}

使用单个数据源ID的请求示例：

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "datasource_id": "550e8400-e29b-41d4-a716-446655440000",
  "enable_rerank": false
}

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "clusters": [
      {
        "db_type": "mysql",
        "connect_name": "生产库A",
        "cluster_tables": [
          {
            "table_name": "orders",
            "columns": [
              {"name": "order_id", "type": "int"},
              {"name": "customer_id", "type": "varchar"},
              {"name": "amount", "type": "decimal"},
              {"name": "create_time", "type": "datetime"}
            ]
          }
        ],
        "target_sql": "SELECT o.customer_id, SUM(o.amount) as total_amount FROM orders o WHERE o.create_time >= DATE_SUB(NOW(), INTERVAL 1 MONTH) AND o.amount > 1000 GROUP BY o.customer_id",
        "rows": [
          {
            "customer_id": "C001",
            "total_amount": 5000.00
          }
        ],
        "entity_ids": ["C001"],
        "datasource_ids": ["uuid1"],
        "datasource_names": ["生产库A"],
        "table_names": ["orders"],
        "warnings": []
      }
    ],
    "merge": {
      "strategy": "SINGLE_CLUSTER",
      "entity_key": "customer_id",
      "fusion_method": "none",
      "note": "单数据源查询，无需跨源融合"
    },
    "final_rows": [
      {
        "customer_id": "C001",
        "total_amount": 5000.00
      }
    ],
    "fill_warnings": [],
    "data_cards": [
      {
        "doc_id": "uuid-string",
        "table_name": "orders",
        "database_name": "ecommerce_db",
        "connect_name": "生产库A",
        "card_content": {}
      }
    ],
    "term_rewrite": {
      "enabled": true,
      "matched_count": 0,
      "matched_terms": [],
      "rewritten_question": "查询最近一个月订单金额大于1000的客户信息"
    }
  }
}

返回字段说明：

与 6.1 接口相同，请参考 6.1 返回字段说明。主要区别在于 term_rewrite.matched_terms 数组中每个元素还会包含以下字段：

融合策略说明： 系统会根据自然语言问题自动推断融合策略：

• OR（或）: 满足任一条件即可，结果为多个数据源的并集

• AND（且）: 需同时满足多个条件，结果为多个数据源的交集

• PRIORITY（优先）: 优先使用主数据源，其他数据源作为补充

• UNION（合并）: 合并所有结果并去重

• TRINO_UNIFIED（Trino统一查询）: 当所有表都通过Trino连接时，使用Trino的跨catalog能力统一查询

关系卡片增强说明：

• 系统优先使用关系卡片中的JOIN条件生成SQL

• 关系卡片提供的JOIN建议包含置信度和关系类型

• 支持跨数据源关系识别（is_cross_source标识）

• 显著提升多表查询准确率（+20-25%）和JOIN条件准确率（+15-20%）

• 减少笛卡尔积等常见问题

权限说明：

• 基于API Key的user_id进行数据隔离

• 只能查询API Key所属用户有权限访问的数据源和数据卡片

• 向量检索召回的数据卡片会自动按用户ID过滤

错误响应：

401 Unauthorized - 缺少API Key：

{
  "code": 401,
  "msg": "缺少 API Key",
  "data": null
}

401 Unauthorized - API Key无效：

{
  "code": 401,
  "msg": "API Key 无效",
  "data": null
}

403 Forbidden - API Key已禁用：

{
  "code": 403,
  "msg": "API Key 已禁用",
  "data": null
}

403 Forbidden - API Key已过期：

{
  "code": 403,
  "msg": "API Key 已过期",
  "data": null
}

400 Bad Request - 缺少query参数：

{
  "code": 400,
  "msg": "请提供 query",
  "data": null
}

说明：

1. 此接口与5.1功能类似，但使用API Key认证而非Session认证

1. 适用于外部系统集成、插件开发等场景

1. API Key会自动映射到所属用户，实现数据隔离

1. 每次成功调用后，系统会自动更新API Key的last_used_at字段

1. 向量检索和重排序的参数（如distance_threshold、max_results等）使用系统默认配置

7. 数据审计模块

7.1 数据质量审计

接口描述： 对指定表进行数据质量审计，统计各字段的空值、空字符串等情况

请求类型： POST

接口路径： /console/api/data_audit

是否需要登录： 是

请求参数：

connect_info 对象结构：

请求示例：

{
  "db_type": "mysql",
  "connect_info": {
    "host": "192.168.1.100",
    "port": 3306,
    "user": "root",
    "password": "password123"
  },
  "database_name": "test_db",
  "table_name": "orders"
}

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "db_type": "mysql",
    "database": "test_db",
    "schema": null,
    "table": "orders",
    "report": [
      {
        "column_name": "customer_name",
        "data_type": "varchar(100)",
        "total_rows": 1000,
        "null_count": 50,
        "empty_str_count": 20,
        "missing_count": 70,
        "missing_pct": 7.0
      },
      {
        "column_name": "order_date",
        "data_type": "datetime",
        "total_rows": 1000,
        "null_count": 10,
        "empty_str_count": 0,
        "missing_count": 10,
        "missing_pct": 1.0
      }
    ]
  }
}

返回字段说明：

• total_rows: 表总行数

• null_count: NULL值数量

• empty_str_count: 空字符串数量（仅字符串类型字段）

• missing_count: 缺失值总数（null_count + empty_str_count）

• missing_pct: 缺失值百分比

8. 版本更新日志模块

8.1 获取版本更新日志列表

接口描述： 获取所有版本更新日志列表

请求类型： GET

接口路径： /console/api/changelog

是否需要登录： 是

请求参数： 无

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "version": "1.0.0",
      "title": "初始版本发布",
      "content_md": "# 更新内容\n\n- 支持MySQL数据库连接\n- 支持数据卡片生成",
      "status": "public",
      "created_at": "2025-01-20T10:30:00",
      "updated_at": "2025-01-20T10:30:00"
    }
  ]
}

8.2 获取版本更新日志详情

接口描述： 获取指定版本的更新日志详情

请求类型： GET

接口路径： /console/api/changelog/

是否需要登录： 是

路径参数：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "version": "1.0.0",
    "title": "初始版本发布",
    "content_md": "# 更新内容\n\n- 支持MySQL数据库连接\n- 支持数据卡片生成",
    "status": "public",
    "created_at": "2025-01-20T10:30:00",
    "updated_at": "2025-01-20T10:30:00"
  }
}

8.3 创建版本更新日志

接口描述： 创建新的版本更新日志

请求类型： POST

接口路径： /console/api/changelog

是否需要登录： 是

请求参数：

请求示例：

{
  "version": "1.1.0",
  "title": "新增数据审计功能",
  "content_md": "# 更新内容\n\n- 新增数据质量审计功能\n- 优化查询性能",
  "status": "public"
}

返回示例：

{
  "code": 200,
  "msg": "created",
  "data": {
    "id": 2
  }
}

8.4 更新版本更新日志

接口描述： 更新指定版本的更新日志

请求类型： PUT

接口路径： /console/api/changelog/

是否需要登录： 是

路径参数：

请求参数：

请求示例：

{
  "title": "更新后的标题",
  "status": "public"
}

返回示例：

{
  "code": 200,
  "msg": "updated",
  "data": {
    "id": 2
  }
}

8.5 删除版本更新日志

接口描述： 删除指定版本的更新日志

请求类型： DELETE

接口路径： /console/api/changelog/

是否需要登录： 是

路径参数：

返回示例：

{
  "code": 200,
  "msg": "deleted",
  "data": {
    "id": 2
  }
}

9. Excel字段提取模块

9.1 从Excel提取字段数据

接口描述： 从Excel文件中提取表字段描述数据，并填充到数据库表结构中

请求类型： POST

接口路径： /console/api/extract_field_data_excel

是否需要登录： 是

请求参数： FormData 格式

field_data JSON结构：

请求示例（FormData）：

file: [Excel文件]
sheet_name: "字段描述"
field_data: {
  "tb_name_column": "A",
  "tb_desc_column": "B",
  "field_name_column": "C",
  "field_desc_column": "D",
  "field_value_desc_column": "E",
  "has_title": true
}

返回示例：

{
  "code": 200,
  "msg": "提取成功",
  "data": {
    "total_tables": 10,
    "filled_tables": 10,
    "total_fields": 150,
    "filled_fields": 145
  }
}

说明： 此接口会解析Excel文件，提取表名、字段名、字段描述等信息，并自动填充到对应的数据库表结构中。

10. 模型配置信息管理模块

接口描述： 管理系统中可用的大模型配置，包括查询、创建、更新和删除。

基础路径： /console/api/model_config

10.1 查询模型配置

• 请求类型： GET

• 是否需要登录： 否

• 查询参数（Query）：

请求示例：

GET /console/api/model_config
GET /console/api/model_config?id=550e8400-e29b-41d4-a716-446655440000

返回示例（列表）：

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "model_name": "豆包大模型",
      "model_type": "豆包",
      "model_api_key": "sk-****",
      "model_class": "大语言",
      "url": "https://api.doubao.com/v1/chat/completions",
      "created_at": "2025-11-28T12:49:00+08:00",
      "updated_at": "2025-11-28T12:49:00+08:00"
    }
  ]
}

返回示例（单条）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "model_name": "豆包大模型",
    "model_type": "豆包",
    "model_api_key": "sk-****",
    "model_class": "大语言",
    "url": "https://api.doubao.com/v1/chat/completions",
    "created_at": "2025-11-28T12:49:00+08:00",
    "updated_at": "2025-11-28T12:49:00+08:00"
  }
}

10.2 新增模型配置

• 请求类型： POST

• 是否需要登录： 否

• 请求参数（JSON）：

请求示例：

{
  "model_name": "千问大模型",
  "model_type": "千问",
  "model_api_key": "sk-qianwen-key-12345",
  "model_class": "大语言",
  "url": "https://api.qianwen.com/v1/chat/completions"
}

成功返回：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

10.3 更新模型配置

• 请求类型： PUT

• 是否需要登录： 否

• 请求参数（JSON）：

请求示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model_name": "豆包大模型-v2",
  "model_api_key": "sk-new-key"
}

成功返回：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

10.4 删除模型配置

• 请求类型： DELETE

• 是否需要登录： 否

• 请求参数（JSON）：

请求示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

成功返回：

{
  "code": 200,
  "msg": "deleted",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

11. 历史查询模块

11.1 查询历史列表

接口描述： 分页获取用户的查询历史记录，支持按数据源、状态、日期范围筛选

请求类型： GET

接口路径： /console/api/query_history/list

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "total_pages": 5,
    "items": [
      {
        "id": "uuid-string",
        "question": "查询最近一周的订单",
        "processed_question": "查询最近一周的GMV（成交总额）",
        "term_rewrite_info": {
          "matched_terms": [
            {
              "term_name": "GMV",
              "term_definition": "商品交易总额",
              "matched_alias": "订单"
            }
          ]
        },
        "sql": "SELECT * FROM orders WHERE ...",
        "cluster_sqls": [
          {
            "datasource_ids": ["uuid1"],
            "datasource_names": ["生产库A"],
            "table_names": ["orders"],
            "sql": "SELECT * FROM orders WHERE ..."
          }
        ],
        "source_datasource_ids": ["uuid1", "uuid2"],
        "source_datasource_names": ["生产库A", "生产库B"],
        "total_duration_ms": 2500,
        "total_tokens": 1500,
        "status": "success",
        "result_count": 50,
        "fusion_strategy": "OR",
        "has_full_result": true,
        "created_at": "2026-04-09T10:30:00"
      }
    ]
  }
}

返回字段说明：

11.2 查询历史详情

接口描述： 获取单条查询历史的完整信息，包括性能指标、Token消耗、质量指标等

请求类型： GET

接口路径： /console/api/query_history/

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "user_id": "user-uuid",
    "api_key_id": "api-key-uuid",
    "question": "查询最近一周的订单",
    "processed_question": "查询最近一周的GMV（成交总额）",
    "term_rewrite_info": {
      "matched_terms": [
        {
          "term_name": "GMV",
          "term_definition": "商品交易总额",
          "matched_alias": "订单",
          "library_name": "电商术语库"
        }
      ],
      "rewrite_count": 1
    },
    "sql": "SELECT * FROM orders WHERE ...",
    "cluster_sqls": [
      {
        "datasource_ids": ["uuid1"],
        "datasource_names": ["生产库A"],
        "table_names": ["orders"],
        "sql": "SELECT * FROM orders WHERE ..."
      }
    ],
    "source_datasource_ids": ["uuid1"],
    "source_datasource_names": ["生产库A"],
    "datasource_ids": ["uuid1"],
    "datasource_names": ["生产库A"],
    "table_names": ["orders", "customers"],
    "performance": {
      "total_duration_ms": 2500,
      "vector_search_ms": 300,
      "rerank_ms": 200,
      "llm_gen_sql_ms": 800,
      "sql_execution_ms": 1200,
      "fusion_ms": 0
    },
    "tokens": {
      "embedding_tokens": 500,
      "rerank_tokens": 200,
      "llm_prompt_tokens": 600,
      "llm_completion_tokens": 200,
      "total_tokens": 1500
    },
    "result": {
      "result_count": 50
    },
    "quality": {
      "cards_recalled": 15,
      "cards_reranked": 10,
      "cards_selected": 5,
      "top1_rerank_score": 0.95,
      "avg_rerank_score": 0.88
    },
    "status": "success",
    "fusion_strategy": "OR",
    "full_response_result": {...},
    "created_at": "2026-04-09T10:30:00"
  }
}

返回字段说明：

11.3 删除查询历史

接口描述： 删除单条查询历史记录（会级联更新聚合统计）

请求类型： DELETE

接口路径： /console/api/query_history/

是否需要登录： 是

路径参数：

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "deleted_id": "uuid-string"
  }
}

11.4 批量删除查询历史

接口描述： 批量删除查询历史记录，支持按ID列表、日期范围、保留天数删除

请求类型： DELETE

接口路径： /console/api/query_history/batch

是否需要登录： 是

请求参数（Query）：

说明： query_ids、before_date、keep_days 三个条件至少要传一个。

返回示例：

{
  "code": 200,
  "msg": "成功删除 50 条记录",
  "data": {
    "deleted_count": 50,
    "total_found": 50
  }
}

11.5 查询历史统计

接口描述： 获取用户的查询统计概览

请求类型： GET

接口路径： /console/api/query_history/stats

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "period": {
      "start_date": "2026-04-01",
      "end_date": "至今"
    },
    "total_queries": 500,
    "success_queries": 480,
    "error_queries": 15,
    "timeout_queries": 5,
    "success_rate": 96.0,
    "total_tokens": 75000,
    "avg_duration_ms": 2300,
    "min_duration_ms": 500,
    "max_duration_ms": 15000
  }
}

12. 监控中心模块

12.1 监控总览

接口描述： 获取监控概览数据，包含实时统计、趋势数据、对比分析等

请求类型： GET

接口路径： /console/api/monitoring/overview

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "recent_24h": {
      "total_queries": 150,
      "success_queries": 145,
      "error_queries": 3,
      "timeout_queries": 2,
      "success_rate": 96.67,
      "avg_duration_ms": 2300,
      "total_tokens": 22500,
      "embedding_tokens": 7500,
      "rerank_tokens": 3000,
      "llm_tokens": 12000
    },
    "today": {
      "total_queries": 45,
      "success_queries": 43,
      "total_tokens": 6750
    },
    "daily_trend": [...],
    "summary_30d": {
      "total_queries": 1500,
      "total_tokens": 225000,
      "total_cost_yuan": 1.25
    },
    "cost_note": "⚠️ 成本为预估值，仅供参考，实际费用以云厂商账单为准",
    "comparison": {
      "vs_yesterday": {...},
      "vs_last_week": {...}
    },
    "hourly_distribution": {...},
    "datasource_stats": {...},
    "status_breakdown": {...},
    "quality_metrics": {...}
  }
}

12.2 监控趋势

接口描述： 获取监控趋势数据，支持按天统计查询量、Token消耗、成本等

请求类型： GET

接口路径： /console/api/monitoring/trend

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "days": 30,
    "items": [
      {
        "date": "2026-04-09",
        "total_queries": 50,
        "success_queries": 48,
        "error_queries": 1,
        "timeout_queries": 1,
        "success_rate": 96.0,
        "tokens": {
          "embedding": 2500,
          "rerank": 1000,
          "llm": 4000,
          "total": 7500
        },
        "cost_yuan": 0.045,
        "performance": {...},
        "quality": {...}
      }
    ],
    "statistics": {...},
    "growth_analysis": {...},
    "peak_valley": {...},
    "weekly_pattern": {...}
  }
}

12.3 实时监控

接口描述： 获取实时监控数据（最近1小时）

请求类型： GET

接口路径： /console/api/monitoring/realtime

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "summary": {
      "total_queries": 25,
      "avg_duration_ms": 2100,
      "total_tokens": 3750
    },
    "minute_data": [...],
    "current_status": {...},
    "qps_stats": {...},
    "error_alerts": {...},
    "recent_queries": {...},
    "datasource_health": {...}
  }
}

12.4 性能分析

接口描述： 获取性能分析数据，包括各环节耗时分布、数据源性能等

请求类型： GET

接口路径： /console/api/monitoring/performance

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "period_days": 7,
    "stage_averages": {
      "vector_search_ms": 300,
      "rerank_ms": 200,
      "llm_gen_sql_ms": 800,
      "sql_execution_ms": 1000,
      "total_avg_ms": 2300
    },
    "slow_queries_top10": [...],
    "latency_distribution": {...},
    "stage_breakdown": {...},
    "datasource_performance": {...},
    "performance_trend": {...},
    "query_patterns": {...}
  }
}

13. 系统配置模块

13.1 获取Token价格配置

接口描述： 获取当前Token价格配置（Embedding、Rerank、LLM输入/输出）

请求类型： GET

接口路径： /console/api/system_config/token_prices

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "scope": "system",
    "embedding": {
      "key": "token_price_embedding",
      "value": "0.0007",
      "description": "Embedding Token 单价（元/千token）"
    },
    "rerank": {
      "key": "token_price_rerank",
      "value": "0.002",
      "description": "Rerank Token 单价（元/千token）"
    },
    "llm_input": {
      "key": "token_price_llm_input",
      "value": "0.002",
      "description": "LLM 输入 Token 单价（元/千token）"
    },
    "llm_output": {
      "key": "token_price_llm_output",
      "value": "0.006",
      "description": "LLM 输出 Token 单价（元/千token）"
    }
  }
}

13.2 更新Token价格配置

接口描述： 批量更新Token价格配置

请求类型： PUT

接口路径： /console/api/system_config/token_prices

是否需要登录： 是

请求参数：

请求示例：

{
  "embedding": 0.0008,
  "rerank": 0.0025,
  "llm_input": 0.003,
  "llm_output": 0.008
}

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "message": "系统级价格配置更新成功",
    "scope": "system",
    "updated": [
      {"key": "token_price_embedding", "value": "0.0008"}
    ]
  }
}

13.3 获取数据保留配置

接口描述： 获取数据保留天数配置

请求类型： GET

接口路径： /console/api/system_config/data_retention

是否需要登录： 是

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "scope": "system",
    "query_logs_retention_days": {
      "value": "180",
      "description": "查询日志保留天数",
      "unit": "天"
    },
    "stats_retention_days": {
      "value": "365",
      "description": "聚合统计保留天数",
      "unit": "天"
    }
  }
}

13.4 更新数据保留配置

接口描述： 更新数据保留天数配置

请求类型： PUT

接口路径： /console/api/system_config/data_retention

是否需要登录： 是

请求参数：

13.5 手动触发数据清理

接口描述： 手动触发过期数据清理任务

请求类型： POST

接口路径： /console/api/system_config/cleanup

是否需要登录： 是

请求参数：

返回示例：

{
  "code": 200,
  "msg": "数据清理完成",
  "data": {
    "type": "all",
    "results": {
      "query_logs": {"deleted": 100},
      "query_stats_daily": {"deleted": 5}
    },
    "total_deleted": 105,
    "duration_ms": 500,
    "executed_at": "2026-04-09T10:30:00"
  }
}

13.6 获取系统配置列表

接口描述： 获取所有系统配置项

请求类型： GET

接口路径： /console/api/system_config/config

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "configs": [
      {
        "id": "uuid",
        "config_key": "token_price_embedding",
        "config_value": "0.0007",
        "description": "Embedding Token 单价（元/千token）",
        "user_id": null,
        "scope": "system"
      }
    ]
  }
}

13.7 更新系统配置

接口描述： 更新或创建系统配置

请求类型： PUT

接口路径： /console/api/system_config/config

是否需要登录： 是

请求参数：

13.8 删除系统配置

接口描述： 删除系统配置（关键配置不可删除）

请求类型： DELETE

接口路径： /console/api/system_config/config

是否需要登录： 是

14. SSO单点登录模块

14.1 SSO登录接口

接口描述： 通过JWT Token实现SSO单点登录，无需用户名密码即可完成认证

请求类型： GET

接口路径： /sso/login

是否需要登录： 否

请求参数（Query）：

URL编码说明：

• token 参数需要使用 encodeURIComponent() 进行URL编码

• redirect_url 参数需要使用 encodeURIComponent() 进行URL编码

完整URL格式：

/sso/login?token={encodeURIComponent(JWT Token)}&redirect_url={encodeURIComponent(回调地址)}

JWT Token结构：

Payload必填字段：

Payload可选字段：

JWT Token生成示例（Python）：

import jwt
from datetime import datetime, timedelta, timezone

SECRET_KEY = "your_shared_secret_key"

payload = {
    "username": "zhang_san",
    "user_id": "SYS_USER_001",
    "nickname": "张三",
    "email": "zhangsan@example.com",
    "source": "your_app",
    "iat": datetime.now(timezone.utc),
    "exp": datetime.now(timezone.utc) + timedelta(minutes=5)
}

token = jwt.encode(payload, SECRET_KEY, algorithm="HS256")
print(token)

JWT Token生成示例（Node.js）：

const jwt = require('jsonwebtoken');

const secretKey = 'your_shared_secret_key';

const payload = {
    username: 'zhang_san',
    user_id: 'SYS_USER_001',
    nickname: '张三',
    email: 'zhangsan@example.com',
    source: 'your_app'
};

const token = jwt.sign(payload, secretKey, {
    algorithm: 'HS256',
    expiresIn: '5m'
});

console.log(token);

跳转示例：

// 生成Token
const token = jwt.sign(payload, secretKey, { algorithm: 'HS256', expiresIn: '5m' });

// 构造SSO登录URL
const ssoUrl = `${API_BASE}/sso/login?token=${encodeURIComponent(token)}&redirect_url=${encodeURIComponent(FRONTEND_URL)}`;

// 跳转
window.location.href = ssoUrl;

登录成功响应：

登录成功后，浏览器会跳转到指定的 redirect_url，并在URL中携带 access_token 参数：

{redirect_url}?access_token={OntiCards平台Token}

示例：

https://frontend.onticards.com/overview?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

前端接收Token示例：

// 从URL获取 access_token 参数
function getAccessToken() {
    const params = new URLSearchParams(window.location.search);
    return params.get('access_token');
}

// 存储Token
const token = getAccessToken();
if (token) {
    localStorage.setItem('access_token', token);

    // 清理URL中的token参数（防止token泄露）
    window.history.replaceState({}, document.title, window.location.pathname);
}

错误响应：

错误响应示例：

{
  "code": 401,
  "msg": "token无效",
  "error": "token无效"
}

错误页面示例： 当SSO登录失败时，会返回错误信息页面：

<!DOCTYPE html>
<html>
<head>
    <title>SSO Login Error</title>
</head>
<body>
    <h1>SSO Login Failed</h1>
    <p>Error: token无效</p>
</body>
</html>

14.2 SSO登录流程说明

整体流程：

1. 企业系统验证用户身份
   ↓
2. 企业后端生成JWT Token（包含用户信息）
   ↓
3. 拼接SSO登录URL
   {OntiCards API地址}/sso/login?token={JWT Token}&redirect_url={回调地址}
   ↓
4. 用户浏览器跳转到OntiCards SSO接口
   ↓
5. OntiCards验证JWT签名和有效期
   ↓
6. 创建/关联用户，生成平台Token
   ↓
7. 跳转到回调地址，携带access_token
   ↓
8. 前端接收Token，登录完成

用户创建/关联逻辑：

1. 接收JWT Token → 获取URL中的token参数

1. 解析Header → 获取算法信息（HS256）

1. 验证签名 → 用共享密钥验证token是否被篡改

1. 检查过期 → 验证exp是否有效

1. 提取Payload → 获取username、user_id等用户信息

1. 查询用户 → 根据 idp_user_id + idp_source 查找已存在用户

1. 创建/关联 → 新用户自动创建，老用户关联登录

1. 生成Token → 生成OntiCards自己的登录Token

1. 跳转回调 → 携带新Token跳转到 redirect_url

14.3 SSO测试页面

SSO测试中心：

http://localhost:9103/static/sso_test.html

回调测试页面：

http://localhost:9103/static/sso_callback.html

测试页面功能：

• 生成测试用JWT Token

• 填写回调地址

• 一键发起SSO登录

• 查看登录结果

14.4 SSO配置说明

服务端配置（环境变量）：

配置示例：

SSO_SECRET_KEY=K7x#9mP$2nL@qR8

密钥要求：

• 建议使用64位以上的随机字符串

• 客户端和服务端必须使用相同的密钥

• 生产环境请使用强密钥，不要使用示例密钥

14.5 SSO安全性说明

14.6 SSO与API Key的区别

15. 提示词配置模块

模块说明： 提供系统提示词模板的管理功能，支持从文件同步到数据库、在线编辑、热更新等操作。

基础路径： /console/api/prompt_config

提示词文件存储位置： libs/prompt/query_agg_prompt/

支持的提示词文件列表：

提示词加载优先级： 数据库（优先） > 缓存 > 文件（fallback）

15.1 获取提示词列表

接口描述： 分页获取提示词列表，支持搜索、分类筛选、数据库类型筛选

请求类型： GET

接口路径： /console/api/prompt_config/list

是否需要登录： 是

请求参数（Query）：

请求示例：

GET /console/api/prompt_config/list?page=1&page_size=20&category=多表查询

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid-string",
        "file_name": "mysql_multi_table.txt",
        "description": "MySQL 多表查询SQL生成 提示词",
        "category": "多表查询",
        "db_type": "MySQL",
        "prompt_length": 15360
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 17,
      "total_pages": 1
    }
  }
}

15.2 获取单个提示词详情

接口描述： 通过UUID获取单个提示词的完整内容

请求类型： GET

接口路径： /console/api/prompt_config/

是否需要登录： 是

路径参数：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "file_name": "mysql_multi_table.txt",
    "prompt": "你是一名专业的 MySQL SQL 查询生成器...",
    "description": "MySQL 多表查询SQL生成 提示词",
    "category": "多表查询",
    "db_type": "MySQL",
    "prompt_length": 15360
  }
}

15.3 通过文件名获取提示词

接口描述： 通过文件名获取提示词内容

请求类型： GET

接口路径： /console/api/prompt_config/file/

是否需要登录： 是

路径参数：

请求示例：

GET /console/api/prompt_config/file/mysql_multi_table.txt

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "file_name": "mysql_multi_table.txt",
    "prompt": "你是一名专业的 MySQL SQL 查询生成器...",
    "description": "MySQL 多表查询SQL生成 提示词",
    "category": "多表查询",
    "db_type": "MySQL",
    "from_cache": true
  }
}

15.4 创建提示词

接口描述： 创建新的提示词配置

请求类型： POST

接口路径： /console/api/prompt_config/list

是否需要登录： 是

请求参数：

请求示例：

{
  "file_name": "custom_prompt.txt",
  "prompt": "自定义提示词内容...",
  "description": "自定义提示词"
}

返回示例：

{
  "code": 200,
  "msg": "创建成功",
  "data": {
    "id": "uuid-string",
    "file_name": "custom_prompt.txt",
    "description": "自定义提示词",
    "message": "创建成功"
  }
}

错误响应（文件名已存在）：

{
  "code": 409,
  "msg": "文件名 'xxx.txt' 已存在，如需更新请使用 PUT 接口"
}

15.5 更新提示词

接口描述： 更新提示词内容或描述

请求类型： PUT

接口路径： /console/api/prompt_config/

是否需要登录： 是

路径参数：

请求参数：

请求示例：

{
  "prompt": "更新后的提示词内容...",
  "description": "更新后的描述"
}

返回示例：

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid-string",
    "file_name": "mysql_multi_table.txt",
    "updated_fields": ["prompt", "description"],
    "message": "更新成功"
  }
}

说明： 更新后会自动清除该提示词的缓存，下次请求时会从数据库读取最新内容（热更新）。

15.6 删除提示词

接口描述： 删除指定的提示词配置

请求类型： DELETE

接口路径： /console/api/prompt_config/

是否需要登录： 是

路径参数：

返回示例：

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "file_name": "custom_prompt.txt",
    "message": "删除成功"
  }
}

15.7 同步提示词（文件到数据库）

接口描述： 将提示词文件内容同步到数据库，支持单个文件或全部文件

请求类型： POST

接口路径： /console/api/prompt_config/sync

是否需要登录： 是

请求参数：

请求示例（同步单个文件）：

{
  "file_name": "mysql_multi_table.txt"
}

请求示例（同步全部）：

{}

返回示例（同步单个）：

{
  "code": 200,
  "msg": "同步成功",
  "data": {
    "file_name": "mysql_multi_table.txt",
    "message": "同步成功",
    "prompt_length": 15360
  }
}

返回示例（同步全部）：

{
  "code": 200,
  "msg": "同步完成",
  "data": {
    "success": ["mysql_multi_table.txt", "postgresql_multi_table.txt", ...],
    "failed": [],
    "total": 17,
    "message": "同步完成，成功 17 个，失败 0 个"
  }
}

15.8 获取提示词分类列表

接口描述： 获取所有提示词分类及统计信息

请求类型： GET

接口路径： /console/api/prompt_config/categories

是否需要登录： 是

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "categories": [
      {
        "name": "多表查询",
        "count": 6,
        "db_types": ["MySQL", "PostgreSQL", "SQL Server", "Oracle", "SQLite", "Trino", "电科金仓（KingBase）", "OceanBase（MySQL 租户模式）", "达梦（DMBase）"]
      },
      {
        "name": "查询策略",
        "count": 1,
        "db_types": ["通用"]
      },
      {
        "name": "结果融合",
        "count": 1,
        "db_types": ["通用"]
      },
      {
        "name": "重试提示",
        "count": 2,
        "db_types": ["通用"]
      }
    ],
    "db_types": ["MySQL", "PostgreSQL", "SQL Server", "Oracle", "SQLite", "Trino", "电科金仓（KingBase）", "OceanBase（MySQL 租户模式）", "达梦（DMBase）", "通用"]
  }
}

15.9 脚本同步工具

说明： 除了API接口，还提供了命令行脚本用于同步提示词文件到数据库。

脚本位置： scripts/sync_prompts_to_db.py

使用方法：

# 1. 进入项目目录
cd OntiCards_Api

# 2. 运行同步脚本（需要Flask应用上下文）
python scripts/sync_prompts_to_db.py

交互式操作菜单：

============================================================
提示词同步工具
============================================================
[1] 同步所有提示词到数据库
[2] 列出数据库中的提示词
[3] 清空所有提示词（谨慎）
[4] 退出

编程式调用：

from app import app
from controllers.prompt_config.sync_prompts_to_db import sync_all_prompts

with app.app_context():
    result = sync_all_prompts()
    print(result)
    # {'success': [...], 'failed': [...], 'total': 17}

16. 业务术语库管理模块

业务术语库模块提供了完整的术语管理功能，支持创建术语库、管理业务术语、从模板导入术语以及将术语库关联到数据源。该模块主要用于NL2SQL场景中的术语扩展和改写，帮助系统更准确地理解用户的自然语言查询。

核心功能：

• 术语库管理：创建、查询、更新、删除术语库

• 业务术语管理：在术语库中添加、编辑、删除业务术语

• 术语模板：从预置模板快速导入行业术语

• 数据源关联：将术语库关联到数据源，实现术语自动识别和改写

应用场景：

• 用户输入"查询GMV"，系统自动识别"GMV"为业务术语，展开为"成交总额"

• 支持多个别名映射到同一标准术语，如"订单金额"、"交易额"都映射到"GMV"

• 不同数据源可以关联不同的术语库，实现术语的精准识别

16.1 术语库管理

16.1.1 获取术语库列表

接口描述：获取当前用户的所有术语库列表，支持分页、搜索、分类筛选和状态筛选。

请求类型：GET

接口路径：/console/api/business_term/libraries

是否需要登录：是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "电商术语库",
        "description": "电商领域常用术语",
        "category": "电商",
        "status": "active",
        "term_count": 25,
        "created_at": "2026-05-14T10:00:00",
        "updated_at": "2026-05-14T10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 5,
      "total_pages": 1
    }
  }
}

返回字段说明：

16.1.2 创建术语库

接口描述：创建新的术语库。

请求类型：POST

接口路径：/console/api/business_term/libraries

是否需要登录：是

请求参数（Body）：

{
  "name": "电商术语库",
  "description": "电商领域常用术语",
  "category": "电商"
}

请求字段说明：

返回示例：

{
  "code": 200,
  "msg": "创建成功",
  "data": {
    "id": "uuid",
    "name": "电商术语库",
    "message": "创建成功"
  }
}

错误响应：

{
  "code": 409,
  "msg": "术语库 '电商术语库' 已存在",
  "data": null
}

16.1.3 获取术语库详情

接口描述：获取指定术语库的详细信息，包含该库下的所有术语（支持分页）。

请求类型：GET

接口路径：/console/api/business_term/libraries/

是否需要登录：是

路径参数：

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "name": "电商术语库",
    "description": "电商领域常用术语",
    "category": "电商",
    "status": "active",
    "term_count": 2,
    "created_at": "2026-05-14T10:00:00",
    "updated_at": "2026-05-14T10:00:00",
    "terms": [
      {
        "id": "uuid",
        "term_name": "GMV",
        "term_alias": ["成交总额", "交易总额"],
        "term_definition": "商品交易总额",
        "status": "active",
        "created_at": "2026-05-14T10:00:00"
      }
    ],
    "terms_pagination": {
      "page": 1,
      "page_size": 100,
      "total": 2,
      "total_pages": 1
    }
  }
}

返回字段说明：

16.1.4 更新术语库

接口描述：更新指定术语库的信息。

请求类型：PUT

接口路径：/console/api/business_term/libraries/

是否需要登录：是

路径参数：

请求参数（Body）：

{
  "name": "电商术语库（更新）",
  "description": "电商领域常用术语（已更新）",
  "status": "active"
}

请求字段说明：

返回示例：

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid",
    "updated_fields": ["name", "description"],
    "message": "更新成功"
  }
}

16.1.5 删除术语库

接口描述：删除指定的术语库及其包含的所有术语（级联删除）。

请求类型：DELETE

接口路径：/console/api/business_term/libraries/

是否需要登录：是

路径参数：

返回示例：

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": "uuid",
    "message": "删除成功，关联术语一并删除"
  }
}

说明：删除术语库时，会同时删除该库下的所有术语，以及数据源与该术语库的关联关系。

16.2 业务术语管理

16.2.1 获取术语列表

接口描述：获取术语列表，支持按术语库筛选、分页、搜索和状态筛选。

请求类型：GET

接口路径：/console/api/business_term/list

是否需要登录：是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "library_id": "uuid",
        "term_name": "GMV",
        "term_alias": ["成交总额", "交易总额"],
        "term_definition": "商品交易总额",
        "applicable_conditions": "适用于电商场景",
        "status": "active",
        "created_at": "2026-05-14T10:00:00",
        "updated_at": "2026-05-14T10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 50,
      "total_pages": 3
    }
  }
}

返回字段说明：

16.2.2 创建术语

接口描述：在指定术语库中创建新术语。

请求类型：POST

接口路径：/console/api/business_term/list

是否需要登录：是

请求参数（Body）：

{
  "library_id": "uuid",
  "term_name": "GMV",
  "term_alias": ["成交总额", "交易总额"],
  "term_definition": "商品交易总额",
  "applicable_conditions": "适用于电商场景",
  "remarks": "核心指标"
}

请求字段说明：

返回示例：

{
  "code": 200,
  "msg": "创建成功",
  "data": {
    "id": "uuid",
    "term_name": "GMV",
    "message": "创建成功"
  }
}

错误响应：

{
  "code": 409,
  "msg": "术语 'GMV' 已存在",
  "data": null
}

16.2.3 获取术语详情

接口描述：获取指定术语的详细信息。

请求类型：GET

接口路径：/console/api/business_term/

是否需要登录：是

路径参数：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "library_id": "uuid",
    "term_name": "GMV",
    "term_alias": ["成交总额", "交易总额"],
    "term_definition": "商品交易总额",
    "applicable_conditions": "适用于电商场景",
    "remarks": "核心指标",
    "related_datacards": [],
    "related_fields": [],
    "related_terms": [],
    "status": "active",
    "created_at": "2026-05-14T10:00:00",
    "updated_at": "2026-05-14T10:00:00"
  }
}

16.2.4 更新术语

接口描述：更新指定术语的信息。

请求类型：PUT

接口路径：/console/api/business_term/

是否需要登录：是

路径参数：

请求参数（Body）：

{
  "term_name": "GMV（更新）",
  "term_alias": ["成交总额", "交易总额", "总GMV"],
  "term_definition": "商品交易总额（已更新）",
  "status": "active"
}

请求字段说明：

返回示例：

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid",
    "updated_fields": ["term_name", "term_alias"],
    "message": "更新成功"
  }
}

16.2.5 删除术语

接口描述：删除指定的术语。

请求类型：DELETE

接口路径：/console/api/business_term/

是否需要登录：是

路径参数：

返回示例：

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": "uuid",
    "message": "删除成功"
  }
}

16.3 术语模板管理

16.3.1 获取模板分类列表

接口描述：获取所有术语模板的分类统计信息，包括每个分类下的模板名称和术语数量。

请求类型：GET

接口路径：/console/api/business_term/templates/categories

是否需要登录：是

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "categories": [
      {
        "category": "电商",
        "templates": [
          {
            "template_name": "电商核心指标",
            "count": 15
          },
          {
            "template_name": "电商用户行为",
            "count": 10
          }
        ]
      },
      {
        "category": "金融",
        "templates": [
          {
            "template_name": "金融风控指标",
            "count": 20
          }
        ]
      }
    ]
  }
}

返回字段说明：

16.3.2 获取模板列表

接口描述：获取术语模板列表，支持按分类和模板名称筛选。

请求类型：GET

接口路径：/console/api/business_term/templates

是否需要登录：是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "category": "电商",
        "template_name": "电商核心指标",
        "term_name": "GMV",
        "term_alias": ["成交总额", "交易总额"],
        "term_definition": "商品交易总额",
        "applicable_conditions": "适用于电商场景"
      }
    ],
    "total": 15
  }
}

返回字段说明：

16.3.3 从模板导入术语

接口描述：从预置模板批量导入术语到指定术语库。支持按模板ID、分类或模板名称导入。

请求类型：POST

接口路径：/console/api/business_term/templates/import

是否需要登录：是

请求参数（Body）：

{
  "library_id": "uuid",
  "template_ids": ["uuid1", "uuid2"],
  "category": "电商",
  "template_name": "电商核心指标"
}

请求字段说明：

说明：template_ids、category、template_name 三个参数至少需要指定一个。

返回示例：

{
  "code": 200,
  "msg": "导入完成",
  "data": {
    "imported_count": 12,
    "skipped_count": 3,
    "message": "导入成功 12 个，跳过 3 个（已存在）",
    "skipped_items": ["GMV", "DAU", "MAU"]
  }
}

返回字段说明：

16.4 数据源-术语库关联管理

16.4.1 获取数据源已添加的术语库列表

接口描述：获取指定数据源已添加的术语库列表，支持分页和状态筛选。

请求类型：GET

接口路径：/console/api/business_term/datasource//libraries

是否需要登录：是

路径参数：

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "datasource_id": "uuid",
        "library_id": "uuid",
        "library_name": "电商术语库",
        "library_category": "电商",
        "term_count": 25,
        "is_enabled": true,
        "added_at": "2026-05-14T10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 3,
      "total_pages": 1
    }
  }
}

返回字段说明：

16.4.2 为数据源添加术语库

接口描述：将术语库关联到指定数据源。

请求类型：POST

接口路径：/console/api/business_term/datasource//libraries

是否需要登录：是

路径参数：

请求参数（Body）：

{
  "library_id": "uuid",
  "is_enabled": true
}

请求字段说明：

返回示例：

{
  "code": 200,
  "msg": "添加成功",
  "data": {
    "id": "uuid",
    "datasource_id": "uuid",
    "library_id": "uuid",
    "library_name": "电商术语库",
    "is_enabled": true,
    "message": "术语库添加成功"
  }
}

错误响应：

{
  "code": 409,
  "msg": "术语库 '电商术语库' 已添加到此数据源",
  "data": null
}

16.4.3 更新数据源术语库状态

接口描述：更新数据源关联的术语库状态（启用/禁用）。

请求类型：PUT

接口路径：/console/api/business_term/datasource//libraries/

是否需要登录：是

路径参数：

请求参数（Body）：

{
  "is_enabled": false
}

请求字段说明：

返回示例：

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid",
    "is_enabled": false,
    "message": "状态更新成功"
  }
}

16.4.4 从数据源移除术语库

接口描述：从数据源移除关联的术语库。

请求类型：DELETE

接口路径：/console/api/business_term/datasource//libraries/

是否需要登录：是

路径参数：

返回示例：

{
  "code": 200,
  "msg": "移除成功",
  "data": {
    "id": "uuid",
    "message": "术语库 '电商术语库' 已从数据源移除"
  }
}

16.4.5 获取数据源可添加的术语库列表

接口描述：获取数据源可添加的术语库列表（未添加的术语库），支持搜索和筛选。

请求类型：GET

接口路径：/console/api/business_term/datasource//available

是否需要登录：是

路径参数：

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "金融术语库",
        "description": "金融领域常用术语",
        "category": "金融",
        "status": "active",
        "term_count": 30,
        "created_at": "2026-05-14T10:00:00"
      }
    ],
    "total": 5
  }
}

说明：该接口只返回状态为 active 且未添加到该数据源的术语库。

返回字段说明：

17. 数据治理模块 - 数据质检（第一阶段）

模块说明： 数据治理分为两个阶段，第一阶段为数据质检（已完成），第二阶段为实际治理（待实现）。

本章节记录的是第一阶段"数据质检"的所有接口，涵盖规则库管理、规则管理、规则执行、报告生成等完整链路。

第二阶段"治理"接口请参见 第18章。

基础路径： /console/api/governance

核心功能：

• 规则库管理：创建、查询、更新、删除规则库

• 规则管理：三种创建模式（手动专家/AI自然语言/模板导入）、规则解析、SQL预览、规则建议

• 规则执行：批量执行规则、基础空值检测、表关系发现

• 报告生成：生成可下载的质检报告（MD/DOCX/PDF/XLSX格式）

• 质量概览：数据质量评分、评级、趋势分析

接口清单：

17.1 规则库管理

17.1.1 获取规则库列表

接口描述： 分页获取当前用户的规则库列表，支持搜索和数据源筛选。

请求类型： GET

接口路径： /console/api/governance/libraries

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid-string",
        "name": "订单数据质量规则库",
        "description": "针对订单表的数据质量检测",
        "datasource_id": "uuid-string",
        "connect_name": "生产库A",
        "database_name": "ecommerce_db",
        "datasource_db_type": "mysql",
        "status": "active",
        "rule_count": 15,
        "created_at": "2026-06-01T10:00:00"
      }
    ],
    "total": 5,
    "page": 1,
    "page_size": 20,
    "pages": 1
  }
}

17.1.2 创建规则库

接口描述： 创建新的规则库，必须关联数据源。

请求类型： POST

接口路径： /console/api/governance/libraries

是否需要登录： 是

请求参数：

请求示例：

{
  "name": "订单数据质量规则库",
  "datasource_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "针对订单表的数据质量检测"
}

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "name": "订单数据质量规则库",
    "datasource_id": "uuid-string",
    "datasource_name": "生产库A",
    "description": "针对订单表的数据质量检测",
    "status": "active",
    "created_at": "2026-06-01T10:00:00"
  }
}

错误响应：

{
  "code": 400,
  "msg": "datasource_id 不能为空，创建规则库必须关联数据源"
}

17.1.3 获取规则库详情

接口描述： 获取指定规则库的详细信息，包含规则列表和数据源信息。

请求类型： GET

接口路径： /console/api/governance/libraries/

是否需要登录： 是

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "name": "订单数据质量规则库",
    "description": "针对订单表的数据质量检测",
    "datasource_id": "uuid-string",
    "datasource": {
      "id": "uuid-string",
      "name": "生产库A",
      "db_type": "mysql"
    },
    "rules": [
      {
        "id": "uuid-string",
        "rule_name": "手机号非空检测",
        "rule_type": "null_check",
        "target_table": "orders",
        "target_column": "phone",
        "severity": "critical",
        "enabled": true
      }
    ],
    "created_at": "2026-06-01T10:00:00"
  }
}

17.1.4 更新规则库

接口描述： 更新规则库的名称、描述或状态。

请求类型： PUT

接口路径： /console/api/governance/libraries/

是否需要登录： 是

请求参数：

请求示例：

{
  "name": "更新后的规则库名称",
  "status": "inactive"
}

17.1.5 删除规则库

接口描述： 删除规则库（会级联删除该规则库下的所有规则）。

请求类型： DELETE

接口路径： /console/api/governance/libraries/

是否需要登录： 是

返回示例：

{
  "code": 200,
  "msg": "删除成功"
}

17.2 规则管理

17.2.1 获取规则列表

接口描述： 获取规则列表，支持按规则库、类型、启用状态、创建来源筛选。

请求类型： GET

接口路径： /console/api/governance/rules

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid-string",
        "library_id": "uuid-string",
        "rule_name": "手机号非空检测",
        "rule_type": "null_check",
        "rule_type_name": "空值检测",
        "target_table": "orders",
        "target_column": "phone",
        "condition_expr": "phone IS NOT NULL",
        "severity": "critical",
        "enabled": true,
        "create_source": "template",
        "created_at": "2026-06-01T10:00:00"
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20,
    "pages": 3
  }
}

17.2.2 创建规则

接口描述： 创建新规则，支持三种模式。

请求类型： POST

接口路径： /console/api/governance/rules

是否需要登录： 是

请求参数：

规则类型说明：

请求示例（手动专家模式）：

{
  "library_id": "uuid-string",
  "rule_name": "订单金额必须为正数",
  "rule_type": "threshold",
  "target_table": "orders",
  "target_column": "total_amount",
  "condition_expr": "total_amount > 0",
  "severity": "critical",
  "enabled": true
}

请求示例（复合规则模式）：

{
  "library_id": "uuid-string",
  "rule_name": "订单完整性检测",
  "rule_type": "composite",
  "target_table": "orders",
  "conditions": [
    {"column": "customer_id", "condition": "customer_id IS NOT NULL"},
    {"column": "total_amount", "condition": "total_amount > 0"},
    {"column": "order_date", "condition": "order_date IS NOT NULL"}
  ],
  "condition_mode": "AND",
  "severity": "critical"
}

请求示例（AI自然语言模式）：

{
  "library_id": "uuid-string",
  "rule_name": "订单金额检测",
  "create_source": "ai",
  "rule_config": {
    "target_table": "orders",
    "target_column": "total_amount",
    "rule_type": "threshold",
    "condition_expr": "total_amount > 0",
    "severity": "warning"
  }
}

17.2.3 获取规则详情

请求类型： GET

接口路径： /console/api/governance/rules/

是否需要登录： 是

17.2.4 更新规则

请求类型： PUT

接口路径： /console/api/governance/rules/

是否需要登录： 是

请求参数（Query）：

请求参数（Body）：

说明：

• 更新 conditions 时会自动切换为复合规则模式

• target_column 在复合规则模式下不会更新

• 复合规则切换到非复合规则时会清空 conditions_config

17.2.5 删除规则

请求类型： DELETE

接口路径： /console/api/governance/rules/

是否需要登录： 是

请求参数（Query）：

17.2.6 启用/禁用规则

接口描述： 切换规则的启用状态。

请求类型： PUT

接口路径： /console/api/governance/rules//toggle

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "enabled": false,
    "msg": "禁用成功"
  }
}

17.2.7 测试执行单条规则

接口描述： 验证规则配置是否正确，实时执行单条规则并返回结果。

请求类型： POST

接口路径： /console/api/governance/rules/execute

是否需要登录： 是

请求参数：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "rule_id": "uuid-string",
    "rule_name": "手机号非空检测",
    "rule_type": "null_check",
    "table_name": "orders",
    "column_name": "phone",
    "total_count": 10000,
    "passed_count": 9980,
    "failed_count": 20,
    "failed_rate": 0.20,
    "status": "passed",
    "execution_time_ms": 125
  }
}

17.3 规则解析与建议

17.3.1 规则解析（自然语言 → 结构化规则）

接口描述： 将自然语言描述的规则解析为结构化规则配置，支持二阶段交互（解析 + 确认）。

请求类型： POST

接口路径： /console/api/governance/rules/parse

是否需要登录： 是

请求参数：

返回示例（阶段1 - 成功解析）：

{
  "code": 200,
  "data": {
    "success": true,
    "needs_confirmation": false,
    "stage": "rule_preview",
    "confidence": 0.95,
    "rule_config": {
      "rule_type": "threshold",
      "target_table": "orders",
      "target_column": "total_amount",
      "condition_expr": "total_amount > 0",
      "severity": "warning"
    },
    "sql_preview": "SELECT * FROM orders WHERE NOT (total_amount > 0) LIMIT 20",
    "reasoning": "检测到数值类型的金额字段，建议使用阈值规则"
  }
}

返回示例（阶段1 - 需要确认）：

{
  "code": 200,
  "data": {
    "success": true,
    "needs_confirmation": true,
    "stage": "table_selection",
    "confidence": 0.7,
    "rule_config": null,
    "candidates": {
      "type": "table",
      "items": [
        {"name": "orders", "score": 0.9, "reason": "表名匹配", "description": "订单主表"},
        {"name": "sales_orders", "score": 0.7, "reason": "实体匹配", "description": "销售订单"}
      ]
    },
    "reasoning": "找到多个候选表，请确认"
  }
}

17.3.2 SQL预览

接口描述： 根据规则配置生成检测SQL并预览，支持四种模式。

请求类型： POST

接口路径： /console/api/governance/rules/preview

是否需要登录： 是

请求参数（模板模式）：

请求参数（单条件专家模式）：

请求参数（复合规则模式）：

模式优先级： template_id > conditions > condition_expr > auto

返回示例：

{
  "code": 200,
  "data": {
    "success": true,
    "sql": "SELECT * FROM orders WHERE NOT (total_amount > 0) LIMIT 20",
    "scope": "column",
    "mode": "expert",
    "rule_type": "threshold",
    "rule_type_label": "阈值检测",
    "description": "专家模式：直接使用用户输入的条件",
    "template_name": null
  }
}

返回字段说明：

17.3.3 规则建议

接口描述： 基于数据源表结构，智能推荐适用的规则模板。

请求类型： POST

接口路径： /console/api/governance/rules/suggest

是否需要登录： 是

请求参数：

返回示例：

{
  "code": 200,
  "data": {
    "success": true,
    "source": "llm",
    "suggestions": [
      {
        "table": "users",
        "column": "phone",
        "column_comment": "手机号码",
        "data_type": "varchar(20)",
        "rule_type": "format",
        "rule_name": "手机号格式检测",
        "rule_description": "手机号应为11位，以1开头",
        "confidence": 0.95,
        "reasoning": "基于列名和注释推断为手机号字段，建议进行格式校验"
      },
      {
        "table": "orders",
        "column": "total_amount",
        "column_comment": "订单总金额",
        "data_type": "decimal(10,2)",
        "rule_type": "threshold_positive",
        "rule_name": "正数检测",
        "rule_description": "金额字段建议检测正数",
        "confidence": 0.90,
        "reasoning": "基于列名和注释推断为金额字段，建议检测正数"
      }
    ]
  }
}

返回字段说明：

17.4 规则执行引擎（环节二核心）

17.4.1 批量执行规则

接口描述： 执行规则库中的规则，收集质检结果，生成报告。是数据质检阶段的核心接口。

请求类型： POST

接口路径： /console/api/governance/execute

是否需要登录： 是

请求参数：

说明： 不传 library_ids 或 rule_ids 时，仅执行基础空值检测。

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "report_id": "uuid-string",
    "quality_score": 85.5,
    "grade": "良好",
    "summary": {
      "total_rules": 20,
      "passed_rules": 17,
      "failed_rules": 3,
      "error_rules": 0,
      "quality_score": 85.0,
      "grade": "良好"
    },
    "execution_time": "2026-07-21T14:30:00",
    "basic_audit": {
      "tables_count": 5,
      "tables": [...]
    },
    "basic_audit_detail": {
      "rules_count": 15,
      "results": [
        {
          "id": "result-uuid",
          "rule_id": null,
          "rule_name": "空值检测: users.phone",
          "rule_type": "null_check",
          "severity": "warning",
          "table_name": "users",
          "column_name": "phone",
          "total_count": 10000,
          "passed_count": 9980,
          "failed_count": 20,
          "failed_rate": 0.20,
          "failed_samples": [...],
          "status": "passed"
        }
      ]
    },
    "quality_audit": {
      "rules_count": 5,
      "results": [
        {
          "id": "result-uuid",
          "rule_id": "rule-uuid",
          "rule_name": "手机号非空检测",
          "rule_type": "null_check",
          "severity": "critical",
          "table_name": "users",
          "column_name": "phone",
          "total_count": 10000,
          "passed_count": 9980,
          "failed_count": 20,
          "failed_rate": 0.20,
          "failed_samples": [...],
          "status": "passed"
        }
      ]
    },
    "relation_discovery": {
      "tables_count": 20,
      "relationships_count": 15,
      "cards_count": 10,
      "statistics": {...},
      "relationships": [...],
      "cards": [...]
    }
  }
}

返回字段说明：

质量评分计算：

• 通过率 = passed_count / total_count × 100

• 严重扣分 = critical_fails × 5 + warning_fails × 2

• 最终评分 = max(0, min(100, 通过率 - 扣分))

质量等级阈值：

17.5 报告管理

17.5.1 获取报告列表

请求类型： GET

接口路径： /console/api/governance/reports

是否需要登录： 是

请求参数（Query）：

17.5.2 获取报告详情

请求类型： GET

接口路径： /console/api/governance/reports/

是否需要登录： 是

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "report-uuid",
    "user_id": "user-uuid",
    "datasource_id": "datasource-uuid",
    "report_name": "质检结果_2026-07-23",
    "execution_time": "2026-07-23T10:30:00",
    "scope_tables": null,
    "rules_applied": 20,
    "include_quality": true,
    "include_basic_audit": true,
    "include_relationship": false,
    "quality_score": 85.5,
    "grade": "良好",
    "basic_audit_result": {
      "users": {
        "columns": {
          "phone": {"null_count": 20, "null_rate": 0.002, "total_count": 10000},
          "email": {"null_count": 5, "null_rate": 0.0005, "total_count": 10000}
        },
        "total_count": 10000
      }
    },
    "basic_audit_detail": {
      "rules_count": 15,
      "results": [
        {
          "id": "result-uuid",
          "rule_id": null,
          "rule_name": "空值检测: users.phone",
          "rule_type": "null_check",
          "severity": "warning",
          "table_name": "users",
          "column_name": "phone",
          "total_count": 10000,
          "passed_count": 9980,
          "failed_count": 20,
          "failed_rate": 0.002,
          "failed_samples": [...],
          "status": "passed"
        }
      ]
    },
    "full_relation_discovery": null,
    "quality_audit_result": [
      {
        "id": "result-uuid",
        "rule_id": "rule-uuid",
        "rule_name": "手机号非空检测",
        "rule_type": "null_check",
        "severity": "critical",
        "table_name": "users",
        "column_name": "phone",
        "total_count": 10000,
        "passed_count": 9980,
        "failed_count": 20,
        "failed_rate": 0.002,
        "failed_samples": [...],
        "status": "passed"
      }
    ],
    "summary": {
      "total_rules": 20,
      "passed_rules": 18,
      "failed_rules": 2,
      "error_rules": 0,
      "quality_score": 85.0,
      "grade": "良好"
    },
    "created_at": "2026-07-23T10:30:00",
    "exported_file_path": "/exports/report_xxx.docx",
    "exported_file_type": "docx",
    "exported_file_name": "质检报告_2026年07月23日.docx",
    "file_size": 123456,
    "file_created_at": "2026-07-23T11:00:00",
    "file_status": "completed",
    "file_error_msg": null,
    "has_export": true,
    "history_files": [
      {
        "id": "file-uuid",
        "file_name": "质检报告_2026年07月23日.docx",
        "file_path": "/exports/report_xxx.docx",
        "file_type": "docx",
        "file_size": 123456,
        "created_at": "2026-07-23T11:00:00"
      }
    ]
  }
}

返回字段说明：

17.5.3 删除报告

请求类型： DELETE

接口路径： /console/api/governance/reports/

是否需要登录： 是

返回示例：

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "report_id": "uuid-string",
    "files_deleted": 2,
    "files_not_found": [],
    "rule_execution_results_cleared": "cascade",
    "table_relationships_deleted": 5,
    "table_relationship_cards_deleted": 3
  }
}

返回字段说明：

17.5.4 修改报告名称

请求类型： PUT

接口路径： /console/api/governance/reports/

是否需要登录： 是

请求参数：

请求示例：

{
  "report_name": "新的报告名称_2026-07-23"
}

返回示例：

成功返回：

{
  "code": 200,
  "msg": "修改成功",
  "data": {
    "report_id": "uuid-string",
    "report_name": "新的报告名称_2026-07-23",
    "files_updated": 3,
    "updated_at": "2026-07-23T10:30:00"
  }
}

失败返回（报告不存在）：

{
  "code": 404,
  "msg": "报告不存在"
}

失败返回（名称为空）：

{
  "code": 400,
  "msg": "report_name 不能为空"
}

失败返回（名称过长）：

{
  "code": 400,
  "msg": "报告名称不能超过255个字符"
}

返回字段说明：

同步更新说明：

本接口会同时更新以下两张表，保证数据一致性：

不会影响的字段（说明）：

前端影响：

• 报告列表中显示的报告名称会更新为新值

• 报告详情页的 history_files 列表中每条历史记录的 report_name 字段也会同步更新

• 已下载/已生成报告的文件名不会改变（如需重新生成才能体现在文件名中）

17.5.5 下载报告文件

接口描述： 下载报告生成的文档文件，支持下载历史文件。

请求类型： GET

接口路径： /console/api/governance/reports//download

是否需要登录： 是

请求参数（Query）：

17.5.6 删除报告文件

请求类型： DELETE

接口路径： /console/api/governance/reports//file

是否需要登录： 是

17.5.7 删除导出文件记录

请求类型： DELETE

接口路径： /console/api/governance/files/

是否需要登录： 是

17.6 报告生成（环节三核心）

17.6.1 生成报告文档

接口描述： 基于已有报告（report_id），生成可下载的文档。是数据质检阶段的最终输出接口。

请求类型： POST

接口路径： /console/api/governance/report

是否需要登录： 是

请求参数：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "report_id": "uuid-string",
    "file_path": "/path/to/report.docx",
    "file_name": "质检报告_2026年07月21日.docx",
    "file_size": 12345,
    "format": "docx",
    "mode": "soffice"
  }
}

生成模式说明：

报告文档结构（六大章节）：

1. 基本信息

1. 质量概览（三大模块质检结果汇总）

1. 基础空值检测结果（以表为单位）

1. 执行明细（基于规则库）

1. 失败样本明细（全字段违规记录）

1. LLM智能总结 + 改进建议

17.6.2 查询报告文档生成状态

接口描述： 查询报告文档的生成状态。

请求类型： GET

接口路径： /console/api/governance/report/

是否需要登录： 是

返回示例：

{
  "code": 200,
  "data": {
    "report_id": "uuid-string",
    "file_status": "completed",
    "file_error_msg": null,
    "exported_file_name": "质检报告_2026年07月21日.docx",
    "exported_file_path": "/path/to/report.docx",
    "file_size": 12345
  }
}

file_status 状态值：

17.7 规则模板

17.7.1 获取系统模板列表

接口描述： 获取所有预置规则模板，支持按类型分组和关键字搜索。

请求类型： GET

接口路径： /console/api/governance/templates

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "groups": [
      {
        "rule_type": "null_check",
        "rule_type_name": "空值检测",
        "templates": [
          {
            "id": "uuid-string",
            "template_id": "tmpl-null-check",
            "template_name": "空值检测",
            "default_condition": "column IS NOT NULL",
            "applicable_columns": ["varchar", "text", "int", "decimal"]
          }
        ]
      }
    ],
    "total": 27
  }
}

17.7.2 获取模板详情

请求类型： GET

接口路径： /console/api/governance/templates/

是否需要登录： 是

17.7.3 从模板导入规则

接口描述： 基于模板创建规则。

请求类型： POST

接口路径： /console/api/governance/templates/import

是否需要登录： 是

请求参数：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "imported_count": 2,
    "target_table": "orders",
    "target_column": null,
    "rules": [
      {
        "id": "rule-uuid",
        "rule_name": "空值检测(orders)",
        "rule_type": "null_check",
        "target_table": "orders",
        "severity": "warning",
        "enabled": true
      }
    ]
  }
}

17.8 治理概览与元数据

17.8.1 质量概览

接口描述： 获取治理模块首页统计数据，包括评分、评级、趋势、维度评分、严重问题摘要等。

请求类型： GET

接口路径： /console/api/governance/quality/overview

是否需要登录： 是

请求参数（Query）：

返回示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "quality_score": 85.5,
    "grade": "良好",
    "report_count": 50,
    "library_count": 5,
    "rule_count": 120,
    "enabled_rule_count": 100,
    "dimensions": {
      "completeness": 92.5,
      "uniqueness": 88.0,
      "validity": 85.0,
      "consistency": 90.0,
      "timeliness": 95.0,
      "composite": 80.0
    },
    "critical_findings": [
      {
        "rule_name": "手机号非空检测",
        "table_name": "users",
        "column_name": "phone",
        "failed_count": 20,
        "failed_rate": 0.002,
        "status": "failed",
        "severity": "critical",
        "rule_id": "rule-uuid",
        "report_id": "report-uuid"
      }
    ],
    "report_trend": [
      {
        "date": "2026-07-20",
        "count": 5,
        "avg_score": 87.5
      }
    ],
    "rule_type_stats": [
      {
        "type": "null_check",
        "type_name": "空值检测",
        "count": 50,
        "percentage": 41.7
      }
    ],
    "date_range": {
      "start": "2026-06-21T00:00:00",
      "end": "2026-07-21T00:00:00",
      "range": "30d"
    }
  }
}

返回字段说明：

17.8.2 获取数据源下的所有表

请求类型： GET

接口路径： /console/api/governance/datasources//tables

是否需要登录： 是

17.8.3 获取指定表的字段列表

请求类型： GET

接口路径： /console/api/governance/datasources//tables//columns

是否需要登录： 是

17.9 数据质检完整链路流程

┌─────────────────────────────────────────────────────────────────────────────┐
│                        数据质检阶段完整链路（已实现）                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  【环节一：规则创建】                                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  用户操作                                                             │   │
│  │  ├── 手动专家模式：直接输入 SQL 条件                                   │   │
│  │  ├── AI自然语言模式：输入"订单金额不能为负" → LLM解析 → 用户确认      │   │
│  │  ├── 模板导入模式：选择预置模板，填入表/列                             │   │
│  │  └── 规则建议：基于Schema智能推荐适用规则                              │   │
│  │                                                                       │   │
│  │  核心接口                                                             │   │
│  │  ├── POST /governance/rules/parse    → 自然语言解析                   │   │
│  │  ├── POST /governance/rules/preview  → SQL预览验证                    │   │
│  │  └── POST /governance/rules          → 创建规则                       │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    ↓                                         │
│  【环节二：规则执行】                                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  POST /governance/execute  （核心接口）                                │   │
│  │                                                                       │   │
│  │  输入: {                                                             │   │
│  │    datasource_id: "xxx",                                             │   │
│  │    library_ids: ["lib1", "lib2"],                                    │   │
│  │    include_basic_audit: true,                                        │   │
│  │    include_relation_discovery: true                                   │   │
│  │  }                                                                   │   │
│  │                                                                       │   │
│  │  执行:                                                               │   │
│  │  1. AuditExecutor.execute_only() → 执行规则库规则                     │   │
│  │  2. 基础空值检测（可选）                                              │   │
│  │  3. 表关系发现（可选）                                                 │   │
│  │  4. 计算质量评分 + 更新报告                                            │   │
│  │  5. 存入 execution_response（唯一真实数据源）                          │   │
│  │                                                                       │   │
│  │  输出: {                                                             │   │
│  │    report_id: "xxx",                                                 │   │
│  │    quality_score: 85.5,                                              │   │
│  │    grade: "良好",                                                    │   │
│  │    summary: {...}                                                    │   │
│  │  }                                                                   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    ↓                                         │
│  【环节三：报告生成】                                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  POST /governance/report  （核心接口）                                 │   │
│  │                                                                       │   │
│  │  输入: {                                                             │   │
│  │    report_id: "xxx",     // 来自环节二                              │   │
│  │    format: "docx",       // docx/pdf/xlsx/md                        │   │
│  │    file_name: "自定义名称"                                            │   │
│  │  }                                                                   │   │
│  │                                                                       │   │
│  │  执行:                                                               │   │
│  │  1. 读取 execution_response                                           │   │
│  │  2. LibreOfficeExporter / MarkdownExporter 生成文档                   │   │
│  │  3. 记录文件到 governance_report_files                                │   │
│  │                                                                       │   │
│  │  输出: {                                                             │   │
│  │    report_id: "xxx",                                                 │   │
│  │    file_path: "/path/to/report.docx",                                │   │
│  │    file_name: "质检报告_2026年07月21日.docx",                        │   │
│  │    file_size: 12345,                                                 │   │
│  │    mode: "soffice"                                                   │   │
│  │  }                                                                   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

18. 数据治理模块 - 治理（第二阶段）

模块说明： 第二阶段为实际治理阶段，基于第一阶段数据质检发现的问题，执行针对性的治理动作。

例如：对账差异处理、问题数据修复/回填、数据隔离/清洗、告警通知等。

此章节内容待实现，完成后将补充具体接口文档。

18.1 治理任务管理（待实现）

18.1.1 创建治理任务

状态： 待实现

说明： 根据质检报告发现的问题，创建针对性的治理任务。

18.1.2 执行治理动作

状态： 待实现

说明： 执行具体的数据修复、对账、回填等治理操作。

18.1.3 治理结果查询

状态： 待实现

说明： 查询治理任务的执行结果和状态。

18.2 数据修复（待实现）

18.2.1 批量修复问题数据

状态： 待实现

18.2.2 数据回填

状态： 待实现

18.2.3 数据清洗

状态： 待实现

18.3 对账核对（待实现）

18.3.1 创建对账任务

状态： 待实现

18.3.2 执行对账

状态： 待实现

18.3.3 对账结果处理

状态： 待实现

18.4 告警通知（待实现）

18.4.1 配置告警规则

状态： 待实现

18.4.2 告警历史查询

状态： 待实现

18.5 治理流程自动化（待实现）

18.5.1 配置治理规则

状态： 待实现

说明： 配置质检问题 → 自动触发治理动作的映射规则。

18.5.2 执行自动化治理

状态： 待实现

18.5.3 治理审计日志

状态： 待实现

错误码说明

注意事项

1. 认证机制：大部分接口需要登录认证，请在请求头中携带有效的Session Cookie或JWT Token

1. 数据源连接：不同数据库类型的连接参数不同，请参考各数据库的必填参数说明

1. 异步操作：表结构提取为异步操作，会立即返回请求ID，实际处理在后台进行

1. 向量检索：数据卡片查询使用向量检索技术，需要配置Weaviate向量数据库

1. SQL生成：智能查询功能依赖LLM生成SQL，需要配置相应的API密钥

1. 文件上传：Excel文件上传限制为20MB，支持.xlsx和.xls格式

1. 分页查询：列表类接口支持分页，建议合理设置page_size避免性能问题

项目功能概述

核心功能

1. 多数据源管理：支持MySQL、PostgreSQL、SQL Server、Oracle、SQLite、Trino、电科金仓（KingBase）、OceanBase（MySQL 租户模式）、达梦（DMBase）等多种数据库

1. 智能表结构提取：自动提取数据库表结构，生成标准化的数据卡片

1. 向量检索：基于Weaviate向量数据库，实现数据卡片的语义检索

1. 智能SQL生成：基于LLM技术，根据自然语言问题自动生成SQL查询

1. 跨数据源查询：支持多数据源联合查询，支持多种融合策略

1. 业务术语库：支持创建和管理业务术语库，实现NL2SQL场景中的术语识别和改写，提升查询准确性

1. 数据质量审计：对数据库表进行数据质量检查，统计空值、空字符串等

1. 用户权限管理：完整的用户、用户组、角色权限管理体系

技术架构

• 后端框架：Flask + Flask-RESTful

• 数据库ORM：SQLAlchemy

• 向量数据库：Weaviate

• 基础对话：qwen-max-latest

• 重排序Rerank：通义 千问的 gte-rerank-v2

• 文本向量化嵌入模型：通义千问的 text-embedding-v3

• LLM集成：支持通义千问等大语言模型

• 数据库支持：MySQL、PostgreSQL、SQL Server、Oracle、SQLite、Trino、电科金仓（KingBase）、OceanBase（MySQL 租户模式）、达梦（DMBase）

业务流程

1. 数据源接入：用户配置数据库连接信息，系统测试连接并提取表结构

1. 数据卡片生成：系统自动为每个表生成数据卡片，包含表结构、字段描述等信息

1. 向量化存储：数据卡片内容向量化后存储到Weaviate，支持语义检索

1. 智能查询：用户输入自然语言问题，系统检索相关数据卡片，生成SQL并执行

1. 结果融合：多数据源查询时，根据融合策略合并结果

附录

数据库连接字符串格式示例

MySQL:

mysql+pymysql://username:password@host:port/database

PostgreSQL:

postgresql+psycopg://username:password@host:port/database

SQL Server:

mssql+pyodbc://username:password@dsn_name/database
或
mssql+pyodbc://username:password@host:port/database?driver=OOntiCards+Driver+17+for+SQL+Server

Oracle:

oracle+oracledb://username:password@host:port/?service_name=SERVICE_NAME
或
oracle+oracledb://username:password@host:port/?sid=SID

SQLite:

sqlite:///path/to/database.db
或
sqlite:///:memory:  (内存模式)

Trino:

trino://username@host:port/catalog/schema

电科金仓（KingBase）:

postgresql+psycopg://username:password@host:port/database

OceanBase（MySQL 租户模式）:

mysql+pymysql://username:password@host:port/database

OceanBase MySQL 租户使用 mysql+pymysql 协议（默认端口 2881），连接串形式与 MySQL 一致。Oracle 租户模式将在后续版本中支持。

达梦（DMBase）:

dm+pymysql://username:password@host:port/database

达梦数据库使用 dm+pymysql 协议，兼容 Oracle 语法风格。

---

文档版本： 1.5.1 最后更新： 2026-08-04 维护者： OntiCards开发团队