Skip to content

Commit a9b8382

Browse files
Copilothotlong
Copilot
and
hotlong
committed
Add Chinese translations for index, guides, and concepts (partial)
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 4a462de commit a9b8382

8 files changed

Lines changed: 357 additions & 0 deletions

File tree

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

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: 宣言
3+
description: 管理 ObjectStack 生态系统的不可动摇的核心原则。后 SaaS 时代的宪法。
4+
---
5+
6+
import { ScrollText, Scale, Database, Code2 } from 'lucide-react';
7+
8+
ObjectStack 的存在是为了将企业应用程序开发回归其本质：**数据**。
9+
10+
为了维护一个健康、解耦和经得起未来考验的生态系统，我们承诺坚守以下不可动摇的核心原则。这些不是建议；它们是使我们获得自由的约束。
11+
12+
<Cards>
13+
<Card
14+
icon={<Scale />}
15+
title="I. 协议中立性"
16+
description="协议即法律。实现仅仅是一种意见。"
17+
/>
18+
<Card
19+
icon={<Code2 />}
20+
title="II. 机制优于策略"
21+
description="提供构建规则的工具，而不是硬编码规则本身。"
22+
/>
23+
<Card
24+
icon={<Database />}
25+
title="III. 数据主权"
26+
description="数据属于用户，而不是 SaaS 提供商。"
27+
/>
28+
</Cards>
29+
30+
---
31+
32+
## 原则 I：协议中立性
33+
34+
**"协议是中立的。引擎是可替换的。"**
35+
36+
ObjectQL 不得包含任何特定于特定语言（例如 Node.js）、数据库（例如 PostgreSQL）或运行时（例如浏览器）的逻辑。
37+
38+
### 法则
39+
* **先规范后引擎：** 在规范层（`packages/spec`）编写任何功能之前，必须首先在规范层定义该功能。我们拒绝"先实现，后标准化"的方法。
40+
* **零泄漏：** 实现细节（如 React Hooks 使用或 SQL 特定语法）绝不能泄漏到协议定义中。
41+
42+
### 好处
43+
这确保了今天定义的 ObjectStack 应用程序理论上可以在以下环境中运行：
44+
* 带 PostgreSQL 的 Node.js 服务器（今天的标准）
45+
* 带 SQLite 的 Python 服务器（AI/数据科学）
46+
* 浏览器中的 Rust WASM 模块（本地优先）
47+
48+
---
49+
50+
## 原则 II：机制优于策略
51+
52+
**"给他们物理学，而不是模拟。"**
53+
54+
ObjectStack 提供**机制**（"如何"）：
55+
* *"这是你如何定义验证规则。"*
56+
* *"这是你如何定义权限范围。"*
57+
58+
ObjectStack 从不规定**策略**（"什么"）：
59+
* *它从不说"密码必须是 8 个字符"。*
60+
* *它从不说"用户必须属于一个部门"。*
61+
62+
### 关注点分离
63+
我们清晰地将**定义**与**执行**分离。
64+
65+
| 层 | 职责 | 示例 |
66+
| :--- | :--- | :--- |
67+
| **协议（机制）** | 定义能力。 | `allowRead: string`（公式的插槽） |
68+
| **应用（策略）** | 定义业务逻辑。 | `allowRead: "$user.role == 'admin'"` |
69+
| **引擎（执行）** | 执行逻辑。 | 将公式编译为 SQL `WHERE` 子句。 |
70+
71+
---
72+
73+
## 原则 III：单一数据源
74+
75+
**"没有'代码'。只有 Schema。"**
76+
77+
在传统应用程序中，"真相"是分散的：
78+
1. 数据库 Schema（`table.sql`）
79+
2. 后端模型（`User.ts`）
80+
3. 前端验证（`schema.zod.ts`）
81+
4. API 文档（`swagger.json`）
82+
83+
在 ObjectStack 中，**对象协议是唯一的真相。**
84+
* 数据库是协议的*衍生物*。
85+
* UI 是协议的*投影*。
86+
* API 是协议的*结果*。
87+
88+
如果你改变了协议，整个系统（DB、API、UI）必须自动适应。
89+
90+
---
91+
92+
## 原则 IV：默认本地优先
93+
94+
**"云是同步对等方，而不是主控方。"**
95+
96+
我们拒绝软件在互联网连接中断时必须停止工作的观念。
97+
* **延迟是敌人：** 所有交互都应该是乐观的和即时的（0ms）。
98+
* **所有权是目标：** 用户的数据实质上存储在他们的设备上。服务器只是备份和协作的中心。
99+
100+
---
101+
102+
> "我们塑造我们的工具，此后我们的工具塑造我们。" — 马歇尔·麦克卢汉

