Skip to content

Commit 96a718d

Browse files
Copilothotlong
Copilot
and
hotlong
committed
Add Chinese translations for concepts section
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent a9b8382 commit 96a718d

6 files changed

Lines changed: 536 additions & 0 deletions

File tree

‎content/docs/concepts/ai-codex.cn.mdx‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: AI 代码手册
3+
description: 如何与人工智能协作构建 ObjectStack 应用程序。
4+
---
5+
6+
import { Bot, Terminal, FileJson, Sparkles } from 'lucide-react';
7+
8+
ObjectStack 设计为 **AI 原生**。
9+
10+
因为我们的基本构建单元是**协议（JSON/YAML Schema）**而不是命令式代码，所以大型语言模型（LLM）在理解和生成 ObjectStack 应用程序方面表现出色。
11+
12+
本指南为使用 Copilot、ChatGPT 或 Claude 构建 ObjectStack 应用程序的开发人员提供"系统提示"心智模型。
13+
14+
## 为什么 ObjectStack 对 AI 友好
15+
16+
| 功能 | 代码优先支持 | ObjectStack 支持 |
17+
| :--- | :--- | :--- |
18+
| **上下文窗口** | 低。需要阅读数千行 TS/SQL。 | 高。Schema 密集且声明性。 |
19+
| **幻觉** | 高。AI 发明不存在的 API。 | 低。Schema 验证（Zod）拒绝无效输出。 |
20+
| **重构** | 困难。需要重写详细逻辑。 | 简单。只需更改 JSON 属性键。 |
21+
22+
## "首席协议架构师"角色
23+
24+
当提示 AI 帮助你构建时，为其分配**首席协议架构师**的角色。
25+
26+
### 系统提示
27+
28+
将此复制到你的自定义说明中：
29+
30+
```markdown
31+
你是一位专家 ObjectStack 架构师。
32+
你的目标是设计声明性协议，而不是命令式代码。
33+
34+
1. **Schema 优先：** 始终从定义 ObjectQL Schema（YAML/JSON）开始。
35+
2. **文件**：当被要求提供功能时，输出相关的 `.object.yml` 或 `.view.yml` 文件。
36+
3. **不要 SQL/React：** 除非明确要求驱动程序或渲染器实现，否则不要编写 SQL 查询或 React 组件。
37+
4. **样式：** 对机器名称使用 `snake_case`，对配置键使用 `camelCase`。
38+
```
39+
40+
## 常见任务
41+
42+
### 1. 从需求生成 Schema
43+
44+
**用户：** "我需要一个 CRM 系统来跟踪潜在客户和机会。"
45+
46+
**AI 响应：**
47+
```yaml
48+
# objects/lead.yml
49+
name: lead
50+
fields:
51+
status:
52+
type: select
53+
options: ['new', 'contacted', 'qualified']
54+
annual_revenue:
55+
type: currency
56+
scale: 2
57+
58+
# objects/opportunity.yml
59+
name: opportunity
60+
fields:
61+
lead_id:
62+
type: lookup
63+
reference_to: lead
64+
```
65+
66+
### 2. 生成 UI 布局
67+
68+
**用户：** "为销售经理创建一个仪表板。"
69+
70+
**AI 响应：**
71+
```yaml
72+
# dashboards/sales_overview.yml
73+
layout: grid
74+
widgets:
75+
- type: chart
76+
title: "按月收入"
77+
query: "select sum(amount), month(close_date) from opportunity group by month"
78+
- type: list
79+
object: opportunity
80+
filter: [["stage", "=", "closed_won"]]
81+
```

