# 项目日志服务使用清单

## 概述
本文档详细列出了项目中各个模块应该使用的日志服务，作为日志改造的实施指南。项目日志系统分为4个独立模块：app、agent、vanna、data_pipeline。

## 日志文件分配方案

### 1. agent.log - Agent相关模块

#### agent目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `agent/citu_agent.py` | print | `get_agent_logger("CituAgent")` | 主Agent类，包含大量调试信息 |
| `agent/classifier.py` | print | `get_agent_logger("Classifier")` | 问题分类器 |
| `agent/config.py` | print | `get_agent_logger("Config")` | 配置管理 |
| `agent/state.py` | 无 | 无需日志 | 仅定义数据结构 |

#### agent/tools目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `agent/tools/general_chat.py` | print | `get_agent_logger("GeneralChat")` | 聊天工具 |
| `agent/tools/sql_execution.py` | print | `get_agent_logger("SQLExecution")` | SQL执行工具 |
| `agent/tools/sql_generation.py` | print | `get_agent_logger("SQLGeneration")` | SQL生成工具 |
| `agent/tools/summary_generation.py` | print | `get_agent_logger("SummaryGeneration")` | 摘要生成工具 |
| `agent/tools/utils.py` | 无 | `get_agent_logger("ToolUtils")` | 工具函数（如需日志） |

### 2. data_pipeline.log - Data Pipeline相关模块

#### data_pipeline根目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `data_pipeline/schema_workflow.py` | logging.getLogger("schema_tools.SchemaWorkflowOrchestrator") | `get_data_pipeline_logger("SchemaWorkflow")` | 工作流编排器 |
| `data_pipeline/metadata_only_generator.py` | print | `get_data_pipeline_logger("MetadataGenerator")` | 元数据生成器 |
| `data_pipeline/config.py` | 无 | 无需日志 | 配置文件 |

#### data_pipeline/ddl_generation目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `data_pipeline/ddl_generation/training_data_agent.py` | logging.getLogger("schema_tools.Agent") | `get_data_pipeline_logger("TrainingDataAgent")` | 训练数据代理 |
| `data_pipeline/ddl_generation/ddl_md_generator.py` | 无具体日志 | `get_data_pipeline_logger("DDLMDGenerator")` | DDL/MD生成器 |

#### data_pipeline/qa_generation目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `data_pipeline/qa_generation/qs_agent.py` | logging.getLogger("schema_tools.QSAgent") | `get_data_pipeline_logger("QSAgent")` | Question-SQL代理 |
| `data_pipeline/qa_generation/qs_generator.py` | 无具体日志 | `get_data_pipeline_logger("QSGenerator")` | Question-SQL生成器 |

#### data_pipeline/analyzers目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `data_pipeline/analyzers/md_analyzer.py` | logging.getLogger("schema_tools.MDFileAnalyzer") | `get_data_pipeline_logger("MDAnalyzer")` | MD文件分析器 |
| `data_pipeline/analyzers/theme_extractor.py` | logging.getLogger("schema_tools.ThemeExtractor") | `get_data_pipeline_logger("ThemeExtractor")` | 主题提取器 |

#### data_pipeline/validators目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `data_pipeline/validators/sql_validator.py` | logging.getLogger("schema_tools.SQLValidator") | `get_data_pipeline_logger("SQLValidator")` | SQL验证器 |
| `data_pipeline/validators/sql_validation_agent.py` | logging.getLogger("schema_tools.SQLValidationAgent") | `get_data_pipeline_logger("SQLValidationAgent")` | SQL验证代理 |
| `data_pipeline/validators/file_count_validator.py` | logging.getLogger("schema_tools.FileCountValidator") | `get_data_pipeline_logger("FileCountValidator")` | 文件计数验证器 |
| `data_pipeline/validators/sql_validate_cli.py` | print | `get_data_pipeline_logger("SQLValidateCLI")` | SQL验证命令行工具 |
| `data_pipeline/validators/sql_validation_example.py` | print | `get_data_pipeline_logger("SQLValidationExample")` | SQL验证示例 |

#### data_pipeline/trainer目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `data_pipeline/trainer/vanna_trainer.py` | print | `get_data_pipeline_logger("VannaTrainer")` | Vanna训练器 |
| `data_pipeline/trainer/run_training.py` | 依赖其他模块日志 | `get_data_pipeline_logger("RunTraining")` | 训练运行脚本 |

#### data_pipeline/utils目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `data_pipeline/utils/logger.py` | 自定义日志系统 | **直接删除或改造为空函数** | 原日志工具，直接使用新系统 |
| `data_pipeline/utils/table_parser.py` | logging.getLogger("schema_tools.TableListParser") | `get_data_pipeline_logger("TableParser")` | 表解析器 |
| `data_pipeline/utils/system_filter.py` | logging.getLogger("schema_tools.SystemTableFilter") | `get_data_pipeline_logger("SystemFilter")` | 系统表过滤器 |
| `data_pipeline/utils/permission_checker.py` | logging.getLogger("schema_tools.DatabasePermissionChecker") | `get_data_pipeline_logger("PermissionChecker")` | 权限检查器 |
| `data_pipeline/utils/large_table_handler.py` | logging.getLogger("schema_tools.LargeTableHandler") | `get_data_pipeline_logger("LargeTableHandler")` | 大表处理器 |
| `data_pipeline/utils/file_manager.py` | logging.getLogger("schema_tools.FileNameManager") | `get_data_pipeline_logger("FileManager")` | 文件管理器 |