‎content/docs/concepts/meta.cn.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"title": "概念",
3+
"root": true,
4+
"pages": [
5+
"manifesto",
6+
"core-values",
7+
"architecture",
8+
"security_architecture",
9+
"enterprise-patterns",
10+
"ai-codex",
11+
"terminology"
12+
]
13+
}

‎content/docs/guides/getting-started.cn.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: 快速开始
3+
description: 5 分钟内构建你的第一个 ObjectStack 应用程序
4+
---
5+
6+
ObjectStack 是一个协议，但 `@objectstack/spec` 是提供 Zod schemas 和严格类型的参考实现库，用于构建有效的元数据。
7+
8+
<Steps>
9+
10+
<Step>
11+
## 初始化你的项目
12+
13+
你可以从头开始或将 ObjectStack 添加到现有的 TypeScript 项目中。
14+
15+
```bash
16+
mkdir my-app
17+
cd my-app
18+
npm init -y
19+
npm install typescript zod @objectstack/spec
20+
npx tsc --init
21+
```
22+
</Step>
23+
24+
<Step>
25+
## 定义你的第一个对象
26+
27+
创建一个名为 `src/objects/contact.schema.ts` 的文件。
28+
这就是 **Zod 优先定义** 的强大之处。你可以开箱即用地获得自动完成和验证。
29+
30+
```typescript
31+
import { ObjectSchema, Field } from '@objectstack/spec';
32+
33+
export const Contact = ObjectSchema.create({
34+
name: 'contact',
35+
label: 'Contact',
36+
fields: {
37+
first_name: Field.text({ label: 'First Name', required: true }),
38+
last_name: Field.text({ label: 'Last Name', required: true }),
39+
email: Field.text({ format: 'email' }),
40+
type: Field.select(['Customer', 'Partner', 'Vendor']),
41+
},
42+
enable: {
43+
api: true,
44+
audit: true
45+
}
46+
});
47+
```
48+
</Step>
49+
50+
<Step>
51+
## 验证协议
52+
53+
创建一个构建脚本 `src/build.ts` 来验证你的定义是否符合 ObjectStack 协议。
54+
55+
```typescript
56+
import { Contact } from './objects/contact.schema';
57+
58+
// 如果你的 schema 无效，这将抛出 ZodError
59+
const protocol = Contact.parse(Contact);
60+
61+
console.log(`✅ Object '${protocol.name}' is valid ObjectStack Metadata!`);
62+
console.log(JSON.stringify(protocol, null, 2));
63+
```
64+
</Step>
65+
66+
<Step>
67+
## 下一步
68+
69+
现在你有了有效的元数据，你可以：
70+
71+
1. **生成 SQL**：使用协议编译器（即将推出）生成 `CREATE TABLE` 语句。
72+
2. **生成 UI**：将 JSON 传入 `<ObjectForm />` React 组件。
73+
3. **部署**：将 JSON 推送到 ObjectOS 内核。
74+
75+
</Step>
76+
77+
</Steps>

‎content/docs/guides/installation.cn.mdx‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: 安装
3+
description: 安装 ObjectStack SDK 和 CLI
4+
---
5+
6+
## 系统要求
7+
8+
* Node.js 18+
9+
* TypeScript 5+
10+
11+
## 包安装
12+
13+
`@objectstack/spec` 包包含核心 Zod 定义和类型接口。
14+
15+
### npm
16+
17+
```bash
18+
npm install @objectstack/spec
19+
```
20+
21+
### pnpm
22+
23+
```bash
24+
pnpm add @objectstack/spec
25+
```
26+
27+
### yarn
28+
29+
```bash
30+
yarn add @objectstack/spec
31+
```
32+
33+
## CLI 安装（可选）
34+
35+
CLI 工具帮助构建新对象并验证现有元数据。
36+
37+
```bash
38+
npm install -g @objectstack/cli
39+
```
40+
41+
## 版本控制
42+
43+
协议遵循语义化版本控制。
44+
* **主版本 (1.x)**：协议的破坏性更改（JSON 结构）。
45+
* **次版本 (1.1.x)**：新的字段类型或配置选项。
46+
* **补丁版本 (1.1.1)**：Zod 验证或类型推断中的错误修复。

‎content/docs/guides/meta.cn.json‎

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+
"getting-started",
6+
"installation",
7+
"project-structure"
8+
]
9+
}

