diff --git a/docs/plans/2026-05-05-digital-employee-plan.md b/docs/plans/2026-05-05-digital-employee-plan.md new file mode 100644 index 0000000..6f8b90c --- /dev/null +++ b/docs/plans/2026-05-05-digital-employee-plan.md @@ -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 | diff --git a/memory/2026-05-05.md b/memory/2026-05-05.md index 504bc0e..accbbb9 100644 --- a/memory/2026-05-05.md +++ b/memory/2026-05-05.md @@ -39,6 +39,12 @@ - P2：用量统计/计费、权限控制 - 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 分钟粒度 + ## 问题与修复 （暂无）