Skip to content

Commit 8aa25ea

Browse files
Copilothotlong
andcommitted
Update architecture and terminology docs with latest protocol classification
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent bfa7bd7 commit 8aa25ea

File tree

4 files changed

+422
-156
lines changed

4 files changed

+422
-156
lines changed
Lines changed: 146 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,185 @@
11
---
22
title: 架构
3-
description: 理解 ObjectStack 三位一体。ObjectQL、ObjectOS 和 ObjectUI 如何协作构建企业内核
3+
description: 理解 ObjectStack 协议架构。11 个协议命名空间如何协作构建企业内核
44
---
55

6-
import { Layers, Database, Layout, ShieldCheck } from 'lucide-react';
6+
import { Layers, Database, Layout, ShieldCheck, Lock, Cog, Brain, Cloud, Zap } from 'lucide-react';
77

8-
ObjectStack 不是一个单体框架。它是围绕**分层架构**设计的可组合生态系统。我们称之为 **"ObjectStack 三位一体"。**
8+
ObjectStack 不是一个单体框架。它是围绕**协议驱动架构**设计的可组合生态系统。系统被组织成 **11 个协议命名空间**,每个命名空间负责特定的领域。
99

10-
每一层都是解耦的,并通过标准 JSON 协议进行通信。这允许你替换实现(例如,将 React 渲染器替换为 Flutter 渲染器),而不会破坏堆栈的其余部分。
10+
每个协议都是解耦的,并通过使用 Zod 定义的标准 JSON schema 进行通信。这允许你替换实现(例如,将 Postgres 驱动替换为 MongoDB,或将 React 渲染器替换为 Flutter),而不会破坏堆栈的其余部分。
11+
12+
## 协议概览
13+
14+
ObjectStack 组织成 11 个协议命名空间:
1115

1216
<Cards>
1317
<Card
1418
icon={<Database />}
15-
title="数据层(ObjectQL)"
16-
description="用于定义和访问的通用协议。"
19+
title="数据协议(Data Protocol)"
20+
description="对象 schema、字段、验证和查询。"
21+
/>
22+
<Card
23+
icon={<Cog />}
24+
title="驱动协议(Driver Protocol)"
25+
description="数据库适配器(Postgres、MongoDB、SQLite 等)。"
1726
/>
1827
<Card
1928
icon={<ShieldCheck />}
20-
title="控制层(ObjectOS"
21-
description="用于编排和治理的业务内核"
29+
title="权限协议(Permission Protocol"
30+
description="对象级、字段级、共享和区域规则"
2231
/>
2332
<Card
2433
icon={<Layout />}
25-
title="视图层(ObjectUI)"
26-
description="用于交互和渲染的投影引擎。"
34+
title="UI 协议(UI Protocol)"
35+
description="应用、视图、仪表板、报表和主题。"
36+
/>
37+
<Card
38+
icon={<Layers />}
39+
title="系统协议(System Protocol)"
40+
description="事件、作业、翻译和审计日志。"
41+
/>
42+
<Card
43+
icon={<Lock />}
44+
title="认证协议(Auth Protocol)"
45+
description="身份、角色、会话和认证策略。"
46+
/>
47+
<Card
48+
icon={<Cog />}
49+
title="内核协议(Kernel Protocol)"
50+
description="插件生命周期、清单、日志和上下文。"
51+
/>
52+
<Card
53+
icon={<Cloud />}
54+
title="Hub 协议(Hub Protocol)"
55+
description="市场、许可、租户和部署。"
56+
/>
57+
<Card
58+
icon={<Brain />}
59+
title="AI 协议(AI Protocol)"
60+
description="AI 代理、RAG、NLQ、预测模型和编排。"
61+
/>
62+
<Card
63+
icon={<Zap />}
64+
title="API 协议(API Protocol)"
65+
description="REST 契约、发现、实时和路由。"
66+
/>
67+
<Card
68+
icon={<Zap />}
69+
title="自动化协议(Automation Protocol)"
70+
description="工作流、流程和 Webhook。"
2771
/>
2872
</Cards>
2973

