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開發團隊