nobody/digital-employee-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
digital-employee-platform/docs/plans/2026-05-05-digital-employee-plan.md
root a8e3ad8e16 docs: add implementation plan for digital employee platform 
5 batches, 15 tasks: scaffold→models→tenants→employees→providers→
conversation SSE→RAG pipeline→integration tests+security hardening.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-05 09:50:50 +08:00

249 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 数字员工平台实施计划
> 日期：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 |
Reference in New Issue View Git Blame Copy Permalink