加入日志管理

IMPACT_ANALYSIS.md

@@ -551,3 +551,44 @@
 | 项 | 说明 |
 |----|------|
 | `SSE_STREAM_CHUNK_CHARS` | 可选；每段 SSE 的 `content` 最大字符数，默认 `64`。 |
+
+---
+
+# Impact Analysis Report — API 日志落盘与可观测性（追加）
+
+## 1. 改动概览
+
+- **背景与目标**：终端日志偏少，难以排查 Text2SQL 全链路问题；需将更细粒度的日志写入仓库 `logs/`，且每次进程启动只保留一个 `.log` 文件。
+- **涉及模块**：`api_server.py`、`backend/utils/repo_logging.py`（新）、`backend/agents/orchestrator.py`、`backend/schema/indexer.py`、`backend/utils/dialog_classifier.py`。
+- **改动类型**：可观测性增强（行为对业务结果无影响）。
+
+## 2. 方法级改动
+
+| 位置 | 变更 |
+|------|------|
+| `configure_text2sql_api_logging` | 新建：清空 `logs/*.log`，创建 `logs/text2sql_api.log`（覆盖写）；root 双 Handler（控制台简短格式 + 文件含 filename/lineno/funcName）；关闭 Chroma/posthog 遥测 logger；`httpx`/`httpcore` 降为 WARNING。 |
+| `api_server` 导入段 | 在 `from main import …` 之前调用上述配置；移除 `basicConfig`；`uvicorn.run(..., log_config=None)` 避免覆盖 root（勿用 `False`，否则会走 `fileConfig` 崩溃），并清空 uvicorn 自带 handler 改为 `propagate`。 |
+| `_run_generate` / `nl_chat` / `_chat_stream_events` | 增加请求维度、对话上文长度、流式结束时的 valid/attempts/tables/SQL 摘要等 INFO 日志。 |
+| `Text2SQLOrchestrator` | 向量粗筛输出表名+分数列表；选表输出 reasoning 预览；few-shot 注入 qid 与问题预览；生成 SQL 全文（超长截断至约 12k 字符）；`_validate_sql` 返回前汇总 valid/errors/warnings/探针。 |
+| `SchemaIndexer.search` | 检索结果由 DEBUG 改为 INFO，输出命中数与 top 表+分。 |
+| `classify_dialog` 规则/hybrid 快路径 | DEBUG 改为 INFO，附用户输入预览；LLM 分支补充 reply 预览。 |
+
+## 3. 调用方与影响范围
+
+- **调用方**：仅通过 `python api_server.py`（或等价导入 `api_server`）启动 API 时生效；`backend/main.py` CLI 仍使用自身 `basicConfig`，不落盘到本 `logs/text2sql_api.log`（未改 CLI）。
+- **破坏性变更**：否。
+
+## 4. 风险与回滚
+
+- **风险级别**：低。日志文件可能含用户查询片段与 SQL，需注意磁盘与隐私（内网演示场景可接受）。
+- **回滚**：删除 `repo_logging` 调用与相关增强日志，恢复 `basicConfig` 与默认 `uvicorn.run` 即可。
+
+**回滚方式是否简单**：是。
+
+## 5. 验证与测试
+
+- 建议：`python -m py_compile api_server.py backend/utils/repo_logging.py`；启动 `python api_server.py` 后确认生成 `logs/text2sql_api.log` 且重启后仅保留该文件。
+
+## 6. 配置变更
+
+- 无新增环境变量；日志路径固定为仓库根下 `logs/text2sql_api.log`。