|
1 | | - |
2 | | -### 🟢 P0: 核心元模型 (The Metamodel) |
3 | | - |
4 | | -*没有这部分，ObjectQL 和 ObjectUI 无法通信，系统无法运转。这是“万物皆对象”的法律定义。* |
5 | | - |
6 | | -* **[ ] 1. 实体定义协议 (`EntitySchema`)** |
7 | | -* **定义目标**: 描述一个“对象”长什么样。 |
8 | | -* **关键字段**: `name` (机器名), `label` (显示名), `dataSource` (存哪), `dbName` (物理表名)。 |
9 | | -* **用途**: ObjectQL 解析 `.gql` 文件后生成的 AST 结构；`/_api/metadata/objects/{name}` 的返回值。 |
10 | | - |
11 | | - |
12 | | -* **[ ] 2. 字段定义协议 (`FieldSchema`)** |
13 | | -* **定义目标**: 描述对象里的“属性”。 |
14 | | -* **关键字段**: `type` (text/number/lookup...), `required`, `unique`, `defaultValue`。 |
15 | | -* **关键枚举**: `FieldType` (必须枚举所有支持的类型，如 `master_detail`, `formula`, `image`)。 |
16 | | -* **用途**: 告诉前端渲染什么组件，告诉后端怎么建表。 |
17 | | - |
18 | | - |
19 | | -* **[ ] 3. 视图/布局协议 (`LayoutSchema`)** |
20 | | -* **定义目标**: 描述界面如何排列。 |
21 | | -* **关键结构**: |
22 | | -* `ListView`: 列定义 (`columns`), 排序 (`sort`), 筛选 (`filters`)。 |
23 | | -* `FormView`: 区域 (`sections`), 字段分组 (`groups`)。 |
24 | | - |
25 | | - |
26 | | -* **用途**: ObjectUI 根据这个 JSON 渲染页面，而不是写死 React 代码。 |
27 | | - |
28 | | - |
29 | | - |
30 | | ---- |
31 | | - |
32 | | -### 🔵 P1: 插件与分发 (Packaging & Runtime) |
33 | | - |
34 | | -*没有这部分，你的应用市场和插件机制就是空谈。* |
35 | | - |
36 | | -* **[ ] 4. 插件清单协议 (`ManifestSchema`)** |
37 | | -* **定义目标**: 描述一个软件包（插件/应用）。 |
38 | | -* **文件对应**: `objectstack.config.ts` 或 `package.json > objectstack`。 |
39 | | -* **关键字段**: `id`, `version`, `type` (app/plugin/driver), `permissions` (申请权限), `menus` (导航注入)。 |
40 | | -* **用途**: CLI 打包校验，应用商店展示。 |
41 | | - |
42 | | - |
43 | | -* **[ ] 5. 生命周期接口 (`PluginLifecycle`)** |
44 | | -* **定义目标**: 插件在运行时如何被加载。 |
45 | | -* **接口定义**: `interface ObjectStackPlugin` |
46 | | -* **关键方法**: `onInstall(ctx)`, `onEnable(ctx)`, `onDisable(ctx)`。 |
47 | | -* **Context 定义**: `ctx.ql` (数据能力), `ctx.os` (系统能力), `ctx.logger`。 |
48 | | -* **用途**: ObjectOS 加载 `node_modules` 时的统一入口标准。 |
49 | | - |
50 | | - |
51 | | -* **[ ] 6. 导航菜单协议 (`NavigationSchema`)** |
52 | | -* **定义目标**: 描述侧边栏菜单结构。 |
53 | | -* **关键字段**: `label`, `icon`, `path`, `children`, `visible_on` (权限控制)。 |
54 | | -* **用途**: 多个插件的菜单合并渲染到 ObjectCloud / Studio 的侧边栏。 |
55 | | - |
56 | | - |
57 | | - |
58 | 1 | --- |
59 | | - |
60 | | -### 🟠 P2: 驱动与连接 (Drivers & Logic) |
61 | | - |
62 | | -*这部分决定了你的系统扩展性（能不能连 Excel，能不能写自定义代码）。* |
63 | | - |
64 | | -* **[ ] 7. 数据驱动接口 (`DriverInterface`)** |
65 | | -* **定义目标**: 任何数据库要想接入 ObjectQL，必须实现的标准。 |
66 | | -* **核心方法**: |
67 | | -* `find(entity, query)` |
68 | | -* `create(entity, data)` |
69 | | -* `update(entity, id, data)` |
70 | | -* `delete(entity, id)` |
71 | | -* `syncSchema(entity)` (DDL 操作：建表/加字段) |
72 | | - |
73 | | - |
74 | | -* **用途**: 让 `driver-postgres`, `driver-excel`, `driver-salesforce` 行为一致。 |
75 | | - |
76 | | - |
77 | | -* **[ ] 8. 触发器上下文协议 (`TriggerContext`)** |
78 | | -* **定义目标**: 当用户写 `beforeInsert` 代码时，传入参数的标准。 |
79 | | -* **接口定义**: |
80 | | -* `doc` (当前记录) |
81 | | -* `previousDoc` (修改前的记录) |
82 | | -* `userId` (谁在操作) |
83 | | - |
84 | | - |
85 | | -* **用途**: 规范化业务逻辑代码的编写。 |
86 | | - |
87 | | - |
88 | | -* **[ ] 9. UI 组件契约 (`WidgetContract`)** |
89 | | -* **定义目标**: 第三方开发者开发自定义 UI 组件（如：地图选择器）的标准。 |
90 | | -* **接口定义**: `interface FieldWidgetProps { value, onChange, readonly, options }`。 |
91 | | -* **用途**: 让社区开发的 React 组件能无缝嵌入到 ObjectUI 的表单中。 |
92 | | - |
93 | | - |
94 | | - |
| 2 | +title: ObjectStack Protocol |
| 3 | +description: The Standard for Post-SaaS Operating Systems |
95 | 4 | --- |
96 | 5 |
|
97 | | -### 💾 你的“立法”行动路线图 |
98 | | - |
99 | | -建议你在 `packages/spec` 仓库中按以下文件结构落地这些协议： |
100 | | - |
101 | | -```text |
102 | | -packages/spec/ |
103 | | -├── src/ |
104 | | -│ ├── types/ |
105 | | -│ │ ├── meta/ <-- P0: Metamodel |
106 | | -│ │ │ ├── entity.ts (EntitySchema) |
107 | | -│ │ │ ├── field.ts (FieldSchema) |
108 | | -│ │ │ └── view.ts (LayoutSchema) |
109 | | -│ │ ├── bundle/ <-- P1: Packaging |
110 | | -│ │ │ ├── manifest.ts (ManifestSchema) |
111 | | -│ │ │ └── menu.ts (NavigationSchema) |
112 | | -│ │ ├── runtime/ <-- P2: Logic |
113 | | -│ │ │ ├── plugin.ts (Lifecycle) |
114 | | -│ │ │ └── driver.ts (DriverInterface) |
115 | | -│ │ └── auth/ <-- from plugin-auth |
116 | | -│ │ └── session.ts (User/Session Interface) |
117 | | -│ ├── zods/ <-- 对应的 Zod 实现 (用于运行时校验) |
118 | | -│ └── constants/ <-- 目录约定 (paths) |
119 | | -└── package.json |
120 | | -
|
121 | | -``` |
122 | | - |
| 6 | +import { FileText, Database, Layout, Settings, Book } from 'lucide-react'; |
| 7 | + |
| 8 | +# ObjectStack Protocol |
| 9 | + |
| 10 | +**ObjectStack Protocol** is the "DNA" and constitution of the ObjectStack platform. It defines the metadata standards, schemas, and runtime behaviors that power a metadata-driven, low-code operating system. |
| 11 | + |
| 12 | +<Callout type="info"> |
| 13 | + This specification serves as the Single Source of Truth for all ObjectStack implementations. All definitions are strictly typed using Zod and TypeScript. |
| 14 | +</Callout> |
| 15 | + |
| 16 | +## The Metamodel Architecture |
| 17 | + |
| 18 | +The protocol is divided into three fundamental pillars that decouple data, presentation, and system configuration. |
| 19 | + |
| 20 | +<Cards> |
| 21 | + <Card |
| 22 | + icon={<Database />} |
| 23 | + href="/docs/concepts/architecture" |
| 24 | + title="Data Protocol" |
| 25 | + description="Core business logic and data modeling. Defines Objects, Fields, Validation Rules, and Flows." |
| 26 | + /> |
| 27 | + <Card |
| 28 | + icon={<Layout />} |
| 29 | + href="/docs/references/App" |
| 30 | + title="UI Protocol" |
| 31 | + description="Presentation layer specifications. Defines Views, Layouts, Menus (Apps), and Dashboards." |
| 32 | + /> |
| 33 | + <Card |
| 34 | + icon={<Settings />} |
| 35 | + href="/docs/references/Datasource" |
| 36 | + title="System Protocol" |
| 37 | + description="Runtime configuration and environment binding. Defines Datasources, APIs, and Manifests." |
| 38 | + /> |
| 39 | +</Cards> |
| 40 | + |
| 41 | +## Core Principles |
| 42 | + |
| 43 | +### 1. Schema First |
| 44 | +Every protocol definition starts with a **Zod Schema**. This ensures runtime validation for the CLI and strict type derivation (`z.infer<T>`) for the IDE. We do not write code without a schema. |
| 45 | + |
| 46 | +### 2. Configuration as Code |
| 47 | +All business logic is expressed as serializable JSON/YAML configuration. This enables: |
| 48 | +- **Version Control**: Git-based history for business logic. |
| 49 | +- **Reviewability**: Pull requests for application changes. |
| 50 | +- **Portability**: Move applications between environments instantly. |
| 51 | + |
| 52 | +### 3. Separation of Concerns |
| 53 | +We strictly separate the **Metamodel** (pure definitions) from the **Runtime** (execution engine). The `spec` package contains *only* definitions, constants, and types—no heavy business logic. |
| 54 | + |
| 55 | +## Directory Structure |
| 56 | + |
| 57 | +The specification is organized reflecting the protocol pillars: |
| 58 | + |
| 59 | +- **`src/data/`**: ObjectQL definitions (Object, Field, Validation). |
| 60 | +- **`src/ui/`**: ObjectUI definitions (App, View, Action). |
| 61 | +- **`src/system/`**: ObjectOS definitions (Manifest, Config). |
| 62 | + |
| 63 | +## Next Steps |
| 64 | + |
| 65 | +<Cards> |
| 66 | + <Card |
| 67 | + icon={<Book />} |
| 68 | + href="/docs/concepts/manifesto" |
| 69 | + title="Read the Manifesto" |
| 70 | + description="Understand the philosophy behind the Post-SaaS Operating System." |
| 71 | + /> |
| 72 | + <Card |
| 73 | + icon={<FileText />} |
| 74 | + href="/docs/references" |
| 75 | + title="API Reference" |
| 76 | + description="Explore the complete API and Schema reference documentation." |
| 77 | + /> |
| 78 | +</Cards> |
0 commit comments