# 数字员工平台实施计划

> 日期：2026-05-05
> 依据设计文档：docs/plans/2026-05-05-digital-employee-design.md
> 状态：待批准

## 总览

MVP 共分 5 个批次，每批次 3 个任务，预计总工时 ~15 人天。

| 批次 | 范围 | 任务数 |
|------|------|--------|
| B1 | 项目脚手架 + 数据模型 + 租户管理 | 3 |
| B2 | 数字员工配置 + LLM Provider 抽象层 | 3 |
| B3 | 对话接口（SSE 流式）+ 对话历史 | 3 |
| B4 | RAG 知识库 + 文档处理 | 3 |
| B5 | 集成测试 + 错误处理 + 启动脚本 | 3 |

---

## 批次 B1：项目脚手架 + 数据模型 + 租户管理

### Task 1.1：初始化项目脚手架

- **修改目标**：创建项目目录结构、Python 依赖配置、FastAPI 入口
- **涉及文件**：
  - `backend/pyproject.toml` — 依赖声明
  - `backend/app/__init__.py`
  - `backend/app/main.py` — FastAPI app 工厂
  - `backend/app/config.py` — Settings（pydantic-settings）
  - `backend/app/database.py` — async SQLAlchemy 引擎 + session
  - `backend/.env.example`
  - `backend/tests/conftest.py` — pytest fixtures（async client + test DB）
- **验证方式**：`uv run uvicorn app.main:app --reload` 启动无报错，`/docs` 可访问
- **完成判定**：服务启动 + Swagger UI 可访问 + test DB fixture 可用

### Task 1.2：创建 SQLAlchemy 数据模型

- **修改目标**：定义全部核心 ORM 模型（Tenant, TenantConfig, DigitalEmployee, Conversation, Message, KnowledgeBase, Document）
- **涉及文件**：
  - `backend/app/models/__init__.py`
  - `backend/app/models/tenant.py` — Tenant, TenantConfig
  - `backend/app/models/employee.py` — DigitalEmployee
  - `backend/app/models/conversation.py` — Conversation, Message
  - `backend/app/models/knowledge.py` — KnowledgeBase, Document
  - `backend/app/database.py` — 添加 `Base.metadata.create_all` 初始化逻辑
- **验证方式**：启动时自动建表，`sqlite` 文件包含全部表
- **完成判定**：`sqlite3 test.db .tables` 输出全部 7 张表

### Task 1.3：租户管理 API（CRUD + LLM 配置）

- **修改目标**：实现租户 CRUD 端点 + LLM 配置更新端点，含 AES-256 加密存储 API Key
- **涉及文件**：
  - `backend/app/schemas/tenant.py` — Pydantic request/response schemas
  - `backend/app/api/deps.py` — DB session 依赖注入
  - `backend/app/api/v1/__init__.py` — v1 router
  - `backend/app/api/v1/tenants.py` — 5 个端点
  - `backend/app/services/tenant_service.py` — 业务逻辑 + 加密
  - `backend/app/middleware/tenant.py` — 租户上下文中间件（预留）
- **验证方式**：
  - RED：`test_tenants.py` 先写失败测试（创建/读取/更新/删除/配置更新）
  - GREEN：实现端点让测试通过
- **完成判定**：全部租户测试通过，API Key 写入后数据库为密文

---

## 批次 B2：数字员工配置 + LLM Provider 抽象层

### Task 2.1：数字员工配置 API

- **修改目标**：实现数字员工 CRUD 端点，支持关联知识库
- **涉及文件**：
  - `backend/app/schemas/employee.py`
  - `backend/app/api/v1/employees.py`
  - `backend/app/services/employee_service.py`
  - `backend/tests/test_employees.py`
- **验证方式**：TDD — RED/GREEN/REFACTOR
- **完成判定**：全部员工测试通过，创建时可关联知识库 ID 列表

### Task 2.2：LLM Provider 抽象层

