diff --git a/.kiro/specs/architecture-evolution/tasks.md b/.kiro/specs/architecture-evolution/tasks.md new file mode 100644 index 0000000..6a5243a --- /dev/null +++ b/.kiro/specs/architecture-evolution/tasks.md @@ -0,0 +1,88 @@ +# 架构演进任务清单 + +## 概述 + +基于两轮架构审查发现的结构性问题,按优先级排列的演进任务。每个任务独立可交付,不依赖其他任务的完成。 + +## Tasks + +- [ ] 1. 引入 Repository 层,分离数据访问逻辑 + - [ ] 1.1 创建 `src/repositories/` 目录,为核心模型创建 Repository 类 + - WorkOrderRepository: 封装工单的 CRUD + 按 tenant_id 过滤 + - KnowledgeRepository: 封装知识库的 CRUD + 按 tenant_id 过滤 + - ConversationRepository: 封装对话/会话的 CRUD + 按 tenant_id 过滤 + - AlertRepository: 封装预警的 CRUD + 按 tenant_id 过滤 + - [ ] 1.2 将 blueprint 中的直接 DB 查询迁移到 Repository + - workorders.py 的 get_workorders、create_workorder、delete_workorder + - knowledge.py 的 get_knowledge、add_knowledge、delete_knowledge + - conversations.py 的所有端点 + - alerts.py 的所有端点 + - [ ] 1.3 在 Repository 基类中统一添加 tenant_id 过滤 + - 所有查询方法自动附加 tenant_id 条件 + - 写操作自动设置 tenant_id + +- [ ] 2. 统一 LLM 客户端 + - [ ] 2.1 将 `src/agent/llm_client.py` 的异步能力合并到 `src/core/llm_client.py` + - LLMClient 同时支持同步和异步调用 + - 统一超时、重试、token 统计逻辑 + - [ ] 2.2 让 agent_assistant.py 使用统一的 LLMClient + - 删除 `src/agent/llm_client.py` 中的 LLMManager/OpenAIClient 等重复类 + - [ ] 2.3 统一 LLM 配置入口 + - 所有 LLM 调用从 unified_config 读取配置 + +- [ ] 3. 引入 MessagePipeline 统一消息处理 + - [ ] 3.1 创建 `src/dialogue/message_pipeline.py` + - 定义统一的消息处理流程:接收 → 租户解析 → 会话管理 → 知识搜索 → LLM 调用 → 保存 → 回复 + - 各入口(WebSocket、HTTP、飞书 bot、飞书长连接)只负责协议适配 + - [ ] 3.2 重构 realtime_chat.py 使用 Pipeline + - process_message 和 process_message_stream 委托给 Pipeline + - [ ] 3.3 重构飞书 bot/longconn 使用 Pipeline + - 消除 feishu_bot.py 和 feishu_longconn_service.py 中的重复逻辑 + +- [ ] 4. 引入 Alembic 数据库迁移 + - [ ] 4.1 初始化 Alembic 配置 + - alembic init, 配置 env.py 连接 unified_config + - [ ] 4.2 生成初始迁移脚本 + - 从当前 models.py 生成 baseline migration + - [ ] 4.3 移除 database.py 中的 _run_migrations 手动迁移逻辑 + - 改为启动时运行 alembic upgrade head + +- [ ] 5. 统一配置管理 + - [ ] 5.1 定义配置优先级:环境变量 > system_settings.json > 代码默认值 + - [ ] 5.2 创建 ConfigService 统一读写接口 + - get(key, default) / set(key, value) / get_section(section) + - 底层自动合并三个来源 + - [ ] 5.3 迁移 SystemOptimizer、PerformanceConfig 使用 ConfigService + +- [ ] 6. API 契约定义 + - [ ] 6.1 引入 Flask-RESTX 或 apispec 生成 OpenAPI 文档 + - [ ] 6.2 为所有 blueprint 端点添加 schema 定义 + - [ ] 6.3 统一所有端点使用 api_response() 标准格式 + +- [ ] 7. 会话状态迁移到 Redis + - [ ] 7.1 将 RealtimeChatManager.active_sessions 迁移到 Redis Hash + - [ ] 7.2 将消息去重从内存缓存迁移到 Redis SET(支持多进程) + - [ ] 7.3 支持多实例部署(无状态 Flask + 共享 Redis) + +- [ ] 8. 密码哈希升级 + - [ ] 8.1 将 SHA-256 替换为 bcrypt(pip install bcrypt) + - [ ] 8.2 兼容旧密码:登录时检测旧格式,自动升级为 bcrypt + +- [ ] 9. 前端状态管理优化 + - [ ] 9.1 引入简易事件总线(EventEmitter 模式) + - 模块间通过事件通信,不直接读写共享状态 + - [ ] 9.2 将 this.xxxCurrentTenantId 等状态封装为 Store 对象 + +- [ ] 10. 清理旧代码 + - [ ] 10.1 删除 src/web/static/js/core/ 目录(旧的未完成重构) + - [ ] 10.2 删除 src/web/static/js/services/ 目录 + - [ ] 10.3 删除 src/web/static/js/components/ 目录 + - [ ] 10.4 删除 src/web/static/js/pages/ 目录(如确认不再使用) + - [ ] 10.5 清理 index.html、chat.html、chat_http.html 中对已删除 JS 的引用 + +## Notes + +- 每个任务独立可交付,按 1 → 2 → 3 的顺序做收益最大 +- 任务 4(Alembic)可以随时做,不依赖其他任务 +- 任务 7(Redis 会话)只在需要多实例部署时才有必要 +- 任务 8(密码升级)安全性高但影响面小,可以穿插做