‎content/docs/concepts/architecture.cn.mdx‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: 架构
3+
description: 理解 ObjectStack 三位一体。ObjectQL、ObjectOS 和 ObjectUI 如何协作构建企业内核。
4+
---
5+
6+
import { Layers, Database, Layout, ShieldCheck } from 'lucide-react';
7+
8+
ObjectStack 不是一个单体框架。它是围绕**分层架构**设计的可组合生态系统。我们称之为 **"ObjectStack 三位一体"。**
9+
10+
每一层都是解耦的，并通过标准 JSON 协议进行通信。这允许你替换实现（例如，将 React 渲染器替换为 Flutter 渲染器），而不会破坏堆栈的其余部分。
11+
12+
<Cards>
13+
<Card
14+
icon={<Database />}
15+
title="数据层（ObjectQL）"
16+
description="用于定义和访问的通用协议。"
17+
/>
18+
<Card
19+
icon={<ShieldCheck />}
20+
title="控制层（ObjectOS）"
21+
description="用于编排和治理的业务内核。"
22+
/>
23+
<Card
24+
icon={<Layout />}
25+
title="视图层（ObjectUI）"
26+
description="用于交互和渲染的投影引擎。"
27+
/>
28+
</Cards>
29+
30+
## 三位一体
31+
32+
### 1. 数据层：ObjectQL
33+
**"通用协议"**
34+
35+
基础是 ObjectQL。它负责**数据定义**和**数据访问**。
36+
37+
* **角色：** 定义*结构*（Schema）和*意图*（查询 AST）。
38+
* **职责：** 它知道*什么是* "客户" 对象，但它不知道*谁*正在访问它或*如何*显示它。
39+
* **关键组件：** **编译器**。它接受抽象查询（`find customers where active = true`）并将其转换为特定底层数据库（Postgres、SQLite、MySQL）的优化 SQL。
40+
41+
### 2. 控制层：ObjectOS
42+
**"业务内核"**
43+
44+
位于中间的是 ObjectOS。它负责**编排**和**治理**。
45+
46+
* **角色：** 管理请求的*生命周期*。
47+
* **职责：**
48+
* **身份：** "这个用户是谁？"（身份验证）。
49+
* **安全：** "他们可以看到这个字段吗？"（RBAC/ACL）。
50+
* **同步：** "我们如何合并这些离线更改？"（冲突解决）。
51+
* **流程：** "保存此记录后会发生什么？"（工作流/触发器）。
52+
* **关键概念：** 它充当网关。不允许直接访问数据库；所有内容都必须通过 OS 内核。
53+
54+
### 3. 视图层：ObjectUI
55+
**"投影引擎"**
56+
57+
顶部是 ObjectUI。它负责**交互**和**渲染**。
58+
59+
* **角色：** 使用协议来渲染界面。
60+
* **职责：** 它不包含硬编码的表单。相反，它询问 ObjectQL：*"客户的 schema 是什么？"* 并根据该元数据动态渲染布局。
61+
* **关键概念：** **服务器驱动 UI（SDUI）**。后端规定布局、验证规则和可用操作。前端只是一个高度强大的渲染器。
62+
63+
---
64+
65+
## 请求生命周期
66+
67+
为了理解这些部分如何配合，让我们跟踪一个典型的用户交互——例如，销售代表在离线时更新交易状态。
68+
69+
1. **交互（ObjectUI）：**
70+
* 用户将 "Deal" 拖到看板中的 "Closed Won" 列。
71+
* 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+
* "更新后" 触发器触发（向经理发送电子邮件）。

