# 下一步完成指南

## 📊 当前状态

已完成基础架构（约30%）：
- ✅ 完整的项目结构
- ✅ 数据库层（模型 + 迁移）
- ✅ 配置和工具模块
- ✅ ModelManager 服务

## 🔜 剩余工作

### 需要创建的文件（按优先级）

#### 1. 服务层（高优先级）

**`app/services/job_manager.py`** - 异步任务管理器
```python
# 核心功能：
# - submit_job(job_fn, *args, **kwargs) -> str
# - get_job_status(job_id) -> Dict
# - wait_for_job(job_id, timeout) -> Any
```

**`app/services/kb_manager.py`** - 知识库管理器
```python
# 核心功能：
# - create_kb(name, description) -> KnowledgeBase
# - ingest_documents(kb_id, docs, embedding_name) -> str
# - query_kb(kb_id, query, k) -> List[Document]
# - save_index(kb_id), load_index(kb_id)
```

**`app/services/conv_manager.py`** - 会话管理器
```python
# 核心功能：
# - create_conversation(user_id, title) -> Conversation
# - chat(conv_id, user_input, kb_id, llm_name) -> Message
# - get_messages(conv_id, limit, offset) -> List[Message]
```

**`app/services/agent_orchestrator.py`** - 智能体编排器
```python
# 核心功能：
# - run_agent(agent_name, input, llm_name, tools, kb_id) -> Dict
# - get_logs(run_id) -> List[ToolCall]
```

**`app/tools/retriever.py`** - 检索工具
**`app/tools/calculator.py`** - 计算器工具

#### 2. API 层（中优先级）

**`app/api/v1/models.py`** - 模型 API
- POST /api/v1/models
- GET /api/v1/models
- GET /api/v1/models/{id}
- PUT /api/v1/models/{id}
- DELETE /api/v1/models/{id}

**`app/api/v1/kb.py`** - 知识库 API
- POST /api/v1/kb
- GET /api/v1/kb
- POST /api/v1/kb/{kb_id}/ingest
- POST /api/v1/kb/{kb_id}/query
- GET /api/v1/kb/{kb_id}/status

**`app/api/v1/conv.py`** - 会话 API
- POST /api/v1/conversations
- GET /api/v1/conversations/{id}
- POST /api/v1/conversations/{id}/messages
- GET /api/v1/conversations/{id}/messages

**`app/api/v1/agent.py`** - 智能体 API
- POST /api/v1/agent/run
- GET /api/v1/agent/logs/{run_id}

#### 3. FastAPI 主程序（高优先级）

**`app/main.py`** - 应用入口
```python
# 核心内容：
# - FastAPI 应用初始化
# - 路由注册
# - 全局异常处理器
# - CORS 中间件
# - 健康检查端点
# - 启动和关闭事件
```

#### 4. Docker 配置（中优先级）

**`docker/Dockerfile`**
**`docker/docker-compose.yml`**
**`.dockerignore`**

#### 5. 测试（低优先级）

**`tests/conftest.py`** - pytest 配置
**`tests/unit/test_model_manager.py`**
**`tests/unit/test_kb_manager.py`**
**`tests/integration/test_api_models.py`**
**`tests/integration/test_api_kb.py`**

#### 6. 文档（低优先级）

**`docs/architecture.md`** - 架构文档
**`docs/runbook.md`** - 运维手册
**`docs/api.md`** - API 使用指南

## 🚀 快速完成建议

### 方式 1: 继续使用 AI 助手

向 AI 助手请求：
```
请继续创建以下文件：
1. src/app/services/job_manager.py
2. src/app/services/kb_manager.py
... (按上述列表)
```

### 方式 2: 参考设计文档手动实现

所有接口定义和实现细节都在：
- `docs/langchain-learning-kit/DESIGN_langchain-learning-kit.md`
- `docs/langchain-learning-kit/TASK_langchain-learning-kit.md`

### 方式 3: 最小可用版本（MVP）

先实现最核心的功能，跳过测试和文档：
1. 完成服务层（4个文件）
2. 实现 2个 API（Model + KB）
3. 创建 main.py
4. 基础 Docker 配置

预计时间：4-5 小时

## 📝 当前可以做的事情

### 1. 安装依赖
```bash
cd langchain-learning-kit
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

### 2. 配置环境变量
```bash
cp .env.example .env
# 编辑 .env，填入你的配置：
# - DATABASE_URL
# - OPENAI_API_KEY
```

### 3. 初始化数据库
```bash
# 方式 1: 使用 Alembic
cd app
alembic upgrade head

# 方式 2: 使用初始化脚本
python scripts/init_db.py
```

### 4. 测试已完成的模块

创建测试脚本 `test_current.py`：
```python
from app.config import get_settings
from app.db.session import init_db_manager
from app.services.model_manager import ModelManager

# 测试配置
settings = get_settings()
print(f"✓ 配置加载成功: {settings.app_name}")

# 测试数据库
db_manager = init_db_manager(settings)
print(f"✓ 数据库连接成功: {settings.database_url}")

# 测试 ModelManager
with db_manager.session_scope() as session:
    manager = ModelManager(session, settings)
    print("✓ ModelManager 初始化成功")

print("\n所有已完成模块测试通过！")
```

## ⚠️ 重要提示

1. **MySQL 必须运行**: 确保 MySQL 服务启动，数据库已创建
2. **OpenAI API Key**: 需要有效的 API Key 才能测试 LLM 功能
3. **Python 版本**: 需要 Python 3.11+

## 🎯 推荐完成顺序

1. **立即创建**:
   - job_manager.py (最简单，无外部依赖)
   - main.py (整合现有代码，可以启动服务)
   - models.py API (可以测试 ModelManager)

2. **随后创建**:
   - kb_manager.py + kb.py API (知识库核心功能)
   - conv_manager.py + conv.py API (对话功能)

3. **最后创建**:
   - agent_orchestrator.py + tools (高级功能)
   - Docker 配置
   - 测试和文档

## 📖 参考资料

- LangChain 文档: https://python.langchain.com/docs/get_started/introduction
- FastAPI 文档: https://fastapi.tiangolo.com/
- FAISS 文档: https://github.com/facebookresearch/faiss
- SQLAlchemy 文档: https://docs.sqlalchemy.org/

## 💡 提示

所有的接口定义、数据流、异常处理都已经在设计文档中详细说明。
实现时可以直接参考 `DESIGN_langchain-learning-kit.md` 中的代码示例。