AI Native ERP - 架构设计文档

语言 / Language: 中文 · English

文档版本: 1.1
更新时间: 2026-07-09
维护者: AI Native ERP 团队

本文描述当前仓库已实现的架构，并标注部分规划能力。
想先建立产品直觉：产品理念 · 用户场景
AI 硬约束：docs/zh/ai-governance.md

架构一句话

把「会说话的入口」和「敢写库的后端」拆开：前端与 Agent 负责理解与编排，Application Service 负责真实业务，SQL Server / Qdrant 各管实时数据与知识，全程可审计。

1. 总体架构

1.1 架构图（实现视角）

┌─────────────────────────────────────────────────────────────┐
│                     用户入口层                                │
│         React Web（仪表盘 / 业务页 / AI 侧边栏 / 命令面板）      │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP / SSE + JWT
┌────────────────────────▼────────────────────────────────────┐
│                     Web API 层                                │
│   Chat / Auth / Sales / Purchase / Warehouse / Finance /     │
│   HR / Production / Approval / Knowledge / Agent Trace       │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Agent 编排层                                │
│  MeAiAgentOrchestrator → Coordinator → Domain Agents         │
│  Sales / Purchase / Inventory / Finance / HR / Production /  │
│  General → ToolGateway → Tool Handlers                       │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   AI 能力中台                                  │
│  DeepSeek LLM │ DomainClassifier │ IntentSchema │ RAG        │
│  Embedding(Ollama) │ Guardrails │ IntentReasoningEngine      │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   ERP 业务域层                                │
│  Application Services（唯一业务写库入口）                       │
│  Sales / Purchase / Inventory / Finance / HR / Production    │
│  Approval Workflow │ Audit Log                               │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                    数据底座层                                 │
│  SQL Server │ Qdrant │ Ollama Embedding │ Serilog 文件日志    │
│  （docker-compose 另含 Redis / RabbitMQ，供扩展）              │
└─────────────────────────────────────────────────────────────┘

1.2 解决方案分层

项目	职责
`AiNativeERP.Domain`	实体、枚举、领域规则
`AiNativeERP.Application`	应用服务、业务用例
`AiNativeERP.Infrastructure`	EF Core、DbContext、种子数据
`AiNativeERP.AI`	LLM、意图、RAG、Guardrails
`AiNativeERP.Agent`	编排、领域 Agent、Tool 路由、审批暂停
`AiNativeERP.WebApi`	HTTP 入口、鉴权、DTO、部分 Tool Handler 注册
`AiNativeERP.Tests`	单元测试 + 集成测试

2. 分层详细说明

2.1 用户入口层

已实现：

React 18 + Vite + Ant Design
登录、仪表盘、销售/采购/库存/财务/HR/生产页面
AI 助手页、全局 AI 侧边栏、SSE 流式对话

规划中（未作为当前运行时依赖）： 移动端、企业微信、独立 BI 驾驶舱。

2.2 Web API 层

ASP.NET Core Web API + JWT Bearer
统一响应与异常处理
Swagger：http://localhost:5195/swagger
主要 Controller：Chat、Auth、各业务域、Knowledge、Approval、Audit、AgentTrace

2.3 AI 能力中台

能力	说明	状态
LLM	DeepSeek Chat Completions	✅
意图识别	DomainClassifier → IntentSchemaRegistry → ReasoningEngine	✅
RAG	Qdrant + Ollama `nomic-embed-text`	✅
Guardrails	输入/输出/工具风险检查	✅
Embedding	Ollama	✅
NL2SQL / OCR	架构预留	⏳ 未作为主路径

原则： AI 层不直接访问业务数据库；只产出候选 Intent/Slots 或检索知识片段。

2.4 Agent 编排层

核心组件（当前实现）：

IAgentOrchestrator (MeAiAgentOrchestrator)
    ↓
IntentReasoningEngine（Domain → Intent，歧义则 Clarify）
    ↓
域直达 Tool 或 Coordinator（MeAiCoordinatorRunner）
    ↓
Domain Agents（Sales/Purchase/Inventory/Finance/HR/Production/General）
    ↓
ToolGateway → Tool Handlers → Application Services
    ↓
Human Approval（高风险写操作）
    ↓
Audit + Agent Trace / Events

执行流程：

用户请求
  → ChatController
  → Guardrails 输入检查
  → 意图推理（先 Domain 后 Intent）
  → 需要澄清则返回 Clarify
  → 可直达则走 Tool；否则 Coordinator 委派领域 Agent
  → 权限 / 业务规则 / 审计
  → Application Service
  → （写）草稿 → 确认 → 执行
  → Guardrails 输出检查
  → 结构化回复 + Trace

