当前系统架构分析

版本: v0.5.0
日期: 2025-12-17
说明: 梳理 v0.4 系统架构与代码逻辑，为 v0.5 升级提供基线

1. 系统概览

1.1 技术栈

后端：FastAPI + SQLAlchemy + PostgreSQL + Redis + Celery
前端：React + Vite + TypeScript
版本：v0.4.0（当前）

1.2 核心架构

Core 单仓：backend/ 目录
Apps 多仓：apps/ 目录（project-mngt, os-assistant, tever-app-template）
前端：frontend/ 目录
Agent：tever-agent/ 目录（v0.4 新增）

2. 后端架构分析

2.1 目录结构（v0.4）

backend/app/
├── api/
│   ├── v1/
│   │   ├── ingest/              # v0.4 新增：/ingest/events
│   │   ├── sources/             # v0.4 新增：EventSource 管理 API
│   │   ├── schemas/             # v0.4 新增：Schema Registry API
│   │   ├── views/
│   │   ├── entities/
│   │   ├── rules/
│   │   └── ...
│   └── middleware/
├── kernel/
│   ├── entities/
│   ├── events/
│   ├── types/
│   ├── views/
│   ├── rules/
│   ├── projection/
│   ├── actions/
│   │   └── executor.py          # v0.4 已有
│   ├── audit/
│   │   └── service.py           # v0.4 已有
│   └── app_host.py
├── models/
│   ├── entity.py
│   ├── event.py                 # v0.4 扩展：EventEnvelopeV1
│   ├── event_sources.py         # v0.4 新增
│   ├── event_schemas.py         # v0.4 新增
│   ├── alerts.py                # v0.4 新增
│   ├── audit_log.py             # v0.4 已有
│   └── ...
├── app_host/
│   └── registries/
│       ├── schema_registry.py   # v0.4 新增
│       ├── rulepack_registry.py # v0.4 新增
│       └── ...
└── workers/
    ├── connectors/              # v0.4 新增：pull connectors
    └── ...

2.2 数据模型（v0.4）

Event 模型（v0.4 格式）

表名：events
字段（v0.4 扩展）：
- id (UUID)
- tenant_id (String) - v0.4 新增
- source_id (String) - v0.4 新增
- collector_id (String) - v0.4 新增
- type (String) - 事件类型
- schema_ref (String) - v0.4 新增
- severity (String) - v0.4 新增
- tags (JSONB) - v0.4 新增
- subject (JSONB) - v0.4 新增
- payload (JSONB)
- dedup_key (String) - v0.4 新增
- trace (JSONB) - v0.4 新增
- signature (JSONB) - v0.4 新增
- created_at (DateTime)

EventSource 模型（v0.4 新增）

表名：event_sources
存储 EventSource 配置

EventSchema 模型（v0.4 新增）

表名：event_schemas
存储 Event Schema（JSON Schema）

Alert 模型（v0.4 新增）

表名：alerts
存储告警对象

ToolCall 模型（v0.4 已有，v0.5 需要扩展）

表名：tool_calls
v0.4 字段：
- id, tenant_id, action_id, tool_name, input, output, status, error, created_at
v0.5 需要扩展：
- prompt_template_id (String)
- prompt_version (String)
- model_provider (String)
- model_name (String)
- model_version (String)
- context_refs (JSONB)
- input_tokens (Integer)
- output_tokens (Integer)
- total_tokens (Integer)
- output_hash (String)
- validation_passed (Boolean)
- execution_time_ms (Integer)

2.3 API 端点（v0.4）

v0.4 已有 API

POST /api/v1/ingest/events - 事件采集入口
GET /api/v1/schemas/{schemaRef} - Schema 查询
POST /api/v1/sources - EventSource 管理
GET /api/v1/query/events - 统一事件查询
GET /api/v1/query/alerts - 告警查询
GET /api/v1/query/aggregates - 聚合结果查询
GET /api/v1/query/audits - 审计记录查询
GET /api/v1/query/search - 统一检索入口

v0.5 需要新增 API

GET /api/v1/prompts/templates - 查询 Prompt 模板列表
GET /api/v1/prompts/templates/{id} - 查询 Prompt 模板详情
POST /api/v1/prompts/templates - 创建 Prompt 模板
PUT /api/v1/prompts/templates/{id} - 更新 Prompt 模板
DELETE /api/v1/prompts/templates/{id} - 删除 Prompt 模板
POST /api/v1/prompts/render - 渲染 Prompt
POST /api/v1/prompts/validate - 验证输出
POST /api/v1/llm/chat - LLM 聊天接口
POST /api/v1/llm/chat/stream - LLM 流式聊天接口（可选）
GET /api/v1/query/ai_insights - AI 洞察查询
GET /api/v1/query/document_drafts - 文档草稿查询