#### data_pipeline/tools目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `data_pipeline/tools/base.py` | logging.getLogger + logging.debug | `get_data_pipeline_logger("ToolBase")` | 工具基类 |
| `data_pipeline/tools/comment_generator.py` | 依赖base.py | `get_data_pipeline_logger("CommentGenerator")` | 注释生成器 |
| `data_pipeline/tools/data_sampler.py` | 依赖base.py | `get_data_pipeline_logger("DataSampler")` | 数据采样器 |
| `data_pipeline/tools/database_inspector.py` | 依赖base.py | `get_data_pipeline_logger("DatabaseInspector")` | 数据库检查器 |
| `data_pipeline/tools/ddl_generator.py` | 依赖base.py | `get_data_pipeline_logger("DDLGenerator")` | DDL生成器 |
| `data_pipeline/tools/doc_generator.py` | 依赖base.py | `get_data_pipeline_logger("DocGenerator")` | 文档生成器 |

### 3. vanna.log - Vanna相关模块

#### core目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `core/vanna_llm_factory.py` | 无 | `get_vanna_logger("VannaFactory")` | Vanna实例工厂 |
| `core/embedding_function.py` | 无 | `get_vanna_logger("EmbeddingFunction")` | 嵌入函数 |

#### customllm目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `customllm/base_llm_chat.py` | print | `get_vanna_logger("BaseLLMChat")` | LLM聊天基类 |
| `customllm/deepseek_chat.py` | 继承base_llm_chat | `get_vanna_logger("DeepSeekChat")` | DeepSeek聊天实现 |
| `customllm/ollama_chat.py` | 继承base_llm_chat | `get_vanna_logger("OllamaChat")` | Ollama聊天实现 |
| `customllm/qianwen_chat.py` | 继承base_llm_chat | `get_vanna_logger("QianwenChat")` | 千问聊天实现 |

#### customembedding目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `customembedding/ollama_embedding.py` | 无 | `get_vanna_logger("OllamaEmbedding")` | Ollama嵌入实现 |

#### custompgvector目录
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `custompgvector/pgvector.py` | logging.info/error | `get_vanna_logger("PGVector")` | PostgreSQL向量存储 |

#### common目录（Vanna相关）
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `common/vanna_instance.py` | 无 | `get_vanna_logger("VannaInstance")` | Vanna实例管理 |
| `common/vanna_combinations.py` | 无 | `get_vanna_logger("VannaCombinations")` | Vanna组合配置 |

### 4. app.log - 主应用和通用模块

#### 主应用文件
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `citu_app.py` | 无 | `get_app_logger("CituApp")` | 主应用入口 |
| `flask_app.py` | 无 | `get_app_logger("FlaskApp")` | Flask应用（暂不考虑） |
| `chainlit_app.py` | 无 | `get_app_logger("ChainlitApp")` | Chainlit应用（暂不考虑） |
| `app_config.py` | 无 | 无需日志 | 应用配置 |

#### common目录（通用功能）
| 文件 | 当前日志方式 | 目标Logger | 说明 |
|------|-------------|-----------|------|
| `common/qa_feedback_manager.py` | print | `get_app_logger("QAFeedbackManager")` | QA反馈管理 |
| `common/redis_conversation_manager.py` | 无 | `get_app_logger("RedisConversation")` | Redis对话管理 |
| `common/embedding_cache_manager.py` | 无 | `get_app_logger("EmbeddingCache")` | 嵌入缓存管理 |
| `common/session_aware_cache.py` | 无 | `get_app_logger("SessionCache")` | 会话缓存 |
| `common/utils.py` | 无 | `get_app_logger("CommonUtils")` | 通用工具 |
| `common/messages.py` | 无 | 无需日志 | 消息定义 |
| `common/result.py` | 无 | 无需日志 | 结果定义 |

## 特殊处理说明

### 1. data_pipeline/utils/logger.py
当前是data_pipeline模块的日志系统，改造方案：
- 直接删除原有日志系统代码
- 保留函数接口（如setup_logging），但函数体为空或直接pass
- 所有调用该模块的地方直接使用新日志系统

### 2. print语句替换策略
- 所有 `print()` 语句根据内容判断日志级别
- 包含 error/exception/fail 的内容 -> `logger.error()`
- 包含 warning/warn 的内容 -> `logger.warning()`
- 包含 debug 的内容 -> `logger.debug()`
- 其他内容 -> `logger.info()`

### 3. 现有logging.getLogger替换
- 所有 `logging.getLogger("schema_tools.*")` 替换为 `get_data_pipeline_logger()`
- 保持原有的日志级别习惯

## 实施优先级

1. **第一优先级**：citu_app.py 和 agent 模块（核心功能）
2. **第二优先级**：data_pipeline 模块（直接改造）
3. **第三优先级**：vanna 相关模块
4. **第四优先级**：common 通用模块

## 注意事项

1. **模块分离**：4个模块的日志完全独立，各自输出到对应的日志文件
2. **上下文信息**：在 agent 模块和 app 模块中支持 user_id 和 session_id（可选）
3. **性能统计**：保留原有的时间统计方式，不使用装饰器
4. **直接改造**：所有模块直接使用新系统，不考虑向后兼容

## 测试建议

1. 先在开发环境测试，确保日志正常输出到对应文件
2. 检查日志文件轮转功能是否正常
3. 验证各模块日志是否正确分离
4. 确认错误降级到控制台的功能正常工作