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>
This commit is contained in:
root
parent
5c13f08c03
commit
a8e3ad8e16
248
docs/plans/2026-05-05-digital-employee-plan.md
Normal file
248
docs/plans/2026-05-05-digital-employee-plan.md
Normal file
@ -0,0 +1,248 @@
|
|||||||
|
# 数字员工平台实施计划
|
||||||
|
|
||||||
|
> 日期：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 |
|
||||||
@ -39,6 +39,12 @@
|
|||||||
- P2：用量统计/计费、权限控制
|
- P2：用量统计/计费、权限控制
|
||||||
- P3：对话质量评估、模板市场、多渠道接入、审批工作流、审计日志
|
- P3：对话质量评估、模板市场、多渠道接入、审批工作流、审计日志
|
||||||
|
|
||||||
|
## 计划
|
||||||
|
|
||||||
|
- 实施计划已生成：docs/plans/2026-05-05-digital-employee-plan.md
|
||||||
|
- 5 批次 15 个任务：B1 脚手架+模型+租户 → B2 员工+Provider → B3 对话SSE → B4 RAG → B5 集成+安全
|
||||||
|
- 每任务严格 TDD（RED/GREEN/REFACTOR），单步 2-5 分钟粒度
|
||||||
|
|
||||||
## 问题与修复
|
## 问题与修复
|
||||||
|
|
||||||
（暂无）
|
（暂无）
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user