2.4 规则引擎（v0.4）

位置：backend/app/kernel/rules/engine.py

能力（v0.4）：

支持 on_event 触发（匹配 event_type）
支持 on_schedule 触发（定时扫描实体）
支持窗口聚合（count/avg/max）
支持告警去重与状态流转
支持 RulePack

v0.5 需要扩展：

支持 AI Actions（invoke_llm_summary、invoke_llm_report、invoke_llm_generate_doc）

2.5 App Host（v0.4）

位置：backend/app/kernel/app_host.py

能力（v0.4）：

安装 App（从路径或 ZIP）
导入 Domain Seeds（types/views/rules）
导入 EventSchemas
导入 RulePack
导入 Source Templates
启用/禁用 App
注册 Action/Tool Provider

v0.5 需要扩展：

导入 PromptPack

3. 前端架构分析

3.1 目录结构（v0.4）

frontend/src/
├── api/
│   ├── entities.ts
│   ├── events.ts
│   ├── alerts.ts              # v0.4 新增
│   ├── sources.ts             # v0.4 新增
│   └── ...
├── pages/
│   ├── AppDashboard.tsx
│   ├── AppManagement.tsx
│   ├── AuditLog.tsx
│   ├── EventStream.tsx        # v0.4 新增
│   ├── AlertInbox.tsx         # v0.4 新增
│   └── ...
└── components/
    ├── entity/
    ├── view/
    └── ...

3.2 v0.5 需要新增的页面

Prompt 管理页面（Prompt 模板列表、详情）
AI 洞察展示组件（在 Alert Detail 中展示）
文档草稿管理页面（草稿列表、详情、编辑、采纳）

4. 关键差异分析（v0.4 vs v0.5）

4.1 新增组件

组件	v0.4	v0.5
Prompt Registry	无	有
LLM Gateway	无	有
AI Actions	无	有（只读）
AI Insight 类型	无	有
Document Draft 类型	无	有

4.2 数据库变更

表	v0.4	v0.5
prompt_templates	无	新增
tool_calls	有	扩展字段

4.3 API 变更

API	v0.4	v0.5
Prompt API	无	新增
LLM API	无	新增
AI Insight 查询	无	新增
Document Draft 查询	无	新增

5. 代码依赖关系（v0.4）

5.1 Event 记录流程（v0.4）

Ingest API → Ingest Gateway → Validate/Normalize → EventBus → Event Store

5.2 规则执行流程（v0.4）

Event 写入 → RuleEngine.execute_rules_for_event() → 条件检查 → Action 执行

5.3 App 安装流程（v0.4）

App Host API → AppHost.install() → 导入 Domain Seeds → 注册 Action/Tool

5.4 v0.5 新增流程

AI Action 执行流程：

Rule 触发 → Action Executor → AI Action Handler → LLM Gateway → Context Builder → Prompt Renderer → LLM Provider → Validator → 写入草稿 → 生成事件

PromptPack 安装流程：

App Host API → AppHost.install() → 检测 PromptPack → 解析 PromptPack → 注册 Prompt 模板

6. 升级影响评估（v0.4 → v0.5）

6.1 数据库迁移

新增表：prompt_templates
扩展表：tool_calls（添加 prompt/模型/tokens 相关字段）

6.2 API 兼容性

向后兼容：v0.4 的所有 API 保持可用
新增 API：Prompt、LLM、AI Insight、Document Draft 查询

6.3 代码重构点

新增模块：Prompt Registry、LLM Gateway
扩展模块：Action Executor（支持 AI Actions）、Audit Service（扩展 tool_call 记录）
新增类型：ai_insight、document_draft

7. 当前系统优势（v0.4）

清晰的 Core/Apps 边界：v0.4 已建立良好基础
多租户隔离：已有 tenant_id 字段
规则引擎基础：已有 RuleEngine 框架，支持窗口聚合
App Host 机制：已有安装/启用/禁用能力，支持 RulePack
事件采集链路：已有 Ingest Gateway、Schema Registry、EventBus

8. 升级难点（v0.4 → v0.5）

LLM Gateway 实现：需要抽象 LLM Provider、实现限流/缓存/重试
Context Pack 组装：需要从 eventIds/alertIds/entityIds/timeRange/viewPreset 组装上下文
Prompt 模板管理：需要实现版本化、渲染、输出校验
AI Actions 约束：需要确保只读、禁止直接改实体
审计记录增强：需要扩展 tool_call 记录，包含 prompt/模型/tokens 信息

最后更新：2025-12-17