- **修改目标**：实现 BaseLLMProvider 接口 + OpenAIProvider + QwenProvider
- **涉及文件**：
  - `backend/app/providers/__init__.py`
  - `backend/app/providers/base.py` — BaseLLMProvider ABC + LLMMessage/LLMResponse
  - `backend/app/providers/openai_provider.py` — chat / chat_stream / embed
  - `backend/app/providers/qwen_provider.py` — 兼容 OpenAI SDK 格式
  - `backend/tests/test_providers.py`
- **验证方式**：TDD — mock LLM API 响应，验证接口一致性和 Provider 注册表路由
- **完成判定**：两个 Provider 的 chat/chat_stream/embed 单测通过（mock 模式）

### Task 2.3：Provider 集成到租户配置

- **修改目标**：tenant_service 根据 tenant_config 动态实例化 Provider，API 端点可验证 Provider 可用性
- **涉及文件**：
  - `backend/app/services/tenant_service.py` — 新增 `get_provider_for_tenant()`
  - `backend/app/api/v1/tenants.py` — 新增 `POST /tenants/{id}/test-provider` 端点
  - `backend/tests/test_providers.py` — 补充集成验证测试
- **验证方式**：TDD — mock Provider 测试路由正确性
- **完成判定**：test-provider 端点根据租户配置返回正确的 Provider 实例信息

---

## 批次 B3：对话接口（SSE 流式）+ 对话历史

### Task 3.1：对话与消息数据模型 + API

- **修改目标**：实现 Conversation / Message CRUD + 消息发送端点（非流式先实现）
- **涉及文件**：
  - `backend/app/schemas/conversation.py`
  - `backend/app/api/v1/conversations.py`
  - `backend/app/services/conversation_service.py`
  - `backend/tests/test_conversations.py`
- **验证方式**：TDD — 创建对话 / 发送消息 / 获取历史
- **完成判定**：全部对话基础测试通过

### Task 3.2：SSE 流式响应

- **修改目标**：实现 SSE 事件流（message_start / token / sources / message_end / error），集成 Provider.chat_stream
- **涉及文件**：
  - `backend/app/api/v1/conversations.py` — 改造 messages 端点为 SSE
  - `backend/app/services/conversation_service.py` — 流式处理 + 持久化
  - `backend/tests/test_conversations.py` — 补充 SSE 测试
- **验证方式**：TDD — 用 TestClient 验证 SSE 事件格式；手动用 curl 验证流式输出
- **完成判定**：SSE 事件格式正确，token 按序到达，message_end 含 token_count

### Task 3.3：会话上下文管理

- **修改目标**：实现 max_context_messages 窗口裁剪、system_prompt 注入、对话历史加载
- **涉及文件**：
  - `backend/app/services/conversation_service.py` — 新增 `build_messages()`
  - `backend/tests/test_conversations.py` — 补充上下文窗口测试
- **验证方式**：TDD — 验证消息超过 max_context_messages 时自动裁剪
- **完成判定**：上下文窗口裁剪正确，system_prompt 始终在首位

---

## 批次 B4：RAG 知识库 + 文档处理

### Task 4.1：知识库 CRUD + 文档上传 API

- **修改目标**：实现知识库和文档的 CRUD 端点，含文件上传
- **涉及文件**：
  - `backend/app/schemas/knowledge.py`
  - `backend/app/api/v1/knowledge.py`
  - `backend/app/services/knowledge_service.py`
  - `backend/tests/test_knowledge.py`
- **验证方式**：TDD — 创建知识库 / 上传文档 / 列出 / 删除
- **完成判定**：知识库 CRUD 测试通过，文件上传持久化到本地存储

### Task 4.2：文档解析与分块

- **修改目标**：实现 PDF/DOCX/TXT/MD 文件解析 → RecursiveCharacterTextSplitter 分块
- **涉及文件**：
  - `backend/app/services/knowledge_service.py` — 新增解析与分块逻辑
  - `backend/tests/test_knowledge.py` — 补充文档解析测试（用小文件 fixture）
