backend/.antigravity/BASELINE.md

Project Baseline: AI-Native CRM (Backend)

🏗️ 全局架构 (Global Architecture)

本项目是一个 AI 原生 (AI-Native) CRM 系统的后端。

• 核心理念：摆脱传统的 REST API 增删改查动作，所有的业务模块定义和数据变更都通过 AI Agent 调用 Tool 实现。
• 技术栈：JDK 19 + Spring Boot 3.2.4 + PostgreSQL。
• 关键组件：
  • CrmTools.java: 系统的“消息枢纽”，包含所有 @Tool 方法（Define, Save, Delete），直接与 Repository 交互。
  • AgentController.java: 主要入口，负责处理自然语言指令或业务事实报告。
  • CopilotKitController.java: 新增，充当 CopilotKit 的后端运行时，统一通过 LangChain4j 调用 AI。
  • 业务模块共享：移除了 /api/entities 的 creatorId 过滤，所有用户可共享业务实体定义 (Schema)，但业务数据记录目前仍保留隔离。

💼 业务逻辑 (Business Logic)

• 动态模块：系统支持通过 AI 指令动态创建业务实体（Entities），并在数据库中自动维护。
• AI 优先变更：禁用了传统的 CRUD REST 接口，强制所有数据变更流经 AI 逻辑，以保证业务意图的记录。

📈 当前开发进度 (Current Progress)

• AI 原生 CRUD：已实现 Agent 驱动的插入、更新和删除。
• 实体关联：支持通过 x-link-entity 扩展 Schema 实现实体间关联选择。
• 用户会话隔离：已完成后端拦截与过滤逻辑。
• CopilotKit 后端转发：已实现 AI 交互的后端中转，提升了安全性。
• CORS 配置：已解决前后端跨域通信问题。
• CopilotKit v1 协议适配: 修复了由于后端控制器 DTO 结构不匹配导致的 Runtime 协议消息解析异常（messages 嵌套在 body 中）。
• Bug Fix: 修复了 CopilotKitController 处理空请求时的 NullPointerException。
• 接口扩充: 新增了 /api/copilotkit/info 发现接口，以适配前端 CopilotKit 库的启动流程。
• 流式配置修复: 修复了 CrmAgent 在处理流式请求时因缺失 StreamingChatLanguageModel 导致的 IllegalArgumentException。
• 流式协议修正: 将 ResponseBodyEmitter 恢复为 SseEmitter。并在流开始时强制发送 threadId 和 runId 初始事件，确保前端 @copilotkit/core 能正确挂载响应流。同时移除了末尾冗余的 result 类型消息以避免解析冲突。
• 流式数据格式修正: 修复了由于 SseEmitter 自动追加 data: 前缀导致前端 @copilotkit/runtime 无法解析流的问题，将实现替换为 ResponseBodyEmitter 结合手动追加 \n 的 NDJSON（换行分隔 JSON）格式。
• Runtime Info 修复: 修复了 /api/copilotkit/info 的响应结构，将 agents 从列表改为 Map (Object)，并显式声明了 default agent。

⚠️ 尚未解决的隐患 (Known Issues/Risks)

• 共享冲突：当多用户同时修改同一个公共实体的 Schema 时，可能产生覆盖风险。
• 权限细化：目前的 X-Creator-Id 仅做基础隔离，缺乏细粒度的 RBAC。

🚀 下一步计划 (Next Steps)

1. 数据共享开关：支持针对特定实体配置是否跨用户共享数据。
2. AI 增强搜索：实现通过 AI 生成复杂查询逻辑。
3. 仪表盘分析：开发动态数据的 AI 汇总分析模块。

---

Last Updated: 2026-03-25 by Antigravity