Skip to content

Commit ab0e51f

Browse files
hotlonghotlong
authored
Merge pull request #52 from objectstack-ai/copilot/implement-metadata-engine
2 parents 760c625 + 797b2f9 commit ab0e51f

10 files changed

Lines changed: 2620 additions & 1 deletion

File tree

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

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
---
2+
title: 企业框架
3+
description: "第一阶段：代码驱动的元数据引擎 - 定义即应用"
4+
---
5+
6+
# ObjectStack 企业框架
7+
8+
**"定义即应用"**
9+
10+
## 概述
11+
12+
ObjectStack 企业框架代表了企业应用开发的新方法——**"面向专业开发者的元数据引擎"**。在第一阶段，我们专注于赋能开发者通过基于代码的元数据定义构建企业级应用，消除了对可视化配置界面的需求，同时保持 ObjectStack 协议生态系统的强大功能和灵活性。
13+
14+
### 核心理念
15+
16+
在第一阶段，我们将 ObjectStack 定义为**"面向专业开发者的企业级应用元框架"**。
17+
18+
* **没有黑盒**: 所有的业务定义都在本地代码中，基于 TypeScript，清晰透明。
19+
* **Git 为中心**: 使用 Git 仓库作为唯一真理来源 (Single Source of Truth)。
20+
* **自带基建**: 开发者只负责写"业务描述"，框架负责"数据库迁移、API 生成、界面渲染"。
21+
22+
---
23+
24+
## 架构全景图
25+
26+
企业框架围绕三个不同的层次构建，这些层次共同将基于代码的定义转换为运行中的应用程序。
27+
28+
```mermaid
29+
graph TB
30+
subgraph "A. 创造层：ObjectStack SDK"
31+
CLI[ObjectStack CLI]
32+
SDK[TypeScript SDK]
33+
MetaCode[代码化元数据]
34+
end
35+
36+
subgraph "B. 治理层：CI/CD 流水线"
37+
Extract[提取元数据]
38+
Compile[编译逻辑]
39+
Bundle[打包制品]
40+
Version[版本控制]
41+
end
42+
43+
subgraph "C. 执行层：ObjectStack 内核"
44+
ObjectQL[ObjectQL - 自动迁移]
45+
ObjectOS[ObjectOS - 逻辑沙箱]
46+
ObjectUI[ObjectUI - 渲染器 API]
47+
end
48+
49+
CLI --> MetaCode
50+
SDK --> MetaCode
51+
MetaCode --> Extract
52+
Extract --> Compile
53+
Compile --> Bundle
54+
Bundle --> Version
55+
Version --> ObjectQL
56+
Version --> ObjectOS
57+
Version --> ObjectUI
58+
```
59+
60+
### A. 创造层：ObjectStack SDK
61+
62+
**"在 IDE 中定义世界"**
63+
64+
开发者不再需要登录网页后台配置，而是直接在 VS Code 或他们喜欢的 IDE 中工作。
65+
66+
#### ObjectStack CLI
67+
68+
命令行工具，用于快速生成代码模板和项目脚手架：
69+
70+
* `ostack init`: 初始化标准项目结构
71+
* `ostack g resource contract`: 生成"合同"模块的标准目录
72+
* `ostack build`: 编译元数据和业务逻辑
73+
* `ostack dev`: 启动本地开发服务器，支持热重载
74+
75+
#### 基于代码的元数据
76+
77+
我们利用 **TypeScript** 的静态类型能力来定义元数据：
78+
79+
* **Schema**: 使用类似 Zod 或 TypeORM 的语法定义数据结构
80+
* **Logic**: 直接编写 TS 函数作为 Trigger
81+
* **UI**: 使用 JSON 或 TS 对象描述界面布局（通过我们提供的类型提示）
82+
83+
**代码示例：**
84+
85+
```typescript
86+
// src/objects/contract.ts
87+
import { defineObject, Field } from '@objectstack/sdk';
88+
89+
export const Contract = defineObject({
90+
name: 'contract',
91+
label: '销售合同',
92+
fields: {
93+
title: Field.String({
94+
label: '标题',
95+
required: true,
96+
maxLength: 200
97+
}),
98+
amount: Field.Currency({
99+
label: '金额',
100+
precision: 18,
101+
scale: 2
102+
}),
103+
status: Field.Select({
104+
options: ['draft', 'signed', 'cancelled'],
105+
defaultValue: 'draft'
106+
}),
107+
signedAt: Field.DateTime({
108+
label: '签署日期',
109+
nullable: true
110+
})
111+
},
112+
113+
// 触发器逻辑直接写在这里
114+
triggers: {
115+
beforeInsert: async ({ doc }) => {
116+
if (doc.amount < 0) {
117+
throw new Error("金额不能为负");
118+
}
119+
},
120+
121+
afterUpdate: async ({ doc, oldDoc }) => {
122+
if (doc.status === 'signed' && oldDoc.status !== 'signed') {
123+
doc.signedAt = new Date();
124+
}
125+
}
126+
},
127+
128+
// 访问控制
129+
permissions: {
130+
create: ['sales', 'admin'],
131+
read: ['sales', 'admin', 'viewer'],
132+
update: ['sales', 'admin'],
133+
delete: ['admin']
134+
}
135+
});
136+
```
137+
138+
### B. 治理层：CI/CD 流水线
139+
140+
**"Git 仓库即控制台"**
141+
142+
没有 Hub，**Git Repository** 就是 Hub。
143+
144+
#### 构建时编排
145+
146+
当代码提交时，ObjectStack 的构建工具（基于 Vite 或 Rollup）会扫描所有 `.ts` 文件：
147+
148+
1. **Extract**: 提取其中的元数据定义（Schema/UI）
149+
2. **Compile**: 将后端逻辑编译为优化的 JS 包
150+
3. **Bundle**: 将这些打包成一个不可变的 **Artifact（制品）**
151+
152+
```mermaid
153+
sequenceDiagram
154+
participant Dev as 开发者
155+
participant Git as Git 仓库
156+
participant CI as CI 服务器
157+
participant Build as 构建工具
158+
participant Artifact as Docker 镜像
159+
160+
Dev->>Git: git push origin main
161+
Git->>CI: 触发构建
162+
CI->>Build: 运行 'ostack build'
163+
Build->>Build: 提取元数据
164+
Build->>Build: 编译 TypeScript
165+
Build->>Build: 生成迁移脚本
166+
Build->>Artifact: 创建 Docker 镜像
167+
Artifact->>Artifact: 打标签版本 (v1.0.0)
168+
```
169+
170+
#### 版本管理
171+
172+
* 利用 **Git Tag** 管理版本（v1.0, v1.1）
173+
* 利用 **Pull Request** 进行变更审批
174+
* 利用 **Git Branches** 进行功能开发和热修复
175+
176+
### C. 执行层：ObjectStack 内核
177+
178+
**"自带动力的单体引擎"**
179+
180+
这是交付给客户的核心——一个标准的 **Docker 镜像** 或 **NPM 包**，客户将其部署在自己的服务器上。
181+
182+
这个 Kernel 包含了统一的"三位一体"引擎：
183+
184+
#### 1. ObjectQL（自动迁移）
185+
186+
应用启动时，Kernel 读取打包好的 Metadata：
187+
188+
* **自动同步 DB**: 发现 `Contract` 对象多了 `amount` 字段 → 自动对 Postgres 执行 `ALTER TABLE`
189+
* **自动生成 API**: 自动挂载 GraphQL/REST 端点 `/api/data/contract`
190+
191+
#### 2. ObjectOS（逻辑沙箱）
192+
193+
* 负责加载并执行开发者编写的 `triggers` 函数
194+
* 管理身份验证和授权（RBAC/ACL）
195+
* 处理工作流状态机
196+
* 编排本地优先同步
197+
198+
#### 3. ObjectUI（渲染器 API）
199+
200+
* 向前端（React/Vue 客户端）提供 `schema.json`
201+
* **Amis 集成**: 如果使用 Amis，这里直接输出 Amis 标准的 JSON 配置，前端直接渲染
202+
* 支持复杂 UI 的自定义 React 组件
203+
204+
---
205+
206+
## 落地工作流
207+
208+
这是客户采用该方案时的标准作业流程（SOP）：
209+
210+
| 步骤 | 角色 | 动作 | 产物 |
211+
|------|------|------|------|
212+
| **1. 初始化** | 架构师 | `npm create objectstack-app my-erp` | 包含核心依赖的 Git 仓库 |
213+
| **2. 开发** | 开发者 | 编写 `.ts` 文件定义对象、逻辑和界面 | 源代码 (Source Code) |
214+
| **3. 提交** | 开发者 | `git push origin main` | 触发 CI 构建 |
215+
| **4. 构建** | CI Server | 运行 `ostack build` | **Docker Image** (包含 Kernel + 业务代码) |
216+
| **5. 部署** | 运维 | `docker run -d my-erp:latest` | 运行中的企业应用 |
217+
| **6. 迭代** | 全员 | 修改代码 → Push → 自动热更新 | 持续交付 |
218+
219+
### 详细工作流示例
220+
221+
```mermaid
222+
stateDiagram-v2
223+
[*] --> 初始化
224+
初始化 --> 开发: ostack init
225+
开发 --> 本地测试: ostack dev
226+
本地测试 --> 开发: 修复问题
227+
本地测试 --> 提交: 测试通过
228+
提交 --> CI: git push
229+
CI --> 构建: 运行流水线
230+
构建 --> 部署: 创建镜像
231+
部署 --> 运行中: docker run
232+
运行中 --> 迭代: 新需求
233+
迭代 --> 开发: 代码变更
234+
运行中 --> [*]: 关闭
235+
```
236+
237+
---
238+
239+
## 商业模式与交付物
240+
241+
在 Phase 1，你交付给客户的是一套 **"开发底座"**。
242+
243+
### 核心交付物清单
244+
245+
1. **`@objectstack/cli`**: 命令行工具 (NPM)
246+
2. **`@objectstack/core`**: 核心运行时依赖 (包含 ObjectQL/OS/UI 的逻辑)
247+
3. **Standard Template**: 标准的企业级项目脚手架
248+
4. **Documentation**: 详细的 API 文档和最佳实践指南
249+
250+
### 卖点话术
251+
252+
* **"不被厂商绑定"**: 代码在你们自己手里，Git 仓库在你们自己服务器上
253+
* **"零技术债务"**: 你们只写业务逻辑，底层脏活累活（数据库连接、API 封装、权限校验）全部由框架处理
254+
* **"类型安全"**: 全链路 TypeScript 支持，重构不再火葬场
255+
256+
---
257+
258+
## 项目结构
259+
260+
典型的 ObjectStack 企业应用遵循以下结构：
261+
262+
```
263+
my-erp/
264+
├── src/
265+
│ ├── objects/ # 业务对象定义
266+
│ │ ├── contract.ts
267+
│ │ ├── customer.ts
268+
│ │ └── order.ts
269+
│ ├── workflows/ # 状态机和流程
270+
│ │ └── order-approval.ts
271+
│ ├── permissions/ # 访问控制定义
272+
│ │ └── roles.ts
273+
│ ├── ui/ # UI 布局和组件
274+
│ │ └── contract-form.json
275+
│ └── triggers/ # 业务逻辑钩子
276+
│ └── calculate-tax.ts
277+
├── migrations/ # 生成的数据库迁移
278+
├── tests/ # 单元和集成测试
279+
├── objectstack.config.ts # 框架配置
280+
├── package.json
281+
└── tsconfig.json
282+
```
283+
284+
---
285+
286+
## 与现有 ObjectStack 概念的集成
287+
288+
企业框架建立在核心 ObjectStack 理念之上：
289+
290+
* **协议驱动**: TypeScript 代码编译为标准 ObjectStack JSON 协议
291+
* **本地优先**: 生成的应用默认支持本地优先架构
292+
* **数据库无关**: ObjectQL 编译目标支持多种数据库后端
293+
294+
但是，它增加了关键的开发者体验层：
295+
296+
* **代码优先的 DX**: 开发者在熟悉的 IDE 中工作，拥有完整的 IntelliSense
297+
* **类型安全**: 在编译时捕获错误，而不是运行时
298+
* **Git 工作流**: 利用现有的基于 Git 的开发实践
299+
300+
---
301+
302+
## 下一步
303+
304+
* **[SDK 参考](../specifications/sdk)**: `@objectstack/sdk` 的详细 API 文档
305+
* **[CLI 指南](../specifications/cli)**: 命令参考和使用示例
306+
* **[部署模式](../specifications/deployment)**: Docker、Kubernetes 和云部署策略
307+
308+
:::tip 企业级准备
309+
ObjectStack 企业框架专为重视代码质量、版本控制和可维护性的团队而设计。它将低代码的力量带入专业开发工作流程。
310+
:::
311+
312+
---
313+
314+
**ObjectStack Enterprise Framework**
315+
*Code it locally. Run it globally.*

0 commit comments

Comments
 (0)