- **验证方式**：TDD — 上传小 PDF/TXT，验证分块结果数量和内容
- **完成判定**：4 种文件类型均能正确解析分块，chunk_size=500, overlap=50

### Task 4.3：RAG Pipeline（嵌入 + 检索 + 注入）

- **修改目标**：实现嵌入生成 → ChromaDB 存储 → 相似度检索 → 上下文注入对话
- **涉及文件**：
  - `backend/app/services/rag_service.py` — RAG 全流程
  - `backend/app/services/conversation_service.py` — 集成 RAG 检索
  - `backend/tests/test_knowledge.py` — 补充 RAG 检索测试（mock embedding）
  - `backend/tests/test_conversations.py` — 补充 RAG 注入测试
- **验证方式**：TDD — mock embedding，验证 ChromaDB 写入/检索/上下文注入逻辑
- **完成判定**：上传文档后对话能检索到相关知识片段并注入 prompt

---

## 批次 B5：集成测试 + 错误处理 + 启动脚本

### Task 5.1：端到端集成测试

- **修改目标**：编写完整链路集成测试：创建租户 → 配置员工 → 上传知识库 → 对话
- **涉及文件**：
  - `backend/tests/test_integration.py`
- **验证方式**：运行集成测试（mock LLM Provider），验证全链路数据流正确
- **完成判定**：集成测试全部通过

### Task 5.2：统一错误处理 + 安全加固

- **修改目标**：
  - 全局异常处理器（Provider 错误、数据库错误、校验错误）
  - 租户隔离校验（所有查询强制 tenant_id 过滤）
  - 输入限制（文件大小、消息长度、速率限制）
- **涉及文件**：
  - `backend/app/middleware/tenant.py` — 租户隔离中间件实现
  - `backend/app/main.py` — 注册异常处理器
  - `backend/app/api/deps.py` — 租户上下文注入
  - `backend/tests/test_tenants.py` — 补充越权测试
- **验证方式**：TDD — 验证租户 A 无法访问租户 B 资源、错误返回正确状态码
- **完成判定**：安全测试通过，越权返回 403

### Task 5.3：启动脚本 + README + .env.example

- **修改目标**：提供一键启动脚本和开发文档
- **涉及文件**：
  - `backend/.env.example` — 环境变量模板
  - `scripts/dev.sh` — 一键启动脚本
  - `README.md` — 项目说明与快速开始
- **验证方式**：从零 `pip install` → 配置 `.env` → `./scripts/dev.sh` 启动成功
- **完成判定**：按 README 步骤能成功启动服务，Swagger UI 可访问

---

## 依赖关系

```
B1 ──→ B2 ──→ B3 ──→ B4 ──→ B5
        │              │
        └── Provider ──┘
```

- B2 依赖 B1（数据模型）
- B3 依赖 B2（需要 Provider 调用 LLM）
- B4 依赖 B2（需要 Provider 生成嵌入）
- B5 依赖 B1-B4（集成测试覆盖全部模块）

## 验证命令

```bash
# 单测
cd backend && uv run pytest tests/ -v

# 集成测试
cd backend && uv run pytest tests/test_integration.py -v

# Lint
cd backend && uv run ruff check app/ tests/

# Type check
cd backend && uv run mypy app/

# 启动开发服务
cd backend && uv run uvicorn app.main:app --reload --port 8000
```

## 风险与待确认项

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| ChromaDB 嵌入式版本并发性能有限 | 多租户同时上传文档可能阻塞 | MVP 阶段文档上传串行处理，V1 迁移 pgvector |
| OpenAI/通义 API 不稳定 | 对话功能不可用 | 重试 + 降级提示 |
| SSE 在测试中验证较复杂 | 测试覆盖可能不足 | 使用 TestClient 的 stream 模式 + 事件格式断言 |
| SQLite 写并发锁 | 多并发写入可能超时 | MVP 阶段 WAL 模式缓解，V1 迁移 PostgreSQL |