2.5 ERP 业务域层

业务域	示例能力	应用服务线索
销售	订单、客户、报价、趋势	`SalesService`
采购	供应商、采购订单	`PurchaseServices`
库存/仓储	现存量、出入库、预警	`WarehouseServices` / `IInventoryService`
财务	发票、费用、收付款	`FinanceServices`
HR	员工、考勤、薪资	`HumanResourceServices`
生产	BOM、生产订单	`ProductionServices`
审批	待办、通过、驳回	Approval 相关服务
知识	制度/流程检索	RAG + Knowledge API

写操作要求： 权限、业务规则、审计、必要时审批、幂等与事务。

2.6 数据底座

类型	技术	用途	运行必需
关系库	SQL Server	业务数据、权限、审计	✅
向量库	Qdrant	知识/意图相关向量	AI 知识库 ✅
Embedding	Ollama	文本向量化	AI 知识库 ✅
日志	Serilog	应用 / LLM / Tool / 审计	✅
缓存	Redis	docker-compose 预置	扩展
消息队列	RabbitMQ	docker-compose 预置	扩展

3. 关键设计模式

3.1 Tool Calling

Tool 定义包含名称、描述、权限、风险等级、是否需人工审批
执行结果标准化：success / toolName / traceId / data / message
禁止 execute_sql、query_any_table 等万能工具

详见 docs/zh/tools.md。

3.2 Guardrails

输入：Prompt 注入、敏感数据
工具：风险评分，超阈值进入审批
输出：内容安全

3.3 Domain → Intent → Schema

自然语言
  → DomainClassifier
  → IntentSchemaRegistry.Resolve
  → SlotExtractor / Resolver（后端定夺最终参数）
  → Tool 或 Clarify

规则详见 docs/zh/intent-domain-rules.md。

3.4 Human-in-the-Loop

写操作 Tool
  → 生成草稿
  → 返回待确认结果
  → 用户确认
  → 正式执行 + 审计

4. 数据流示例

场景：用户询问「帮我分析一下本月销售额」

1. ChatController 接收消息
2. Guardrails 检查输入
3. DomainClassifier → Sales
4. IntentSchema → sales.trend.analyze / sales.report.query
5. Agent 调用 analyze_sales_trend / query_sales_report
6. Application Service 查 SQL Server
7. LLM 组织分析叙述（可选）
8. Guardrails 检查输出
9. 返回结构化结果 + Trace

场景：用户询问「销售部有多少员工」

1. DomainClassifier → HR（不是 Sales）
2. IntentSchema → hr.employee.query
3. query_employee → HumanResourceServices
4. 返回员工统计/列表

场景：用户询问「采购流程怎么操作」

1. DomainClassifier → Knowledge
2. query_knowledge（仅 knowledge_article 池）
3. Qdrant 检索制度/流程正文
4. 返回结构化知识说明

5. 安全设计

Layer 1: JWT 认证
Layer 2: 角色 / API 权限
Layer 3: 数据范围 / 租户上下文
Layer 4: Guardrails 输入
Layer 5: Tool Permission
Layer 6: Human-in-the-loop（高风险）
Layer 7: Guardrails 输出
Layer 8: 审计日志 + Agent Trace

风险等级	示例	要求
Low	查询	权限 + 审计
Medium	创建草稿	权限 + 确认 + 审计
High	下单 / 审批	权限 + 审批 + 审计
Critical	付款 / 删除	多级审批 + 完整审计

6. 扩展性

6.1 模型

通过 ILlmService 抽象；当前默认 DeepSeek。路线图包含 OpenAI / Azure / 本地模型适配。

6.2 向量库

通过向量库抽象对接 Qdrant；可扩展 Milvus / pgvector 等。

6.3 MCP（路线图）

MCP Server 只能转发到 ToolGateway，不能直连数据库，也不能绕过权限与审计。

7. 可观测性

Serilog 文件日志（应用 / LLM / Tool / 审计）
Agent Trace API
Agent Event 总线
会话历史

建议关注指标：API 延迟、LLM 成功率、Tool 成功率、意图准确率、Token / 成本。

8. 相关文档

文档	说明
README.md	快速开始
docs/zh/ai-governance.md	AI 治理硬约束
docs/zh/intent-domain-rules.md	域/意图规则
docs/zh/tools.md	Tool 清单
docs/zh/api-overview.md	API 概览
ARCHITECTURE.en.md	English version

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History