# Interfaces / 接口与集成

## REST API 概览

所有 API 以 `/api/` 为前缀，返回 JSON。认证通过 Flask session 或 JWT。

### 工单 (workorders)
| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/workorders` | 工单列表（分页） |
| POST | `/api/workorders` | 创建工单 |
| GET | `/api/workorders/<id>` | 工单详情 |
| PUT | `/api/workorders/<id>` | 更新工单 |
| DELETE | `/api/workorders/<id>` | 删除工单 |
| POST | `/api/workorders/ai-suggestion` | 生成 AI 建议 |
| POST | `/api/workorders/import` | 批量导入 |

### 知识库 (knowledge)
| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/knowledge` | 知识条目列表 |
| POST | `/api/knowledge` | 添加条目 |
| GET | `/api/knowledge/search` | 搜索知识库 |
| GET | `/api/knowledge/stats` | 统计信息 |
| POST | `/api/knowledge/upload` | 文件导入 |
| PUT | `/api/knowledge/<id>/verify` | 验证条目 |

### 对话 (chat / conversations)
| Method | Path | 说明 |
|--------|------|------|
| POST | `/api/chat/sessions` | 创建会话 |
| GET | `/api/chat/sessions` | 活跃会话列表 |
| POST | `/api/chat/message` | 发送消息 |
| POST | `/api/chat/message/stream` | 流式消息 (SSE) |
| GET | `/api/conversations` | 对话历史 |

### 租户 (tenants)
| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/tenants` | 租户列表 |
| POST | `/api/tenants` | 创建租户 |
| PUT | `/api/tenants/<id>` | 更新租户 |
| DELETE | `/api/tenants/<id>` | 删除租户 |
| GET | `/api/tenants/feishu-groups` | 飞书群列表 |

### 认证 (auth)
| Method | Path | 说明 |
|--------|------|------|
| POST | `/api/auth/login` | 登录 |
| POST | `/api/auth/logout` | 登出 |
| GET | `/api/auth/status` | 认证状态 |
| POST | `/api/auth/register` | 注册 |

### Agent
| Method | Path | 说明 |
|--------|------|------|
| POST | `/api/agent/chat` | Agent 对话 |
| GET | `/api/agent/status` | Agent 状态 |
| POST | `/api/agent/tools/execute` | 执行工具 |

### 飞书同步 (feishu-sync)
| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/feishu-sync/status` | 同步状态 |
| POST | `/api/feishu-sync/from-feishu` | 从飞书拉取 |
| POST | `/api/feishu-sync/<id>/to-feishu` | 推送到飞书 |
| GET/POST | `/api/feishu-sync/config` | 同步配置 |

## WebSocket 接口

- **端口**: 8765
- **协议**: JSON 消息
- **功能**: 实时聊天，客户端连接后通过 JSON 消息与 RealtimeChatManager 交互

## 外部集成

```mermaid
sequenceDiagram
    participant User as 用户
    participant Feishu as 飞书
    participant LongConn as 飞书长连接服务
    participant DM as DialogueManager
    participant LLM as Qwen API
    participant KB as KnowledgeManager

    User->>Feishu: 发送消息
    Feishu->>LongConn: 事件推送
    LongConn->>DM: 处理消息
    DM->>KB: 知识库检索
    KB-->>DM: 相关知识
    DM->>LLM: 生成回复
    LLM-->>DM: AI 回复
    DM->>Feishu: 回复消息
```

## 装饰器接口

| 装饰器 | 位置 | 功能 |
|--------|------|------|
| `@handle_errors` | `decorators.py` | 统一异常捕获，返回标准错误响应 |
| `@require_json(fields)` | `decorators.py` | 验证请求体为 JSON 且包含必填字段 |
| `@with_service(name)` | `decorators.py` | 从 ServiceManager 注入服务实例 |
| `@rate_limit(max, period)` | `decorators.py` | 基于 IP 的频率限制 |
| `@cache_response(timeout)` | `decorators.py` | 响应缓存 |