sql_qa_pair/docs/software_requirements.md

智能问答模块软件需求说明书

1. 总体概述

• 本系统外挂在现有 BI 平台，负责解析仪表板、卡片以及机构（bbk）维度下的问答需求，自动生成 SQL 并在 BI 系统中执行。
• 系统提供 FastAPI 后端接口，供前端或其他服务发起“问题生成/确认”流程，并将确认后的问答对写入 parquet 文件，用于离线训练或直接答复。
• 全部服务运行在后台，无前端组件；所有对话上下文均来源于 DuckDB 中的 BI 元数据表及机构配置。

2. 数据结构要求

1. 卡片-数据集-仪表板映射表：字段 card_id、dashboard_id、dataset_id、dashboard_name、card_name、dataset_name、bbk_id。作为主数据表，保证数据有效。
2. 卡片信息表：字段 card_id、card_name、card_desc、sql_select、sql_where、sql_groupby 描述卡片的 SQL 形态。
3. 卡片筛选器信息表：字段 card_id、filter_id、filter_type(F/D)、where_clause、default_value、options 描述可选筛选器与内置过滤条件。
4. 仪表板信息表：字段 dashboard_id、dashboard_name、dashboard_desc、folder_path 描述仪表板元数据。
5. 数据集 DDL 表：字段 dataset_id、dataset_ddl，按 HiveSQL 规范存放。

这些结构均存放于 DuckDB，所有查询均基于机构编号（bbk/bbk_id）过滤。

3. 系统架构

• 接口层：app/endpoints 下的 FastAPI generate_qa_pair 接口作为唯一对外入口。
• 工作流层：PipelineManager + Workflow 负责解析配置化节点依赖，并串联 operator。
• Operator 层：generate_qa_pair operator 协调数据读取、prompt 渲染、LLM 调用与结果解析。
• 支撑模块：
  • LLMManager 统一管理不同模型提供方与解析策略。
  • PromptManager 负责 prompt 模板的存储、渲染和复用。
  • ParserManager/parsers 定义 LLM 输出解析策略。
  • DuckDBClient 提供线程安全的数据查询封装。
  • 日志模块 app.log 负责统一输出。
  • 常量模块 app.const 维护目录、阈值等。

模块间关系：接口层调用 Workflow；Workflow 根据配置调用 operator；operator 内部组合数据访问模块、Prompt/LLM 管理器与解析器。最终结果写入日志目录与 parquet 文件。

4. 模块划分与实现要点

4.1 接口模块（FastAPI）

• 负责接收 QARequest，校验卡片数量不超过 MAX_INPUT_CARD_IDS。
• 将 bbk_id/dashbord/card_ids/user_request 打包成 input_args 交给 Workflow。
• 返回 QAResponse，包含仪表板、机构、卡片 ID 及问答列表。

4.2 工作流模块

• PipelineManager：从 config/pipeline_settings.yaml 读取节点定义，生成拓扑顺序。
• Workflow：按照拓扑依次执行 operator，支持异步/流式输出。
• 节点之间通过 workflow.result 共享数据，last_node 节点需写入最终结果。

4.3 Operator：generate_qa_pair

• 从 DuckDBClient 读取仪表板、卡片、筛选器及 DDL 元数据，组装为 DashboardInfo。
• 使用 PromptManager 渲染 generate_qa_pair 或带用户偏好模板。
• 调用 LLMManager 按节点配置选择模型，获取 JSON 问答列表，并借助 ParserManager 解析。
• 将过滤条件转换为 WHERE/HAVING 语句，拼接最终 SQL，构造 QAPair。
• 记录 prompt 文本和生成结果日志，并触发 parquet 落盘（后续模块负责）。

4.4 LLM 管理模块

• LLMManager 为单例，读取 config/llm_settings.yaml。
• 支持多种 provider：默认 echo（回声，便于测试）、http（通过 HTTP 调用自建/第三方 LLM 服务）。
• 每个模型可指定解析器（如 json、text），通过 ParserManager 统一管理。
• 暴露 get_llm_model(model_name)，operator 根据 pipeline 配置取用。

4.5 Prompt 管理模块

• PromptManager 读取 config/prompt_template.yaml 或使用内置默认模板。
• 模板可存放于 prompts/ 目录或直接配置在 YAML 中，支持变量占位与必填校验。
• PromptTemplate.ainvoke(context) 异步渲染并返回文本，供 operator 直接写入日志或传给 LLM。

4.6 解析器模块

• parsers.BaseParser 抽象解析器接口。
• 内置 JsonParser（去除 Markdown 包裹、解析 JSON）与 TextParser（直接返回文本）。
• ParserManager 允许通过配置注册自定义解析器或重写默认行为。

4.7 数据访问模块

• DuckDBClient 封装了线程安全查询方法，支持：
  • fetch_dashboard_cards：根据 dashboard_id、card_ids、bbk_id 过滤卡片。
  • fetch_card_definition：获取卡片 SQL 定义。
  • fetch_card_filters：获取筛选器/固化条件。
  • fetch_dashboard_info、fetch_dataset_ddl：补全仪表板及数据集信息。
• 所有查询返回字段-值 dict 列表，以供 Pydantic 模型构造。

4.8 存储与日志

• 日志目录 app/log，通过 app.log.logger 写入，支持级别控制。
• Prompt 与问答日志写入 LOG_ROOT/prompts/... 便于审计。
• 经过人工确认的问题将由后续节点序列化到 parquet，文件路径遵循 DATA_DIR/parquet/{bbk_id}/{dashboard_id}/。

5. 业务流程

1. 用户在 BI 前端选定仪表板、卡片与机构，触发 API。
2. 接口层调用 Workflow；get_dashboard_info 节点（后续实现）使用 DuckDBClient 读取所需元数据。
3. generate_qa_pair operator 构建 prompt，调用 LLM 生成若干候选问题和过滤条件。
4. 系统将问答转成 SQL，连同 slot 化问题写入返回体与 parquet，日志记录 prompt 与 SQL。
5. 后续模块可基于这些问答对执行真实查询或训练问答模型。

6. 非功能需求

• 性能：单次请求支持最多 3 张卡片（可通过常量调整）。DuckDB 查询需在 1 秒内返回元数据。
• 扩展性：LLM 与 Prompt 均通过配置驱动，可为不同机构配置不同模型或模板。
• 可观测性：日志必须包含 request_id、bbk_id、dashboard_id 以便审计。
• 安全：所有外部 LLM HTTP 调用需支持自定义 Header，用于透传鉴权 token。

7. 开发注意事项

• 任何变量或字段中包含 bbk/bbk_id 均指机构编号。
• 当 YAML/模板缺失时，模块会回退到默认模板与 Echo LLM，方便在无外部依赖下开发调试。
• DuckDB 表结构需与上述字段保持一致，字段命名采用 snake_case。