‎content/docs/guides/project-structure.cn.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: 项目结构
3+
description: ObjectStack 项目的推荐目录布局
4+
---
5+
6+
为了保持元数据的组织性，我们推荐以下文件夹结构（"领域模式"）。
7+
8+
<FileTree>
9+
<Folder name="src" defaultOpen>
10+
<Folder name="domains" defaultOpen>
11+
<Folder name="crm" defaultOpen>
12+
<File name="contact.object.ts" />
13+
<File name="account.object.ts" />
14+
<File name="lead.object.ts" />
15+
</Folder>
16+
<Folder name="finance" defaultOpen>
17+
<File name="invoice.object.ts" />
18+
<File name="payment.object.ts" />
19+
</Folder>
20+
</Folder>
21+
<Folder name="apps">
22+
<File name="backoffice.app.ts" />
23+
<File name="portal.app.ts" />
24+
</Folder>
25+
<Folder name="config">
26+
<File name="datasources.ts" />
27+
<File name="acl.ts" />
28+
</Folder>
29+
</Folder>
30+
<File name="package.json" />
31+
<File name="tsconfig.json" />
32+
<File name="objectstack.config.ts" />
33+
</FileTree>
34+
35+
## 核心概念
36+
37+
### 领域
38+
39+
按业务领域（CRM、财务、人力资源）而不是技术类型组织你的对象。这与**领域驱动设计（DDD）**原则保持一致。
40+
41+
### 命名约定
42+
43+
* **文件**：`kebab-case.suffix.ts`（例如，`project-task.object.ts`、`main-dashboard.view.ts`）
44+
* **变量**：`PascalCase`（例如，`ProjectTask`、`MainDashboard`）
45+
* **机器名称**：定义内使用 `snake_case`（例如，`name: 'project_task'`）

‎content/docs/index.cn.mdx‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: 欢迎来到 ObjectStack
3+
description: 后 SaaS 时代的元数据驱动协议
4+
---
5+
6+
import { Book, Compass, FileText, Layers } from 'lucide-react';
7+
8+
**ObjectStack** 不仅仅是一个框架；它是构建企业软件的**协议**。
9+
它将*业务意图*（用 JSON/YAML 定义）与*技术执行*（由内核处理）解耦。
10+
11+
本文档是 ObjectStack 协议的权威参考。
12+
13+
## 如何导航
14+
15+
<Cards>
16+
<Card
17+
icon={<FileText />}
18+
title="快速开始"
19+
href="/docs/guides/getting-started"
20+
description="5 分钟内构建你的第一个对象。学习 SDK 的基础知识。"
21+
/>
22+
<Card
23+
icon={<Compass />}
24+
title="概念"
25+
href="/docs/concepts/manifesto"
26+
description="理解"意图优于实现"的理念和"本地优先"架构。"
27+
/>
28+
<Card
29+
icon={<Layers />}
30+
title="规范"
31+
href="/docs/specifications/data/architecture"
32+
description="架构蓝图。深入了解 ObjectQL（数据）、ObjectUI（视图）和 ObjectOS（控制）。"
33+
/>
34+
<Card
35+
icon={<Book />}
36+
title="协议参考"
37+
href="/docs/references/data/core/Object"
38+
description="字典。每个 Schema、字段类型和配置选项的全面参考。"
39+
/>
40+
</Cards>
41+
42+
## "三位一体"架构
43+
44+
ObjectStack 建立在三个协同工作的支柱之上：
45+
46+
| 支柱 | 协议 | 职责 |
47+
| :--- | :--- | :--- |
48+
| **数据层** | **[ObjectQL](/docs/specifications/data/architecture)** | 定义数据的形状（`Object`）以及如何访问它（`AST`）。不依赖于 SQL/NoSQL。 |
49+
| **控制层** | **[ObjectOS](/docs/specifications/server/kernel-architecture)** | 内核。处理身份、安全、同步和自动化。 |
50+
| **视图层** | **[ObjectUI](/docs/specifications/ui/sdui-protocol)** | 投影。将用户界面定义为抽象的 JSON 布局，实现服务器驱动 UI。 |
51+
52+
## 这是为谁准备的？
53+
54+
* **平台架构师：** 想要构建可扩展的内部开发者平台（IDP）的人。
55+
* **协议实现者：** 想要为 ObjectQL 编写新驱动程序（例如，用于 FoundationDB）或为 ObjectUI 编写新渲染器（例如，用于 Flutter）的人。
56+
* **AI 代理开发者：** 需要一种确定性的、结构化的通用语言来让 AI 生成软件的人。

‎content/docs/meta.cn.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"title": "文档",
3+
"pages": [
4+
"guides",
5+
"concepts",
6+
"specifications",
7+
"references"
8+
]
9+
}

0 commit comments

Comments
 (0)