30-
## 三位一体
74+
## 三层架构
75+
76+
虽然 ObjectStack 有 11 个协议命名空间,但它们在逻辑上被分组为三个架构层:
77+
78+
### 1. 数据层(ObjectQL)
79+
**"通用数据协议"**
80+
81+
负责**数据定义****数据访问**的基础层。
3182

32-
### 1. 数据层:ObjectQL
33-
**"通用协议"**
83+
**协议:**
84+
* **数据协议:** 对象 schema、字段、验证、查询、过滤器
85+
* **驱动协议:** 用于 Postgres、MongoDB、SQLite 等的数据库适配器
86+
* **权限协议:** 对象级 CRUD、字段级安全、共享规则
87+
* **AI 协议:** AI 代理、RAG 管道、NLQ、预测模型
3488

35-
基础是 ObjectQL。它负责**数据定义****数据访问**
89+
**角色:** 定义*结构*(Schema)和*意图*(查询 AST)
3690

37-
* **角色:** 定义*结构*(Schema)和*意图*(查询 AST)。
38-
* **职责:** 它知道*什么是* "客户" 对象,但它不知道**正在访问它或*如何*显示它。
39-
* **关键组件:** **编译器**。它接受抽象查询(`find customers where active = true`)并将其转换为特定底层数据库(Postgres、SQLite、MySQL)的优化 SQL。
91+
**职责:** 它知道*什么是* "客户" 对象,但它不知道**正在访问它或*如何*显示它。
4092

41-
### 2. 控制层:ObjectOS
93+
**关键组件:** **编译器**。它接受抽象查询(`find customers where active = true`)并将其转换为特定底层数据库的优化 SQL/NoSQL 查询。
94+
95+
### 2. 控制层(ObjectOS)
4296
**"业务内核"**
4397

44-
位于中间的是 ObjectOS。它负责**编排****治理**
98+
负责**运行时****治理**的编排层。
99+
100+
**协议:**
101+
* **系统协议:** 事件、作业、翻译、审计日志
102+
* **认证协议:** 身份、角色、会话、认证策略
103+
* **内核协议:** 插件生命周期、清单、日志、上下文
104+
* **Hub 协议:** 市场、许可、多租户、部署
105+
* **自动化协议:** 工作流、流程、Webhook
106+
107+
**角色:** 管理请求的*生命周期*
108+
109+
**职责:**
110+
* **身份:** "这个用户是谁?"(身份验证)
111+
* **安全:** "他们可以看到这个字段吗?"(RBAC/ACL)
112+
* **同步:** "我们如何合并这些离线更改?"(冲突解决)
113+
* **流程:** "保存此记录后会发生什么?"(工作流/触发器)
45114

46-
* **角色:** 管理请求的*生命周期*
47-
* **职责:**
48-
* **身份:** "这个用户是谁?"(身份验证)。
49-
* **安全:** "他们可以看到这个字段吗?"(RBAC/ACL)。
50-
* **同步:** "我们如何合并这些离线更改?"(冲突解决)。
51-
* **流程:** "保存此记录后会发生什么?"(工作流/触发器)。
52-
* **关键概念:** 它充当网关。不允许直接访问数据库;所有内容都必须通过 OS 内核。
115+
**关键概念:** 它充当网关。不允许直接访问数据库;所有内容都必须通过 OS 内核。
53116

54-
### 3. 视图层ObjectUI
117+
### 3. 视图层ObjectUI
55118
**"投影引擎"**
56119

57-
顶部是 ObjectUI。它负责**交互****渲染**
120+
负责**交互****渲染**的表示层。
121+
122+
**协议:**
123+
* **UI 协议:** 应用、视图、仪表板、报表、主题、操作
124+
* **API 协议:** REST 契约、发现、实时、路由
125+
126+
**角色:** 使用协议来渲染界面。
127+
128+
**职责:** 它不包含硬编码的表单。相反,它询问数据层:*"客户的 schema 是什么?"* 并根据该元数据动态渲染布局。
58129

