# 系统日志分析与调试操作指南 (System Debugging Guide)

本文档旨在记录当前系统的运行状况、已知问题以及标准化的调试流程。它将指导开发人员如何利用现有工具（如 Docker、Tilt、自定义脚本）快速定位问题。

## 1. 系统现状 (System Status Snapshot)

截至 2025-11-20，Fundamental Analysis 系统由多个微服务组成，采用 Docker Compose 编排，并通过 Tilt 进行开发环境的热重载管理。

### 1.1 服务概览

| 服务名称 | 职责 | 当前状态 | 关键依赖 |
| :--- | :--- | :--- | :--- |
| **API Gateway** | 流量入口，任务分发，服务发现 | 🟢 正常 | NATS, Providers |
| **Report Generator** | 接收指令，调用 LLM 生成报告 | 🟢 正常 (但在等待任务) | NATS, Data Persistence, LLM API |
| **Data Persistence** | 数据库读写，配置管理，Session 数据隔离 | 🟢 正常 (已恢复 Seeding) | Postgres |
| **Alphavantage** | 美股数据 Provider | 🟢 正常 | NATS, External API |
| **YFinance** | 雅虎财经 Provider | 🟢 正常 | NATS, External API |
| **Tushare** | A股数据 Provider | 🟢 正常 | NATS, External API |
| **Finnhub** | 市场数据 Provider | 🟡 **降级 (Degraded)** | 缺少 API Key 配置 |

### 1.2 核心问题：报告生成流程阻塞
目前用户在前端点击 "生成报告" 后无反应。
*   **现象**：API Gateway 未收到生成报告的请求，Report Generator 未收到 NATS 消息。
*   **原因推断**：Finnhub Provider 因配置缺失处于 "Degraded" 状态，导致前端轮询的任务列表 (`GET /tasks/{id}`) 中始终包含未完成/失败的任务。前端逻辑可能因等待所有 Provider 完成而阻塞了后续 "Generate Report" 请求的发送。

---

## 2. 运维与开发流程 (DevOps & Workflow)

我们使用 **Tilt** 管理 Docker Compose 环境。这意味着你不需要手动 `docker-compose up/down` 来应用代码变更。

### 2.1 启动与更新
1.  **启动环境**：
    在项目根目录运行：
    ```bash
    tilt up
    ```
    这会启动所有服务，并打开 Tilt UI (通常在 `http://localhost:10350`)。

2.  **代码更新**：
    *   直接在 IDE 中修改代码并保存。
    *   **Tilt 会自动检测变更**：
        *   如果是前端代码，Tilt 会触发前端热更新。
        *   如果是 Rust 服务代码，Tilt 会在容器内或宿主机触发增量编译并重启服务。
    *   **操作建议**：修改代码后，只需**等待一会儿**，观察 Tilt UI 变绿即可。无需手动重启容器。

3.  **配置变更**：
    *   如果修改了 `docker-compose.yml` 或 `.env`，Tilt 通常也会检测到并重建相关资源。

### 2.2 快速重置数据库 (如有必要)
如果遇到严重的数据不一致或认证问题，可使用以下命令重置数据库（**警告：数据将丢失，但会自动 Seed 默认模板**）：
```bash
docker-compose down postgres-db
docker volume rm fundamental_analysis_pgdata
docker-compose up -d postgres-db
# 等待几秒后
# Tilt 会自动重启依赖 DB 的服务，触发 Seeding
```

---

## 3. 调试与分析工具 (Debugging Tools)

为了快速诊断跨服务的问题，我们提供了一个能够聚合查看所有容器最新日志的脚本。

### 3.1 `inspect_logs.sh` 使用指南

该脚本位于 `scripts/inspect_logs.sh`。它能一次性输出所有关键服务的最后 N 行日志，避免手动切换容器查看。

*   **基本用法** (默认显示最后 10 行)：
    ```bash
    ./scripts/inspect_logs.sh
    ```

*   **指定行数** (例如查看最后 50 行)：
    ```bash
    ./scripts/inspect_logs.sh 50
    ```

### 3.2 分析策略

当遇到 "点击无反应" 或 "流程卡住" 时，请按以下步骤操作：

1.  **运行脚本**：`./scripts/inspect_logs.sh 20`
2.  **检查 API Gateway**：
    *   是否有 `Received data fetch request`？ -> 如果无，说明前端没发请求。
    *   是否有 `Publishing analysis generation command`？ -> 如果无，说明 Gateway 没收到生成指令，或者内部逻辑（如等待 Provider）卡住了。
3.  **检查 Provider**：
    *   是否有 `Degraded` 或 `Error` 日志？(如当前的 Finnhub 问题)
4.  **检查 Report Generator**：
    *   是否有 `Received NATS command`？ -> 如果无，说明消息没发过来。

---

## 4. 当前待办与修复建议 (Action Items)

为了打通流程，我们需要解决 Finnhub 导致的阻塞问题。

1.  **修复配置**：
    *   在 `config/data_sources.yaml` (或数据库 `configs` 表) 中配置有效的 Finnhub API Key。
    *   或者，暂时在配置中**禁用** Finnhub (`enabled: false`)，让前端忽略该 Provider。

2.  **前端容错**：
    *   检查前端 `useReportEngine.ts`。
    *   确保即使某个 Provider 失败/超时，用户依然可以强制触发 "Generate Report"。

3.  **验证**：
    *   使用 `inspect_logs.sh` 确认 Finnhub 不再报错，或已被跳过。
    *   确认 API Gateway 日志中出现 `Publishing analysis generation command`。

