Skip to content

Commit b536010

Browse files
Copilothotlong
andcommitted
Add Chinese translations for specifications meta files and key architecture docs
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 96a718d commit b536010

7 files changed

Lines changed: 193 additions & 0 deletions

File tree

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: 编译器架构
3+
description: ObjectQL 的高级架构。数据库编译器如何将声明性意图转换为物理执行。
4+
---
5+
6+
import { Database, FileJson, ServerCog, ArrowRight } from 'lucide-react';
7+
8+
**ObjectQL** 决定数据层的行为。它被设计为一个**编译器**,将通用 JSON 中间表示(IR)转换为特定数据库的指令(SQL、NoSQL 等)。
9+
10+
## 架构管道
11+
12+
ObjectStack 数据引擎在四个不同的阶段运行。这种关注点分离使系统能够在保持原生性能的同时与数据库无关。
13+
14+
### 1. 定义阶段(Schema)
15+
**输入:** YAML/JSON Schema 文件(`*.object.yml`
16+
**角色:** 定义数据的"形状"和"规则"。
17+
**产物:**
18+
* **对象定义:** 表/集合。
19+
* **字段定义:** 列/属性。
20+
* **验证规则:** 完整性约束。
21+
22+
### 2. 组合阶段(AST)
23+
**输入:** API 请求 / SDK 调用
24+
**角色:** 将传入的意图解析为规范化的**抽象语法树(AST)**
25+
**关键操作:**
26+
* **验证:** 确保查询与 Schema 匹配。
27+
* **权限注入:** 基于 ACL 自动添加过滤器(例如,`AND owner = 'me'`)。
28+
* **规范化:** 将语法糖转换为严格的逻辑表达式。
29+
30+
### 3. 编译阶段(驱动程序)
31+
**输入:** 规范化查询 AST
32+
**角色:** 底层**驱动程序**(Postgres、SQLite、Mongo)接收 AST 并将其编译为数据库的原生语言。
33+
**示例:**
34+
* *Postgres 驱动程序:* `SELECT * FROM accounts WHERE type = 'customer'`
35+
* *Mongo 驱动程序:* `db.accounts.find({ type: 'customer' })`
36+
37+
### 4. 执行阶段(结果)
38+
**输入:** 原生游标
39+
**角色:** 执行物理查询并将输出格式化回标准 JSON 协议。
40+
41+
---
42+
43+
## 协议三位一体
44+
45+
ObjectQL 由三个核心规范组成:
46+
47+
| 规范 | 范围 | 职责 |
48+
| :--- | :--- | :--- |
49+
| **[Schema 定义](./schema-definition)** | 静态 | 如何定义对象、字段和关系。 |
50+
| **[AST 结构](./ast-structure)** | 运行时 | JSON 查询对象("IR")的结构。 |
51+
| **[传输协议](./wire-protocol)** | 传输 | 客户端和服务器如何通过 HTTP 交换这些结构。 |
52+
53+
## 设计约束
54+
55+
为了维护"一次编写,随处运行"的承诺,ObjectQL 强制执行以下约束:
56+
57+
1. **无泄漏抽象:** 你不能执行原始 SQL 字符串。所有访问都必须通过 AST。
58+
2. **幂等 Schema:** 应用两次 Schema 定义必须产生相同的数据库状态。
59+
3. **原子事务:** 所有变更操作(插入/更新/删除)默认必须是事务性的。
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"title": "ObjectQL",
3+
"pages": [
4+
"architecture",
5+
"schema-definition",
6+
"advanced-types",
7+
"ast-structure",
8+
"analytics-protocol",
9+
"transaction-model",
10+
"wire-protocol"
11+
]
12+
}
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"title": "规范",
3+
"root": true,
4+
"pages": [
5+
"data",
6+
"ui",
7+
"server"
8+
]
9+
}
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: 内核架构
3+
description: ObjectOS 内核的设计。用于身份、安全和同步的集中式引擎。
4+
---
5+
6+
import { Cpu, ShieldCheck, RefreshCw, Zap } from 'lucide-react';
7+
8+
**ObjectOS** 是堆栈的"操作系统"。ObjectQL 处理*数据*,而 ObjectOS 处理*控制*
9+
10+
它充当位于 API 和数据库驱动程序之间的中间件内核,确保每次数据访问都经过身份验证、授权并符合业务规则。
11+
12+
## 内核层
13+
14+
### 1. 身份层(谁?)
15+
在任何逻辑运行之前,内核解析行为者。
16+
* **身份验证:** OIDC、SAML 或 LDAP。
17+
* **会话管理:** 无状态 JWT 或会话存储。
18+
* **上下文注入:**`userId``role``organization` 加载到请求上下文中。
19+
20+
### 2. 策略层(他们可以吗?)
21+
内核强制执行**"纵深防御"**安全模型。
22+
* **配置文件检查:** 此用户是否有使用此应用的许可证?
23+
* **对象权限:** 他们可以 `READ` `Contract` 对象吗?
24+
* **字段级安全(FLS):** 他们可以看到 `contract_value` 吗?
25+
* **共享规则:** 他们可以访问*此特定记录*吗?
26+
27+
### 3. 逻辑层(会发生什么?)
28+
这是"业务逻辑"容器。
29+
* **触发器:** 同步逻辑(`beforeInsert`)。
30+
* **流程:** 可视化编排(`审批流程`)。
31+
* **作业:** 异步任务(`发送电子邮件`)。
32+
33+
### 4. 同步层(它在哪里?)
34+
ObjectOS 设计为**本地优先**操作。
35+
* **变更数据捕获(CDC):** 跟踪每个事务的"增量"。
36+
* **复制:** 将这些增量同步到边缘设备(SQLite)或数据仓库(Snowflake)。
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"title": "ObjectOS",
3+
"pages": [
4+
"kernel-architecture",
5+
"permission-governance",
6+
"workflow-engine",
7+
"automation-rules",
8+
"audit-compliance",
9+
"integration-etl",
10+
"plugin-manifest"
11+
]
12+
}
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"title": "ObjectUI",
3+
"pages": [
4+
"sdui-protocol",
5+
"component-schema",
6+
"view-protocol",
7+
"layout-system",
8+
"action-triggers",
9+
"report-template"
10+
]
11+
}
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: SDUI 协议
3+
description: 服务器驱动 UI 架构。ObjectStack 如何将"界面作为数据"来实现无限定制。
4+
---
5+
6+
import { LayoutTemplate, Layers, Blocks, Smartphone } from 'lucide-react';
7+
8+
**ObjectUI** 是视图层规范。它建立在**服务器驱动 UI(SDUI)**的原则之上。
9+
10+
在传统的前端中,布局在 React/Vue 组件中硬编码(`<CustomerForm />`)。
11+
在 ObjectStack 中,前端是一个通用**渲染器**。它从服务器下载 JSON 布局定义并即时绘制。
12+
13+
## UI 管道
14+
15+
### 1. 布局请求
16+
客户端询问:*"给我编辑发票 #1024 的表单"*
17+
```http
18+
GET /api/v4/ui/layouts/invoice/edit
19+
```
20+
21+
### 2. 解析引擎
22+
服务器提供布局,合并三层定制:
23+
1. **基础协议:**`invoice.object.yml` 中定义的默认字段。
24+
2. **管理员配置:** 通过页面构建器添加的自定义部分和字段。
25+
3. **用户偏好:** 用户个性化的列宽和隐藏字段。
26+
27+
### 3. 布局 JSON(响应)
28+
服务器响应组件树描述,而不是 HTML。
29+
```json
30+
{
31+
"type": "page",
32+
"layout": "two_column",
33+
"regions": {
34+
"main": [
35+
{ "type": "field_group", "label": "Basics", "children": ["name", "date"] },
36+
{ "type": "related_list", "object": "invoice_line", "label": "Line Items" }
37+
],
38+
"sidebar": [
39+
{ "type": "widget", "component": "approval_history" }
40+
]
41+
}
42+
}
43+
```
44+
45+
### 4. 渲染器(客户端)
46+
通用 `PageRenderer` 组件遍历此 JSON 并实例化映射的组件(`FieldGroup``RelatedList``Widget`)。
47+
48+
---
49+
50+
## 为什么选择 SDUI?
51+
52+
1. **即时更新:** 在 Schema 中更改字段标签或移动部分,每个用户(Web、移动、外部门户)都会立即看到它,无需应用更新。
53+
2. **平台原生:** 相同的 JSON 可以在 React 中渲染为 DOM 节点,在 SwiftUI/Kotlin 中渲染为原生视图,或在 TUI 中渲染为命令行。
54+
3. **个性化:** 因为布局是按请求生成的,我们可以根据用户的角色或记录的状态隐藏整个部分(例如,如果状态为"草稿",则隐藏"批准"按钮)。

0 commit comments

Comments
 (0)