# 企业 IT 故障诊断助手(课后作业)

基于 `Agentic_Rag` 参考项目改造的 IT 域 Agentic RAG,支持 aliyun_ssl_vpn / auth_timeout
两类问题的多源检索、Grader 控流与综合判断。

## 目录结构

```
homework/
├── app/                      # 业务代码
│   ├── config.py             # Settings (Pydantic + SecretStr)
│   ├── schemas.py            # RouteDecision / Evidence / QueryResponse 等
│   ├── sql_store.py          # SQLite 故障工单仓库
│   ├── milvus_store.py       # Milvus 向量库 + 过滤字段
│   ├── decision_engine.py    # Demo / DeepSeek 决策引擎
│   ├── tools.py              # SQL / Milvus / Web 三个 Tool
│   ├── graph.py              # LangGraph 状态机
│   ├── service.py            # AgenticRAGService 装配
│   ├── main.py               # FastAPI /health + /query
│   └── cli.py                # 命令行入口
├── data/
│   ├── source/incidents.csv  # 故障工单原始数据(4 条)
│   └── documents/            # 内部排障手册
├── docs/apipost_example.md   # Apipost 调用示例 + 真实响应
├── scripts/
│   ├── prepare_data.py       # SQLite + Milvus 数据导入
│   └── capture_apipost_example.py  # 复现 Apipost 示例响应的脚本
└── tests/test_it_diagnosis.py
```

## 快速开始

```bash
# 1. 安装依赖(沿用参考项目 venv 或自行创建)
python -m venv .venv && source .venv/bin/activate
pip install fastapi pydantic pydantic-settings pymilvus langgraph langchain-core \
            openai tavily-python python-dotenv pytest httpx

# 2. 准备数据(SQLite + Milvus)
python scripts/prepare_data.py

# 3. 启动 API
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 4. 调用
curl -s http://localhost:8000/health
curl -X POST http://localhost:8000/query -H "Content-Type: application/json" \
  -d '{"query":"aliyun_ssl_vpn auth_timeout 怎么排查?","debug":true}'
```

详见 `docs/apipost_example.md`。

## 测试

```bash
python -m pytest tests/test_it_diagnosis.py -v
# 13 passed
```

6 个验收测试覆盖:
1. `test_sql_30day_count` — SQL 聚合 30 天同类故障次数
2. `test_sql_only_route` — 仅 SQL 路由
3. `test_milvus_only_route` — 仅 Milvus 路由(带 `service_name` / `client_os` / `doc_type` 过滤)
4. `test_vendor_missing_returns_partial` — 厂商公告缺失时返回 partial 且不能排除公共服务异常
5. `test_milvus_first_call_empty_triggers_rewrite` — Milvus 首轮空时触发有限 Query Rewrite
6. `test_three_sources_accept` — 三类证据齐备时 Grader 返回 accept

补充测试覆盖 CLARIFY / REFUSE / 官方源过滤 / SQL 注入防御 / SecretStr / /health 端点。

## 关键设计约束

- **沙箱白名单**:只处理 `aliyun_ssl_vpn` + `auth_timeout`,其他服务名/错误类型一律 CLARIFY 或 REFUSE。
- **官方源过滤**:Web 搜索 query 固定带 `site:help.aliyun.com/zh/vpn`,Provider 内部再二次过滤非 `help.aliyun.com` 的 URL。
- **SQL 注入防御**:`service_name` / `error_type` / `client_os` / `days` 全部走参数化绑定,非法字符直接 ValueError。
- **Rewrite 预算**:`max_rounds` 在 Graph 层强制 stop,模型不能越权无限重试。
- **可观测性**:`debug=true` 时返回完整 `executed_queries` + `trace`,LangGraph 各节点状态一览无遗。