‎content/docs/concepts/core-values.cn.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: 核心价值
3+
description: 深入了解 ObjectStack 的三大支柱：协议驱动架构、本地优先数据主权和数据库无关性。
4+
---
5+
6+
import { Database, Link, Laptop } from 'lucide-react';
7+
8+
ObjectStack 建立在三个不可协商的架构价值之上。这些不仅仅是"功能"；它们是指导我们做出的每一个设计决策的约束。
9+
10+
## 1. 协议驱动：意图优于实现
11+
12+
ObjectStack 的基本论点是**应用程序逻辑应该由声明性数据定义，而不是命令式代码。**
13+
14+
### "代码优先"的问题
15+
在现代开发中，"意图"（例如，*"此字段是必填的电子邮件地址"*）通常分散在三层：
16+
1. **数据库：** SQL 约束（`NOT NULL`）。
17+
2. **后端：** ORM 验证（例如，TypeORM 装饰器）。
18+
3. **前端：** UI 验证（例如，React Hook Form + Zod）。
19+
20+
当业务需求发生变化时，你必须在三个地方更新代码。这就是**实现耦合**。
21+
22+
### 协议驱动的解决方案
23+
ObjectStack 将"意图"集中到单个协议定义（JSON/YAML）中。实现层（React、Node.js、SQL）仅充当解释此协议的**运行时引擎**。
24+
25+
<Callout type="info">
26+
UI 是投影。API 是结果。
27+
</Callout>
28+
29+
* **UI 是投影：** ObjectUI 不"构建"表单；它*投影* ObjectQL schema 到视觉表示。
30+
* **API 是结果：** 你不编写端点；ObjectOS *生成*基于访问控制协议的安全图。
31+
32+
> **类比：** 将 ObjectStack 想象成一个 Web 浏览器。你向它发送 HTML（协议），它渲染一个页面。你不必每次想要更改网站上的文本时都重写浏览器引擎（C++）。
33+
34+
## 2. 本地优先：所有权和零延迟
35+
36+
在过去的十年中，"云原生"一直是黄金标准。虽然它解决了部署问题，但它引入了一个新问题：**用户租用他们对数据的访问。**
37+
38+
如果服务器很慢，应用程序就很慢。如果互联网断开，应用程序就死了。
39+
40+
### "七跳"问题
41+
在传统的云应用程序中，一个简单的按钮点击会经过：
42+
`点击 -> Wi-Fi -> ISP -> 云负载均衡器 -> Web 服务器 -> 数据库 -> 查询执行` ……然后一路返回。
43+
44+
### 本地优先解决方案
45+
ObjectStack 应用程序设计为首先读写**本地数据库**（嵌入在客户端环境中）。
46+
`点击 -> 本地 DB -> UI 更新`（0ms 延迟）。
47+
48+
与云的同步在后台异步发生。
49+
50+
1. **即时响应：** UI 立即反应（乐观 UI），使企业应用程序感觉像原生桌面软件一样快速。
51+
2. **离线能力：** 现场工作人员、飞机或不稳定的连接不再是障碍。
52+
3. **数据主权：** 数据实际存储在用户的设备上。云充当同步中心，而不是唯一的看门人。
53+
54+
## 3. 数据库无关性：通用编译器
55+
56+
行业分为 SQL（Postgres、MySQL）和 NoSQL（MongoDB、Redis）阵营。开发人员经常将自己锁定在一个供应商的方言中。
57+
58+
ObjectStack 引入 **ObjectQL**，这是一种统一的查询语言，可以编译到任何后端。
59+
60+
* **供应商锁定自由：** 从 SQLite 开始进行原型设计，迁移到 PostgreSQL 用于生产，并存档到 Snowflake 用于分析——无需重写一行业务逻辑。
61+
* **一流的驱动程序：** 我们不实现数据库；我们实现*驱动程序*，将数据库视为愚蠢的存储引擎。我们在应用层（内核）处理复杂的逻辑（RBAC、验证）。
62+
63+
### 编译器方法
64+
与运行时包装器（如 ORM）不同，ObjectQL 作为**编译器**运行。
65+
1. **输入：** ObjectQL 抽象语法树（AST）。
66+
2. **处理：** 将 AST 编译为特定方言的 SQL。
67+
3. **输出：** 针对目标的高度优化查询。
68+
69+
这种架构允许激进的灵活性：
70+
* **开发：** 在 **SQLite** 上运行（零设置，单个文件）。
71+
* **生产：** 在 **PostgreSQL** 上运行（稳健，可扩展）。
72+
* **边缘：** 在 **Cloudflare D1** 上运行（分布式）。
73+
* **遗留：** 连接到现有的 **Oracle/SQL Server**（集成）。
74+
75+
你更改*驱动程序*，而不是*代码*。
76+
77+
## 总结
78+
79+
| 价值 | 旧方式 | ObjectStack 方式 |
80+
| :--- | :--- | :--- |
81+
| **架构** | 代码驱动（命令式） | 协议驱动（声明式） |
82+
| **逻辑位置** | 分散（DB + API + UI） | 集中（JSON/YAML Schema） |
83+
| **数据访问** | 依赖云（仅在线） | 本地优先（离线 + 同步） |
84+
| **存储** | 锁定到供应商 | 数据库无关 |
85+
86+
通过坚持这些价值观，我们构建的软件**对变化有弹性**，**尊重用户时间**，并且**技术自主**。

