# 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。
    - [x] **业务模块共享**：移除了 `/api/entities` 的 `creatorId` 过滤，所有用户可共享业务实体定义 (Schema)，但业务数据记录目前仍保留隔离。

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

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