59-
* **角色:** 使用协议来渲染界面。
60-
* **职责:** 它不包含硬编码的表单。相反,它询问 ObjectQL:*"客户的 schema 是什么?"* 并根据该元数据动态渲染布局。
61-
* **关键概念:** **服务器驱动 UI(SDUI)**。后端规定布局、验证规则和可用操作。前端只是一个高度强大的渲染器。
130+
**关键概念:** **服务器驱动 UI(SDUI)**。后端规定布局、验证规则和可用操作。前端只是一个高度强大的渲染器。
62131

63132
---
64133

65134
## 请求生命周期
66135

67136
为了理解这些部分如何配合,让我们跟踪一个典型的用户交互——例如,销售代表在离线时更新交易状态。
68137

69-
1. **交互(ObjectUI):**
138+
1. **交互(UI 协议):**
70139
* 用户将 "Deal" 拖到看板中的 "Closed Won" 列。
71140
* UI 乐观地更新屏幕(0ms)。
72-
* UI 向本地 ObjectOS 客户端分派 `update` 操作。
73-
74-
2. **内核守卫(ObjectOS 客户端):**
75-
* 客户端内核检查:*用户是否有权编辑 'Status'?*
76-
* 内核执行通用验证:*'Status' 是否是有效选项?*
77-
* 事务提交到 SQLite(本地 DB)。
78-
79-
3. **同步(ObjectOS 同步):**
80-
* 后台进程检测 SQLite 中的更改。
81-
* 将更改压缩为**操作载荷**
82-
* 将载荷发送到服务器 API。
83-
84-
4. **服务器执行(ObjectOS 服务器):**
85-
* 服务器内核验证请求。
86-
* 服务器内核运行 "更新前" 触发器(例如,检查信用额度)。
87-
* 服务器将 AST 传递给 ObjectQL 编译器。
88-
89-
5. **持久化(ObjectQL):**
90-
* 编译器为 PostgreSQL 生成 `UPDATE deals SET status = 'closed_won' ...`
91-
* 写入被提交。
92-
* "更新后" 触发器触发(向经理发送电子邮件)。
141+
* UI 向本地内核分派 `update` 操作。
142+
143+
2. **内核守卫(内核协议):**
144+
* 客户端内核通过**认证协议**检查:*用户是否有权编辑 'Status'?*
145+
* 内核执行**数据协议**验证:*'Status' 是否是有效选项?*
146+
* 通过**驱动协议**将事务提交到 SQLite(本地 DB)。
147+
148+
3. **同步(系统协议):**
149+
* 后台进程通过**系统事件**检测更改。
150+
* 根据 **API 契约**将更改压缩为**操作载荷**
151+
* 通过 **API 协议**将载荷发送到服务器 API。
152+
153+
4. **服务器执行(内核协议):**
154+
* 服务器内核通过**认证协议**验证请求。
155+
* 服务器内核运行**自动化协议**触发器(例如,检查信用额度)。
156+
* 服务器将 AST 传递给数据层编译器。
157+
158+
5. **持久化(数据 + 驱动协议):**
159+
* **驱动协议**为 PostgreSQL 生成 `UPDATE deals SET status = 'closed_won' ...`
160+
* 通过**驱动协议**提交写入。
161+
* **自动化协议**触发器触发(通过 webhook 向经理发送电子邮件)。
162+
163+
## 协议依赖关系
164+
165+
协议具有明确的依赖关系,并以结构化的方式交互:
166+
167+
```
168+
内核协议(运行时核心)
169+
├── 认证协议(身份和会话)
170+
├── 系统协议(事件、作业、审计)
171+
└── Hub 协议(租户、许可)
172+
173+
数据协议(业务逻辑)
174+
├── 驱动协议(存储适配器)
175+
├── 权限协议(访问控制)
176+
└── AI 协议(智能层)
177+
178+
UI 协议(表示层)
179+
└── API 协议(通信)
180+
181+
自动化协议(业务流程)
182+
└── 依赖于:数据、系统、API
183+
```
184+
185+
每个协议都在 `@objectstack/spec` 中使用 Zod schema 定义,可以独立验证、版本化和演进。

0 commit comments

Comments
 (0)