zhaojie
11eef49271
- 新增 .agents/summary/ 完整文档（架构、组件、接口、数据模型、流程、依赖） - 新增 AGENTS.md（AI 助手导航） - 更新 README.md - 修复 dashboard.html 租户模态框多余 </div> 导致保存按钮失效 - 更新 .gitignore 排除虚拟环境文件
105 lines
3.4 KiB
Markdown
105 lines
3.4 KiB
Markdown
# 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` | 响应缓存 |
|