‎content/docs/concepts/enterprise-patterns.cn.mdx‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: 企业模式
3+
description: 使用协议驱动方法处理复杂的 ERP/CRM 业务逻辑（状态机、计算、RBAC）。
4+
---
5+
6+
import { Sliders, GitMerge, Calculator, BookOpen } from 'lucide-react';
7+
8+
关于"低代码"或"协议驱动"平台的一个常见误解是它们只适用于简单的 CRUD 应用程序。
9+
10+
虽然许多可视化构建器确实如此，但 **ObjectStack** 专门为企业资源计划（ERP）和客户关系管理（CRM）系统的复杂性而设计。我们不是通过隐藏复杂性来处理它，而是通过在协议中**显式建模**它来处理。
11+
12+
以下是我们如何将常见的企业模式映射到 ObjectStack 架构。
13+
14+
## 1. 工作流作为状态机（FSM）
15+
16+
在企业软件中，记录（例如，"采购订单"）很少只是静态数据。它是一个在生命周期中移动的活实体。
17+
18+
### 反模式
19+
在控制器中编写分散的 `if/else` 逻辑：
20+
```javascript
21+
// 不要这样做
22+
if (order.status === 'draft' && user.role === 'manager') {
23+
order.status = 'approved';
24+
}
25+
```
26+
27+
### ObjectStack 模式
28+
我们将生命周期定义为 ObjectOS 协议中的**有限状态机（FSM）**。这使业务流程具有确定性和可视化。
29+
30+
```yaml
31+
# workflows/purchase_order.yaml
32+
name: purchase_approval
33+
object: purchase_order
34+
states:
35+
draft:
36+
initial: true
37+
on_exit: ['validate_budget']
38+
transitions:
39+
submit: pending_approval
40+
pending_approval:
41+
transitions:
42+
approve: approved
43+
reject: rejected
44+
guards:
45+
approve: "user.has_permission('approve_budget')"
46+
approved:
47+
final: true
48+
```
49+
50+
## 2. 动态汇总（计算字段）
51+
52+
ERP 系统通常需要"主-明细"数学。*示例：订单的总额是其行项目的总和。*
53+
54+
### 反模式
55+
在每个报表中手动编写 SQL `SUM()` 查询，或使用难以调试的数据库触发器。
56+
57+
### ObjectStack 模式
58+
我们在对象协议中定义**汇总字段**。ObjectQL 编译器处理底层复杂性（通过实时 `JOIN` 或后台聚合）。
59+
60+
```yaml
61+
# objects/order.yml
62+
fields:
63+
total_amount:
64+
type: summary
65+
summary_object: line_items
66+
summary_field: amount
67+
summary_type: sum
68+
```
69+
70+
## 3. 多态关系
71+
72+
CRM 系统通常需要"多对任意"关系。*示例：任务可以与潜在客户、联系人或客户相关。*
73+
74+
### ObjectStack 模式
75+
我们使用具有多个目标的 `reference` 类型。
76+
77+
```yaml
78+
# objects/task.yml
79+
fields:
80+
related_to:
81+
type: lookup
82+
reference_to: ['lead', 'contact', 'account', 'opportunity']
83+
```
84+
85+
这指示 ObjectQL 编译器生成必要的多态键（例如，`related_to_id` 和 `related_to_type` 列）。
86+
87+
## 总结
88+
89+
ObjectStack 通过**将模式提升为协议**来处理企业复杂性。
90+
91+
| 模式 | 传统代码 | ObjectStack 协议 |
92+
| :--- | :--- | :--- |
93+
| **逻辑** | 意大利面条式 `if/else` | 状态机（YAML） |
94+
| **数学** | 手动循环/SQL | 虚拟/汇总字段 |
95+
| **关系** | 自定义连接表 | 多态引用 |

0 commit comments

Comments
 (0)