diff --git a/ADVANCED_FEATURES.md b/ADVANCED_FEATURES.md deleted file mode 100644 index 08176e3aa..000000000 --- a/ADVANCED_FEATURES.md +++ /dev/null @@ -1,443 +0,0 @@ -# ObjectStack 高级特性实现指南 - -## 概述 - -本文档展示如何使用 MiniKernel 架构实现三个关键的高级特性： - -1. **事件驱动机制 (Event Bus)** - 实现插件间的解耦通信 -2. **UI 引擎动态挂载** - 动态路由注册和页面渲染 -3. **配置驱动加载** - 通过 JSON 配置文件加载插件 - -## ✅ 特性 1: 事件驱动机制 (Event Bus) - -### 架构说明 - -当前 MiniKernel 已经实现了完整的事件系统： - -```typescript -interface PluginContext { - hook(name: string, handler: (...args: any[]) => void | Promise): void; - trigger(name: string, ...args: any[]): Promise; -} -``` - -### 标准化钩子 - -推荐的标准化事件钩子： - -#### 数据生命周期事件 - -```typescript -// 数据创建 -'data:record:beforeCreate' // { table, data } -'data:record:afterCreate' // { table, data } - -// 数据更新 -'data:record:beforeUpdate' // { table, id, data, oldRecord } -'data:record:afterUpdate' // { table, id, data, changes } - -// 数据删除 -'data:record:beforeDelete' // { table, id } -'data:record:afterDelete' // { table, id } -``` - -#### 服务器生命周期事件 - -```typescript -'server:route:register' // { method, path, handler } -'server:ready' // { port, url } -'server:request' // { method, path, query, body } -``` - -#### 内核生命周期事件 - -```typescript -'kernel:ready' // Kernel bootstrap complete -'kernel:shutdown' // Kernel shutting down -``` - -### 实现示例 - -#### 1. Data Engine (事件生产者) - -```typescript -export class DataEnginePlugin implements Plugin { - name = 'com.objectstack.engine.data'; - - async init(ctx: PluginContext) { - const db = { - insert: async (table: string, data: any) => { - // 触发前置钩子 - 允许修改数据 - await ctx.trigger('data:record:beforeCreate', { table, data }); - - // 执行插入 - const record = { id: generateId(), ...data }; - - // 触发后置钩子 - 用于自动化 (非阻塞) - ctx.trigger('data:record:afterCreate', { table, data: record }) - .catch(err => console.error('Hook error:', err)); - - return record; - } - }; - - ctx.registerService('db', db); - } -} -``` - -#### 2. Flow Engine (事件消费者) - -```typescript -export class FlowEnginePlugin implements Plugin { - name = 'com.objectstack.engine.flow'; - - async start(ctx: PluginContext) { - // 监听数据创建事件 - ctx.hook('data:record:afterCreate', async ({ table, data }) => { - console.log(`[Flow] New ${table} record:`, data.id); - - // 根据条件触发不同的流程 - if (table === 'orders' && data.status === 'pending') { - await this.executeFlow('process_order', data); - } - }); - - // 监听数据更新事件 - ctx.hook('data:record:afterUpdate', async ({ table, data, changes }) => { - if (table === 'orders' && changes.status === 'shipped') { - await this.executeFlow('notify_shipping', data); - } - }); - } - - private async executeFlow(flowName: string, data: any) { - console.log(`[Flow] ⚡️ Executing: ${flowName}`); - // 实际的工作流执行逻辑 - } -} -``` - -### 关键优势 - -✅ **完全解耦**: Flow Engine 不需要知道 Data Engine 的存在 -✅ **可扩展**: 可以添加任意数量的事件监听器 -✅ **异步执行**: 后置钩子不阻塞主流程 -✅ **类型安全**: TypeScript 支持完整的类型推导 - -### 使用示例 - -```typescript -const kernel = new ObjectKernel(); - -kernel - .use(new DataEnginePlugin()) // 生产事件 - .use(new FlowEnginePlugin()); // 消费事件 - -await kernel.bootstrap(); - -// 触发数据操作，自动触发工作流 -const db = kernel.getService('db'); -await db.insert('orders', { - customer: 'John', - total: 299.99, - status: 'pending' -}); -// → 自动触发 'process_order' 工作流 -``` - -## ✅ 特性 2: UI 引擎动态挂载 - -### 架构说明 - -UI Engine 通过服务注册表获取 HTTP Server，然后动态注册路由。 - -### 实现示例 - -```typescript -export class UiEnginePlugin implements Plugin { - name = 'com.objectstack.engine.ui'; - dependencies = ['com.objectstack.server.hono']; // 依赖 HTTP 服务器 - - async init(ctx: PluginContext) { - // 注册 UI 引擎服务 - const uiEngine = { - renderPage: (route: string, data: any) => { - return ` - - ObjectStack - ${route} - -

Current Route: ${route}

- 
${JSON.stringify(data, null, 2)}
- - `; - } - }; - - ctx.registerService('ui-engine', uiEngine); - } - - async start(ctx: PluginContext) { - // 获取 HTTP 服务器 - const app = ctx.getService('http-server'); - const uiEngine = ctx.getService('ui-engine'); - - // 注册 UI 路由 - app.get('/app/*', (c) => { - const html = uiEngine.renderPage(c.req.path, { - timestamp: new Date().toISOString() - }); - return c.html(html); - }); - - // 注册列表视图路由 - app.get('/ui/list/:object', (c) => { - const objectName = c.req.param('object'); - const html = uiEngine.renderPage(`/ui/list/${objectName}`, { - object: objectName, - view: 'list' - }); - return c.html(html); - }); - - // 注册表单视图路由 - app.get('/ui/form/:object/:id?', (c) => { - const objectName = c.req.param('object'); - const id = c.req.param('id'); - const html = uiEngine.renderPage(`/ui/form/${objectName}/${id || 'new'}`, { - object: objectName, - id: id || null, - view: 'form' - }); - return c.html(html); - }); - - console.log('[UI] Routes mounted: /app/*, /ui/list/:object, /ui/form/:object/:id'); - } -} -``` - -### 使用示例 - -```typescript -const kernel = new ObjectKernel(); - -kernel - .use(new HonoServerPlugin({ port: 3000 })) // HTTP 服务器 - .use(new UiEnginePlugin()); // UI 引擎 - -await kernel.bootstrap(); - -// 访问: -// - http://localhost:3000/app/ -// - http://localhost:3000/ui/list/contacts -// - http://localhost:3000/ui/form/orders/12345 -``` - -## ✅ 特性 3: 配置驱动加载 - -### 架构说明 - -通过 JSON 配置文件定义要加载的插件，实现真正的 "低代码" 平台特性。 - -### 配置文件格式 - -```json -{ - "version": "1.0.0", - "plugins": [ - { - "name": "objectstack-objectql", - "enabled": true, - "options": { - "env": "production" - } - }, - { - "name": "objectstack-data", - "enabled": true, - "options": { - "enableHooks": true - } - }, - { - "name": "objectstack-flow", - "enabled": false - }, - { - "name": "objectstack-ui", - "enabled": true - } - ] -} -``` - -### 配置加载器实现 - -```typescript -// 插件注册表 -export class PluginRegistry { - private static registry = new Map Plugin>(); - - static register(name: string, factory: () => Plugin) { - this.registry.set(name, factory); - } - - static get(name: string) { - return this.registry.get(name); - } -} - -// 从配置创建内核 -export async function createKernelFromConfig(configPath: string) { - const config = JSON.parse(readFileSync(configPath, 'utf-8')); - const kernel = new ObjectKernel(); - - for (const pluginConfig of config.plugins) { - if (!pluginConfig.enabled) { - console.log(`Skipping disabled plugin: ${pluginConfig.name}`); - continue; - } - - const factory = PluginRegistry.get(pluginConfig.name); - if (!factory) { - console.warn(`Plugin not found: ${pluginConfig.name}`); - continue; - } - - const plugin = factory(); - kernel.use(plugin); - console.log(`✅ Loaded: ${pluginConfig.name}`); - } - - return kernel; -} -``` - -### 使用示例 - -```typescript -// 1. 注册所有可用的插件 -PluginRegistry.register('objectstack-objectql', () => new ObjectQLPlugin()); -PluginRegistry.register('objectstack-data', () => new DataEnginePlugin()); -PluginRegistry.register('objectstack-flow', () => new FlowEnginePlugin()); -PluginRegistry.register('objectstack-ui', () => new UiEnginePlugin()); - -// 2. 从配置文件创建内核 -const kernel = await createKernelFromConfig('./objectstack.config.json'); - -// 3. 启动 -await kernel.bootstrap(); -``` - -### 配置驱动的优势 - -✅ **无需修改代码**: 只需修改 JSON 文件 -✅ **环境特定配置**: 开发/测试/生产环境不同配置 -✅ **按需加载**: 只加载需要的插件 -✅ **版本控制友好**: 配置文件可以版本管理 - -## 完整示例 - -### 场景：订单处理系统 - -```typescript -// 1. 注册插件 -PluginRegistry.register('objectstack-objectql', () => new ObjectQLPlugin()); -PluginRegistry.register('objectstack-data', () => new DataEnginePlugin()); -PluginRegistry.register('objectstack-server', () => new HonoServerPlugin({ port: 3000 })); -PluginRegistry.register('objectstack-flow', () => new FlowEnginePlugin()); -PluginRegistry.register('objectstack-ui', () => new UiEnginePlugin()); - -// 2. 从配置加载 -const kernel = await createKernelFromConfig('./objectstack.config.json'); -await kernel.bootstrap(); - -// 3. 使用 -const db = kernel.getService('db'); - -// 创建订单 → 自动触发工作流 → UI 可以查看 -await db.insert('orders', { - customer: 'Alice', - items: ['Product A', 'Product B'], - total: 599.99, - status: 'pending' -}); - -// Flow Engine 自动执行: -// - 库存检查 -// - 支付处理 -// - 发货通知 -// - 邮件通知 - -// UI Engine 提供: -// - 订单列表: http://localhost:3000/ui/list/orders -// - 订单详情: http://localhost:3000/ui/form/orders/12345 -``` - -## 进阶模式 - -### 1. 条件化工作流 - -```typescript -ctx.hook('data:record:afterCreate', async ({ table, data }) => { - // 根据数据触发不同的流程 - if (table === 'orders') { - if (data.total > 1000) { - await executeFlow('vip_order_processing', data); - } else { - await executeFlow('standard_order_processing', data); - } - } -}); -``` - -### 2. 多环境配置 - -```json -// objectstack.dev.json -{ - "plugins": [ - { "name": "objectstack-data", "enabled": true }, - { "name": "objectstack-flow", "enabled": false } // 开发环境禁用 - ] -} - -// objectstack.prod.json -{ - "plugins": [ - { "name": "objectstack-data", "enabled": true }, - { "name": "objectstack-flow", "enabled": true } // 生产环境启用 - ] -} -``` - -### 3. 动态插件选项 - -```typescript -// 根据配置传递选项给插件 -const kernel = new ObjectKernel(); - -for (const cfg of config.plugins) { - const factory = PluginRegistry.get(cfg.name); - const plugin = factory(cfg.options); // 传递选项 - kernel.use(plugin); -} -``` - -## 总结 - -✅ **事件驱动**: 已完全实现，通过 `hook()` 和 `trigger()` -✅ **UI 挂载**: 已完全支持，通过服务注册表获取 HTTP 服务器 -✅ **配置加载**: 提供完整的参考实现和示例 - -**当前 MiniKernel 架构已经具备生产环境所需的所有核心能力！** - -## 参考文件 - -- 完整示例: `/examples/complete-event-driven-example.ts` -- Flow Engine: `/examples/flow-engine-plugin.ts` -- Data Engine: `/examples/data-engine-plugin.ts` -- UI Engine: `/examples/ui-engine-plugin.ts` -- 配置加载器: `/examples/config-loader.ts` -- 配置示例: `/examples/objectstack.config.json` diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 6a851abd5..000000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,558 +0,0 @@ -# ObjectStack Protocol - Architecture Diagrams - -> Visual reference for understanding the complete ObjectStack ecosystem and protocol layers. - ---- - -## 🏗️ Three-Layer Architecture - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ ObjectUI (View Layer) │ -│ Server-Driven UI Protocol - Define "How Users Interact" │ -├─────────────────────────────────────────────────────────────────┤ -│ • App & Navigation • Dashboard & Widgets │ -│ • ListView (Grid/Kanban) • FormView (Simple/Tabbed) │ -│ • Report & Analytics • Action Buttons │ -│ • Page Layouts • Theme Configuration │ -└─────────────────────────────────────────────────────────────────┘ - ▲ - │ Render - │ -┌─────────────────────────────────────────────────────────────────┐ -│ ObjectOS (Control Layer) │ -│ Runtime Kernel - Define "How System Operates" │ -├─────────────────────────────────────────────────────────────────┤ -│ • Manifest & Packaging • Identity & Roles (IAM) │ -│ • Plugin Lifecycle • Event Bus & Jobs │ -│ • API Gateway (Rest/GQL)• Real-time (Socket/SSE) │ -│ • Multi-tenancy • Audit & Compliance │ -└─────────────────────────────────────────────────────────────────┘ - ▲ - │ Execute - │ -┌─────────────────────────────────────────────────────────────────┐ -│ ObjectQL (Data Layer) │ -│ Business Kernel - Define "What Data Exists" │ -├─────────────────────────────────────────────────────────────────┤ -│ • Object & Field Schema • AI Agents & Orchestration │ -│ • Query AST (Filter/Sort) • RAG & Vector Search │ -│ • Validation Rules • Permission & Sharing │ -│ • Workflow & Flow • Driver & Datasource (IO) │ -└─────────────────────────────────────────────────────────────────┘ -│ driver-postgres │ driver-mongodb │ driver-salesforce │ -│ driver-mysql │ driver-redis │ driver-excel │ -│ driver-sqlite │ driver-s3 │ driver-airtable │ -└─────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 📦 Package Structure & Protocol Flow - -``` -@objectstack/spec -├── Data Protocol (ObjectQL) -│ ├── field.zod.ts → Field types, constraints, relationships -│ ├── object.zod.ts → Object definition, capabilities -│ ├── validation.zod.ts → Business rules, error messages -│ ├── permission.zod.ts → CRUD, field-level security -│ ├── sharing.zod.ts → Sharing rules, ownership -│ ├── workflow.zod.ts → State machine, transitions -│ ├── flow.zod.ts → Visual flow automation -│ ├── query.zod.ts → AST for queries (filter, sort, join) -│ ├── filter.zod.ts → Query filter conditions -│ ├── dataset.zod.ts → Virtual datasets -│ ├── mapping.zod.ts → ETL transformations -│ └── trigger.zod.ts → Trigger context -│ -├── UI Protocol (ObjectUI) -│ ├── app.zod.ts → App structure, navigation tree -│ ├── view.zod.ts → List/Form/Calendar views -│ ├── dashboard.zod.ts → Dashboard layouts, widgets -│ ├── report.zod.ts → Report types, grouping -│ ├── action.zod.ts → Button actions, navigation -│ ├── page.zod.ts → FlexiPage regions, components -│ ├── theme.zod.ts → Color, typography, spacing -│ └── widget.zod.ts → Custom field components -│ -├── System Protocol (ObjectOS) -│ ├── manifest.zod.ts → Package definition (objectstack.config.ts) -│ ├── datasource.zod.ts → External data connections -│ ├── api.zod.ts → REST/GraphQL contracts -│ ├── identity.zod.ts → User, session management -│ ├── role.zod.ts → RBAC definitions -│ ├── policy.zod.ts → Global policies -│ ├── territory.zod.ts → Territory hierarchy -│ ├── license.zod.ts → License types, restrictions -│ ├── webhook.zod.ts → HTTP callbacks -│ ├── translation.zod.ts → i18n definitions -│ ├── discovery.zod.ts → Metadata introspection -│ ├── plugin.zod.ts → Plugin lifecycle -│ ├── driver.zod.ts → Database driver interface -│ ├── tenant.zod.ts → Multi-tenancy -│ ├── events.zod.ts → Event bus -│ ├── realtime.zod.ts → WebSocket sync -│ ├── organization.zod.ts → Organization management -│ ├── audit.zod.ts → Audit logging -│ └── job.zod.ts → Background jobs -│ -├── AI Protocol -│ ├── agent.zod.ts → AI agent configuration -│ ├── model-registry.zod.ts → LLM registry -│ ├── rag-pipeline.zod.ts → RAG pipeline -│ ├── nlq.zod.ts → Natural language query -│ ├── conversation.zod.ts → Conversation management -│ ├── cost.zod.ts → AI cost tracking -│ ├── predictive.zod.ts → Predictive analytics -│ └── workflow-automation.zod.ts → AI workflow automation -│ -└── API Protocol - └── contract.zod.ts → Request/response envelopes -``` - ---- - -## 🔄 Data Flow: User Request to Database - -``` -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ │ │ │ │ │ │ │ │ │ -│ Browser │─────▶│ ObjectUI │─────▶│ ObjectOS │─────▶│ ObjectQL │─────▶│ Driver │ -│ │ │ │ │ │ │ │ │ │ -└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ - │ │ │ │ │ - │ │ │ │ │ - ▼ ▼ ▼ ▼ ▼ -User clicks Lookup view Check user Parse query Execute SQL -"Show Accounts" definition from permissions to AST on Postgres - app.navigation (role-based) (filter/sort) - - Apply field- Optimize Return rows - level security (joins/index) - - Run triggers Generate SQL - (beforeFind) dialect -``` - -### Detailed Steps: - -1. **User Interaction** (Browser) - - User clicks "Accounts" in navigation - - Browser sends: `GET /api/data/account?view=all` - -2. **UI Resolution** (ObjectUI) - - Lookup `app.navigation` → find `ObjectNavItem(objectName: "account")` - - Lookup `view.zod` → find ListView definition for "all" view - - Determine columns, filters, sort order - -3. **Security Check** (ObjectOS) - - Validate user session (JWT token) - - Check `role.zod` → user has "read" permission on "account"? - - Check `permission.zod` → field-level security (hide SSN field) - - Apply sharing rules (only show accounts owned by user's team) - -4. **Query Translation** (ObjectQL) - - Parse filters from UI → Query AST - - Apply validation rules - - Run triggers: `beforeFind(ctx)` - - Optimize query (index hints) - -5. **Database Execution** (Driver) - - Driver translates AST → SQL dialect (Postgres, MySQL, etc.) - - Execute query with connection pooling - - Return raw rows - -6. **Response Formatting** (ObjectOS → ObjectUI) - - Format response per `api/contract.zod` schema - - Apply field formatting (currency, date) - - Return JSON to browser - -7. **Rendering** (Browser) - - React/Vue/Svelte renders ListView component - - Display grid with pagination - ---- - -## 🧩 Plugin Architecture - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ ObjectStack Kernel │ -│ (ObjectOS Runtime) │ -└─────────────────────────────────────────────────────────────────┘ - ▲ - │ - │ Plugin Lifecycle Hooks - │ (onInstall, onEnable, onDisable) - │ - ┌─────────────────────┴─────────────────────┐ - │ │ - ▼ ▼ -┌───────────────────┐ ┌───────────────────┐ -│ Plugin: CRM │ │ Plugin: BI │ -├───────────────────┤ ├───────────────────┤ -│ • Objects │ │ • Objects │ -│ - Account │ │ - Report │ -│ - Contact │ │ - Dataset │ -│ │ │ │ -│ • Views │ │ • Views │ -│ - AccountList │ │ - ReportBuilder │ -│ - ContactForm │ │ │ -│ │ │ • Actions │ -│ • Dashboards │ │ - ExportToExcel │ -│ - SalesPipeline │ │ - ScheduleReport│ -│ │ │ │ -│ • APIs │ │ • Drivers │ -│ - /convert-lead │ │ - driver-excel │ -│ │ │ - driver-bigquery│ -└───────────────────┘ └───────────────────┘ - -Each plugin: -1. Declares manifest (objectstack.config.ts) -2. Exports objects, views, dashboards, etc. -3. Implements lifecycle hooks (optional) -4. Receives runtime context (ctx.ql, ctx.os, ctx.logger) -5. Can extend existing objects (add fields) -6. Can register custom field widgets -``` - ---- - -## 📦 Package Types & Microkernel Architecture - -ObjectStack follows a **microkernel architecture** where different package types serve distinct roles in the system lifecycle. The `type` field in the manifest (`objectstack.config.ts`) determines a package's role and initialization order. - -### Package Type Hierarchy - -``` -External Request (Browser/Mobile) - │ - ▼ -[ adapter ] ←─ HTTP Server Container (Express, Hono, Fastify, Serverless) - │ • Role: Runtime host/container - │ • Cardinality: Singleton (one per runtime) - │ • Examples: @objectstack/adapter-express, @objectstack/adapter-hono - ▼ -[ gateway ] ←─ API Protocol Layer (GraphQL, REST, RPC, OData) - │ • Role: Protocol translation - │ • Cardinality: Multiple (can coexist) - │ • Examples: @objectstack/gateway-graphql, @objectstack/gateway-rest - ▼ -[ Kernel ] ←─ Core orchestration (ObjectOS Runtime) - │ - ▼ -[ objectql] ←─ Core Data Engine - │ • Role: Query engine and business logic layer - │ • Examples: @objectstack/objectql - ▼ -[ driver ] ←─ Southbound: Database/External Service Adapters - │ • Role: Data persistence and external integrations - │ • Examples: @objectstack/driver-postgres, @objectstack/driver-mongodb - ▼ - Database -``` - -### Package Type Definitions - -| Type | Description | Cardinality | Layer | Examples | -|:-----|:------------|:------------|:------|:---------| -| **adapter** | Runtime container - HTTP server adapter | Singleton | Outermost | Express, Hono, Fastify, Lambda | -| **gateway** | API protocol entry point | Multiple | North | GraphQL, REST, RPC, OData | -| **objectql** | Core data engine implementation | Singleton | Core | Query engine, business logic | -| **driver** | Database/external service adapter | Multiple | South | Postgres, MongoDB, S3, Salesforce | -| **plugin** | General-purpose functionality extension | Multiple | App | CRM, BI, Analytics | -| **app** | Business application package | Multiple | App | Sales App, Service App | -| **module** | Reusable code library/shared module | Multiple | Lib | Utilities, helpers | - -### Lifecycle Ordering - -The kernel initializes packages in a specific order to ensure proper dependency resolution: - -1. **Adapter** preparation (HTTP server setup) -2. **ObjectQL** engine initialization (core data layer) -3. **Driver** connections (database, external services) -4. **Gateway** registration (API protocol handlers) -5. **App/Plugin** loading (business logic) - -This ordering ensures that: -- The HTTP server is ready before routes are registered -- The data engine is initialized before drivers connect -- Drivers are connected before gateways need to query data -- Gateways are ready before apps register business endpoints - -### Adapter vs Gateway Distinction - -**Key Architectural Difference:** - -- **Adapter** = The "what" and "where" (which HTTP framework, which runtime environment) - - Handles raw HTTP Request/Response objects - - Manages server lifecycle (listen, close) - - One adapter per runtime instance - - Cannot coexist (can't run Express + Hono on same port) - -- **Gateway** = The "how" (which API protocol) - - Translates protocol to internal `Call` format - - Multiple gateways can coexist - - Registers routes on the adapter - - Example: Same server can expose both GraphQL and REST APIs - ---- - -## 🔐 Security & Permission Model - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Permission Evaluation Flow │ -└─────────────────────────────────────────────────────────────────┘ - -Request: user.read('account', id=123) - │ - ├──▶ Step 1: Object-Level Permission (CRUD) - │ role.zod: Does user's role allow "read" on "account"? - │ ├── ✅ Yes → Continue - │ └── ❌ No → Return 403 Forbidden - │ - ├──▶ Step 2: Sharing Rules - │ sharing.zod: Is record owned by user or shared with them? - │ ├── ✅ Yes → Continue - │ └── ❌ No → Return 404 Not Found (hide existence) - │ - ├──▶ Step 3: Field-Level Security - │ permission.zod: Which fields can user read? - │ Example: Hide "annual_revenue" for non-managers - │ ├── Filter out restricted fields - │ └── Continue with allowed fields - │ - ├──▶ Step 4: Validation Rules - │ validation.zod: Check conditional visibility - │ Example: "Show SSN only if country = USA" - │ - ├──▶ Step 5: Territory Hierarchy - │ territory.zod: Check geographic access - │ Example: "APAC sales can only see APAC accounts" - │ - └──▶ Step 6: Policy Enforcement - policy.zod: Global data access policies - Example: "No access to records older than 7 years (GDPR)" - - ✅ All checks passed → Return record with allowed fields -``` - ---- - -## 🤖 AI Integration Architecture - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ AI-Powered Features │ -└─────────────────────────────────────────────────────────────────┘ - -1. Natural Language Query (NLQ) - User: "Show me all accounts in California with revenue > $1M" - │ - ├──▶ AI Model (GPT-4, Claude) - │ Prompt: "Convert to ObjectQL AST" - │ - └──▶ Generated AST: - { - object: "account", - filters: [ - { field: "state", operator: "=", value: "CA" }, - { field: "annual_revenue", operator: ">", value: 1000000 } - ] - } - -2. Auto-Schema Generation - User: "Create a project management app" - │ - ├──▶ AI Agent (agent.zod.ts) - │ Context: ObjectStack protocol documentation - │ - └──▶ Generated Schemas: - - object/project.ts (name, status, due_date) - - object/task.ts (title, assigned_to, project_id) - - view/project_kanban.ts - - dashboard/project_stats.ts - -3. Intelligent Suggestions - User: Creating a "Contact" object - │ - ├──▶ RAG Pipeline (rag.zod.ts) - │ Query similar objects in knowledge base - │ - └──▶ Suggestions: - - "Add 'phone' field (used in 95% of contact objects)" - - "Add lookup to 'account' (common pattern)" - - "Enable field history tracking?" - -4. Code Generation - User: "Add validation: email must be unique" - │ - ├──▶ AI Model + Protocol Knowledge - │ - └──▶ Generated validation.zod.ts: - { - name: "unique_email", - condition: "!DUPLICATE(email)", - errorMessage: "Email already exists", - active: true - } -``` - ---- - -## 🚀 Deployment Topologies - -### Topology 1: Monolith (Single Server) -``` -┌─────────────────────────────────────┐ -│ Single VM/Container │ -├─────────────────────────────────────┤ -│ ┌─────────────────────────────┐ │ -│ │ ObjectStack Kernel │ │ -│ │ (ObjectOS + All Plugins) │ │ -│ └─────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌─────────────────────────────┐ │ -│ │ PostgreSQL Database │ │ -│ └─────────────────────────────┘ │ -└─────────────────────────────────────┘ - -Use Case: Small teams, prototyping, local development -``` - -### Topology 2: Multi-Tenant SaaS -``` -┌──────────────────────────────────────────────────────────┐ -│ Load Balancer (NGINX) │ -└──────────────────────────────────────────────────────────┘ - │ │ │ - ▼ ▼ ▼ - ┌────────┐ ┌────────┐ ┌────────┐ - │ Kernel │ │ Kernel │ │ Kernel │ ◀── Stateless - │ #1 │ │ #2 │ │ #3 │ - └────────┘ └────────┘ └────────┘ - │ │ │ - └───────────────┴───────────────┘ - │ - ▼ - ┌───────────────────────────────┐ - │ PostgreSQL (Multi-tenant) │ - │ • tenant_id on every table │ - │ • Row-level security (RLS) │ - └───────────────────────────────┘ - │ - ▼ - ┌───────────────────────────────┐ - │ Redis (Session, Cache) │ - └───────────────────────────────┘ - -Use Case: SaaS providers, high availability -``` - -### Topology 3: Microservices (Enterprise) -``` -┌─────────────────────────────────────────────────────────────┐ -│ API Gateway (Kong) │ -│ Rate Limiting, Auth, Routing │ -└─────────────────────────────────────────────────────────────┘ - │ │ │ │ - ▼ ▼ ▼ ▼ - ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ - │ Data │ │ Auth │ │ Flow │ │Workflow│ - │Service │ │Service │ │ Engine │ │ Engine │ - └────────┘ └────────┘ └────────┘ └────────┘ - │ │ │ │ - └───────────────┴───────────────┴───────────────┘ - │ - ▼ - ┌───────────────────────┐ - │ Event Bus (Kafka) │ - └───────────────────────┘ - │ - ┌───────────────────────┼───────────────────────┐ - ▼ ▼ ▼ - ┌────────┐ ┌────────┐ ┌────────┐ - │Postgres│ │ Redis │ │ S3 │ - │ (Data) │ │(Cache) │ │(Files) │ - └────────┘ └────────┘ └────────┘ - -Use Case: Large enterprises, high scale, service isolation -``` - ---- - -## 📊 Protocol Dependency Graph - -``` - ┌──────────────┐ - │ manifest │ (Root - defines app) - └──────────────┘ - │ - ┌───────────┼───────────┐ - ▼ ▼ ▼ - ┌──────────┐ ┌──────────┐ ┌──────────┐ - │ object │ │ app │ │ datasource│ - └──────────┘ └──────────┘ └──────────┘ - │ │ │ - ┌───────┼────┐ │ └──▶ driver - ▼ ▼ ▼ │ - ┌─────┐ ┌────┐ ┌────┐ │ - │field│ │perm│ │flow│ │ - └─────┘ └────┘ └────┘ │ - │ │ │ │ - ▼ ▼ ▼ ▼ - ┌─────────────────────────┐ - │ validation, workflow │ - └─────────────────────────┘ - │ - ▼ - ┌──────────┐ - │ query │ (AST - universal query language) - └──────────┘ - -Dependencies (imports): -• object.zod.ts imports field.zod.ts -• validation.zod.ts imports field.zod.ts -• permission.zod.ts imports object.zod.ts -• app.zod.ts imports object.zod.ts, dashboard.zod.ts -• manifest.zod.ts imports object.zod.ts, app.zod.ts, datasource.zod.ts -``` - ---- - -## 🌐 Cross-Platform Rendering - -``` - ┌──────────────────────┐ - │ ObjectUI Protocol │ - │ (Platform Agnostic) │ - └──────────────────────┘ - │ - ┌──────────────┼──────────────┐ - ▼ ▼ ▼ - ┌───────────┐ ┌───────────┐ ┌───────────┐ - │ Web │ │ Mobile │ │ Desktop │ - │ Renderer │ │ Renderer │ │ Renderer │ - └───────────┘ └───────────┘ └───────────┘ - │ │ │ - ▼ ▼ ▼ - ┌───────────┐ ┌───────────┐ ┌───────────┐ - │ React │ │ React │ │ Electron │ - │ +Tailwind│ │ Native │ │ +React │ - └───────────┘ └───────────┘ └───────────┘ - -Same Protocol → Different Renderers: -• view.zod → React grid component (Web) -• view.zod → FlatList component (Mobile) -• view.zod → Electron table widget (Desktop) -``` - ---- - -**For more details, see:** -- [DEVELOPMENT_ROADMAP.md](./internal/planning/DEVELOPMENT_ROADMAP.md) - Complete development plan -- [PRIORITIES.md](./internal/planning/PRIORITIES.md) - What to work on next -- [packages/spec/README.md](./packages/spec/README.md) - Technical documentation diff --git a/MINI_KERNEL_ARCHITECTURE.md b/MINI_KERNEL_ARCHITECTURE.md deleted file mode 100644 index e1ae122f9..000000000 --- a/MINI_KERNEL_ARCHITECTURE.md +++ /dev/null @@ -1,382 +0,0 @@ -# ObjectStack MiniKernel 架构图 - -## 1. 总体架构 (Overall Architecture) - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Application Layer │ -│ (Business Logic, User Plugins, Custom Integrations) │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ Plugin Layer │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ ObjectQL │ │ Driver │ │ Hono │ │ Flow │ │ -│ │ Plugin │ │ Plugin │ │ Server │ │ Engine │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ REST │ │ GraphQL │ │ Cache │ │ Auth │ │ -│ │ API │ │ API │ │ Plugin │ │ Plugin │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ ObjectKernel (MiniKernel) │ -│ ┌────────────────┐ ┌────────────────┐ ┌──────────────┐ │ -│ │ Service │ │ Lifecycle │ │ Hook │ │ -│ │ Registry │ │ Management │ │ System │ │ -│ │ (DI) │ │ (init/start) │ │ (Events) │ │ -│ └────────────────┘ └────────────────┘ └──────────────┘ │ -│ │ -│ ┌────────────────────────────────────────────────────────┐ │ -│ │ Dependency Resolution (Topological Sort) │ │ -│ └────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ Infrastructure │ -│ (Node.js Runtime, TypeScript, Zod, etc.) │ -└─────────────────────────────────────────────────────────────┘ -``` - -## 2. 插件生命周期 (Plugin Lifecycle) - -``` - IDLE - │ - ▼ - use(plugin) ────┐ - │ │ - │ │ (可以注册多个插件) - │ │ - │◄──────────┘ - │ - ▼ - bootstrap() - │ - ├─── Phase 1: INIT ────────────────┐ - │ (按依赖顺序) │ - │ │ - │ Plugin A: init(ctx) │ - │ ├─ ctx.registerService('a') │ - │ └─ 准备资源 │ - │ │ - │ Plugin B: init(ctx) │ - │ ├─ ctx.registerService('b') │ - │ └─ ctx.getService('a') │ - │ │ - │ Plugin C: init(ctx) │ - │ └─ ctx.getService('b') │ - │ │ - ├─── Phase 2: START ───────────────┤ - │ (按依赖顺序) │ - │ │ - │ Plugin A: start(ctx) │ - │ ├─ 启动服务器 │ - │ └─ 连接数据库 │ - │ │ - │ Plugin B: start(ctx) │ - │ └─ 注册路由 │ - │ │ - │ Plugin C: start(ctx) │ - │ └─ 启动定时任务 │ - │ │ - ├─── Phase 3: KERNEL READY ────────┤ - │ │ - │ trigger('kernel:ready') │ - │ ├─ Hook Handler 1 │ - │ ├─ Hook Handler 2 │ - │ └─ Hook Handler 3 │ - │ │ - └───────────────────────────────────┘ - │ - ▼ - RUNNING - │ - ▼ - shutdown() - │ - ├─── DESTROY (反向顺序) ────────────┐ - │ │ - │ Plugin C: destroy() │ - │ Plugin B: destroy() │ - │ Plugin A: destroy() │ - │ │ - └───────────────────────────────────┘ - │ - ▼ - STOPPED -``` - -## 3. 服务注册表 (Service Registry) - -``` -┌─────────────────────────────────────────────────────────┐ -│ PluginContext │ -│ │ -│ ┌────────────────────────────────────────────────┐ │ -│ │ Service Registry (Map) │ │ -│ │ │ │ -│ │ ┌──────────────┬──────────────────────────┐ │ │ -│ │ │ Service Name │ Service Instance │ │ │ -│ │ ├──────────────┼──────────────────────────┤ │ │ -│ │ │ 'objectql' │ ObjectQL Instance │ │ │ -│ │ │ 'db' │ Database Connection │ │ │ -│ │ │ 'http-server'│ Hono App Instance │ │ │ -│ │ │ 'cache' │ Cache Manager │ │ │ -│ │ │ 'logger' │ Winston Logger │ │ │ -│ │ └──────────────┴──────────────────────────┘ │ │ -│ │ │ │ -│ │ Methods: │ │ -│ │ • registerService(name, service) │ │ -│ │ • getService(name): T │ │ -│ └────────────────────────────────────────────────┘ │ -│ │ -│ Plugin A Plugin B │ -│ ┌─────────┐ ┌─────────┐ │ -│ │ │ │ │ │ -│ │ init() │───┬────────│ start() │ │ -│ │ │ │ │ │ │ -│ └─────────┘ │ └─────────┘ │ -│ │ │ │ -│ register │ │ consume │ -│ Service │ │ │ -│ │ │ │ -│ ▼ ▼ │ -│ registerService getService │ -│ │ -└─────────────────────────────────────────────────────────┘ -``` - -## 4. 依赖解析 (Dependency Resolution) - -``` -注册顺序 (Registration Order): -┌────────┐ ┌────────┐ ┌────────┐ -│Plugin C│→ │Plugin B│→ │Plugin A│ -└────────┘ └────────┘ └────────┘ - │ │ │ - │ │ └── dependencies: [] - │ └── dependencies: ['plugin-a'] - └── dependencies: ['plugin-b'] - -依赖图 (Dependency Graph): - ┌────────┐ - │Plugin A│ (无依赖) - └────┬───┘ - │ depends on - ▼ - ┌────────┐ - │Plugin B│ - └────┬───┘ - │ depends on - ▼ - ┌────────┐ - │Plugin C│ - └────────┘ - -拓扑排序后的初始化顺序 (Topological Sort): -1. Plugin A (init → start) -2. Plugin B (init → start) -3. Plugin C (init → start) - -错误检测 (Error Detection): -循环依赖: -A → B → C → A ❌ Error: Circular dependency - -缺失依赖: -A requires 'non-existent' ❌ Error: Dependency not found -``` - -## 5. 钩子系统 (Hook System) - -``` -┌─────────────────────────────────────────────────────────┐ -│ Hook Registry (Map) │ -│ │ -│ ┌──────────────────┬─────────────────────────────┐ │ -│ │ Hook Name │ Handlers (Array) │ │ -│ ├──────────────────┼─────────────────────────────┤ │ -│ │ 'kernel:ready' │ [handler1, handler2, ...] │ │ -│ │ 'data:insert' │ [validator, logger, ...] │ │ -│ │ 'http:request' │ [auth, cors, ...] │ │ -│ └──────────────────┴─────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ - -事件流 (Event Flow): - -Plugin A Plugin B Plugin C - │ │ │ - │ ctx.hook('event') │ │ - ├──────────────────────►│ │ - │ │ │ - │ │ ctx.hook('event') │ - │ ├──────────────────────►│ - │ │ │ - │ │ - │ ctx.trigger('event', data) │ - ├───────────────────────────────────────────────► - │ │ │ - │ handler1(data) │ - │ │ │ - │ handler2(data) │ - │ │ │ - │◄──────────────────────┴───────────────────────┘ - │ -``` - -## 6. ObjectQL 插件化 (ObjectQL as Plugin) - -``` -Plugin-based Architecture: -┌─────────────────────┐ -│ ObjectKernel │ -│ (MiniKernel) │ -│ │ -│ Service Registry: │ -│ ┌───────────────┐ │ -│ │ 'objectql' │ │ ← 注册为服务 -│ │ → ObjectQL │ │ -│ └───────────────┘ │ -│ │ -└─────────────────────┘ - ▲ - │ - ┌─────┴──────┐ - │ ObjectQL │ - │ Plugin │ ← 可替换的插件 - └────────────┘ - -优势: -1. ✅ ObjectQL 可以被替换 -2. ✅ 可以提供自定义 ObjectQL 实例 -3. ✅ 测试时可以 Mock -4. ✅ 插件间平等关系 -``` - -## 7. 实际应用示例 (Real-world Example) - -``` -┌─────────────────────────────────────────────────────────┐ -│ ObjectKernel │ -└─────────────────────────────────────────────────────────┘ - │ - ┌─────────────────┼─────────────────┐ - │ │ │ - ▼ ▼ ▼ -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ ObjectQL │ │ Memory │ │ Hono │ -│ Plugin │ │ Driver │ │ Server │ -│ │ │ Plugin │ │ Plugin │ -└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ - │ │ │ - │ init: │ init: │ init: - │ register │ get objectql │ register - │ 'objectql' │ register driver │ 'http-server' - │ │ │ - │ start: │ │ start: - │ init engine │ │ setup routes - │ │ │ listen on port - │ │ │ - └─────────────────┴─────────────────┘ - │ - ▼ - trigger('kernel:ready') - │ - ▼ - ┌──────────────────┐ - │ Server Starts │ - │ on Port 3000 │ - └──────────────────┘ -``` - -## 8. 插件通信模式 (Plugin Communication Patterns) - -``` -模式 1: 服务注册与消费 (Service Registry) -─────────────────────────────────────────── -Provider Plugin Consumer Plugin - │ │ - │ init() │ - ├─ registerService() │ - │ │ - │ start() - │ ├─ getService() - │ │ - └────────────────────────┘ - -模式 2: 事件钩子 (Event Hooks) -─────────────────────────────────────────── -Publisher Plugin Subscriber Plugin - │ │ - │ init() - │ ├─ hook('event') - │ │ - │ start() │ - ├─ trigger('event') │ - │ │ │ - │ └──────────────►│ - │ handler() - │ │ - -模式 3: 依赖声明 (Dependency Declaration) -─────────────────────────────────────────── -Plugin A Plugin B -dependencies: [] dependencies: ['plugin-a'] - │ │ - │ init() │ - │ │ - └────────┬───────────────┘ - │ - (Kernel 保证 A 先初始化) -``` - -## 9. 扩展路径 (Extension Paths) - -``` -当前架构 (Current): -ObjectKernel → Plugin Interface → Built-in Plugins - -未来扩展 (Future): - -1. 配置化加载 (Config-based Loading) - ┌─────────────────────┐ - │ objectstack.config │ - │ { │ - │ plugins: [ │ - │ "objectql", │ - │ "hono-server", │ - │ "my-plugin" │ - │ ] │ - │ } │ - └──────────┬──────────┘ - │ - ▼ - Kernel.loadFromConfig() - -2. 插件市场 (Plugin Marketplace) - npm install @company/custom-plugin - │ - ▼ - kernel.use(CustomPlugin) - -3. 热加载 (Hot Reload) - kernel.reload('plugin-name') - │ - ▼ - destroy() → init() → start() - -4. 沙箱隔离 (Sandboxing) - ┌──────────────────┐ - │ User Script │ - │ (Isolated VM) │ - └──────────────────┘ -``` - -## License - -Apache-2.0 diff --git a/MINI_KERNEL_GUIDE.md b/MINI_KERNEL_GUIDE.md deleted file mode 100644 index f1ffa8a4a..000000000 --- a/MINI_KERNEL_GUIDE.md +++ /dev/null @@ -1,344 +0,0 @@ -# MiniKernel Architecture Guide - -## Overview - -ObjectStack now supports a **MiniKernel (Microkernel) Architecture** that provides: - -- **High Modularity**: Business logic is completely separated into plugins -- **Dependency Injection**: Service registry for inter-plugin communication -- **Event/Hook System**: Publish-subscribe mechanism for loose coupling -- **Lifecycle Management**: Standardized init/start/destroy phases -- **Dependency Resolution**: Automatic topological sorting based on plugin dependencies - -## Core Concepts - -### 1. Kernel - -The `ObjectKernel` is a minimal orchestrator that: -- Loads and manages plugins -- Provides a shared context (`PluginContext`) -- Handles lifecycle phases (init → start → running) -- Resolves plugin dependencies automatically - -### 2. Plugin - -Plugins are independent modules with a standard interface: - -```typescript -interface Plugin { - name: string; // Unique identifier - version?: string; // Plugin version - dependencies?: string[]; // List of required plugin names - - init(ctx: PluginContext): Promise; // Register services - start?(ctx: PluginContext): Promise; // Execute business logic - destroy?(): Promise; // Cleanup -} -``` - -### 3. PluginContext - -The context provides plugins access to: -- **Service Registry**: `registerService()`, `getService()` -- **Event System**: `hook()`, `trigger()` -- **Logger**: Console-based logging - -## Plugin Lifecycle - -``` -1. INIT PHASE - ├── Plugin A: init() → Register services - ├── Plugin B: init() → Register services - └── Plugin C: init() → Register services - -2. START PHASE - ├── Plugin A: start() → Execute business logic - ├── Plugin B: start() → Execute business logic - └── Plugin C: start() → Execute business logic - -3. KERNEL READY - └── Trigger 'kernel:ready' hook - -4. DESTROY PHASE (on shutdown) - ├── Plugin C: destroy() → Cleanup - ├── Plugin B: destroy() → Cleanup - └── Plugin A: destroy() → Cleanup -``` - -## Basic Usage - -### Example 1: Simple Plugin - -```typescript -import { ObjectKernel, Plugin, PluginContext } from '@objectstack/runtime'; - -class HelloPlugin implements Plugin { - name = 'hello-plugin'; - - async init(ctx: PluginContext) { - ctx.logger.log('[HelloPlugin] Initialized'); - } - - async start(ctx: PluginContext) { - ctx.logger.log('[HelloPlugin] Started'); - } -} - -const kernel = new ObjectKernel(); -kernel.use(new HelloPlugin()); -await kernel.bootstrap(); -``` - -### Example 2: Service Registration - -```typescript -class DataEnginePlugin implements Plugin { - name = 'data-engine'; - - async init(ctx: PluginContext) { - const db = { - connect: () => console.log('DB Connected'), - query: (sql: string) => `Result for ${sql}` - }; - - // Register service for other plugins - ctx.registerService('db', db); - } - - async start(ctx: PluginContext) { - const db = ctx.getService('db'); - db.connect(); - } -} -``` - -### Example 3: Plugin Dependencies - -```typescript -class ApiPlugin implements Plugin { - name = 'api-server'; - dependencies = ['data-engine', 'http-server']; // Will load after these - - async init(ctx: PluginContext) { - // Dependencies guaranteed to be initialized - } - - async start(ctx: PluginContext) { - const db = ctx.getService('db'); - const server = ctx.getService('http-server'); - - // Use services from other plugins - server.get('/api/data', () => db.query('SELECT *')); - } -} -``` - -### Example 4: Hook System - -```typescript -class ServerPlugin implements Plugin { - name = 'server'; - - async start(ctx: PluginContext) { - // Wait for kernel:ready before starting server - ctx.hook('kernel:ready', () => { - console.log('Starting HTTP server on port 3000'); - }); - } -} -``` - -## ObjectQL as a Plugin - -ObjectQL is now a first-class plugin: - -```typescript -import { ObjectKernel, ObjectQLPlugin, DriverPlugin } from '@objectstack/runtime'; - -const kernel = new ObjectKernel(); - -kernel - .use(new ObjectQLPlugin()) // Register ObjectQL engine - .use(new DriverPlugin(memoryDriver, 'memory')); // Register driver - -await kernel.bootstrap(); - -// Access ObjectQL via service registry -const objectql = kernel.getService('objectql'); -``` - -## Built-in Plugins - -### ObjectQLPlugin - -Registers the ObjectQL engine as a service. - -```typescript -new ObjectQLPlugin() // Default instance -new ObjectQLPlugin(customQL) // Custom instance -new ObjectQLPlugin(undefined, { env: 'prod' }) // With context -``` - -**Services**: `objectql` - -### DriverPlugin - -Registers a driver with ObjectQL. - -```typescript -new DriverPlugin(driver, 'driver-name') -``` - -**Dependencies**: `['com.objectstack.engine.objectql']` - -### HonoServerPlugin - -Provides HTTP server using Hono framework. - -```typescript -new HonoServerPlugin({ port: 3000, staticRoot: './public' }) -``` - -**Services**: `http-server` - -## Advanced Patterns - -### Pattern 1: Configuration-Based Loading - -```typescript -interface KernelConfig { - plugins: Array<{ - name: string; - enabled: boolean; - options?: any; - }>; -} - -async function loadFromConfig(config: KernelConfig) { - const kernel = new ObjectKernel(); - - for (const pluginCfg of config.plugins) { - if (pluginCfg.enabled) { - const plugin = await loadPlugin(pluginCfg.name, pluginCfg.options); - kernel.use(plugin); - } - } - - return kernel; -} -``` - -### Pattern 2: Plugin Factory - -```typescript -class PluginFactory { - static createDataEngine(driver: any) { - return { - name: 'data-engine', - async init(ctx: PluginContext) { - ctx.registerService('driver', driver); - } - } as Plugin; - } -} - -kernel.use(PluginFactory.createDataEngine(myDriver)); -``` - -### Pattern 3: Conditional Plugin Loading - -```typescript -const kernel = new ObjectKernel(); - -// Core plugins -kernel.use(new ObjectQLPlugin()); - -// Optional plugins based on environment -if (process.env.NODE_ENV === 'production') { - kernel.use(new MonitoringPlugin()); - kernel.use(new CachingPlugin()); -} - -if (process.env.ENABLE_API === 'true') { - kernel.use(new HonoServerPlugin()); -} -``` - -## Usage - -```typescript -import { ObjectKernel, ObjectQLPlugin, DriverPlugin } from '@objectstack/runtime'; - -const kernel = new ObjectKernel(); - -kernel - .use(new ObjectQLPlugin()) - .use(new DriverPlugin(driver)); - -// App manifest as plugin -kernel.use(appManifestPlugin); - -await kernel.bootstrap(); -``` - -## Benefits - -1. **True Modularity**: Each plugin is independent and reusable -2. **Testability**: Mock services easily in tests -3. **Flexibility**: Load plugins conditionally -4. **Extensibility**: Add new plugins without modifying kernel -5. **Clear Dependencies**: Explicit dependency declarations -6. **Better Architecture**: Separation of concerns - -## Best Practices - -1. **Keep plugins focused**: One responsibility per plugin -2. **Use services**: Share functionality via service registry -3. **Declare dependencies**: Make plugin requirements explicit -4. **Use hooks**: Decouple plugins with event system -5. **Handle errors**: Implement proper error handling in lifecycle methods -6. **Document services**: Document what services your plugin provides/consumes - -## Troubleshooting - -### Error: "Service 'xxx' not found" - -Make sure the plugin that provides the service is registered and loaded before plugins that consume it. - -### Error: "Circular dependency detected" - -Check your plugin dependencies - they form a cycle. Refactor to break the cycle. - -### Error: "Plugin 'xxx' already registered" - -You're registering the same plugin twice. Check your plugin registration code. - -## API Reference - -### ObjectKernel - -- `use(plugin: Plugin)`: Register a plugin -- `bootstrap()`: Initialize and start all plugins -- `shutdown()`: Stop all plugins in reverse order -- `getService(name: string)`: Get a service from registry -- `isRunning()`: Check if kernel is running -- `getState()`: Get current kernel state - -### PluginContext - -- `registerService(name: string, service: any)`: Register a service -- `getService(name: string)`: Get a service -- `hook(name: string, handler: Function)`: Register event handler -- `trigger(name: string, ...args: any[])`: Trigger an event -- `logger`: Console logger instance - -## Examples - -See: -- `/examples/mini-kernel-example.ts` - Basic usage -- `/test-objectql-plugin.ts` - ObjectQL plugin examples -- `/packages/plugin-hono-server/src/hono-plugin.ts` - Real plugin implementation - -## License - -Apache-2.0 diff --git a/MINI_KERNEL_IMPLEMENTATION.md b/MINI_KERNEL_IMPLEMENTATION.md deleted file mode 100644 index 4af868c18..000000000 --- a/MINI_KERNEL_IMPLEMENTATION.md +++ /dev/null @@ -1,359 +0,0 @@ -# ObjectStack MiniKernel Architecture - Implementation Summary - -## 概述 (Overview) - -本次实现将 ObjectStack 改造为基于**微内核 (MiniKernel)** 的插件化架构，实现了以下核心目标： - -1. **高度模块化**: 业务逻辑完全剥离到插件中 -2. **依赖注入 (DI)**: 通过服务注册表实现插件间通信 -3. **生命周期管理**: 标准化的 init → start → destroy 流程 -4. **事件/钩子机制**: 松耦合的插件通信方式 -5. **ObjectQL 插件化**: 数据引擎成为可替换的插件 - -## 核心组件 (Core Components) - -### 1. ObjectKernel (MiniKernel) - -**文件位置**: `packages/runtime/src/mini-kernel.ts` - -**功能**: -- 插件生命周期管理 -- 服务注册表 (Service Registry) -- 事件钩子系统 (Hook System) -- 依赖解析 (拓扑排序) - -**主要方法**: -```typescript -class ObjectKernel { - use(plugin: Plugin): ObjectKernel - bootstrap(): Promise - shutdown(): Promise - getService(name: string): T -} -``` - -### 2. Plugin Interface - -**文件位置**: `packages/runtime/src/types.ts` - -**定义**: -```typescript -interface Plugin { - name: string; - version?: string; - dependencies?: string[]; - - init(ctx: PluginContext): Promise; - start?(ctx: PluginContext): Promise; - destroy?(): Promise; -} -``` - -**生命周期**: -1. **init**: 注册服务、准备资源 -2. **start**: 执行业务逻辑、启动服务器 -3. **destroy**: 清理资源、关闭连接 - -### 3. PluginContext - -**功能**: 为插件提供运行时上下文 - -**主要方法**: -```typescript -interface PluginContext { - registerService(name: string, service: any): void; - getService(name: string): T; - hook(name: string, handler: Function): void; - trigger(name: string, ...args: any[]): Promise; - logger: Console; -} -``` - -## 核心插件 (Built-in Plugins) - -### 1. ObjectQLPlugin - -**文件位置**: `packages/runtime/src/objectql-plugin.ts` - -**功能**: 将 ObjectQL 数据引擎注册为服务 - -**服务**: `'objectql'` - -**使用示例**: -```typescript -kernel.use(new ObjectQLPlugin()); -// 或 -kernel.use(new ObjectQLPlugin(customQL)); -``` - -### 2. DriverPlugin - -**文件位置**: `packages/runtime/src/driver-plugin.ts` - -**功能**: 将数据驱动器包装为插件 - -**依赖**: `['com.objectstack.engine.objectql']` - -**使用示例**: -```typescript -kernel.use(new DriverPlugin(memoryDriver, 'memory')); -``` - -### 3. HonoServerPlugin (已更新) - -**文件位置**: `packages/plugin-hono-server/src/hono-plugin.ts` - -**功能**: HTTP 服务器插件 - -**服务**: `'http-server'` - -**更新内容**: -- 实现新的 Plugin 接口 -- 保持向后兼容 -- 使用服务注册表 - -## 架构优势 (Benefits) - -### 1. 真正的模块化 - -- 每个插件独立开发、测试、部署 -- 插件可以按需加载/卸载 -- 清晰的依赖关系 - -### 2. 灵活性 - -- 支持配置化加载插件 -- 可以条件性加载插件 -- 易于扩展新功能 - -### 3. 可测试性 - -- 服务可以被 Mock -- 插件可以独立测试 -- 依赖注入简化测试 - - - -## 使用示例 (Usage Examples) - -### 基础用法 - -```typescript -import { ObjectKernel, ObjectQLPlugin, DriverPlugin } from '@objectstack/runtime'; - -const kernel = new ObjectKernel(); - -kernel - .use(new ObjectQLPlugin()) - .use(new DriverPlugin(driver, 'memory')) - .use(new HonoServerPlugin({ port: 3000 })); - -await kernel.bootstrap(); -``` - -### 服务注册与消费 - -```typescript -// Plugin A: 注册服务 -class DataPlugin implements Plugin { - name = 'data-plugin'; - - async init(ctx: PluginContext) { - ctx.registerService('db', myDatabase); - } -} - -// Plugin B: 消费服务 -class ApiPlugin implements Plugin { - name = 'api-plugin'; - dependencies = ['data-plugin']; - - async start(ctx: PluginContext) { - const db = ctx.getService('db'); - // 使用数据库服务 - } -} -``` - -### 使用钩子系统 - -```typescript -class ServerPlugin implements Plugin { - name = 'server'; - - async start(ctx: PluginContext) { - ctx.hook('kernel:ready', () => { - console.log('Kernel is ready, starting server...'); - server.listen(3000); - }); - } -} -``` - -## 文件结构 (File Structure) - -``` -packages/runtime/src/ -├── mini-kernel.ts # ObjectKernel 实现 -├── types.ts # Plugin, PluginContext 接口 -├── objectql-plugin.ts # ObjectQL 插件 -├── driver-plugin.ts # Driver 插件 -├── protocol.ts # Runtime Protocol -└── index.ts # 导出 - -MINI_KERNEL_GUIDE.md # 完整使用指南 -examples/mini-kernel-example.ts # 示例代码 -test-mini-kernel.ts # 测试套件 -``` - -## 使用指南 (Usage Guide) - -### 创建新插件 - -```typescript -import { Plugin, PluginContext } from '@objectstack/runtime'; - -class MyPlugin implements Plugin { - name = 'my-plugin'; - version = '1.0.0'; - dependencies = ['other-plugin']; // 可选 - - async init(ctx: PluginContext) { - // 注册服务 - ctx.registerService('my-service', myService); - } - - async start(ctx: PluginContext) { - // 启动业务逻辑 - const otherService = ctx.getService('other-service'); - } - - async destroy() { - // 清理资源 - } -} -``` - -## 测试 (Testing) - -测试文件: `test-mini-kernel.ts` - -包含以下测试用例: -1. ✅ 基础生命周期 -2. ✅ 服务注册表 -3. ✅ 依赖解析 -4. ✅ 钩子系统 -5. ✅ ObjectQL 插件 -6. ✅ 多插件协作 -7. ✅ 错误处理 - -## 下一步计划 (Next Steps) - -1. **配置化加载**: 从 `objectstack.config.ts` 动态加载插件 -2. **更多内置插件**: - - Flow Engine Plugin - - Cache Plugin - - Monitoring Plugin -3. **插件市场**: 支持第三方插件发布和安装 -4. **沙箱隔离**: 为用户自定义脚本提供安全执行环境 - -## 参考文档 (References) - -- [MINI_KERNEL_GUIDE.md](./MINI_KERNEL_GUIDE.md) - 完整使用指南 -- [examples/mini-kernel-example.ts](./examples/mini-kernel-example.ts) - 示例代码 -- [packages/runtime/src/mini-kernel.ts](./packages/runtime/src/mini-kernel.ts) - 核心实现 - -## 技术要点 (Technical Highlights) - -### 依赖解析算法 - -使用**拓扑排序 (Topological Sort)** 解决插件依赖问题: - -```typescript -private resolveDependencies(): Plugin[] { - const resolved: Plugin[] = []; - const visited = new Set(); - const visiting = new Set(); - - const visit = (pluginName: string) => { - if (visited.has(pluginName)) return; - if (visiting.has(pluginName)) { - throw new Error(`Circular dependency: ${pluginName}`); - } - visiting.add(pluginName); - - // Visit dependencies first - const deps = plugin.dependencies || []; - for (const dep of deps) { - visit(dep); - } - - visiting.delete(pluginName); - visited.add(pluginName); - resolved.push(plugin); - }; - - for (const pluginName of this.plugins.keys()) { - visit(pluginName); - } - - return resolved; -} -``` - -### 服务注册表 - -使用 **Map** 实现高效的服务注册和查找: - -```typescript -private services: Map = new Map(); - -registerService(name, service) { - if (this.services.has(name)) { - throw new Error(`Service '${name}' already registered`); - } - this.services.set(name, service); -} - -getService(name: string): T { - const service = this.services.get(name); - if (!service) { - throw new Error(`Service '${name}' not found`); - } - return service as T; -} -``` - -### 钩子机制 - -使用**发布-订阅模式**实现事件通信: - -```typescript -private hooks: Map = new Map(); - -hook(name, handler) { - if (!this.hooks.has(name)) { - this.hooks.set(name, []); - } - this.hooks.get(name)!.push(handler); -} - -async trigger(name, ...args) { - const handlers = this.hooks.get(name) || []; - for (const handler of handlers) { - await handler(...args); - } -} -``` - -## 设计原则 (Design Principles) - -1. **单一职责**: 内核只负责生命周期、DI 和事件，不包含业务逻辑 -2. **开放封闭**: 对扩展开放（新插件），对修改封闭（内核不变） -3. **依赖倒置**: 高层模块不依赖低层模块，都依赖抽象（接口） -4. **接口隔离**: 插件只需实现必要的接口 -5. **最小惊讶**: API 设计符合直觉，易于理解和使用 - -## License - -Apache-2.0 diff --git a/MINI_KERNEL_INDEX.md b/MINI_KERNEL_INDEX.md deleted file mode 100644 index acc6ef483..000000000 --- a/MINI_KERNEL_INDEX.md +++ /dev/null @@ -1,89 +0,0 @@ -# ObjectStack MiniKernel 架构索引 - -## 📚 文档导航 - -本次架构改造将 ObjectStack 从单体架构转变为**微内核 (MiniKernel)** 架构，实现了业务逻辑的完全插件化。 - -### 核心文档 - -1. **[架构实现总结](./MINI_KERNEL_IMPLEMENTATION.md)** - 实现概述、核心组件、使用示例 - - 快速了解 MiniKernel 是什么 - - 核心组件说明 - - 迁移指南 - - 技术要点 - -2. **[完整使用指南](./MINI_KERNEL_GUIDE.md)** - 详细的 API 文档和最佳实践 - - 概念介绍 - - 基础用法 - - 高级模式 - - 故障排查 - -3. **[架构设计图](./MINI_KERNEL_ARCHITECTURE.md)** - 可视化架构图和流程图 - - 总体架构 - - 生命周期流程 - - 服务注册表 - - 依赖解析 - - 钩子系统 - -### 代码示例 - -1. **[基础示例](./examples/mini-kernel-example.ts)** - 简单的 MiniKernel 使用示例 -2. **[测试套件](./test-mini-kernel.ts)** - 完整的测试用例 - -### 源代码 - -- **[ObjectKernel](./packages/runtime/src/mini-kernel.ts)** - 微内核实现 -- **[Plugin Types](./packages/runtime/src/types.ts)** - 插件接口定义 -- **[ObjectQLPlugin](./packages/runtime/src/objectql-plugin.ts)** - ObjectQL 插件 -- **[DriverPlugin](./packages/runtime/src/driver-plugin.ts)** - 驱动器插件 -- **[HonoServerPlugin](./packages/plugin-hono-server/src/hono-plugin.ts)** - HTTP 服务器插件 - -## 🚀 快速开始 - -```typescript -import { ObjectKernel, ObjectQLPlugin, DriverPlugin } from '@objectstack/runtime'; - -const kernel = new ObjectKernel(); - -kernel - .use(new ObjectQLPlugin()) - .use(new DriverPlugin(memoryDriver, 'memory')); - -await kernel.bootstrap(); - -// 访问服务 -const objectql = kernel.getService('objectql'); -``` - -## 📋 核心特性 - -- ✅ **插件化架构**: 业务逻辑完全剥离到插件 -- ✅ **依赖注入**: 服务注册表实现 DI -- ✅ **生命周期管理**: init → start → destroy -- ✅ **事件系统**: Hook 机制实现松耦合 -- ✅ **依赖解析**: 自动拓扑排序 -- ✅ **向后兼容**: 保留旧 API - -## 🔄 使用示例 - -```typescript -const kernel = new ObjectKernel(); -kernel.use(new ObjectQLPlugin()); -kernel.use(appManifestPlugin); -await kernel.bootstrap(); -``` - -## 📖 推荐阅读顺序 - -1. 先读 [实现总结](./MINI_KERNEL_IMPLEMENTATION.md) 了解整体概况 -2. 查看 [架构图](./MINI_KERNEL_ARCHITECTURE.md) 理解设计思路 -3. 参考 [使用指南](./MINI_KERNEL_GUIDE.md) 学习具体用法 -4. 运行 [示例代码](./examples/mini-kernel-example.ts) 实践操作 - -## 🤝 贡献 - -欢迎贡献新的插件、改进文档或提出问题！ - -## 📄 License - -Apache-2.0 diff --git a/MINI_KERNEL_SUMMARY.md b/MINI_KERNEL_SUMMARY.md deleted file mode 100644 index 020a93289..000000000 --- a/MINI_KERNEL_SUMMARY.md +++ /dev/null @@ -1,439 +0,0 @@ -# 🎯 ObjectStack MiniKernel 架构改造总结 - -## 概述 - -本次改造将 ObjectStack 从单体架构转变为**微内核 (MiniKernel)** 架构，实现了业务逻辑的完全插件化。 - -**核心原则**: 像 Linux Kernel 一样，将核心功能剥离到最小，所有业务逻辑作为插件加载。 - -## 架构特点 - -```typescript -// ObjectQL 成为可插拔的服务 -class ObjectKernel { - private services: Map; // ← 服务注册表 - - use(plugin: Plugin) { - // 插件注册 - } - - async bootstrap() { - // 1. Init: 插件注册服务 - // 2. Start: 插件启动 - // 3. Ready: 触发 kernel:ready 事件 - } -} -``` - -**优势:** -- ✅ ObjectQL 可替换 (new ObjectQLPlugin(customQL)) -- ✅ 服务注册表实现 DI -- ✅ 标准生命周期 (init/start/destroy) -- ✅ 易于测试和 Mock - -## 核心组件 - -### 1. ObjectKernel (微内核) - -**文件**: `packages/runtime/src/mini-kernel.ts` - -**职责:** -- 🔄 管理插件生命周期 -- 📦 提供服务注册表 (DI) -- 🔗 实现钩子系统 (Event Bus) -- 📊 解析依赖关系 (拓扑排序) - -**API:** -```typescript -kernel.use(plugin) // 注册插件 -kernel.bootstrap() // 启动内核 -kernel.shutdown() // 关闭内核 -kernel.getService(name) // 获取服务 -``` - -### 2. Plugin Interface - -**文件**: `packages/runtime/src/types.ts` - -**定义:** -```typescript -interface Plugin { - name: string; - dependencies?: string[]; - init(ctx: PluginContext): Promise; - start?(ctx: PluginContext): Promise; - destroy?(): Promise; -} -``` - -**生命周期:** -``` -idle → use() → init() → start() → running → destroy() → stopped -``` - -### 3. PluginContext - -**API:** -```typescript -ctx.registerService(name, service) // 注册服务 -ctx.getService(name) // 获取服务 -ctx.hook(event, handler) // 注册钩子 -ctx.trigger(event, ...args) // 触发事件 -ctx.logger // 日志 -``` - -## 内置插件 - -### 1. ObjectQLPlugin - -```typescript -kernel.use(new ObjectQLPlugin()); -// 注册服务: 'objectql' -``` - -### 2. DriverPlugin - -```typescript -kernel.use(new DriverPlugin(driver, 'memory')); -// 依赖: ['com.objectstack.engine.objectql'] -``` - -### 3. HonoServerPlugin - -```typescript -kernel.use(new HonoServerPlugin({ port: 3000 })); -// 注册服务: 'http-server' -``` - -## 实际应用示例 - -### 基础用法 - -```typescript -import { ObjectKernel, ObjectQLPlugin, DriverPlugin } from '@objectstack/runtime'; - -const kernel = new ObjectKernel(); - -kernel - .use(new ObjectQLPlugin()) - .use(new DriverPlugin(memoryDriver)); - -await kernel.bootstrap(); -``` - -### 插件通信 - -```typescript -// Plugin A: 提供服务 -class DataPlugin implements Plugin { - name = 'data'; - - async init(ctx) { - ctx.registerService('db', myDatabase); - } -} - -// Plugin B: 消费服务 -class ApiPlugin implements Plugin { - name = 'api'; - dependencies = ['data']; - - async start(ctx) { - const db = ctx.getService('db'); - // 使用数据库 - } -} -``` - -### 事件通信 - -```typescript -class ServerPlugin implements Plugin { - name = 'server'; - - async start(ctx) { - ctx.hook('kernel:ready', () => { - server.listen(3000); - }); - } -} -``` - -## 技术亮点 - -### 1. 依赖解析 (拓扑排序) - -```typescript -// 注册顺序无关紧要 -kernel.use(new PluginC()); // depends on B -kernel.use(new PluginB()); // depends on A -kernel.use(new PluginA()); // no deps - -// 自动排序为: A → B → C -``` - -**算法**: 深度优先搜索 + 拓扑排序 -**时间复杂度**: O(V + E) -**空间复杂度**: O(V) - -### 2. 服务注册表 - -```typescript -private services: Map = new Map(); - -registerService(name, service) { - if (this.services.has(name)) { - throw new Error(`Service '${name}' already exists`); - } - this.services.set(name, service); -} -``` - -**特点:** -- O(1) 查找时间 -- 类型安全 (泛型) -- 防止重复注册 - -### 3. 钩子系统 - -```typescript -private hooks: Map = new Map(); - -hook(name, handler) { - if (!this.hooks.has(name)) { - this.hooks.set(name, []); - } - this.hooks.get(name).push(handler); -} - -async trigger(name, ...args) { - const handlers = this.hooks.get(name) || []; - for (const handler of handlers) { - await handler(...args); - } -} -``` - -**特点:** -- 发布-订阅模式 -- 异步执行 -- 顺序保证 - -## 文档体系 - -### 📚 完整文档 (1,250+ 行) - -1. **[MINI_KERNEL_INDEX.md](./MINI_KERNEL_INDEX.md)** - - 导航索引 - - 快速开始 - - 推荐阅读顺序 - -2. **[MINI_KERNEL_IMPLEMENTATION.md](./MINI_KERNEL_IMPLEMENTATION.md)** - - 实现总结 (中英双语) - - 核心组件详解 - - 迁移指南 - -3. **[MINI_KERNEL_GUIDE.md](./MINI_KERNEL_GUIDE.md)** - - 完整 API 文档 - - 使用示例 - - 最佳实践 - - 故障排查 - -4. **[MINI_KERNEL_ARCHITECTURE.md](./MINI_KERNEL_ARCHITECTURE.md)** - - 架构图 (ASCII Art) - - 流程图 - - 序列图 - - 扩展路径 - -## 代码统计 - -### 核心实现 (~500 行) -- `mini-kernel.ts`: 248 行 -- `types.ts`: 114 行 -- `driver-plugin.ts`: 42 行 -- `objectql-plugin.ts`: 84 行 - -### 文档 (~1,700 行) -- 主文档: 1,250 行 -- 示例代码: 200 行 -- 测试套件: 260 行 - -### 总计: **~2,200 行** - -## 设计原则 - -### SOLID 原则 - -1. **S** - Single Responsibility - - Kernel 只负责生命周期/DI/事件 - - 业务逻辑全部在插件中 - -2. **O** - Open/Closed - - 对扩展开放 (新插件) - - 对修改封闭 (Kernel 不变) - -3. **L** - Liskov Substitution - - 所有 Plugin 可以互换 - - ObjectQLPlugin 可以替换 - -4. **I** - Interface Segregation - - Plugin 只需实现必要方法 - - start/destroy 都是可选的 - -5. **D** - Dependency Inversion - - 高层不依赖低层 - - 都依赖 Plugin 接口 - -### 其他原则 - -- **最小惊讶原则**: API 直观易懂 -- **约定优于配置**: 合理的默认值 -- **显式优于隐式**: 依赖声明清晰 - -## 测试覆盖 - -### 测试用例 (test-mini-kernel.ts) - -1. ✅ 基础生命周期 -2. ✅ 服务注册表 -3. ✅ 依赖解析 -4. ✅ 钩子系统 -5. ✅ ObjectQL 插件 -6. ✅ 多插件协作 -7. ✅ 错误处理 - -### 运行测试 - -```bash -node test-mini-kernel.js -``` - -## 使用指南 - -### 步骤 1: 安装依赖 - -```bash -npm install @objectstack/runtime -``` - -### 步骤 2: 编写代码 - -```typescript -import { ObjectKernel, ObjectQLPlugin } from '@objectstack/runtime'; - -const kernel = new ObjectKernel(); - -kernel - .use(new ObjectQLPlugin()) - .use(appManifestPlugin); - -await kernel.bootstrap(); -``` - -### 步骤 3: 测试 - -```bash -npm test -``` - - - -## 性能特点 - -### 启动时间 - -- 5个插件: ~220ms -- 依赖解析: O(V+E) 时间复杂度 - -### 内存占用 - -- 基础内存: ~52MB -- 服务注册表: O(1) 查找性能 - -## 未来规划 - -### Phase 1: 配置化加载 ✨ - -```typescript -// objectstack.config.ts -export default { - plugins: [ - 'objectql', - 'memory-driver', - 'hono-server' - ] -}; - -// 自动加载 -const kernel = await loadFromConfig('./objectstack.config.ts'); -``` - -### Phase 2: 插件市场 🏪 - -```bash -npm install @company/awesome-plugin - -# objectstack.config.ts -plugins: ['@company/awesome-plugin'] -``` - -### Phase 3: 热重载 🔥 - -```typescript -kernel.reload('plugin-name'); // 无需重启 -``` - -### Phase 4: 沙箱隔离 🔒 - -```typescript -// 用户脚本在隔离环境运行 -kernel.use(new SandboxPlugin({ - userScript: './user-plugin.js', - permissions: ['read', 'write'] -})); -``` - -## 常见问题 - -### Q: 为什么要微内核？ - -A: -1. **模块化**: 业务逻辑完全解耦 -2. **可测试**: Mock 变得简单 -3. **可扩展**: 插件式扩展 -4. **灵活性**: 按需加载插件 - -### Q: 性能会下降吗？ - -A: 不会。开销仅在启动时 (+10%)，运行时几乎无差异。 - -### Q: 如何迁移现有代码？ - -A: 平滑迁移，旧代码继续工作。参考 [迁移指南](#迁移指南)。 - -### Q: 可以自定义 ObjectQL 吗？ - -A: 可以！`new ObjectQLPlugin(customQL)` - -## 参考资料 - -- [Microkernel Architecture Pattern](https://en.wikipedia.org/wiki/Microkernel) -- [Plugin Architecture](https://martinfowler.com/articles/plugins.html) -- [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) -- [Service Locator Pattern](https://martinfowler.com/articles/injection.html) - -## 贡献者 - -- [@hotlong](https://github.com/hotlong) - 架构设计与实现 -- GitHub Copilot - 代码辅助 - -## License - -Apache-2.0 - ---- - -**🎉 成功实现了一个真正的微内核架构！** - -> "The best architectures, requirements, and designs emerge from self-organizing teams." -> — Agile Manifesto diff --git a/OBJECTQL_PLUGIN_QUICKSTART.md b/OBJECTQL_PLUGIN_QUICKSTART.md deleted file mode 100644 index f9b82dc29..000000000 --- a/OBJECTQL_PLUGIN_QUICKSTART.md +++ /dev/null @@ -1,215 +0,0 @@ -# ObjectQL Plugin - Quick Reference - -## Installation - -```bash -npm install @objectstack/runtime -``` - -## Basic Usage - -### Default ObjectQL (Recommended) - -```typescript -import { ObjectKernel, ObjectQLPlugin } from '@objectstack/runtime'; - -const kernel = new ObjectKernel(); -kernel.use(new ObjectQLPlugin()); -// ... other plugins - -await kernel.bootstrap(); -``` - -### Custom ObjectQL Instance - -```typescript -import { ObjectKernel, ObjectQLPlugin, ObjectQL } from '@objectstack/runtime'; - -// Create custom instance -const customQL = new ObjectQL({ - env: 'production', - // custom options -}); - -// Configure as needed -customQL.registerHook('beforeInsert', async (ctx) => { - console.log(`Inserting into ${ctx.object}`); -}); - -// Use in kernel -const kernel = new ObjectKernel(); -kernel.use(new ObjectQLPlugin(customQL)); -// ... other plugins - -await kernel.bootstrap(); -``` - -## API Reference - -### ObjectQLPlugin Constructor - -```typescript -new ObjectQLPlugin(ql?: ObjectQL, hostContext?: Record) -``` - -**Parameters:** -- `ql` (optional): Custom ObjectQL instance to use -- `hostContext` (optional): Configuration for new ObjectQL instance (ignored if `ql` provided) - -**Note:** If both parameters are provided, `hostContext` is ignored with a warning. - -### Examples - -```typescript -// Create with default settings -new ObjectQLPlugin() - -// Use custom instance -const custom = new ObjectQL({ env: 'prod' }); -new ObjectQLPlugin(custom) - -// Create with custom context -new ObjectQLPlugin(undefined, { env: 'prod', debug: true }) -``` - -## Migration Guide - -### From Array-Based to Chaining Pattern - -**Before:** -```typescript -const kernel = new ObjectKernel([appConfig, driver]); -``` - -**After:** -```typescript -const kernel = new ObjectKernel(); -kernel.use(new ObjectQLPlugin()); // Add this line -kernel.use(appConfig); -kernel.use(driver); - -await kernel.bootstrap(); -``` - -## Common Patterns - -### Testing with Mock ObjectQL - -```typescript -import { ObjectKernel, ObjectQLPlugin } from '@objectstack/runtime'; -import { MockObjectQL } from './mocks'; - -const mockQL = new MockObjectQL(); -const kernel = new ObjectKernel(); -kernel.use(new ObjectQLPlugin(mockQL)); -// ... test config - -await kernel.bootstrap(); -``` - -### Multiple Environments - -```typescript -// Production -const prodQL = new ObjectQL({ env: 'production', cache: true }); -const prodKernel = new ObjectKernel(); -prodKernel.use(new ObjectQLPlugin(prodQL)); -// ... production plugins - -await prodKernel.bootstrap(); - -// Development -const devKernel = new ObjectKernel(); -devKernel.use(new ObjectQLPlugin(undefined, { env: 'development', debug: true })); -// ... dev plugins - -await devKernel.bootstrap(); -``` - -### Custom ObjectQL from Separate Project - -```typescript -// Your custom implementation -import { ObjectKernel, ObjectQLPlugin } from '@objectstack/runtime'; -import { MyCustomObjectQL } from '@mycompany/custom-objectql'; - -const customQL = new MyCustomObjectQL({ - specialFeature: true, - // custom options -}); - -const kernel = new ObjectKernel(); -kernel.use(new ObjectQLPlugin(customQL)); -// ... other plugins - -await kernel.bootstrap(); -``` - -## Troubleshooting - -### Error: "ObjectQL engine not initialized" - -This means the kernel tried to use ObjectQL before it was set up. Make sure you register the `ObjectQLPlugin`: - -```typescript -const kernel = new ObjectKernel(); -kernel.use(new ObjectQLPlugin()); // Add this -// ... other plugins - -await kernel.bootstrap(); -``` - -### Warning: "Both ql and hostContext provided..." - -You passed both a custom ObjectQL instance and host context: - -```typescript -// ❌ Don't do this -new ObjectQLPlugin(customQL, { env: 'prod' }) // hostContext ignored - -// ✅ Do this instead -new ObjectQLPlugin(customQL) // Use custom instance - -// ✅ Or this -new ObjectQLPlugin(undefined, { env: 'prod' }) // Create with context -``` - -## Advanced - -### Type-Based Detection - -ObjectQLPlugin uses a `type` field for reliable detection: - -```typescript -// Check if a plugin is an ObjectQL plugin -const isObjectQLPlugin = plugin && plugin.type === 'objectql'; -``` - -The plugin sets `type = 'objectql'` which aligns with the manifest schema that supports package types: 'app', 'plugin', 'driver', 'module', 'objectql', 'gateway', 'adapter'. - -### Type Safety - -The kernel's `ql` property is typed as optional: - -```typescript -export class ObjectKernel { - public ql?: ObjectQL; - - private ensureObjectQL(): ObjectQL { - if (!this.ql) { - throw new Error('ObjectQL engine not initialized'); - } - return this.ql; - } -} -``` - -## Resources - -- [Full Documentation](./packages/runtime/README.md) -- [Implementation Summary](./OBJECTQL_PLUGIN_SUMMARY.md) -- [Custom ObjectQL Example](./examples/custom-objectql-example.ts) - -## License - -Apache-2.0 diff --git a/PROTOCOL_EXTENSIONS_COMPLETED.md b/PROTOCOL_EXTENSIONS_COMPLETED.md deleted file mode 100644 index b52b0f181..000000000 --- a/PROTOCOL_EXTENSIONS_COMPLETED.md +++ /dev/null @@ -1,447 +0,0 @@ -# ObjectStack Protocol Extensions - Completion Report - -> **完成日期**: 2026-01-27 -> **状态**: ✅ 所有建议的协议扩展已完成实现 - ---- - -## 📋 执行摘要 - -本文档记录了 ObjectStack 协议扩展机会的实现状态。根据 [PROTOCOL_OPTIMIZATION_PLAN.md](./PROTOCOL_OPTIMIZATION_PLAN.md) 中的建议，以下所有高级查询功能和字段类型扩展已经成功实现并通过测试。 - ---- - -## ✅ 2.1 高级查询功能 - 已完成实现 - -### 2.1.1 窗口函数 (Window Functions) ✅ 已完成 - -**实现位置**: `packages/spec/src/data/query.zod.ts` (行 236-381) - -**功能状态**: 🟢 **已完全实现** - -**支持的窗口函数**: -- ✅ `row_number` - Sequential number within partition -- ✅ `rank` - Rank with gaps for ties -- ✅ `dense_rank` - Rank without gaps -- ✅ `percent_rank` - Relative rank as percentage -- ✅ `lag` - Access previous row value -- ✅ `lead` - Access next row value -- ✅ `first_value` - First value in window -- ✅ `last_value` - Last value in window -- ✅ Aggregate window functions: `sum`, `avg`, `count`, `min`, `max` - -**协议定义**: -```typescript -export const WindowFunction = z.enum([ - 'row_number', 'rank', 'dense_rank', 'percent_rank', - 'lag', 'lead', 'first_value', 'last_value', - 'sum', 'avg', 'count', 'min', 'max' -]); - -export const WindowFunctionNodeSchema = z.object({ - function: WindowFunction.describe('Window function name'), - field: z.string().optional().describe('Field to operate on'), - alias: z.string().describe('Result column alias'), - over: WindowSpecSchema.describe('Window specification (OVER clause)'), -}); -``` - -**使用示例**: -```typescript -// SQL: SELECT *, ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY amount DESC) as rank -{ - object: 'order', - fields: ['id', 'customer_id', 'amount'], - windowFunctions: [ - { - function: 'row_number', - alias: 'rank', - over: { - partitionBy: ['customer_id'], - orderBy: [{ field: 'amount', order: 'desc' }] - } - } - ] -} -``` - -**测试覆盖**: `packages/spec/src/data/query.test.ts` - 20+ 测试用例 - ---- - -### 2.1.2 HAVING 子句 ✅ 已完成 - -**实现位置**: `packages/spec/src/data/query.zod.ts` (行 457) - -**功能状态**: 🟢 **已完全实现** - -**协议定义**: -```typescript -export const QuerySchema = z.object({ - // ... other fields - groupBy: z.array(z.string()).optional().describe('GROUP BY fields'), - having: FilterConditionSchema.optional().describe('HAVING clause for aggregation filtering'), - // ... -}); -``` - -**使用示例**: -```typescript -// SQL: SELECT region, SUM(amount) as total -// FROM sales -// GROUP BY region -// HAVING total > 1000 -{ - object: 'sales', - fields: ['region'], - aggregations: [ - { function: 'sum', field: 'amount', alias: 'total' } - ], - groupBy: ['region'], - having: { total: { $gt: 1000 } } -} -``` - -**测试覆盖**: `packages/spec/src/data/query.test.ts` - 10+ 测试用例 - ---- - -### 2.1.3 DISTINCT 查询 ✅ 已完成 - -**实现位置**: `packages/spec/src/data/query.zod.ts` (行 463) - -**功能状态**: 🟢 **已完全实现** - -**协议定义**: -```typescript -export const QuerySchema = z.object({ - // ... other fields - distinct: z.boolean().optional().describe('SELECT DISTINCT flag'), -}); -``` - -**使用示例**: -```typescript -// SQL: SELECT DISTINCT customer_id FROM orders -{ - object: 'order', - fields: ['customer_id'], - distinct: true -} -``` - -**测试覆盖**: `packages/spec/src/data/query.test.ts` - 5+ 测试用例 - ---- - -### 2.1.4 子查询支持 (Subqueries) ✅ 已完成 - -**实现位置**: `packages/spec/src/data/query.zod.ts` (行 231) - -**功能状态**: 🟢 **已完全实现** - -**协议定义**: -```typescript -export const JoinNodeSchema = z.object({ - type: JoinType.describe('Join type'), - object: z.string().describe('Object/table to join'), - alias: z.string().optional().describe('Table alias'), - on: FilterConditionSchema.describe('Join condition'), - subquery: z.lazy(() => QuerySchema).optional().describe('Subquery instead of object'), -}); -``` - -**使用示例**: -```typescript -// Join with a subquery (filtered dataset) -{ - object: 'customer', - joins: [ - { - type: 'left', - object: 'order', - alias: 'high_value_orders', - on: ['customer.id', '=', 'high_value_orders.customer_id'], - subquery: { - object: 'order', - fields: ['customer_id', 'total'], - where: { total: { $gt: 1000 } } - } - } - ] -} -``` - -**测试覆盖**: `packages/spec/src/data/query.test.ts` - 8+ 测试用例 - ---- - -## ✅ 2.2 运行时扩展与协议边界 - 已完成实现 - -### 2.2.1 Vector 字段类型 ✅ 已纳入协议 - -**实现位置**: `packages/spec/src/data/field.zod.ts` (行 43, 150-156) - -**功能状态**: 🟢 **已完全实现并纳入协议** - -**协议定义**: -```typescript -export const FieldType = z.enum([ - // ... other types - 'vector', // Vector embeddings for AI/ML (semantic search, RAG) -]); - -export const VectorConfigSchema = z.object({ - dimensions: z.number().int().min(1).max(10000) - .describe('Vector dimensionality (e.g., 1536 for OpenAI embeddings)'), - distanceMetric: z.enum(['cosine', 'euclidean', 'dotProduct', 'manhattan']) - .default('cosine') - .describe('Distance/similarity metric for vector search'), - normalized: z.boolean().default(false) - .describe('Whether vectors are normalized (unit length)'), - indexed: z.boolean().default(true) - .describe('Whether to create a vector index for fast similarity search'), - indexType: z.enum(['hnsw', 'ivfflat', 'flat']).optional() - .describe('Vector index algorithm'), -}); -``` - -**使用场景**: -- ✅ 语义搜索 (Semantic Search) -- ✅ RAG (Retrieval-Augmented Generation) -- ✅ 文本嵌入 (Text Embeddings) -- ✅ 图像特征向量 (Image Feature Vectors) -- ✅ 推荐系统 (Recommendation Systems) - -**使用示例**: -```typescript -{ - name: 'embedding', - type: 'vector', - label: 'Content Embedding', - vectorConfig: { - dimensions: 1536, // OpenAI text-embedding-ada-002 - distanceMetric: 'cosine', - indexed: true, - indexType: 'hnsw' - } -} -``` - -**测试覆盖**: `packages/spec/src/data/field.test.ts` - 15+ 测试用例 - ---- - -### 2.2.2 Location 字段类型 ✅ 已纳入协议 - -**实现位置**: `packages/spec/src/data/field.zod.ts` (行 31, 74-82) - -**功能状态**: 🟢 **已完全实现并纳入协议** - -**协议定义**: -```typescript -export const FieldType = z.enum([ - // ... other types - 'location', // GPS coordinates -]); - -export const LocationCoordinatesSchema = z.object({ - latitude: z.number().min(-90).max(90).describe('Latitude coordinate'), - longitude: z.number().min(-180).max(180).describe('Longitude coordinate'), - altitude: z.number().optional().describe('Altitude in meters'), - accuracy: z.number().optional().describe('Accuracy in meters'), -}); -``` - -**使用场景**: -- ✅ GPS 定位 (GPS Positioning) -- ✅ 地理围栏 (Geofencing) -- ✅ 位置追踪 (Location Tracking) -- ✅ 距离计算 (Distance Calculation) -- ✅ 地图展示 (Map Display) - -**使用示例**: -```typescript -{ - name: 'store_location', - type: 'location', - label: 'Store Location', - displayMap: true, - allowGeocoding: true -} -``` - -**测试覆盖**: `packages/spec/src/data/field.test.ts` - 10+ 测试用例 - ---- - -### 2.2.3 其他增强字段类型 ✅ 已纳入协议 - -以下字段类型也已完全实现并纳入协议: - -- ✅ **Address** (`address`) - 结构化地址 (行 116-124) -- ✅ **Object** - 通过 `lookup` 和 `master_detail` 实现关系 -- ✅ **Grid** - 通过 UI 层的 `view.zod.ts` 实现 - ---- - -## 🔧 2.3 驱动能力声明 - 已完成实现 - -**实现位置**: `packages/spec/src/system/driver.zod.ts` (行 44-135) - -**功能状态**: 🟢 **已完全实现** - -**协议定义**: -```typescript -export const DriverCapabilitiesSchema = z.object({ - // Query Operations - queryFilters: z.boolean().describe('Supports WHERE clause filtering'), - queryAggregations: z.boolean().describe('Supports GROUP BY and aggregation functions'), - querySorting: z.boolean().describe('Supports ORDER BY sorting'), - queryPagination: z.boolean().describe('Supports LIMIT/OFFSET pagination'), - queryWindowFunctions: z.boolean().describe('Supports window functions with OVER clause'), - querySubqueries: z.boolean().describe('Supports subqueries'), - joins: z.boolean().describe('Supports SQL joins'), - - // Advanced Features - fullTextSearch: z.boolean().describe('Supports full-text search'), - vectorSearch: z.boolean().default(false).describe('Supports vector embeddings and similarity search'), - geoSpatial: z.boolean().default(false).describe('Supports geospatial queries'), - jsonFields: z.boolean().describe('Supports JSON field types'), - arrayFields: z.boolean().describe('Supports array field types'), - - // ... other capabilities -}); -``` - -**驱动实现示例** (`packages/driver-memory/src/memory-driver.ts`): -```typescript -supports = { - transactions: false, - queryFilters: false, - queryAggregations: false, - querySorting: false, - queryPagination: true, - queryWindowFunctions: false, // ✅ 现在有明确定义 - querySubqueries: false, // ✅ 现在有明确定义 - joins: false, - fullTextSearch: false, - vectorSearch: false, - geoSpatial: false, - jsonFields: true, - arrayFields: true, -}; -``` - ---- - -## 📊 总体完成度评估 - -### Query Protocol - 完整度: 95% → **100%** ✅ - -| 功能 | 之前状态 | 当前状态 | 协议位置 | -|------|---------|---------|---------| -| Window Functions | 🟡 SQL 驱动支持但协议未定义 | ✅ 已完全定义 | `query.zod.ts:236-381` | -| Subqueries | 🟡 部分支持但协议未定义 | ✅ 已完全定义 | `query.zod.ts:231` | -| HAVING Clause | 🟡 GroupBy 已实现但无 HAVING | ✅ 已完全定义 | `query.zod.ts:457` | -| DISTINCT Query | 🟡 实现为独立方法 | ✅ 已纳入 QueryAST | `query.zod.ts:463` | - -### Field Types - 完整度: 95% → **100%** ✅ - -| 字段类型 | 之前状态 | 当前状态 | 协议位置 | -|---------|---------|---------|---------| -| Vector | ⚠️ Runtime Extension | ✅ 已纳入协议 | `field.zod.ts:43, 150-156` | -| Location | ⚠️ Runtime Extension | ✅ 已纳入协议 | `field.zod.ts:31, 74-82` | -| Address | ✅ 已实现 | ✅ 已纳入协议 | `field.zod.ts:116-124` | - -### Driver Capabilities - 完整度: 85% → **100%** ✅ - -| 能力标志 | 之前状态 | 当前状态 | 协议位置 | -|---------|---------|---------|---------| -| queryWindowFunctions | ❌ 未定义 | ✅ 已定义 | `driver.zod.ts:89` | -| querySubqueries | ❌ 未定义 | ✅ 已定义 | `driver.zod.ts:95` | -| vectorSearch | ❌ 未定义 | ✅ 已定义 | `driver.zod.ts:129` | -| geoSpatial | ❌ 未定义 | ✅ 已定义 | `driver.zod.ts:134` | - ---- - -## 🧪 测试覆盖率 - -**总体测试状态**: ✅ **1695 测试全部通过** - -### 相关测试文件: -- ✅ `packages/spec/src/data/query.test.ts` - 105 tests (包含 Window Functions, HAVING, DISTINCT 测试) -- ✅ `packages/spec/src/data/field.test.ts` - 81 tests (包含 Vector, Location 字段测试) -- ✅ `packages/spec/src/system/driver.test.ts` - 23 tests (包含驱动能力测试) - -### 测试执行结果: -```bash -✓ src/data/query.test.ts (105 tests) 83ms -✓ src/data/field.test.ts (81 tests) 54ms -✓ src/system/driver.test.ts (23 tests) 19ms - -Test Files 50 passed (50) -Tests 1695 passed (1695) -``` - ---- - -## 📚 文档和示例 - -### 代码文档 (JSDoc) -所有新增的协议扩展都包含完整的 JSDoc 文档，包括: -- ✅ 功能描述 -- ✅ SQL 等效语法 -- ✅ 使用示例 -- ✅ 性能考虑 -- ✅ 行业对标 (Salesforce, PostgreSQL, etc.) - -### 示例代码 -每个协议扩展都在 JSDoc 中包含至少 2-3 个实际使用示例。 - ---- - -## 🎯 与行业标准对标 - -| 功能 | ObjectStack | SQL | MongoDB | Salesforce | 状态 | -|------|------------|-----|---------|-----------|------| -| Window Functions | ✅ | ✅ | ❌ | ✅ (Analytics) | ⭐⭐⭐⭐⭐ | -| HAVING Clause | ✅ | ✅ | ✅ ($match after $group) | ✅ | ⭐⭐⭐⭐⭐ | -| DISTINCT | ✅ | ✅ | ✅ | ✅ | ⭐⭐⭐⭐⭐ | -| Subqueries | ✅ | ✅ | ✅ ($lookup) | ✅ (Relationship Queries) | ⭐⭐⭐⭐⭐ | -| Vector Search | ✅ | ✅ (pgvector) | ✅ (Atlas Vector Search) | ❌ | ⭐⭐⭐⭐⭐ | -| Geo Location | ✅ | ✅ (PostGIS) | ✅ | ✅ | ⭐⭐⭐⭐⭐ | - -**行业对标评分**: ⭐⭐⭐⭐⭐ (5/5) - **完全对齐行业最佳实践** - ---- - -## ✅ 结论 - -所有在 [问题 #2](https://github.com/objectstack-ai/spec/issues/2) 中提出的协议扩展建议已经 **100% 完成实现**: - -1. ✅ **Window Functions** - 完整的窗口函数支持，包括 ROW_NUMBER, RANK, LAG, LEAD 等 -2. ✅ **HAVING Clause** - 支持对聚合结果进行过滤 -3. ✅ **DISTINCT Query** - 作为 QueryAST 的一部分实现 -4. ✅ **Subqueries** - 支持在 JOIN 中使用子查询 -5. ✅ **Vector Field Type** - 完整的向量嵌入支持，适用于 AI/ML 场景 -6. ✅ **Location Field Type** - 完整的地理位置支持 -7. ✅ **Driver Capabilities** - 完整的驱动能力声明系统 - -**ObjectStack Query Protocol** 现在已达到 **100% 完整度**，完全对齐行业最佳实践，支持现代应用开发的所有核心功能。 - ---- - -## 📞 下一步行动 - -建议的后续工作: -1. ✅ 更新 PROTOCOL_OPTIMIZATION_PLAN.md 以反映完成状态 -2. ✅ 为所有驱动实现（SQL、MongoDB、Memory）更新能力声明 -3. ⚠️ 添加更多实际使用场景的端到端示例 -4. ⚠️ 编写迁移指南，帮助现有项目升级到新协议 - ---- - -**最后更新**: 2026-01-27 -**文档版本**: 1.0.0 -**协议版本**: 0.3.3+ diff --git a/PROTOCOL_INDEX.md b/PROTOCOL_INDEX.md deleted file mode 100644 index 2f204e119..000000000 --- a/PROTOCOL_INDEX.md +++ /dev/null @@ -1,204 +0,0 @@ -# ObjectStack Protocol Quick Index - -> **Fast navigation to all 70 protocol specifications** - -Last Updated: 2026-01-27 - -## Quick Links - -| Category | Count | Documentation | Source Code | -| :--- | :---: | :--- | :--- | -| **Data** | 8 | [docs/references/data/](./content/docs/references/data/) | [src/data/](./packages/spec/src/data/) | -| **UI** | 10 | [docs/references/ui/](./content/docs/references/ui/) | [src/ui/](./packages/spec/src/ui/) | -| **System** | 14 | [docs/references/system/](./content/docs/references/system/) | [src/system/](./packages/spec/src/system/) | -| **AI** | 8 | [docs/references/ai/](./content/docs/references/ai/) | [src/ai/](./packages/spec/src/ai/) | -| **API** | 6 | [docs/references/api/](./content/docs/references/api/) | [src/api/](./packages/spec/src/api/) | -| **Automation** | 7 | [docs/references/automation/](./content/docs/references/automation/) | [src/automation/](./packages/spec/src/automation/) | -| **Auth** | 6 | [docs/references/auth/](./content/docs/references/auth/) | [src/auth/](./packages/spec/src/auth/) | -| **Permission** | 4 | [docs/references/permission/](./content/docs/references/permission/) | [src/permission/](./packages/spec/src/permission/) | -| **Hub** | 5 | [docs/references/hub/](./content/docs/references/hub/) | [src/hub/](./packages/spec/src/hub/) | -| **Shared** | 1 | [docs/references/shared/](./content/docs/references/shared/) | [src/shared/](./packages/spec/src/shared/) | -| **Stack** | 1 | — | [src/stack.zod.ts](./packages/spec/src/stack.zod.ts) | - -## Data Protocol (8 protocols) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Field** | [field.zod.ts](./packages/spec/src/data/field.zod.ts) | 44 field types for data modeling | -| **Object** | [object.zod.ts](./packages/spec/src/data/object.zod.ts) | Object/table definitions | -| **Query** | [query.zod.ts](./packages/spec/src/data/query.zod.ts) | Query AST with advanced features | -| **Validation** | [validation.zod.ts](./packages/spec/src/data/validation.zod.ts) | Validation rules | -| **Filter** | [filter.zod.ts](./packages/spec/src/data/filter.zod.ts) | Query filtering | -| **Dataset** | [dataset.zod.ts](./packages/spec/src/data/dataset.zod.ts) | Dataset definitions | -| **Mapping** | [mapping.zod.ts](./packages/spec/src/data/mapping.zod.ts) | Field mappings | -| **Hook** | [hook.zod.ts](./packages/spec/src/data/hook.zod.ts) | Lifecycle hooks | - -## UI Protocol (10 protocols) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **View** | [view.zod.ts](./packages/spec/src/ui/view.zod.ts) | List/form views | -| **Page** | [page.zod.ts](./packages/spec/src/ui/page.zod.ts) | FlexiPage layouts | -| **App** | [app.zod.ts](./packages/spec/src/ui/app.zod.ts) | App navigation | -| **Dashboard** | [dashboard.zod.ts](./packages/spec/src/ui/dashboard.zod.ts) | Dashboard layouts | -| **Report** | [report.zod.ts](./packages/spec/src/ui/report.zod.ts) | Report definitions | -| **Action** | [action.zod.ts](./packages/spec/src/ui/action.zod.ts) | UI actions | -| **Component** | [component.zod.ts](./packages/spec/src/ui/component.zod.ts) | Reusable components | -| **Block** | [block.zod.ts](./packages/spec/src/ui/block.zod.ts) | UI blocks | -| **Theme** | [theme.zod.ts](./packages/spec/src/ui/theme.zod.ts) | Theming system | -| **Widget** | [widget.zod.ts](./packages/spec/src/ui/widget.zod.ts) | Custom widgets | - -## System Protocol (14 protocols) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Manifest** | [manifest.zod.ts](./packages/spec/src/system/manifest.zod.ts) | Package manifest | -| **Datasource** | [datasource.zod.ts](./packages/spec/src/system/datasource.zod.ts) | Data source config | -| **Driver** | [driver.zod.ts](./packages/spec/src/system/driver.zod.ts) | Database drivers | -| **PostgreSQL** | [driver/postgres.zod.ts](./packages/spec/src/system/driver/postgres.zod.ts) | PostgreSQL driver | -| **MongoDB** | [driver/mongo.zod.ts](./packages/spec/src/system/driver/mongo.zod.ts) | MongoDB driver | -| **Plugin** | [plugin.zod.ts](./packages/spec/src/system/plugin.zod.ts) | Plugin interface | -| **Context** | [context.zod.ts](./packages/spec/src/system/context.zod.ts) | Kernel context | -| **Events** | [events.zod.ts](./packages/spec/src/system/events.zod.ts) | Event bus | -| **Job** | [job.zod.ts](./packages/spec/src/system/job.zod.ts) | Background jobs | -| **Audit** | [audit.zod.ts](./packages/spec/src/system/audit.zod.ts) | Audit logging | -| **Logger** | [logger.zod.ts](./packages/spec/src/system/logger.zod.ts) | Logging config | -| **Translation** | [translation.zod.ts](./packages/spec/src/system/translation.zod.ts) | i18n support | -| **Feature** | [feature.zod.ts](./packages/spec/src/system/feature.zod.ts) | Feature flags | -| **Storage** | [scoped-storage.zod.ts](./packages/spec/src/system/scoped-storage.zod.ts) | Key-value storage | - -## AI Protocol (8 protocols) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Agent** | [agent.zod.ts](./packages/spec/src/ai/agent.zod.ts) | AI agent definitions | -| **Model Registry** | [model-registry.zod.ts](./packages/spec/src/ai/model-registry.zod.ts) | LLM model registry | -| **RAG Pipeline** | [rag-pipeline.zod.ts](./packages/spec/src/ai/rag-pipeline.zod.ts) | RAG workflows | -| **NLQ** | [nlq.zod.ts](./packages/spec/src/ai/nlq.zod.ts) | Natural language query | -| **Conversation** | [conversation.zod.ts](./packages/spec/src/ai/conversation.zod.ts) | Conversation mgmt | -| **Cost** | [cost.zod.ts](./packages/spec/src/ai/cost.zod.ts) | Cost tracking | -| **Predictive** | [predictive.zod.ts](./packages/spec/src/ai/predictive.zod.ts) | Predictive models | -| **Orchestration** | [orchestration.zod.ts](./packages/spec/src/ai/orchestration.zod.ts) | AI orchestration | - -## API Protocol (6 protocols) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Contract** | [contract.zod.ts](./packages/spec/src/api/contract.zod.ts) | API contracts | -| **Endpoint** | [endpoint.zod.ts](./packages/spec/src/api/endpoint.zod.ts) | REST endpoints | -| **Router** | [router.zod.ts](./packages/spec/src/api/router.zod.ts) | API routing | -| **OData** | [odata.zod.ts](./packages/spec/src/api/odata.zod.ts) | OData support | -| **Realtime** | [realtime.zod.ts](./packages/spec/src/api/realtime.zod.ts) | Real-time subscriptions | -| **Discovery** | [discovery.zod.ts](./packages/spec/src/api/discovery.zod.ts) | API discovery | - -## Automation Protocol (7 protocols) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Flow** | [flow.zod.ts](./packages/spec/src/automation/flow.zod.ts) | Visual workflows | -| **Workflow** | [workflow.zod.ts](./packages/spec/src/automation/workflow.zod.ts) | Workflow rules | -| **Approval** | [approval.zod.ts](./packages/spec/src/automation/approval.zod.ts) | Approval processes | -| **Webhook** | [webhook.zod.ts](./packages/spec/src/automation/webhook.zod.ts) | Webhooks | -| **ETL** | [etl.zod.ts](./packages/spec/src/automation/etl.zod.ts) | ETL pipelines | -| **Sync** | [sync.zod.ts](./packages/spec/src/automation/sync.zod.ts) | Data sync | -| **Connector** | [connector.zod.ts](./packages/spec/src/automation/connector.zod.ts) | External connectors | - -## Auth Protocol (6 protocols) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Identity** | [identity.zod.ts](./packages/spec/src/auth/identity.zod.ts) | User identity | -| **Role** | [role.zod.ts](./packages/spec/src/auth/role.zod.ts) | Role definitions | -| **Organization** | [organization.zod.ts](./packages/spec/src/auth/organization.zod.ts) | Multi-org | -| **Policy** | [policy.zod.ts](./packages/spec/src/auth/policy.zod.ts) | Security policies | -| **Config** | [config.zod.ts](./packages/spec/src/auth/config.zod.ts) | OAuth/SAML/SSO | -| **SCIM** | [scim.zod.ts](./packages/spec/src/auth/scim.zod.ts) | SCIM provisioning | - -## Permission Protocol (4 protocols) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Permission** | [permission.zod.ts](./packages/spec/src/permission/permission.zod.ts) | Object permissions | -| **Sharing** | [sharing.zod.ts](./packages/spec/src/permission/sharing.zod.ts) | Sharing rules | -| **RLS** | [rls.zod.ts](./packages/spec/src/permission/rls.zod.ts) | Row-level security | -| **Territory** | [territory.zod.ts](./packages/spec/src/permission/territory.zod.ts) | Territories | - -## Hub Protocol (5 protocols) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Marketplace** | [marketplace.zod.ts](./packages/spec/src/hub/marketplace.zod.ts) | Plugin marketplace | -| **Composer** | [composer.zod.ts](./packages/spec/src/hub/composer.zod.ts) | Dependency mgmt | -| **License** | [license.zod.ts](./packages/spec/src/hub/license.zod.ts) | Feature licensing | -| **Tenant** | [tenant.zod.ts](./packages/spec/src/hub/tenant.zod.ts) | Multi-tenancy | -| **Space** | [space.zod.ts](./packages/spec/src/hub/space.zod.ts) | Workspace mgmt | - -## Shared Protocol (1 protocol) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Identifiers** | [identifiers.zod.ts](./packages/spec/src/shared/identifiers.zod.ts) | Common identifiers | - -## Stack Protocol (1 protocol) - -| Protocol | File | Description | -| :--- | :--- | :--- | -| **Stack** | [stack.zod.ts](./packages/spec/src/stack.zod.ts) | Root stack definition | - -## Documentation Resources - -- **[PROTOCOL_REFERENCE.md](./PROTOCOL_REFERENCE.md)** - Detailed reference with examples -- **[PROTOCOL_ORGANIZATION.md](./PROTOCOL_ORGANIZATION.md)** - Visual diagrams and relationships -- **[README.md](./README.md)** - Project overview -- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System architecture -- **[content/docs/references/](./content/docs/references/)** - Generated API documentation (473 files) - -## How to Use - -### View Source Code -```bash -# View a protocol definition -cat packages/spec/src/data/field.zod.ts - -# Search for specific schema -grep -r "FieldSchema" packages/spec/src/ -``` - -### Import in Code -```typescript -import { FieldSchema, ObjectSchema } from '@objectstack/spec/data'; -import { ViewSchema, AppSchema } from '@objectstack/spec/ui'; -import { ManifestSchema } from '@objectstack/spec/system'; -``` - -### Generate JSON Schema -```bash -# Build generates JSON schemas -pnpm --filter @objectstack/spec build - -# Output location -ls packages/spec/json-schema/ -``` - -### Generate Documentation -```bash -# Generate reference docs -pnpm --filter @objectstack/spec gen:docs - -# Output location -ls content/docs/references/ -``` - -## Version Information - -- **Protocol Version:** 0.3.3 -- **Total Protocols:** 70 -- **Generated Documentation Files:** 473 -- **Last Updated:** 2026-01-27 - ---- - -**See Also:** -- [Contributing Guide](./CONTRIBUTING.md) -- [Development Roadmap](./internal/planning/DEVELOPMENT_ROADMAP.md) -- [Protocol Extensions](./PROTOCOL_EXTENSIONS_COMPLETED.md) diff --git a/PROTOCOL_OPTIMIZATION_PLAN.md b/PROTOCOL_OPTIMIZATION_PLAN.md deleted file mode 100644 index 4944307c5..000000000 --- a/PROTOCOL_OPTIMIZATION_PLAN.md +++ /dev/null @@ -1,849 +0,0 @@ -# ObjectStack 协议优化与调整计划 - -> **初次评估日期**: 2026-01-26 -> **最后更新**: 2026-01-27 -> **评估范围**: ObjectQL (数据核心) / ObjectUI (交互体验) / ObjectOS (业务编排) -> **对标标准**: Salesforce, ServiceNow, Kubernetes, Prisma, OData v4, SCIM 2.0 - ---- - -## 📋 执行摘要 - -本文档基于行业最佳实践，对 ObjectStack 现有协议进行全面评估，识别缺口并提出优化计划。 - -### 核心发现 (更新于 2026-01-27) - -1. ✅ **已完成协议** (90%+): ObjectStack 已经实现了大部分核心协议 - - ✅ **Query Protocol 100% 完成** - Window Functions, HAVING, DISTINCT, Subqueries 全部实现 - - ✅ **Schema Definition 100% 完成** - Vector 和 Location 字段类型已纳入协议 -2. ⚠️ **需要增强** (7%): 部分协议需要补充行业标准特性 -3. 🆕 **需要新增** (3%): 少量关键协议尚未实现 - -> 📘 **重要更新**: 参见 [PROTOCOL_EXTENSIONS_COMPLETED.md](./PROTOCOL_EXTENSIONS_COMPLETED.md) 了解最新完成的协议扩展详情。 - ---- - -## 1️⃣ ObjectQL：数据与模型层 (The "Brain") - -### 1.1 Schema Definition DSL ✅ 完整度: 100% (更新于 2026-01-27) - -#### 现状评估 -**已实现**: -- ✅ Objects 定义 (`object.zod.ts`) - 完整支持 -- ✅ Fields 字段类型 (`field.zod.ts`) - 44 种字段类型 - - 基础类型: text, number, date, boolean, select - - 关系类型: lookup, master_detail, tree - - 高级类型: formula, summary, autonumber - - 增强类型: location, address, qrcode, slider, rating, code, color, signature - - **AI/ML 类型**: vector (向量嵌入，用于语义搜索和 RAG) ✅ 已纳入协议 -- ✅ Relationships: Lookup, Master-Detail, Hierarchical -- ✅ Field Level Security (FLS) -- ✅ Object Capabilities (History, API, Search, etc.) -- ✅ Vector Field Configuration (VectorConfigSchema) - 支持多种距离度量和索引算法 -- ✅ Location Field Configuration (LocationCoordinatesSchema) - GPS 坐标支持 - -> 📘 **详细文档**: 参见 [PROTOCOL_EXTENSIONS_COMPLETED.md](./PROTOCOL_EXTENSIONS_COMPLETED.md) 了解 Vector 和 Location 字段类型的完整实现细节。 - -**优化建议** ⚠️: -1. ~~**添加 Vector 字段类型** (对标 pgvector, MongoDB Atlas Vector Search)~~ - ✅ 已完成 (2026-01-27) -2. ~~**添加 Location 字段类型** (对标 PostGIS, MongoDB GeoJSON)~~ - ✅ 已完成 (2026-01-27) -3. **添加 Schema 迁移协议** (对标 Prisma Migrate) - 🔜 未来增强 - ```typescript - // 新增: packages/spec/src/data/migration.zod.ts - export const MigrationSchema = z.object({ - version: z.string().describe('Migration version'), - operations: z.array(z.discriminatedUnion('type', [ - AlterTableSchema, - AddFieldSchema, - DropFieldSchema, - RenameFieldSchema, - AddIndexSchema, - ])), - rollback: z.array(MigrationOperationSchema).optional(), - }); - ``` - -4. **添加 Virtual Fields 支持** (对标 Salesforce Formula Fields) - 🔜 未来增强 - - 当前 `formula` 字段已存在，但需要明确计算时机 (实时 vs 存储) - ```typescript - // 增强: packages/spec/src/data/field.zod.ts - formula: z.string().optional(), - formulaMode: z.enum(['computed', 'stored']).default('computed'), - ``` - -**行业对标**: ⭐⭐⭐⭐⭐ (5/5) - **字段类型系统已完全对齐行业标准，包括 AI/ML 和地理位置功能** - ---- - -### 1.2 Query Protocol ✅ 完整度: 100% (更新于 2026-01-27) - -#### 现状评估 -**已实现**: -- ✅ Filtering (AND/OR, Nested) - `filter.zod.ts` -- ✅ Aggregation (Sum, Count, GroupBy) - `query.zod.ts` -- ✅ Window Functions (ROW_NUMBER, RANK, LAG, LEAD, DENSE_RANK, PERCENT_RANK, FIRST_VALUE, LAST_VALUE) - `query.zod.ts:236-381` -- ✅ HAVING Clause (过滤聚合结果) - `query.zod.ts:457` -- ✅ DISTINCT Query (去重查询) - `query.zod.ts:463` -- ✅ Subqueries (子查询支持) - `query.zod.ts:231` -- ✅ Joins (Inner, Left, Right, Full) - `query.zod.ts` -- ✅ Pagination (Limit/Offset + Cursor) - `query.zod.ts` -- ✅ Sorting (排序) - `query.zod.ts` - -> 📘 **详细文档**: 参见 [PROTOCOL_EXTENSIONS_COMPLETED.md](./PROTOCOL_EXTENSIONS_COMPLETED.md) 了解完整实现细节和使用示例。 - -**优化建议** ⚠️: -1. ~~**添加窗口函数 (Window Functions)** - ✅ 已完成 (2026-01-27)~~ -2. ~~**添加 HAVING 子句** - ✅ 已完成 (2026-01-27)~~ -3. ~~**添加 DISTINCT 查询** - ✅ 已完成 (2026-01-27)~~ -4. ~~**添加子查询支持 (Subqueries)** - ✅ 已完成 (2026-01-27)~~ -5. **添加 OData v4 兼容层** (对标 Microsoft Dynamics) - 🔜 未来增强 - ```typescript - // 新增: packages/spec/src/api/odata.zod.ts - export const ODataQuerySchema = z.object({ - $select: z.array(z.string()).optional(), - $filter: z.string().optional(), // OData filter syntax - $orderby: z.string().optional(), - $top: z.number().optional(), - $skip: z.number().optional(), - $expand: z.string().optional(), - $count: z.boolean().optional(), - }); - ``` - -6. **添加 GraphQL Schema 生成** (对标 Hasura) - 🔜 未来增强 - - 自动从 ObjectSchema 生成 GraphQL SDL - ```typescript - // 新增: packages/spec/src/api/graphql-schema.zod.ts - export const GraphQLSchemaGeneratorConfig = z.object({ - objects: z.array(z.string()).optional(), - excludeFields: z.record(z.array(z.string())).optional(), - customResolvers: z.record(z.any()).optional(), - }); - ``` - -7. **添加查询性能分析** (对标 Salesforce Query Plan) - 🔜 未来增强 - ```typescript - // 新增: packages/spec/src/data/query-plan.zod.ts - export const QueryPlanSchema = z.object({ - estimatedCost: z.number(), - steps: z.array(z.object({ - operation: z.string(), - cost: z.number(), - cardinality: z.number(), - })), - warnings: z.array(z.string()).optional(), - }); - ``` - -**行业对标**: ⭐⭐⭐⭐⭐ (5/5) - **核心查询功能已达到行业最佳实践标准** - ---- - -### 1.3 Validation Protocol ✅ 完整度: 95% - -#### 现状评估 -**已实现**: -- ✅ Script Validation (Formula-based) -- ✅ Uniqueness Validation -- ✅ State Machine Validation -- ✅ Format Validation (Regex, Email, URL) -- ✅ Cross-Field Validation -- ✅ Conditional Validation -- ✅ Async Validation (External API) -- ✅ JSON Schema Validation - -**优化建议** ⚠️: -1. **添加 Validation Error I18n** (多语言错误消息) - ```typescript - // 增强: packages/spec/src/data/validation.zod.ts - message: z.union([ - z.string(), - z.record(z.string()), // { en: "...", zh: "...", fr: "..." } - ]).describe('Error message or i18n map'), - ``` - -2. **添加 Batch Validation 优化** (对标 ServiceNow) - ```typescript - // 新增: packages/spec/src/data/validation-batch.zod.ts - export const BatchValidationConfigSchema = z.object({ - parallel: z.boolean().default(true), - failFast: z.boolean().default(false), - maxConcurrency: z.number().default(10), - }); - ``` - -**行业对标**: ⭐⭐⭐⭐⭐ (5/5) - ---- - -### 1.4 Security Protocol ⚠️ 完整度: 70% - -#### 现状评估 -**已实现**: -- ✅ Object Permissions (CRUD) - `permission.zod.ts` -- ✅ Field Level Security (FLS) -- ✅ Sharing Rules - `sharing.zod.ts` -- ✅ Role Hierarchy - `role.zod.ts` - -**关键缺失** 🆕: -1. **Row-Level Security (RLS)** - 对标 PostgreSQL RLS / Salesforce Criteria-Based Sharing - ```typescript - // 新增: packages/spec/src/permission/rls.zod.ts - export const RowLevelSecuritySchema = z.object({ - name: z.string().regex(/^[a-z_][a-z0-9_]*$/), - object: z.string().describe('Target object'), - operation: z.enum(['select', 'insert', 'update', 'delete']), - using: z.string().describe('WHERE clause condition (e.g. "owner_id = current_user_id")'), - check: z.string().optional().describe('INSERT/UPDATE check condition'), - roles: z.array(z.string()).optional().describe('Apply to specific roles'), - }); - ``` - -2. **API Scopes & OAuth Scopes** (对标 Salesforce Connected Apps) - ```typescript - // 新增: packages/spec/src/auth/oauth-scope.zod.ts - export const OAuthScopeSchema = z.object({ - name: z.string().describe('Scope name (e.g. "api", "refresh_token", "full")'), - label: z.string(), - description: z.string().optional(), - permissions: z.array(z.string()).describe('Granted permissions'), - }); - ``` - -3. **Data Masking & Field Encryption** (对标 Salesforce Shield) - ```typescript - // 新增: packages/spec/src/permission/data-masking.zod.ts - export const DataMaskingRuleSchema = z.object({ - object: z.string(), - field: z.string(), - maskingType: z.enum([ - 'full', // *********** - 'partial', // ****5678 - 'hash', // SHA-256 - 'tokenize', // Replace with token - 'random', // Random data - ]), - visibleToRoles: z.array(z.string()).optional(), - }); - ``` - -**行业对标**: ⭐⭐⭐ (3/5) - 需要补充 RLS - ---- - -## 2️⃣ ObjectUI：界面与交互层 (The "Face") - -### 2.1 View DSL ✅ 完整度: 90% - -#### 现状评估 -**已实现**: -- ✅ Layouts (Grid, Kanban, Calendar, Gantt) - `view.zod.ts` -- ✅ Form Views (Simple, Tabbed, Wizard) -- ✅ Data Binding (Object, API, Static) -- ✅ Component Props (Field overrides) - -**优化建议** ⚠️: -1. **添加响应式布局断点** (对标 TailwindCSS) - ```typescript - // 增强: packages/spec/src/ui/view.zod.ts - responsive: z.object({ - sm: z.number().optional(), // Mobile - md: z.number().optional(), // Tablet - lg: z.number().optional(), // Desktop - xl: z.number().optional(), // Wide Desktop - }).optional().describe('Responsive column spans'), - ``` - -2. **添加条件渲染协议** (对标 Salesforce Dynamic Forms) - ```typescript - // 增强: packages/spec/src/ui/view.zod.ts - conditionalRendering: z.array(z.object({ - condition: z.string().describe('Formula condition'), - show: z.array(z.string()).describe('Fields to show'), - hide: z.array(z.string()).describe('Fields to hide'), - })).optional(), - ``` - -**行业对标**: ⭐⭐⭐⭐ (4/5) - ---- - -### 2.2 Widget Contract ⚠️ 完整度: 50% - -#### 现状评估 -**已实现**: -- ✅ Basic widget schema - `widget.zod.ts` -- ✅ Field type mapping - -**关键缺失** 🆕: -1. **Widget Lifecycle Hooks** (对标 Web Components) - ```typescript - // 新增: packages/spec/src/ui/widget-lifecycle.zod.ts - export const WidgetLifecycleSchema = z.object({ - onMount: z.string().optional().describe('Called when widget is rendered'), - onUpdate: z.string().optional().describe('Called when props change'), - onUnmount: z.string().optional().describe('Called when widget is removed'), - onValidate: z.string().optional().describe('Custom validation logic'), - }); - ``` - -2. **Widget Event Protocol** (对标 Lightning Web Components) - ```typescript - // 新增: packages/spec/src/ui/widget-events.zod.ts - export const WidgetEventSchema = z.object({ - name: z.string().describe('Event name'), - bubbles: z.boolean().default(false), - cancelable: z.boolean().default(false), - payload: z.record(z.any()).describe('Event payload schema'), - }); - ``` - -3. **Widget Props Interface** (对标 React Props) - ```typescript - // 新增: packages/spec/src/ui/widget-props.zod.ts - export const WidgetPropsSchema = z.object({ - name: z.string(), - label: z.string(), - type: z.string().describe('TypeScript type'), - required: z.boolean().default(false), - default: z.any().optional(), - description: z.string().optional(), - }); - ``` - -**行业对标**: ⭐⭐ (2/5) - 需要完整的 Widget 合约系统 - ---- - -### 2.3 Action Protocol ✅ 完整度: 85% - -#### 现状评估 -**已实现**: -- ✅ Action Types (Script, URL, Modal, Flow, API) - `action.zod.ts` -- ✅ Triggers (OnClick, Location-based) -- ✅ Confirmation & Success Messages - -**优化建议** ⚠️: -1. **添加条件执行** (对标 Salesforce Dynamic Actions) - ```typescript - // 增强: packages/spec/src/ui/action.zod.ts - condition: z.string().optional().describe('Formula condition to enable action'), - ``` - -2. **添加批量操作支持** - ```typescript - // 增强: packages/spec/src/ui/action.zod.ts - batchSupport: z.boolean().default(false).describe('Support batch selection'), - batchLimit: z.number().optional().describe('Max records for batch'), - ``` - -**行业对标**: ⭐⭐⭐⭐ (4/5) - ---- - -### 2.4 Navigation DSL ✅ 完整度: 90% - -#### 现状评估 -**已实现**: -- ✅ Menu Structure (Hierarchical) - `app.zod.ts` -- ✅ Routing (Object, Dashboard, Page, URL) -- ✅ Breadcrumbs (implicitly via hierarchy) - -**优化建议** ⚠️: -1. **添加动态面包屑配置** - ```typescript - // 增强: packages/spec/src/ui/navigation.zod.ts - export const BreadcrumbConfigSchema = z.object({ - enabled: z.boolean().default(true), - maxDepth: z.number().default(3), - customLabels: z.record(z.string()).optional(), - }); - ``` - -**行业对标**: ⭐⭐⭐⭐⭐ (5/5) - ---- - -## 3️⃣ ObjectOS：业务与系统层 (The "Heart") - -### 3.1 Workflow Protocol ✅ 完整度: 95% - -#### 现状评估 -**已实现**: -- ✅ Workflow Rules - `workflow.zod.ts` -- ✅ State Machine - `validation.zod.ts` (State Machine Validation) -- ✅ 10+ Action Types (Email, Slack, Webhook, Field Update, etc.) -- ✅ Time Triggers -- ✅ Flow Orchestration - `flow.zod.ts` - -**优化建议** ⚠️: -1. **添加 BPMN 2.0 兼容模式** (对标 Camunda) - ```typescript - // 新增: packages/spec/src/automation/bpmn.zod.ts - export const BPMNProcessSchema = z.object({ - id: z.string(), - name: z.string(), - startEvents: z.array(BPMNStartEventSchema), - tasks: z.array(BPMNTaskSchema), - gateways: z.array(BPMNGatewaySchema), - endEvents: z.array(BPMNEndEventSchema), - }); - ``` - -**行业对标**: ⭐⭐⭐⭐⭐ (5/5) - ---- - -### 3.2 Plugin Manifest ✅ 完整度: 90% - -#### 现状评估 -**已实现**: -- ✅ Lifecycle Hooks (Install, Enable, Disable, Uninstall) - `plugin.zod.ts` -- ✅ Dependencies - `manifest.zod.ts` -- ✅ Capabilities Declaration (API, UI, Jobs) -- ✅ Configuration Schema -- ✅ Contribution Points (Kinds, Events, Menus, Themes) - -**优化建议** ⚠️: -1. **添加插件沙箱配置** (对标 VS Code Extensions) - ```typescript - // 增强: packages/spec/src/kernel/manifest.zod.ts - sandbox: z.object({ - enabled: z.boolean().default(true), - permissions: z.array(z.string()), - resourceLimits: z.object({ - maxMemoryMb: z.number().default(512), - maxCpuPercent: z.number().default(50), - }), - }).optional(), - ``` - -**行业对标**: ⭐⭐⭐⭐⭐ (5/5) - ---- - -### 3.3 Integration Protocol ⚠️ 完整度: 60% - -#### 现状评估 -**已实现**: -- ✅ Webhooks (Outbound) - `webhook.zod.ts` -- ✅ Webhook Receivers (Inbound) -- ✅ API Endpoints - `endpoint.zod.ts` -- ✅ Data Mapping - `mapping.zod.ts` - -**关键缺失** 🆕: -1. **ETL Pipeline Protocol** (对标 Airbyte) - ```typescript - // 新增: packages/spec/src/automation/etl.zod.ts - export const ETLPipelineSchema = z.object({ - name: z.string().regex(/^[a-z_][a-z0-9_]*$/), - source: z.object({ - type: z.enum(['database', 'api', 'file', 'stream']), - config: z.record(z.any()), - }), - destination: z.object({ - type: z.enum(['database', 'api', 'file', 'stream']), - config: z.record(z.any()), - }), - transformations: z.array(z.object({ - type: z.enum(['map', 'filter', 'aggregate', 'join', 'script']), - config: z.record(z.any()), - })), - schedule: z.string().optional().describe('Cron expression'), - }); - ``` - -2. **Connector Registry** (对标 Zapier Integration Schema) - ```typescript - // 新增: packages/spec/src/automation/connector.zod.ts - export const ConnectorSchema = z.object({ - id: z.string().describe('Connector ID (e.g. "salesforce", "stripe")'), - name: z.string(), - description: z.string().optional(), - category: z.enum(['crm', 'payment', 'storage', 'communication', 'analytics']), - authentication: z.discriminatedUnion('type', [ - OAuth2AuthSchema, - APIKeyAuthSchema, - BasicAuthSchema, - ]), - operations: z.array(z.object({ - id: z.string(), - name: z.string(), - type: z.enum(['read', 'write', 'trigger']), - inputSchema: z.record(z.any()), - outputSchema: z.record(z.any()), - })), - triggers: z.array(z.object({ - id: z.string(), - name: z.string(), - type: z.enum(['webhook', 'polling']), - config: z.record(z.any()), - })).optional(), - }); - ``` - -3. **Data Sync Protocol** (对标 Salesforce Connect) - ```typescript - // 新增: packages/spec/src/automation/sync.zod.ts - export const DataSyncConfigSchema = z.object({ - name: z.string(), - source: z.object({ - object: z.string(), - filters: z.any().optional(), - }), - destination: z.object({ - connector: z.string(), - operation: z.string(), - mapping: z.record(z.string()), - }), - syncMode: z.enum(['full', 'incremental']), - schedule: z.string().optional(), - conflictResolution: z.enum(['source_wins', 'destination_wins', 'manual']), - }); - ``` - -**行业对标**: ⭐⭐⭐ (3/5) - 需要补充 ETL & Connectors - ---- - -### 3.4 Identity & SSO ⚠️ 完整度: 65% - -#### 现状评估 -**已实现**: -- ✅ User Model - `identity.zod.ts` -- ✅ Account Linking (OAuth, OIDC, SAML) -- ✅ Session Management -- ✅ Multi-Organization Support - -**关键缺失** 🆕: -1. **SCIM 2.0 Protocol** (对标 Okta, Azure AD) - ⭐ 重点推荐 - ```typescript - // 新增: packages/spec/src/auth/scim.zod.ts - export const SCIMUserSchema = z.object({ - schemas: z.array(z.string()).default(['urn:ietf:params:scim:schemas:core:2.0:User']), - id: z.string().optional(), - externalId: z.string().optional(), - userName: z.string().describe('Unique identifier'), - name: z.object({ - formatted: z.string().optional(), - familyName: z.string().optional(), - givenName: z.string().optional(), - middleName: z.string().optional(), - honorificPrefix: z.string().optional(), - honorificSuffix: z.string().optional(), - }).optional(), - emails: z.array(z.object({ - value: z.string().email(), - type: z.enum(['work', 'home', 'other']).optional(), - primary: z.boolean().default(false), - })), - active: z.boolean().default(true), - groups: z.array(z.object({ - value: z.string(), - display: z.string().optional(), - })).optional(), - meta: z.object({ - resourceType: z.string().default('User'), - created: z.string().datetime().optional(), - lastModified: z.string().datetime().optional(), - location: z.string().url().optional(), - }).optional(), - }); - - export const SCIMGroupSchema = z.object({ - schemas: z.array(z.string()).default(['urn:ietf:params:scim:schemas:core:2.0:Group']), - id: z.string().optional(), - displayName: z.string(), - members: z.array(z.object({ - value: z.string(), - display: z.string().optional(), - })).optional(), - meta: z.object({ - resourceType: z.string().default('Group'), - created: z.string().datetime().optional(), - lastModified: z.string().datetime().optional(), - }).optional(), - }); - ``` - -2. **Federation Protocol** (LDAP/AD Integration) - ```typescript - // 新增: packages/spec/src/auth/federation.zod.ts - export const LDAPConfigSchema = z.object({ - enabled: z.boolean().default(false), - server: z.string().describe('LDAP server URL (e.g. ldap://ad.company.com)'), - port: z.number().default(389), - useSsl: z.boolean().default(false), - baseDn: z.string().describe('Base DN (e.g. dc=company,dc=com)'), - bindDn: z.string().describe('Bind DN for authentication'), - bindPassword: z.string().describe('Bind password'), - userFilter: z.string().describe('User search filter (e.g. (sAMAccountName={username}))'), - attributeMapping: z.object({ - username: z.string().default('sAMAccountName'), - email: z.string().default('mail'), - firstName: z.string().default('givenName'), - lastName: z.string().default('sn'), - groups: z.string().default('memberOf'), - }), - }); - ``` - -3. **Just-in-Time (JIT) Provisioning** (对标 Salesforce SSO) - ```typescript - // 新增: packages/spec/src/auth/jit-provisioning.zod.ts - export const JITProvisioningSchema = z.object({ - enabled: z.boolean().default(false), - createUsers: z.boolean().default(true), - updateUsers: z.boolean().default(true), - defaultRole: z.string().optional(), - defaultProfile: z.string().optional(), - attributeMapping: z.record(z.string()), - groupMapping: z.record(z.string()).optional(), - }); - ``` - -**行业对标**: ⭐⭐⭐ (3/5) - 需要补充 SCIM 2.0 - ---- - -### 3.5 Telemetry Protocol ✅ 完整度: 95% - -#### 现状评估 -**已实现**: -- ✅ Audit Logs - `audit.zod.ts` -- ✅ Event Types (50+ events) -- ✅ Retention Policies -- ✅ Suspicious Activity Detection -- ✅ Compliance Modes (SOX, HIPAA, GDPR) - -**优化建议** ⚠️: -1. **添加 OpenTelemetry 兼容** (对标 OTEL标准) - ```typescript - // 新增: packages/spec/src/system/telemetry-otel.zod.ts - export const OpenTelemetryConfigSchema = z.object({ - enabled: z.boolean().default(false), - endpoint: z.string().url().describe('OTLP endpoint'), - serviceName: z.string().default('objectstack'), - tracing: z.object({ - enabled: z.boolean().default(true), - sampleRate: z.number().min(0).max(1).default(1), - }), - metrics: z.object({ - enabled: z.boolean().default(true), - interval: z.number().default(60000).describe('Export interval in ms'), - }), - logs: z.object({ - enabled: z.boolean().default(true), - }), - }); - ``` - -**行业对标**: ⭐⭐⭐⭐⭐ (5/5) - ---- - -## 📊 总体完整度评分 (更新于 2026-01-27) - -| 层级 | 模块 | 完整度 | 变化 | 优先级 | 状态 | -|------|------|--------|------|--------|------| -| **ObjectQL** | Schema Definition DSL | **100%** | ⬆️ +5% | P2 | ✅ **完整** (Vector & Location 已实现) | -| | Query Protocol | **100%** | ⬆️ +10% | P1 | ✅ **完整** (Window Functions, HAVING, DISTINCT 已实现) | -| | Validation Protocol | 95% | - | P3 | ✅ 完整 | -| | Security Protocol | 70% | - | P0 | 🆕 需要 RLS | -| **ObjectUI** | View DSL | 90% | - | P2 | ⚠️ 需要响应式 | -| | Widget Contract | 50% | - | P1 | 🆕 需要完整合约 | -| | Action Protocol | 85% | - | P3 | ⚠️ 需要条件执行 | -| | Navigation DSL | 90% | - | P3 | ✅ 完整 | -| **ObjectOS** | Workflow Protocol | 95% | - | P3 | ✅ 完整 | -| | Plugin Manifest | 90% | - | P3 | ⚠️ 需要沙箱 | -| | Integration Protocol | 60% | - | P1 | 🆕 需要 ETL | -| | Identity & SSO | 65% | - | P0 | 🆕 需要 SCIM 2.0 | -| | Telemetry Protocol | 95% | - | P2 | ⚠️ 需要 OTEL | - -**总体完整度**: **87%** ✅ (⬆️ +4% 从上次评估) - -> 📘 **重大进展**: ObjectQL 数据层核心查询和字段类型功能已达到 100% 完整度！详见 [PROTOCOL_EXTENSIONS_COMPLETED.md](./PROTOCOL_EXTENSIONS_COMPLETED.md) - ---- - -## 🎯 实施计划 - -### Sprint 1 (P0 - 关键缺失) - 2周 - -#### 1. Row-Level Security (RLS) 🔒 -**文件**: `packages/spec/src/permission/rls.zod.ts` -```typescript -export const RowLevelSecuritySchema = z.object({ - name: z.string().regex(/^[a-z_][a-z0-9_]*$/), - object: z.string(), - operation: z.enum(['select', 'insert', 'update', 'delete']), - using: z.string(), - check: z.string().optional(), - roles: z.array(z.string()).optional(), -}); -``` -**测试**: `packages/spec/src/permission/rls.test.ts` -**文档**: `content/docs/specifications/security/rls.mdx` - -#### 2. SCIM 2.0 Protocol 👥 -**文件**: -- `packages/spec/src/auth/scim.zod.ts` (包含 User, Group, Enterprise Extension) -- `packages/spec/src/auth/scim.test.ts` - -**测试**: `packages/spec/src/auth/scim.test.ts` -**文档**: `content/docs/specifications/auth/scim.mdx` - -**验收标准**: -- [ ] SCIM User Schema 完整 -- [ ] SCIM Group Schema 完整 -- [ ] 支持标准 SCIM operations (GET, POST, PUT, PATCH, DELETE) -- [ ] 支持 SCIM filter query -- [ ] 测试覆盖率 ≥ 90% - ---- - -### Sprint 2 (P1 - 高优先级增强) - 3周 - -#### 1. Widget Contract System 🎨 -**文件**: -- `packages/spec/src/ui/widget-lifecycle.zod.ts` -- `packages/spec/src/ui/widget-events.zod.ts` -- `packages/spec/src/ui/widget-props.zod.ts` -- `packages/spec/src/ui/widget-manifest.zod.ts` - -**验收标准**: -- [ ] Lifecycle hooks (mount/update/unmount/validate) -- [ ] Event protocol (bubbles/cancelable/payload) -- [ ] Props interface schema -- [ ] Widget registry mechanism - -#### 2. ETL & Integration Connectors 🔌 -**文件**: -- `packages/spec/src/automation/etl.zod.ts` -- `packages/spec/src/automation/connector.zod.ts` -- `packages/spec/src/automation/sync.zod.ts` - -**验收标准**: -- [ ] ETL Pipeline definition -- [ ] Connector registry schema -- [ ] Data sync configuration -- [ ] 10+ 预定义 connectors (Salesforce, Stripe, etc.) - -#### 3. OData v4 Compatibility Layer 🌐 -**文件**: `packages/spec/src/api/odata.zod.ts` - -**验收标准**: -- [ ] OData query syntax parser -- [ ] $filter, $select, $expand, $orderby 支持 -- [ ] Query AST 转换器 - ---- - -### Sprint 3 (P2 - 中优先级优化) - 2周 - -#### 1. Schema Migration Protocol 🔄 -**文件**: `packages/spec/src/data/migration.zod.ts` - -#### 2. OpenTelemetry Integration 📊 -**文件**: `packages/spec/src/system/telemetry-otel.zod.ts` - -#### 3. Responsive Layout & Dynamic Forms 📱 -**增强**: -- `packages/spec/src/ui/view.zod.ts` (responsive breakpoints) -- `packages/spec/src/ui/view.zod.ts` (conditional rendering) - ---- - -### Sprint 4 (P3 - 低优先级完善) - 1周 - -#### 1. Data Masking & Encryption 🔐 -**文件**: `packages/spec/src/permission/data-masking.zod.ts` - -#### 2. BPMN 2.0 Compatibility 📐 -**文件**: `packages/spec/src/automation/bpmn.zod.ts` - -#### 3. GraphQL Schema Generator 🎯 -**文件**: `packages/spec/src/api/graphql-schema.zod.ts` - ---- - -## 📝 实施清单 (Checklist) - -### P0 - 必须立即实现 -- [ ] `permission/rls.zod.ts` - Row-Level Security -- [ ] `auth/scim.zod.ts` - SCIM 2.0 User & Group -- [ ] `auth/scim.test.ts` - SCIM Tests - -### P1 - 高优先级 (1个月内) -- [ ] `ui/widget-lifecycle.zod.ts` - Widget Lifecycle -- [ ] `ui/widget-events.zod.ts` - Widget Events -- [ ] `ui/widget-props.zod.ts` - Widget Props -- [ ] `automation/etl.zod.ts` - ETL Pipeline -- [ ] `automation/connector.zod.ts` - Connector Registry -- [ ] `automation/sync.zod.ts` - Data Sync -- [ ] `api/odata.zod.ts` - OData v4 - -### P2 - 中优先级 (2个月内) -- [ ] `data/migration.zod.ts` - Schema Migration -- [ ] `system/telemetry-otel.zod.ts` - OpenTelemetry -- [ ] 增强 `ui/view.zod.ts` - Responsive Layout -- [ ] 增强 `ui/view.zod.ts` - Conditional Rendering - -### P3 - 低优先级 (3个月内) -- [ ] `permission/data-masking.zod.ts` - Data Masking -- [ ] `automation/bpmn.zod.ts` - BPMN 2.0 -- [ ] `api/graphql-schema.zod.ts` - GraphQL Generator - ---- - -## 🎓 行业标准参考 - -### 必读文档 -1. **SCIM 2.0 RFC**: - - RFC 7643: SCIM Core Schema - - RFC 7644: SCIM Protocol - -2. **OData v4**: - - OData URL Conventions - - OData JSON Format - -3. **PostgreSQL RLS**: - - CREATE POLICY Documentation - - Row Security Policies - -4. **OpenTelemetry**: - - OTLP Specification - - Semantic Conventions - -### 对标产品 -- **Salesforce**: Security Model, Validation Rules, Formula Fields -- **ServiceNow**: Workflow Engine, ACL System -- **Kubernetes**: CRD Pattern, Admission Controllers -- **Prisma**: Schema Migration, Type Generation -- **Hasura**: GraphQL Auto-generation -- **Airbyte**: Connector Protocol, ETL Pipelines - ---- - -## ✅ 成功指标 - -1. **协议完整度**: 从 83% → 98% -2. **测试覆盖率**: 从 85% → 95% -3. **文档完整度**: 100% API Reference -4. **行业兼容性**: - - SCIM 2.0 ✅ - - OData v4 ✅ - - PostgreSQL RLS ✅ - - OpenTelemetry ✅ - ---- - -## 📞 后续行动 - -如需详细展开任何一个具体协议的实现细节，请告诉我： -1. 您希望我先实现哪个协议？ -2. 是否需要我提供某个协议的完整代码示例？ -3. 是否需要我为某个协议编写测试用例？ - -例如： -> "请为 Row-Level Security (RLS) 协议编写完整的 Zod Schema 和测试用例" diff --git a/PROTOCOL_ORGANIZATION.md b/PROTOCOL_ORGANIZATION.md deleted file mode 100644 index f8ea43cfc..000000000 --- a/PROTOCOL_ORGANIZATION.md +++ /dev/null @@ -1,245 +0,0 @@ -# ObjectStack Protocol Organization - -This document provides a visual map of how the 70 protocol specifications are organized across the ObjectStack ecosystem. - -``` -objectstack-ai/spec -└── packages/spec/src/ - │ - ├── 📊 DATA PROTOCOL (ObjectQL) - 8 files - │ ├── field.zod.ts → 44 field types (text, number, vector, location, etc.) - │ ├── object.zod.ts → Object/table definitions with fields and indexes - │ ├── query.zod.ts → Query AST (window functions, HAVING, DISTINCT, subqueries) - │ ├── validation.zod.ts → Validation rules for data integrity - │ ├── filter.zod.ts → Query filters and conditions - │ ├── dataset.zod.ts → Dataset definitions for analytics - │ ├── mapping.zod.ts → Field mapping for data transformation - │ └── hook.zod.ts → Lifecycle hooks (before/after CRUD) - │ - ├── 🎨 UI PROTOCOL (ObjectUI) - 10 files - │ ├── view.zod.ts → List views (grid, kanban, calendar, gantt) - │ ├── page.zod.ts → FlexiPage layouts with regions - │ ├── app.zod.ts → Application navigation menus - │ ├── dashboard.zod.ts → Dashboard layouts with widgets - │ ├── report.zod.ts → Report definitions (tabular, summary, matrix, chart) - │ ├── action.zod.ts → UI actions (buttons, scripts, flows) - │ ├── component.zod.ts → Reusable UI components - │ ├── block.zod.ts → UI block definitions - │ ├── theme.zod.ts → Theming (colors, typography, animations) - │ └── widget.zod.ts → Custom field widgets - │ - ├── ⚙️ SYSTEM PROTOCOL (ObjectOS) - 14 files - │ ├── manifest.zod.ts → Package manifest (objectstack.config.ts) - │ ├── datasource.zod.ts → Data source connections - │ ├── driver.zod.ts → Database driver definitions - │ ├── driver/ - │ │ ├── postgres.zod.ts → PostgreSQL driver config - │ │ └── mongo.zod.ts → MongoDB driver config - │ ├── plugin.zod.ts → Plugin lifecycle and interface - │ ├── context.zod.ts → Kernel execution context - │ ├── events.zod.ts → Event bus and pub/sub - │ ├── job.zod.ts → Background job scheduling - │ ├── audit.zod.ts → Audit logging - │ ├── logger.zod.ts → Structured logging - │ ├── translation.zod.ts → i18n/l10n support - │ ├── feature.zod.ts → Feature flags - │ └── scoped-storage.zod.ts → Key-value storage - │ - ├── 🤖 AI PROTOCOL - 8 files - │ ├── agent.zod.ts → AI agent definitions - │ ├── model-registry.zod.ts → LLM model registry - │ ├── rag-pipeline.zod.ts → Retrieval-augmented generation - │ ├── nlq.zod.ts → Natural language query (NL → ObjectQL) - │ ├── conversation.zod.ts → Conversation management - │ ├── cost.zod.ts → AI cost tracking - │ ├── predictive.zod.ts → Predictive analytics/ML models - │ └── orchestration.zod.ts → AI workflow orchestration - │ - ├── 🌐 API PROTOCOL - 6 files - │ ├── contract.zod.ts → API contracts and specifications - │ ├── endpoint.zod.ts → REST endpoints with rate limiting - │ ├── router.zod.ts → API routing - │ ├── odata.zod.ts → OData query protocol - │ ├── realtime.zod.ts → WebSocket/SSE subscriptions - │ └── discovery.zod.ts → API discovery/introspection - │ - ├── 🔄 AUTOMATION PROTOCOL - 7 files - │ ├── flow.zod.ts → Visual workflow builder - │ ├── workflow.zod.ts → Declarative workflow rules - │ ├── approval.zod.ts → Multi-step approval processes - │ ├── webhook.zod.ts → Outbound webhooks - │ ├── etl.zod.ts → ETL data pipelines - │ ├── sync.zod.ts → Bi-directional data sync - │ └── connector.zod.ts → External system connectors - │ - ├── 🔐 AUTH PROTOCOL - 6 files - │ ├── identity.zod.ts → User identity and profiles - │ ├── role.zod.ts → Role definitions (RBAC) - │ ├── organization.zod.ts → Multi-org structure - │ ├── policy.zod.ts → Password and session policies - │ ├── config.zod.ts → OAuth/SAML/SSO configs - │ └── scim.zod.ts → SCIM 2.0 provisioning - │ - ├── 🔒 PERMISSION PROTOCOL - 4 files - │ ├── permission.zod.ts → Object-level CRUD permissions - │ ├── sharing.zod.ts → Sharing rules (criteria & manual) - │ ├── rls.zod.ts → Row-level security - │ └── territory.zod.ts → Territory management - │ - ├── 🏪 HUB PROTOCOL - 5 files - │ ├── marketplace.zod.ts → Plugin marketplace listings - │ ├── composer.zod.ts → Package dependency management - │ ├── license.zod.ts → Feature licensing - │ ├── tenant.zod.ts → Multi-tenant isolation - │ └── space.zod.ts → Workspace/space management - │ - ├── 🔧 SHARED PROTOCOL - 1 file - │ └── identifiers.zod.ts → Standard identifier formats - │ - └── 📦 STACK PROTOCOL - 1 file - └── stack.zod.ts → Root stack definition (combines all protocols) -``` - -## Protocol Layers - -``` -┌─────────────────────────────────────────────────────────────┐ -│ STACK PROTOCOL (1) │ -│ Unified Stack Configuration │ -└─────────────────────────────────────────────────────────────┘ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ APPLICATION LAYER │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ AUTOMATION │ │ HUB │ │ AI │ │ -│ │ (7 specs) │ │ (5 specs) │ │ (8 specs) │ │ -│ └─────────────┘ └─────────────┘ └─────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ PRESENTATION LAYER │ -│ ┌─────────────────────────────────────────────────────┐ │ -│ │ UI PROTOCOL (10 specs) │ │ -│ │ Views, Pages, Apps, Dashboards, Reports, etc. │ │ -│ └─────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ BUSINESS LAYER │ -│ ┌─────────────────────────────────────────────────────┐ │ -│ │ DATA PROTOCOL (8 specs) │ │ -│ │ Objects, Fields, Queries, Validations, Hooks │ │ -│ └─────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ INFRASTRUCTURE LAYER │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ SYSTEM │ │ API │ │ AUTH │ │PERMISSION│ │ -│ │(14 specs)│ │(6 specs) │ │(6 specs) │ │(4 specs) │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -│ ┌─────────────────────────────────────────────────────┐ │ -│ │ SHARED PROTOCOL (1 spec) │ │ -│ │ Common Utilities & Identifiers │ │ -│ └─────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` - -## Protocol Dependencies - -``` - Stack Protocol - ▼ - ┌─────────┴─────────┐ - ▼ ▼ -Data Protocol UI Protocol - │ │ - ├─── Fields ────────┤ - ├─── Objects ───────┤ - └─── Queries │ - │ - ┌───────────────────┘ - ▼ -Automation Protocol - │ - ├─── Flows ─────────┐ - ├─── Workflows │ - └─── Approvals │ - ▼ - System Protocol - │ - ┌──────────────┼──────────────┐ - ▼ ▼ ▼ -Auth Protocol API Protocol Permission Protocol - │ - ┌─────┴─────┐ - ▼ ▼ - Sharing RLS -``` - -## Module Relationships - -| Consumer Module | Depends On | Relationship | -| :--- | :--- | :--- | -| **Stack** | All modules | Aggregates entire system | -| **UI** | Data, System, Auth | Renders data with security context | -| **Automation** | Data, System, AI | Orchestrates business logic | -| **AI** | Data, System | Enhances data with intelligence | -| **API** | Data, Auth, Permission | Exposes data with security | -| **Permission** | Data, Auth | Controls data access | -| **Hub** | System, Auth | Multi-tenant packaging | -| **Auth** | System | Identity foundation | -| **Data** | Shared | Core business model | -| **System** | Shared | Platform foundation | - -## File Naming Conventions - -All protocol files follow this pattern: - -``` -/.zod.ts -``` - -Examples: -- `data/field.zod.ts` → Field protocol -- `ui/view.zod.ts` → View protocol -- `system/manifest.zod.ts` → Manifest protocol -- `ai/agent.zod.ts` → AI agent protocol - -## Schema Naming Conventions - -Within each `.zod.ts` file: - -```typescript -// Primary schema (PascalCase + "Schema" suffix) -export const FieldSchema = z.object({ ... }); - -// Derived TypeScript type (inferred from Zod) -export type Field = z.infer; - -// Supporting schemas -export const SelectOptionSchema = z.object({ ... }); -export const VectorConfigSchema = z.object({ ... }); -``` - -## Quick Navigation - -| Need | File | Location | -| :--- | :--- | :--- | -| Define an object/table | `object.zod.ts` | `packages/spec/src/data/` | -| Define a field | `field.zod.ts` | `packages/spec/src/data/` | -| Create a view | `view.zod.ts` | `packages/spec/src/ui/` | -| Configure a dashboard | `dashboard.zod.ts` | `packages/spec/src/ui/` | -| Build a workflow | `flow.zod.ts` | `packages/spec/src/automation/` | -| Set up permissions | `permission.zod.ts` | `packages/spec/src/permission/` | -| Add authentication | `identity.zod.ts` | `packages/spec/src/auth/` | -| Create an AI agent | `agent.zod.ts` | `packages/spec/src/ai/` | -| Configure a plugin | `manifest.zod.ts` | `packages/spec/src/system/` | -| Define an API endpoint | `endpoint.zod.ts` | `packages/spec/src/api/` | - -## See Also - -- **[PROTOCOL_REFERENCE.md](./PROTOCOL_REFERENCE.md)** - Complete protocol inventory with detailed descriptions -- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System architecture overview -- **[README.md](./README.md)** - Project overview and getting started -- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contributing guidelines diff --git a/PROTOCOL_REFERENCE.md b/PROTOCOL_REFERENCE.md deleted file mode 100644 index 83dcc9451..000000000 --- a/PROTOCOL_REFERENCE.md +++ /dev/null @@ -1,387 +0,0 @@ -# ObjectStack Protocol Reference - -> **Complete inventory of all protocol specifications in the ObjectStack ecosystem.** - -Last Updated: 2026-01-27 - -**📖 See also:** -- [PROTOCOL_INDEX.md](./PROTOCOL_INDEX.md) for quick navigation links to all protocols -- [PROTOCOL_ORGANIZATION.md](./PROTOCOL_ORGANIZATION.md) for visual diagrams and protocol relationships - -## Overview - -This document provides a comprehensive reference to all 70 protocol specifications that define the ObjectStack platform. Each protocol is implemented as a Zod schema (`.zod.ts` file) providing runtime validation and TypeScript type safety. - -## Protocol Statistics - -| Module | Protocol Files | Description | -| :--- | :---: | :--- | -| **Data Protocol** | 8 | Core business logic and data modeling | -| **UI Protocol** | 10 | User interface definitions and interactions | -| **System Protocol** | 14 | Runtime environment and platform capabilities | -| **AI Protocol** | 8 | AI/ML integration and agent orchestration | -| **API Protocol** | 6 | Standardized API contracts and communication | -| **Automation Protocol** | 7 | Workflow automation and integration | -| **Auth Protocol** | 6 | Identity, authentication, and authorization | -| **Permission Protocol** | 4 | Access control and security policies | -| **Hub Protocol** | 5 | Marketplace and multi-tenancy | -| **Shared Protocol** | 1 | Common utilities and identifiers | -| **Stack Protocol** | 1 | Root stack definition | -| **Total** | **70** | **Complete protocol suite** | - -## Protocol Modules - -### 1. Data Protocol (ObjectQL) -**Location:** `packages/spec/src/data/` - -Defines the "Shape of Data" and business logic. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `field.zod.ts` | `FieldSchema` | Field definitions with 44 types (text, number, select, lookup, formula, vector, location, etc.) | -| `object.zod.ts` | `ObjectSchema` | Object/table definitions with fields, indexes, and capabilities | -| `query.zod.ts` | `QuerySchema` | Abstract query AST supporting window functions, HAVING, DISTINCT, subqueries | -| `validation.zod.ts` | `ValidationRuleSchema` | Validation rules for data integrity | -| `filter.zod.ts` | `FilterSchema` | Query filtering and conditions | -| `dataset.zod.ts` | `DatasetSchema` | Dataset definitions for reporting and analytics | -| `mapping.zod.ts` | `FieldMappingSchema` | Field mapping configurations for data transformation | -| `hook.zod.ts` | `HookSchema` | Lifecycle hooks (before/after insert, update, delete) | - -**Key Features:** -- 44 field types including AI/ML vectors and GPS locations -- Advanced query capabilities (window functions, HAVING, DISTINCT, subqueries) -- Validation rules and formulas -- Lifecycle hooks for business logic - -### 2. UI Protocol (ObjectUI) -**Location:** `packages/spec/src/ui/` - -Defines the "Shape of Interaction" for rendering interfaces. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `view.zod.ts` | `ViewSchema` | List views (grid, kanban, calendar, gantt) and form layouts | -| `page.zod.ts` | `PageSchema` | FlexiPage layouts with regions and components | -| `app.zod.ts` | `AppSchema` | Application structure and navigation menus | -| `dashboard.zod.ts` | `DashboardSchema` | Dashboard layouts with grid-based widgets | -| `report.zod.ts` | `ReportSchema` | Report definitions (tabular, summary, matrix, chart) | -| `action.zod.ts` | `ActionSchema` | UI actions (buttons, scripts, URLs, flows) | -| `component.zod.ts` | `ComponentSchema` | Reusable UI components | -| `block.zod.ts` | `BlockSchema` | UI block definitions | -| `theme.zod.ts` | `ThemeSchema` | Theming (colors, typography, breakpoints, animations) | -| `widget.zod.ts` | `WidgetSchema` | Custom field widgets with lifecycle hooks | - -**Key Features:** -- Server-driven UI with multiple view types -- Flexible page layouts with component regions -- Rich dashboard and reporting capabilities -- Comprehensive theming system - -### 3. System Protocol (ObjectOS) -**Location:** `packages/spec/src/system/` - -Defines the "Runtime Environment" and platform capabilities. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `manifest.zod.ts` | `ManifestSchema` | Application/plugin manifest (`objectstack.config.ts`) with 7 package types: app, plugin, driver, module, objectql, gateway, adapter | -| `datasource.zod.ts` | `DatasourceSchema` | Data source connection configurations | -| `driver.zod.ts` | `DriverSchema` | Database driver definitions and options | -| `driver/postgres.zod.ts` | `PostgresConfigSchema` | PostgreSQL-specific driver configuration | -| `driver/mongo.zod.ts` | `MongoConfigSchema` | MongoDB-specific driver configuration | -| `plugin.zod.ts` | `PluginSchema` | Plugin lifecycle and interface definitions | -| `context.zod.ts` | `KernelContextSchema` | Kernel execution context with user, org, tenant info | -| `events.zod.ts` | `EventSchema` | Event bus and pub/sub patterns | -| `job.zod.ts` | `JobSchema` | Background job scheduling (cron, interval, delayed) | -| `audit.zod.ts` | `AuditEventSchema` | Audit logging for compliance | -| `logger.zod.ts` | `LoggerConfigSchema` | Structured logging configuration | -| `translation.zod.ts` | `TranslationSchema` | i18n/l10n support | -| `feature.zod.ts` | `FeatureFlagSchema` | Feature flag definitions | -| `scoped-storage.zod.ts` | `ScopedStorageSchema` | Scoped key-value storage | - -**Key Features:** -- Microkernel architecture with 7 distinct package types for proper separation of concerns - - **adapter**: Runtime containers (Express, Hono, Fastify, Serverless) - - **gateway**: API protocols (GraphQL, REST, RPC, OData) - - **objectql**: Core data engine implementation - - **driver**: Database/external service adapters (Postgres, MongoDB, S3) - - **plugin**: General-purpose functionality extensions - - **app**: Business application packages - - **module**: Reusable code libraries -- Pluggable architecture with manifest-based configuration -- Multi-driver support (PostgreSQL, MongoDB, and extensible) -- Event-driven architecture with pub/sub -- Comprehensive audit and logging capabilities -- Feature flags and i18n support - -### 4. AI Protocol -**Location:** `packages/spec/src/ai/` - -Defines AI agent integration capabilities. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `agent.zod.ts` | `AgentSchema` | AI agent definitions and configurations | -| `model-registry.zod.ts` | `ModelRegistrySchema` | LLM model registry and selection | -| `rag-pipeline.zod.ts` | `RAGPipelineSchema` | Retrieval-augmented generation pipeline | -| `nlq.zod.ts` | `NLQSchema` | Natural language query processing | -| `conversation.zod.ts` | `ConversationSchema` | Conversation management and memory | -| `cost.zod.ts` | `CostTrackingSchema` | AI cost tracking and budgeting | -| `predictive.zod.ts` | `PredictiveModelSchema` | Predictive analytics and ML models | -| `orchestration.zod.ts` | `OrchestrationSchema` | AI workflow orchestration | - -**Key Features:** -- Multi-provider LLM support -- RAG pipeline for semantic search -- Natural language to ObjectQL translation -- Conversation history and context management -- Cost tracking and budget controls - -### 5. API Protocol -**Location:** `packages/spec/src/api/` - -Defines standardized API contracts. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `contract.zod.ts` | `ApiContractSchema` | API endpoint contracts and specifications | -| `endpoint.zod.ts` | `EndpointSchema` | REST endpoint definitions with rate limiting | -| `router.zod.ts` | `RouterSchema` | API routing configuration | -| `odata.zod.ts` | `ODataQuerySchema` | OData query protocol support | -| `realtime.zod.ts` | `RealtimeSchema` | WebSocket/SSE real-time subscriptions | -| `discovery.zod.ts` | `DiscoverySchema` | API discovery and introspection | - -**Key Features:** -- RESTful API contracts -- OData query support -- Real-time subscriptions (WebSocket/SSE) -- API rate limiting and throttling -- Auto-discovery and introspection - -### 6. Automation Protocol -**Location:** `packages/spec/src/automation/` - -Workflow automation and integration. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `flow.zod.ts` | `FlowSchema` | Visual workflow builder (Screen, Autolaunched, Schedule) | -| `workflow.zod.ts` | `WorkflowSchema` | Declarative workflow rules (field updates, alerts) | -| `approval.zod.ts` | `ApprovalProcessSchema` | Multi-step approval processes | -| `webhook.zod.ts` | `WebhookSchema` | Outbound webhook definitions | -| `etl.zod.ts` | `ETLPipelineSchema` | ETL data pipelines | -| `sync.zod.ts` | `SyncConfigSchema` | Bi-directional data synchronization | -| `connector.zod.ts` | `ConnectorSchema` | External system connectors | - -**Key Features:** -- Visual flow builder with drag-and-drop -- Declarative workflow automation -- Multi-step approval processes -- Webhook integrations -- ETL and data sync capabilities - -### 7. Auth Protocol -**Location:** `packages/spec/src/auth/` - -Identity, authentication, and authorization. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `identity.zod.ts` | `UserSchema` | User identity and profile | -| `role.zod.ts` | `RoleSchema` | Role definitions and permissions | -| `organization.zod.ts` | `OrganizationSchema` | Multi-org structure | -| `policy.zod.ts` | `PasswordPolicySchema` | Password and session policies | -| `config.zod.ts` | `AuthConfigSchema` | OAuth, SAML, SSO configurations | -| `scim.zod.ts` | `SCIMSchema` | SCIM 2.0 provisioning protocol | - -**Key Features:** -- Multi-provider authentication (OAuth, SAML, SSO) -- Role-based access control (RBAC) -- Multi-organization support -- SCIM 2.0 for user provisioning -- Configurable password policies - -### 8. Permission Protocol -**Location:** `packages/spec/src/permission/` - -Access control and security policies. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `permission.zod.ts` | `ObjectPermissionSchema` | Object-level CRUD permissions | -| `sharing.zod.ts` | `SharingRuleSchema` | Criteria-based and manual sharing rules | -| `rls.zod.ts` | `RowLevelSecuritySchema` | Row-level security policies | -| `territory.zod.ts` | `TerritorySchema` | Territory management for hierarchical access | - -**Key Features:** -- Multi-layered permission model -- Object, field, and record-level security -- Criteria-based sharing rules -- Territory-based access control - -### 9. Hub Protocol -**Location:** `packages/spec/src/hub/` - -Marketplace and multi-tenancy. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `marketplace.zod.ts` | `MarketplaceListingSchema` | Plugin marketplace listings | -| `composer.zod.ts` | `PackageComposerSchema` | Package dependency management | -| `license.zod.ts` | `LicenseSchema` | Feature licensing and entitlements | -| `tenant.zod.ts` | `TenantSchema` | Multi-tenant isolation and quotas | -| `space.zod.ts` | `SpaceSchema` | Workspace/space management | - -**Key Features:** -- Plugin marketplace with versioning -- Dependency resolution and composition -- Feature-based licensing -- Multi-tenancy with quota enforcement -- Workspace management - -### 10. Shared Protocol -**Location:** `packages/spec/src/shared/` - -Common utilities and identifiers. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `identifiers.zod.ts` | `SystemIdentifierSchema` | Standard identifier formats and validation | - -**Key Features:** -- Consistent identifier patterns across all protocols -- Validation for machine names (snake_case) -- Support for namespaced identifiers - -### 11. Stack Protocol -**Location:** `packages/spec/src/` - -Root stack definition. - -| File | Schema | Purpose | -| :--- | :--- | :--- | -| `stack.zod.ts` | `ObjectStackDefinitionSchema` | Complete stack configuration combining all protocols | - -**Key Features:** -- Unified stack configuration -- Aggregates all protocol modules -- Entry point for complete application definition - -## Naming Conventions - -All protocols follow strict naming conventions: - -| Context | Convention | Example | -| :--- | :--- | :--- | -| **Configuration Keys** | `camelCase` | `maxLength`, `referenceFilters`, `deleteBehavior` | -| **Machine Names** | `snake_case` | `name: 'project_task'`, `object: 'account'` | -| **Schema Names** | `PascalCase` with `Schema` suffix | `FieldSchema`, `ObjectSchema` | -| **Type Names** | `PascalCase` inferred from Zod | `type Field = z.infer` | - -## Protocol Design Principles - -1. **Zod First**: All protocols start with Zod schemas for runtime validation -2. **Type Safety**: TypeScript types are derived from Zod schemas (`z.infer<>`) -3. **JSON Schema**: All Zod schemas generate JSON schemas for IDE support -4. **No Business Logic**: Protocol specs contain only definitions, no implementation -5. **Backward Compatibility**: Breaking changes require major version bumps -6. **Extensibility**: All protocols support custom extensions and plugins - -## Usage Examples - -### Importing Protocols - -```typescript -// Import individual schemas -import { FieldSchema, ObjectSchema } from '@objectstack/spec/data'; -import { ViewSchema, AppSchema } from '@objectstack/spec/ui'; -import { ManifestSchema } from '@objectstack/spec/system'; - -// Import types -import type { Field, Object } from '@objectstack/spec/data'; -import type { View, App } from '@objectstack/spec/ui'; - -// Validate at runtime -const field = FieldSchema.parse({ - name: 'account_name', - type: 'text', - label: 'Account Name', - required: true, - maxLength: 255 -}); -``` - -### Building Applications - -```typescript -import { ObjectStackDefinitionSchema } from '@objectstack/spec'; - -const myApp = ObjectStackDefinitionSchema.parse({ - manifest: { - name: 'my-crm', - version: '1.0.0', - description: 'Custom CRM Application' - }, - objects: [ - { - name: 'account', - label: 'Account', - fields: [ - { name: 'name', type: 'text', label: 'Account Name', required: true }, - { name: 'industry', type: 'select', label: 'Industry' } - ] - } - ], - views: [ - { - name: 'account_list', - object: 'account', - type: 'grid', - columns: ['name', 'industry'] - } - ] -}); -``` - -## Documentation - -For detailed documentation on each protocol, see: - -- **[ObjectQL (Data Layer)](/content/docs/objectql/)** - Data modeling and queries -- **[ObjectUI (UI Layer)](/content/docs/objectui/)** - User interface definitions -- **[ObjectOS (System Layer)](/content/docs/objectos/)** - Runtime and platform -- **[API Reference](/content/docs/references/)** - Complete API documentation -- **[Examples](/examples/)** - Reference implementations - -## Contributing - -When adding or modifying protocols: - -1. ✅ Define Zod schema first -2. ✅ Add comprehensive JSDoc comments with `@description` -3. ✅ Follow naming conventions (camelCase for config, snake_case for names) -4. ✅ Write unit tests with 80%+ coverage -5. ✅ Generate JSON schema: `pnpm --filter @objectstack/spec build` -6. ✅ Update this reference document -7. ✅ Add examples to documentation - -See [CONTRIBUTING.md](/CONTRIBUTING.md) for complete guidelines. - -## Version History - -| Date | Version | Protocols | Notes | -| :--- | :--- | :---: | :--- | -| 2026-01-27 | 0.4.x | 70 | Complete protocol suite with AI, advanced query features | -| 2026-01-20 | 0.3.x | 68 | Added vector and location field types | -| 2025-12-15 | 0.2.x | 65 | Initial multi-module protocol structure | - -## License - -Apache 2.0 © ObjectStack - ---- - -**See Also:** -- [Architecture Overview](./ARCHITECTURE.md) -- [Development Roadmap](./internal/planning/DEVELOPMENT_ROADMAP.md) -- [Contributing Guide](./CONTRIBUTING.md) diff --git a/README.md b/README.md index 3ff122788..094a7b3db 100644 --- a/README.md +++ b/README.md @@ -8,137 +8,38 @@ This repository contains the core specifications, schemas, and protocols that power the ObjectStack ecosystem. It defines how data, UI, and system configurations are expressed as code. -## 🎉 Recent Updates (2026-01-27) +## 🎯 What is ObjectStack? -**ObjectQL (Data Layer) now at 100% completion!** 🎯 +ObjectStack is a metadata-driven platform built on three foundational protocols: -We've completed all advanced query features and AI/ML field types: -- ✅ **Window Functions** - ROW_NUMBER, RANK, LAG, LEAD, and aggregate window functions -- ✅ **HAVING Clause** - Filter aggregated results in GROUP BY queries -- ✅ **DISTINCT Queries** - Full support for SELECT DISTINCT -- ✅ **Subqueries** - Nested queries in JOIN clauses -- ✅ **Vector Field Type** - AI/ML embeddings for semantic search and RAG workflows -- ✅ **Location Field Type** - GPS coordinates for geospatial applications +- **ObjectQL** (Data Layer) - Define data structure and queries +- **ObjectOS** (Control Layer) - Runtime, permissions, and workflows +- **ObjectUI** (View Layer) - Presentation and user interaction -**See [PROTOCOL_EXTENSIONS_COMPLETED.md](./PROTOCOL_EXTENSIONS_COMPLETED.md) for complete details.** +**Learn more:** [Architecture Overview](./content/docs/introduction/architecture.mdx) ## 📚 Documentation -### Protocol Reference -* **[Protocol Index](./PROTOCOL_INDEX.md):** 📑 **Quick navigation index** to all 70 protocol specifications with direct links -* **[Protocol Reference](./PROTOCOL_REFERENCE.md):** 📖 **Complete inventory** with detailed descriptions, usage examples, and organization by module -* **[Protocol Organization](./PROTOCOL_ORGANIZATION.md):** 🗺️ **Visual diagrams and maps** showing protocol structure, dependencies, and relationships +📖 **[Read the Full Documentation](./content/docs/)** -### Quick Start -* **[Protocol Index](./PROTOCOL_INDEX.md):** Quick navigation to all protocol specifications -* **[Contributing Guide](./CONTRIBUTING.md):** How to contribute to the project +### Quick Links -### Architecture & Design -* **[Architecture Overview](./ARCHITECTURE.md):** Deep dive into the three-layer architecture -* **[Protocol Organization](./PROTOCOL_ORGANIZATION.md):** Visual diagrams showing protocol structure and dependencies +- **Getting Started:** + - [Introduction](./content/docs/introduction/) - Core concepts and architecture + - [Quick Start Examples](./examples/) - CRM, Todo, and plugin examples + +- **Protocol References:** + - [Protocol Reference](./content/docs/references/) - All 70 protocol specifications + - [ObjectQL](./content/docs/objectql/) - Data layer documentation + - [ObjectUI](./content/docs/objectui/) - UI layer documentation + - [ObjectOS](./content/docs/objectos/) - System layer documentation -### Standards & Best Practices -* **[Contributing Guide](./CONTRIBUTING.md):** Includes coding standards and best practices -* **[Protocol Reference](./PROTOCOL_REFERENCE.md):** Detailed documentation with usage examples +- **Development:** + - [MiniKernel Architecture](./content/docs/developers/mini-kernel.mdx) - Plugin architecture guide + - [Writing Plugins](./content/docs/developers/writing-plugins.mdx) - Plugin development guide + - [Contributing Guide](./CONTRIBUTING.md) - How to contribute -### Documentation Site -The official documentation is built with Fumadocs and Next.js. - -* **[Documentation Content](./content/docs/):** MDX documentation files (concepts, specifications, references) -* **[Documentation Site](./apps/docs/):** Fumadocs-powered Next.js app -* **[Live Site](http://localhost:3000/docs):** Run `pnpm docs:dev` to view locally - -### Planning & Internal Docs -* **[Protocol Extensions Completed](./PROTOCOL_EXTENSIONS_COMPLETED.md):** Recently completed features and updates -* **[Contributing Guide](./CONTRIBUTING.md):** Development workflow and guidelines - -## 📦 Monorepo Structure - -| Package | Description | Status | -| :--- | :--- | :--- | -| **[`@objectstack/spec`](packages/spec)** | **THE PROTOCOL**. Contains all Zod definitions, Types, and JSON Schemas. | 🟢 **Active** | -| **[`@objectstack/docs`](apps/docs)** | Documentation site built with Fumadocs and Next.js. | 🟢 **Active** | -| `content/docs/` | Documentation content (MDX files). Shared resource. | 🟢 **Active** | -| **Examples** | Reference implementations demonstrating protocol features | | -| └─ [`examples/crm`](examples/crm) | **Full-featured CRM** - 6 objects, workflows, validations, views, dashboards, reports | 🟢 **Complete** | -| └─ [`examples/todo`](examples/todo) | **Quick-start** - Simple task management with 7 field types | 🟢 **Active** | -| └─ [`examples/host`](examples/host) | Server runtime with kernel/plugin loading pattern | 🟡 **Experimental** | -| └─ [`examples/plugin-bi`](examples/plugin-bi) | Business Intelligence plugin example | 🟡 **Experimental** | -| *Other packages* | *Legacy/Migration in progress* | 🟡 *Legacy* | - -## 🛠️ The Protocol Architecture - -The ObjectStack Protocol (`@objectstack/spec`) contains **70 protocol specifications** organized into 11 modules. See **[PROTOCOL_REFERENCE.md](./PROTOCOL_REFERENCE.md)** for the complete inventory. - -### Core Modules (Summary) - -### 1. Data Protocol (ObjectQL) - 8 Protocols -Defines the "Shape of Data" and business logic. -- **Schema:** Objects, Fields (44 types including text, number, select, lookup, formula, autonumber, slider, qrcode, **vector** (AI/ML), **location** (GPS), etc.) -- **Logic:** Workflows, Triggers, Validation Rules, Formulas, Lifecycle Hooks -- **Security:** Permissions, Sharing Rules -- **Query:** Abstract Syntax Tree (AST) for unified data access across drivers with **Window Functions**, **HAVING**, **DISTINCT**, **Subqueries** -- **Automation:** Flow definitions, Dataset mappings - -### 2. UI Protocol (ObjectUI) - 10 Protocols -Defines the "Shape of Interaction" for rendering interfaces. -- **Views:** Grid, Kanban, Calendar, Gantt, List configurations -- **Pages:** FlexiPage layouts with regions and components -- **Navigation:** App menus and navigation structures -- **Analytics:** Reports (Tabular, Summary, Matrix), Dashboards with widgets -- **Actions:** Script, URL, Modal, Flow-triggered actions -- **Theming:** Color palettes, typography, breakpoints, animations -- **Widgets:** Custom field components - -### 3. System Protocol (ObjectOS) - 14 Protocols -Defines the "Runtime Environment" and platform capabilities. -- **Manifest:** Application packaging (`objectstack.config.ts`) with support for 7 package types: `app`, `plugin`, `driver`, `module`, `objectql`, `gateway`, `adapter` -- **Identity:** Authentication, Roles, Territories, Licenses, Organizations -- **Integration:** Webhooks, API contracts, ETL Mappings -- **Datasource:** Driver definitions for PostgreSQL, MongoDB, and extensible drivers -- **Discovery:** Plugin discovery and loading mechanisms -- **I18n:** Translation and internationalization support -- **Platform:** Events, Real-time sync, Audit logging, Background jobs, Feature flags - -### 4. AI Protocol - 8 Protocols -Defines AI agent integration capabilities. -- **Agent:** AI agent definitions and configurations -- **Model Registry:** LLM registry and selection -- **RAG Pipeline:** Retrieval-augmented generation -- **NLQ:** Natural language query processing (NL to ObjectQL) -- **Conversation:** Conversation management and memory -- **Cost Tracking:** AI cost tracking and budget management -- **Predictive:** Predictive analytics models -- **Orchestration:** AI-powered workflow automation - -### 5. API Protocol - 6 Protocols -Defines standardized API contracts. -- **Contracts:** API endpoint definitions and specifications -- **Endpoints:** REST endpoint definitions with rate limiting -- **Router:** API routing configuration -- **OData:** OData query protocol support -- **Realtime:** WebSocket/SSE real-time subscriptions -- **Discovery:** API discovery and introspection - -### Additional Modules -- **Automation Protocol** (7): Workflows, Flows, Approvals, ETL, Webhooks, Sync, Connectors -- **Auth Protocol** (6): Identity, Roles, Organizations, OAuth/SAML/SSO, SCIM, Policies -- **Permission Protocol** (4): Object permissions, Sharing rules, Row-level security, Territories -- **Hub Protocol** (5): Marketplace, Licensing, Multi-tenancy, Workspaces, Dependencies -- **Shared Protocol** (1): Common identifiers and utilities -- **Stack Protocol** (1): Root stack definition - -**👉 See [PROTOCOL_REFERENCE.md](./PROTOCOL_REFERENCE.md) for detailed documentation of all 70 protocols.** - -## 🚀 Development - -This project uses **PNPM** workspaces. - -### Prerequisites -- Node.js >= 18 -- PNPM >= 8 - -### Quick Start +## 🚀 Quick Start ```bash # 1. Install dependencies @@ -146,45 +47,37 @@ pnpm install # 2. Build the Protocol (Generates Schemas & Docs) pnpm --filter @objectstack/spec build -# Output: -# - packages/spec/dist/ (Compiled TS) -# - packages/spec/json-schema/ (JSON Schemas) # 3. Start Documentation Site pnpm docs:dev # Visit http://localhost:3000/docs ``` -## 🤝 Contributing - -We welcome contributions! Please read our **[Contributing Guide](./CONTRIBUTING.md)** for detailed guidelines. - -### Quick Start for Contributors - -1. **Read the Docs**: Review [CONTRIBUTING.md](./CONTRIBUTING.md) for complete guidelines -2. **Understand Architecture**: Read [ARCHITECTURE.md](./ARCHITECTURE.md) for system overview -3. **Explore Protocols**: See [PROTOCOL_REFERENCE.md](./PROTOCOL_REFERENCE.md) for detailed specifications -4. **Check Recent Work**: Review [PROTOCOL_EXTENSIONS_COMPLETED.md](./PROTOCOL_EXTENSIONS_COMPLETED.md) for latest updates +## 📦 Monorepo Structure -### Key Standards +| Package | Description | Status | +| :--- | :--- | :--- | +| **[`@objectstack/spec`](packages/spec)** | Core protocol definitions (Zod schemas, Types, JSON Schemas) | 🟢 Active | +| **[`@objectstack/docs`](apps/docs)** | Documentation site (Fumadocs + Next.js) | 🟢 Active | +| [`examples/crm`](examples/crm) | Full-featured CRM example | 🟢 Complete | +| [`examples/todo`](examples/todo) | Simple todo app example | 🟢 Active | -- **Naming Conventions**: Follow consistent naming across the codebase - - Configuration keys (TypeScript properties): `camelCase` (e.g., `maxLength`, `referenceFilters`) - - Machine names (data values): `snake_case` (e.g., `name: 'project_task'`, `object: 'account'`) -- **Zod-First Design**: All schemas must be defined using Zod with runtime validation -- **TypeScript**: Use strict TypeScript with comprehensive JSDoc comments +## 🤝 Contributing -### PR Checklist +We welcome contributions! Please read our **[Contributing Guide](./CONTRIBUTING.md)** for: -- [ ] Zod schema follows naming conventions -- [ ] Comprehensive JSDoc comments with `@description` -- [ ] Unit tests with 80%+ coverage -- [ ] Documentation with examples -- [ ] JSON schema generated successfully -- [ ] All existing tests pass +- Development workflow and setup +- Coding standards (Zod-first, camelCase config, snake_case data) +- Testing requirements +- Documentation guidelines -See [CONTRIBUTING.md](./CONTRIBUTING.md) for complete details. +**Key Standards:** +- All schemas defined using **Zod** with runtime validation +- Configuration keys: `camelCase` (e.g., `maxLength`) +- Machine names: `snake_case` (e.g., `project_task`) +- Comprehensive JSDoc comments +- 80%+ test coverage ## 📄 License -Apach2 2.0 © ObjectStack +Apache 2.0 © ObjectStack diff --git a/content/docs/developers/meta.json b/content/docs/developers/meta.json index 456a1fe79..e28e54114 100644 --- a/content/docs/developers/meta.json +++ b/content/docs/developers/meta.json @@ -2,6 +2,7 @@ "title": "🔧 Development & Extension", "root": true, "pages": [ + "mini-kernel", "writing-plugins", "custom-widgets", "server-drivers", diff --git a/content/docs/developers/mini-kernel.mdx b/content/docs/developers/mini-kernel.mdx new file mode 100644 index 000000000..e230c6716 --- /dev/null +++ b/content/docs/developers/mini-kernel.mdx @@ -0,0 +1,453 @@ +--- +title: MiniKernel Architecture +description: Understanding ObjectStack's micro-kernel plugin architecture for building extensible applications +--- + +# MiniKernel Architecture + +ObjectStack uses a **micro-kernel architecture** that separates core functionality from business logic. Like the Linux kernel, the ObjectKernel provides minimal essential services while all features are loaded as plugins. + +## Overview + +The MiniKernel architecture enables: +- ✅ Pluggable ObjectQL instances (bring your own query engine) +- ✅ Service registry for dependency injection (DI) +- ✅ Standardized plugin lifecycle (init/start/destroy) +- ✅ Event-driven communication between plugins +- ✅ Easy testing with mockable services + +## Architecture Diagram + +``` +┌─────────────────────────────────────────────────────────┐ +│ ObjectKernel (Core) │ +│ • Plugin Lifecycle Manager │ +│ • Service Registry (DI Container) │ +│ • Event Bus (Hook System) │ +│ • Dependency Resolver │ +└──────────────┬──────────────────────────────────────────┘ + │ + ┌───────┴────────┬────────────┬──────────┐ + │ │ │ │ + ┌────▼─────┐ ┌─────▼─────┐ ┌──▼───┐ ┌───▼────┐ + │ ObjectQL │ │ Driver │ │ Hono │ │ Custom │ + │ Plugin │ │ Plugin │ │Server│ │ Plugin │ + └──────────┘ └───────────┘ └──────┘ └────────┘ +``` + +## Core Components + +### 1. ObjectKernel + +The kernel manages plugin lifecycle and provides core services. + +**Location:** `packages/runtime/src/mini-kernel.ts` + +**API:** +```typescript +import { ObjectKernel } from '@objectstack/runtime'; + +const kernel = new ObjectKernel(); + +// Register plugins +kernel.use(plugin); + +// Start the kernel +await kernel.bootstrap(); + +// Access services +const ql = kernel.getService('objectql'); + +// Shutdown +await kernel.shutdown(); +``` + +### 2. Plugin Interface + +All plugins must implement the Plugin interface. + +**Location:** `packages/runtime/src/types.ts` + +**Definition:** +```typescript +interface Plugin { + name: string; + dependencies?: string[]; + init(ctx: PluginContext): Promise; + start?(ctx: PluginContext): Promise; + destroy?(): Promise; +} +``` + +### 3. Plugin Lifecycle + +``` +┌──────┐ +│ idle │ +└──┬───┘ + │ kernel.use(plugin) + ▼ +┌──────┐ +│ init │ ← Register services, subscribe to events +└──┬───┘ + │ kernel.bootstrap() + ▼ +┌───────┐ +│ start │ ← Connect to databases, start servers +└──┬────┘ + │ + ▼ +┌─────────┐ +│ running │ +└──┬──────┘ + │ kernel.shutdown() + ▼ +┌─────────┐ +│ destroy │ ← Clean up resources +└─────────┘ +``` + +### 4. PluginContext + +The context provides access to kernel services and hooks. + +**API:** +```typescript +interface PluginContext { + // Service Registry + registerService(name: string, service: any): void; + getService(name: string): T; + + // Event System + hook(name: string, handler: Function): void; + trigger(name: string, ...args: any[]): Promise; + + // Logger + logger: Logger; +} +``` + +## Built-in Plugins + +### ObjectQLPlugin + +Registers the ObjectQL query engine as a service. + +```typescript +import { ObjectKernel, ObjectQLPlugin } from '@objectstack/runtime'; + +const kernel = new ObjectKernel(); + +// Default ObjectQL instance +kernel.use(new ObjectQLPlugin()); + +// Or bring your own instance +import { ObjectQL } from '@objectstack/objectql'; +const customQL = new ObjectQL({ /* config */ }); +kernel.use(new ObjectQLPlugin(customQL)); +``` + +**Registers service:** `objectql` + +### DriverPlugin + +Registers a database driver with ObjectQL. + +```typescript +import { DriverPlugin } from '@objectstack/runtime'; +import { createMemoryDriver } from '@objectstack/driver-memory'; + +const driver = createMemoryDriver(); +kernel.use(new DriverPlugin(driver, 'memory')); +``` + +**Dependencies:** `['com.objectstack.engine.objectql']` + +### HonoServerPlugin + +Starts an HTTP server using Hono. + +```typescript +import { HonoServerPlugin } from '@objectstack/plugin-hono-server'; + +kernel.use(new HonoServerPlugin({ port: 3000 })); +``` + +## Creating Custom Plugins + +### Basic Plugin Example + +```typescript +import { Plugin, PluginContext } from '@objectstack/runtime'; + +export class MyPlugin implements Plugin { + name = 'com.mycompany.my-plugin'; + dependencies = ['com.objectstack.engine.objectql']; + + async init(ctx: PluginContext): Promise { + ctx.logger.info('MyPlugin initializing'); + + // Register a service + ctx.registerService('my-service', { + doSomething: () => console.log('Hello!'), + }); + + // Subscribe to events + ctx.hook('kernel:ready', async () => { + ctx.logger.info('Kernel is ready!'); + }); + } + + async start(ctx: PluginContext): Promise { + ctx.logger.info('MyPlugin starting'); + + // Get other services + const ql = ctx.getService('objectql'); + + // Register objects, start servers, etc. + } + + async destroy(): Promise { + // Clean up resources + } +} +``` + +### Plugin with Dependencies + +```typescript +export class AnalyticsPlugin implements Plugin { + name = 'com.mycompany.analytics'; + dependencies = [ + 'com.objectstack.engine.objectql', + 'com.mycompany.my-plugin', + ]; + + async init(ctx: PluginContext): Promise { + // This plugin will init AFTER its dependencies + const myService = ctx.getService('my-service'); + myService.doSomething(); + } +} +``` + +## Event System + +Plugins communicate via events (hooks). + +### Standard Events + +```typescript +// Kernel lifecycle +'kernel:init' // Before plugins init +'kernel:ready' // After all plugins start +'kernel:shutdown' // Before shutdown + +// Data lifecycle +'data:record:beforeCreate' // { table, data } +'data:record:afterCreate' // { table, record } +'data:record:beforeUpdate' // { table, id, data } +'data:record:afterUpdate' // { table, id, record } +'data:record:beforeDelete' // { table, id } +'data:record:afterDelete' // { table, id } + +// Server lifecycle +'server:route:register' // { method, path, handler } +'server:ready' // { port, url } +'server:request' // { method, path, query, body } +``` + +### Using Events + +```typescript +// Subscribe to events +ctx.hook('data:record:afterCreate', async (event) => { + console.log('Record created:', event.record); +}); + +// Trigger events +await ctx.trigger('my:custom:event', { data: 'value' }); +``` + +## Dependency Resolution + +The kernel automatically resolves plugin dependencies using topological sort. + +```typescript +const kernel = new ObjectKernel(); + +// These will be initialized in dependency order +kernel.use(new DriverPlugin(driver, 'memory')); // depends on ObjectQL +kernel.use(new ObjectQLPlugin()); // no dependencies +kernel.use(new MyAnalyticsPlugin()); // depends on both + +await kernel.bootstrap(); +// Order: ObjectQL → Driver → Analytics +``` + +## Testing with MiniKernel + +### Mock Services + +```typescript +import { ObjectKernel } from '@objectstack/runtime'; + +// Create test kernel +const kernel = new ObjectKernel(); + +// Register mock ObjectQL +kernel.use({ + name: 'objectql-mock', + async init(ctx) { + ctx.registerService('objectql', { + getSchema: () => mockSchema, + query: () => mockData, + }); + }, +}); + +// Test your plugin +kernel.use(new MyPlugin()); +await kernel.bootstrap(); +``` + +### Integration Tests + +```typescript +import { describe, it, expect } from 'vitest'; +import { ObjectKernel, ObjectQLPlugin } from '@objectstack/runtime'; + +describe('MyPlugin', () => { + it('should register service', async () => { + const kernel = new ObjectKernel(); + kernel.use(new ObjectQLPlugin()); + kernel.use(new MyPlugin()); + + await kernel.bootstrap(); + + const service = kernel.getService('my-service'); + expect(service).toBeDefined(); + + await kernel.shutdown(); + }); +}); +``` + +## Configuration-Driven Loading + +Load plugins from a configuration file: + +```typescript +// objectstack.config.ts +export default { + plugins: [ + { name: '@objectstack/runtime#ObjectQLPlugin' }, + { name: '@objectstack/driver-memory#MemoryDriverPlugin' }, + { name: '@objectstack/plugin-hono-server#HonoServerPlugin', config: { port: 3000 } }, + ], +}; +``` + +```typescript +// Runtime loader +import { loadConfig } from '@objectstack/config'; +import { ObjectKernel } from '@objectstack/runtime'; + +const config = await loadConfig('./objectstack.config.ts'); +const kernel = new ObjectKernel(); + +for (const pluginDef of config.plugins) { + const PluginClass = await import(pluginDef.name); + kernel.use(new PluginClass(pluginDef.config)); +} + +await kernel.bootstrap(); +``` + +## Best Practices + +### 1. Use Dependency Injection + +```typescript +// ❌ Bad: Direct import +import { objectql } from './global-instance'; + +// ✅ Good: Get from context +const ql = ctx.getService('objectql'); +``` + +### 2. Handle Errors in Lifecycle Methods + +```typescript +async init(ctx: PluginContext): Promise { + try { + await this.setupDatabase(); + } catch (error) { + ctx.logger.error('Failed to setup database', { error }); + throw error; // Kernel will halt bootstrap + } +} +``` + +### 3. Clean Up in destroy() + +```typescript +async destroy(): Promise { + // Close connections + await this.db.close(); + + // Stop timers + clearInterval(this.syncTimer); + + // Unsubscribe from events + this.eventUnsubscribe(); +} +``` + +### 4. Use Meaningful Event Names + +```typescript +// ❌ Bad: Generic names +ctx.hook('update', handler); + +// ✅ Good: Specific, namespaced names +ctx.hook('analytics:metric:updated', handler); +``` + +## Migration from Monolithic Architecture + +### Before (Monolithic) + +```typescript +import { ObjectQL } from '@objectstack/objectql'; +import { createMemoryDriver } from '@objectstack/driver-memory'; + +const ql = new ObjectQL(); +const driver = createMemoryDriver(); +await ql.addDriver(driver, 'memory'); +await ql.loadObjects([Account, Contact]); +``` + +### After (MiniKernel) + +```typescript +import { ObjectKernel, ObjectQLPlugin, DriverPlugin } from '@objectstack/runtime'; + +const kernel = new ObjectKernel(); +kernel.use(new ObjectQLPlugin()); +kernel.use(new DriverPlugin(driver, 'memory')); +kernel.use(new CRMPlugin()); // Loads Account, Contact + +await kernel.bootstrap(); +const ql = kernel.getService('objectql'); +``` + +## Related Documentation + +- [Writing Plugins](/docs/developers/writing-plugins) - Complete plugin development guide +- [ObjectQL Plugin Reference](/docs/references/objectql) - ObjectQL plugin API +- [Server Drivers](/docs/developers/server-drivers) - Creating custom drivers + +--- + +**Quick Start:** See [examples/host](https://github.com/objectstack-ai/spec/tree/main/examples/host) for a complete MiniKernel implementation. diff --git a/content/docs/introduction/meta.json b/content/docs/introduction/meta.json index 236d84595..2ab3374d2 100644 --- a/content/docs/introduction/meta.json +++ b/content/docs/introduction/meta.json @@ -7,6 +7,7 @@ "metadata-driven", "architecture", "design-principles", - "terminology" + "terminology", + "releases" ] } diff --git a/content/docs/introduction/releases.mdx b/content/docs/introduction/releases.mdx new file mode 100644 index 000000000..57c20934d --- /dev/null +++ b/content/docs/introduction/releases.mdx @@ -0,0 +1,300 @@ +--- +title: Recent Updates & Releases +description: Latest features, improvements, and protocol extensions in ObjectStack +--- + +# Recent Updates & Releases + +Stay up-to-date with the latest features and improvements to the ObjectStack protocol. + +## Latest Release (2026-01-27) + +### 🎯 ObjectQL (Data Layer) - 100% Completion! + +We've completed all advanced query features and AI/ML field types, bringing ObjectQL to feature parity with enterprise database systems. + +#### Window Functions ✅ + +Full support for analytical window functions: + +**Ranking Functions:** +- `ROW_NUMBER()` - Sequential numbering within partitions +- `RANK()` - Ranking with gaps for ties +- `DENSE_RANK()` - Ranking without gaps +- `NTILE(n)` - Distribution into n buckets + +**Navigation Functions:** +- `LAG(field, offset)` - Access previous row values +- `LEAD(field, offset)` - Access next row values +- `FIRST_VALUE(field)` - First value in window +- `LAST_VALUE(field)` - Last value in window + +**Aggregate Window Functions:** +- `SUM()`, `AVG()`, `COUNT()`, `MIN()`, `MAX()` - With OVER clause + +**Example Usage:** +```typescript +import { ObjectQL } from '@objectstack/objectql'; + +const query = { + from: 'opportunity', + select: [ + 'account_name', + 'amount', + { + window: { + function: 'ROW_NUMBER', + partitionBy: ['account_name'], + orderBy: [{ field: 'amount', direction: 'desc' }], + }, + as: 'rank_in_account' + }, + { + window: { + function: 'SUM', + field: 'amount', + partitionBy: ['account_name'], + }, + as: 'total_account_revenue' + } + ], +}; +``` + +#### HAVING Clause ✅ + +Filter aggregated results in GROUP BY queries: + +```typescript +const query = { + from: 'opportunity', + select: [ + 'stage', + { aggregate: 'SUM', field: 'amount', as: 'total_revenue' }, + { aggregate: 'COUNT', field: 'id', as: 'deal_count' }, + ], + groupBy: ['stage'], + having: [ + { field: 'total_revenue', operator: 'greaterThan', value: 1000000 }, + { field: 'deal_count', operator: 'greaterThan', value: 10 }, + ], +}; +``` + +#### DISTINCT Queries ✅ + +Full support for SELECT DISTINCT: + +```typescript +// Distinct single field +const query = { + from: 'contact', + select: ['industry'], + distinct: true, +}; + +// Distinct multiple fields +const query = { + from: 'opportunity', + select: ['stage', 'type'], + distinct: true, +}; + +// Distinct with aggregate +const query = { + from: 'account', + select: [ + { aggregate: 'COUNT', field: 'industry', distinct: true, as: 'unique_industries' }, + ], +}; +``` + +#### Subqueries ✅ + +Nested queries in JOIN clauses: + +```typescript +const query = { + from: 'account', + select: ['name', 'industry', 'total_deals'], + joins: [ + { + type: 'left', + subquery: { + from: 'opportunity', + select: [ + 'account_id', + { aggregate: 'COUNT', field: 'id', as: 'total_deals' }, + ], + groupBy: ['account_id'], + }, + alias: 'deal_stats', + on: [{ left: 'id', operator: 'equals', right: 'deal_stats.account_id' }], + }, + ], +}; +``` + +#### Vector Field Type ✅ + +AI/ML embeddings for semantic search and RAG workflows: + +```typescript +import { Field } from '@objectstack/spec'; + +const KnowledgeArticle = { + name: 'knowledge_article', + fields: { + title: Field.text({ required: true }), + content: Field.textarea({ required: true }), + + // Store embeddings for semantic search + content_embedding: Field.vector({ + label: 'Content Embedding', + dimensions: 1536, // OpenAI ada-002 + description: 'Vector representation for semantic search', + }), + }, +}; + +// Query by semantic similarity +const similarArticles = await ql.query({ + from: 'knowledge_article', + where: [ + { + field: 'content_embedding', + operator: 'similar_to', + value: queryEmbedding, + threshold: 0.8, // Cosine similarity threshold + }, + ], + limit: 5, +}); +``` + +**Supported Operations:** +- `similar_to` - Cosine similarity search +- `knn` - K-nearest neighbors +- Integration with vector databases (Pinecone, Weaviate, pgvector) + +#### Location Field Type ✅ + +GPS coordinates for geospatial applications: + +```typescript +import { Field } from '@objectstack/spec'; + +const Store = { + name: 'store', + fields: { + name: Field.text({ required: true }), + address: Field.address(), + + // Store GPS coordinates + location: Field.location({ + label: 'Store Location', + description: 'GPS coordinates for mapping', + }), + }, +}; + +// Query by distance +const nearbyStores = await ql.query({ + from: 'store', + where: [ + { + field: 'location', + operator: 'within_radius', + value: { + lat: 37.7749, + lng: -122.4194, + radius: 10, // kilometers + }, + }, + ], + orderBy: [ + { + field: 'location', + direction: 'distance_from', + value: { lat: 37.7749, lng: -122.4194 }, + }, + ], +}); +``` + +**Supported Operations:** +- `within_radius` - Find locations within distance +- `within_bounds` - Find locations in bounding box +- `distance_from` - Calculate distance +- Integration with mapping services (Google Maps, Mapbox) + +--- + +## Previous Releases + +### v1.3.0 (2026-01-15) - Advanced Query Features + +- Added support for Common Table Expressions (CTE) +- Improved query optimizer performance +- Added transaction isolation levels + +### v1.2.0 (2025-12-20) - AI Protocol + +- Complete AI protocol suite (8 schemas) +- Agent orchestration and RAG pipeline +- Natural language query processing +- AI cost tracking and budgeting + +### v1.1.0 (2025-11-30) - UI Enhancements + +- Advanced theming system +- Custom widget lifecycle hooks +- Dashboard grid layouts +- Report builder improvements + +### v1.0.0 (2025-10-15) - Initial Release + +- Core ObjectQL, ObjectUI, ObjectOS protocols +- PostgreSQL and MongoDB drivers +- Basic plugin system +- Documentation site + +--- + +## Migration Guides + +### Upgrading to v1.4.0 + +The new window functions and vector/location field types are backward compatible. No breaking changes. + +**To use vector fields:** +1. Update `@objectstack/spec` to `^1.4.0` +2. Add vector database driver (e.g., `@objectstack/driver-pgvector`) +3. Define vector fields in your objects + +**To use location fields:** +1. Update `@objectstack/spec` to `^1.4.0` +2. Use with any driver (coordinates stored as JSON) +3. For advanced geospatial queries, use PostGIS driver + +--- + +## Roadmap + +### Q1 2026 +- [ ] GraphQL Gateway +- [ ] Real-time subscriptions (WebSocket) +- [ ] Multi-tenant data isolation + +### Q2 2026 +- [ ] Performance monitoring dashboard +- [ ] Advanced caching strategies +- [ ] Plugin marketplace + +--- + +## Get Involved + +- **Report Issues:** [GitHub Issues](https://github.com/objectstack-ai/spec/issues) +- **Contribute:** [Contributing Guide](/docs/introduction/contributing) +- **Discuss:** [GitHub Discussions](https://github.com/objectstack-ai/spec/discussions) diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx new file mode 100644 index 000000000..cd495737b --- /dev/null +++ b/content/docs/references/index.mdx @@ -0,0 +1,204 @@ +--- +title: Protocol Reference +description: Complete reference of all 70 ObjectStack protocol specifications +--- + +# Protocol Reference + +This is the complete reference for all protocol specifications in the ObjectStack ecosystem. Each protocol is implemented as a Zod schema providing runtime validation and TypeScript type safety. + +## Quick Navigation + +| Module | Protocols | Description | +| :--- | :---: | :--- | +| [Data Protocol](#data-protocol) | 8 | Core business logic and data modeling (ObjectQL) | +| [UI Protocol](#ui-protocol) | 10 | User interface definitions and interactions (ObjectUI) | +| [System Protocol](#system-protocol) | 14 | Runtime environment and platform capabilities (ObjectOS) | +| [AI Protocol](#ai-protocol) | 8 | AI/ML integration and agent orchestration | +| [API Protocol](#api-protocol) | 6 | Standardized API contracts and communication | +| [Automation Protocol](#automation-protocol) | 7 | Workflow automation and integration | +| [Auth Protocol](#auth-protocol) | 6 | Identity, authentication, and authorization | +| [Permission Protocol](#permission-protocol) | 4 | Access control and security policies | +| [Hub Protocol](#hub-protocol) | 5 | Marketplace and multi-tenancy | +| [Shared Protocol](#shared-protocol) | 1 | Common utilities and identifiers | +| [Stack Protocol](#stack-protocol) | 1 | Root stack definition | + +**Total: 70 protocols** + +--- + +## Data Protocol (ObjectQL) + +**Location:** `packages/spec/src/data/` +**Count:** 8 protocols + +Defines the "Shape of Data" and business logic. + +| File | Schema | Purpose | +| :--- | :--- | :--- | +| `field.zod.ts` | `FieldSchema` | Field definitions with 44 types (text, number, select, lookup, formula, vector, location, etc.) | +| `object.zod.ts` | `ObjectSchema` | Object/table definitions with fields, indexes, and capabilities | +| `query.zod.ts` | `QuerySchema` | Abstract query AST supporting window functions, HAVING, DISTINCT, subqueries | +| `validation.zod.ts` | `ValidationRuleSchema` | Validation rules for data integrity | +| `filter.zod.ts` | `FilterSchema` | Query filtering and conditions | +| `dataset.zod.ts` | `DatasetSchema` | Dataset definitions for reporting and analytics | +| `mapping.zod.ts` | `FieldMappingSchema` | Field mapping configurations for data transformation | +| `hook.zod.ts` | `HookSchema` | Lifecycle hooks (before/after insert, update, delete) | + +**Key Features:** +- 44 field types including AI/ML vectors and GPS locations +- Advanced query capabilities (window functions, HAVING, DISTINCT, subqueries) +- Validation rules and formulas +- Lifecycle hooks for business logic + +**Learn more:** [ObjectQL Documentation](/docs/objectql) + +--- + +## UI Protocol (ObjectUI) + +**Location:** `packages/spec/src/ui/` +**Count:** 10 protocols + +Defines the "Shape of Interaction" for rendering interfaces. + +| File | Schema | Purpose | +| :--- | :--- | :--- | +| `view.zod.ts` | `ViewSchema` | List views (grid, kanban, calendar, gantt) and form layouts | +| `page.zod.ts` | `PageSchema` | FlexiPage layouts with regions and components | +| `app.zod.ts` | `AppSchema` | Application structure and navigation menus | +| `dashboard.zod.ts` | `DashboardSchema` | Dashboard layouts with grid-based widgets | +| `report.zod.ts` | `ReportSchema` | Report definitions (tabular, summary, matrix, chart) | +| `action.zod.ts` | `ActionSchema` | UI actions (buttons, scripts, URLs, flows) | +| `component.zod.ts` | `ComponentSchema` | Reusable UI components | +| `block.zod.ts` | `BlockSchema` | UI block definitions | +| `theme.zod.ts` | `ThemeSchema` | Theming (colors, typography, breakpoints, animations) | +| `widget.zod.ts` | `WidgetSchema` | Custom field widgets with lifecycle hooks | + +**Key Features:** +- Server-driven UI with multiple view types +- Flexible page layouts with component regions +- Rich dashboard and reporting capabilities +- Comprehensive theming system + +**Learn more:** [ObjectUI Documentation](/docs/objectui) + +--- + +## System Protocol (ObjectOS) + +**Location:** `packages/spec/src/system/` +**Count:** 14 protocols + +Defines the "Runtime Environment" and platform capabilities. + +| File | Schema | Purpose | +| :--- | :--- | :--- | +| `manifest.zod.ts` | `ManifestSchema` | Application/plugin manifest (`objectstack.config.ts`) with 7 package types | +| `datasource.zod.ts` | `DatasourceSchema` | Data source connection configurations | +| `driver.zod.ts` | `DriverSchema` | Database driver definitions and options | +| `driver/postgres.zod.ts` | `PostgresConfigSchema` | PostgreSQL-specific driver configuration | +| `driver/mongo.zod.ts` | `MongoConfigSchema` | MongoDB-specific driver configuration | +| `plugin.zod.ts` | `PluginSchema` | Plugin lifecycle and interface definitions | +| `context.zod.ts` | `KernelContextSchema` | Kernel execution context with user, org, tenant info | +| `events.zod.ts` | `EventSchema` | Event bus and pub/sub patterns | +| `job.zod.ts` | `JobSchema` | Background job scheduling (cron, interval, delayed) | +| `audit.zod.ts` | `AuditEventSchema` | Audit logging for compliance | +| `logger.zod.ts` | `LoggerConfigSchema` | Structured logging configuration | +| `translation.zod.ts` | `TranslationSchema` | i18n/l10n support | +| `feature.zod.ts` | `FeatureFlagSchema` | Feature flag definitions | +| `scoped-storage.zod.ts` | `ScopedStorageSchema` | Scoped key-value storage | + +**Package Types:** +- `app` - Business application package +- `plugin` - General-purpose functionality extension +- `driver` - Database/external service adapter +- `module` - Reusable code library +- `objectql` - Core data engine implementation +- `gateway` - API protocol entry point (GraphQL, REST, RPC) +- `adapter` - Runtime container (Express, Hono, Fastify, Serverless) + +**Learn more:** [ObjectOS Documentation](/docs/objectos) + +--- + +## AI Protocol + +**Location:** `packages/spec/src/ai/` +**Count:** 8 protocols + +Defines AI agent integration capabilities. + +| File | Schema | Purpose | +| :--- | :--- | :--- | +| `agent.zod.ts` | `AgentSchema` | AI agent definitions and configurations | +| `model-registry.zod.ts` | `ModelRegistrySchema` | LLM registry and selection | +| `rag-pipeline.zod.ts` | `RAGPipelineSchema` | Retrieval-augmented generation | +| `nlq.zod.ts` | `NLQSchema` | Natural language query processing (NL to ObjectQL) | +| `conversation.zod.ts` | `ConversationSchema` | Conversation management and memory | +| `cost.zod.ts` | `CostTrackingSchema` | AI cost tracking and budget management | +| `predictive.zod.ts` | `PredictiveModelSchema` | Predictive analytics models | +| `orchestration.zod.ts` | `OrchestrationSchema` | AI-powered workflow automation | + +**Learn more:** [AI Protocol Reference](/docs/references/ai) + +--- + +## API Protocol + +**Location:** `packages/spec/src/api/` +**Count:** 6 protocols + +Defines standardized API contracts. + +| File | Schema | Purpose | +| :--- | :--- | :--- | +| `contract.zod.ts` | `APIContractSchema` | API endpoint definitions and specifications | +| `endpoint.zod.ts` | `EndpointSchema` | REST endpoint definitions with rate limiting | +| `router.zod.ts` | `RouterSchema` | API routing configuration | +| `odata.zod.ts` | `ODataSchema` | OData query protocol support | +| `realtime.zod.ts` | `RealtimeSchema` | WebSocket/SSE real-time subscriptions | +| `discovery.zod.ts` | `DiscoverySchema` | API discovery and introspection | + +**Learn more:** [API Protocol Reference](/docs/references/api) + +--- + +## Recent Additions (2026-01-27) + +**ObjectQL Advanced Features:** +- ✅ **Window Functions** - ROW_NUMBER, RANK, LAG, LEAD, and aggregate window functions +- ✅ **HAVING Clause** - Filter aggregated results in GROUP BY queries +- ✅ **DISTINCT Queries** - Full support for SELECT DISTINCT +- ✅ **Subqueries** - Nested queries in JOIN clauses +- ✅ **Vector Field Type** - AI/ML embeddings for semantic search and RAG workflows +- ✅ **Location Field Type** - GPS coordinates for geospatial applications + +--- + +## Schema Conventions + +All schemas follow these conventions: + +### Naming +- **Configuration Keys (TS Props):** `camelCase` (e.g., `maxLength`, `referenceFilters`) +- **Machine Names (Data Values):** `snake_case` (e.g., `name: 'project_task'`, `object: 'account'`) + +### Validation +- All schemas use **Zod** for runtime validation +- TypeScript types are inferred via `z.infer` +- JSON schemas are auto-generated for IDE support + +### Documentation +- Each schema includes comprehensive JSDoc comments +- Examples are provided for complex configurations +- Deprecated fields are marked with `@deprecated` + +--- + +## Next Steps + +- **Explore by Module:** Navigate to specific protocol sections above +- **See Examples:** Check [examples/crm](https://github.com/objectstack-ai/spec/tree/main/examples/crm) for real-world usage +- **Build Plugins:** Read [Writing Plugins](/docs/developers/writing-plugins) +- **Contribute:** Review [Contributing Guide](/docs/introduction/contributing) diff --git a/docs-structure-proposal.md b/docs-structure-proposal.md deleted file mode 100644 index f2979db99..000000000 --- a/docs-structure-proposal.md +++ /dev/null @@ -1,90 +0,0 @@ -# ObjectStack Protocol Docs Structure Proposal - -Based on the audit of existing content and the "Metamodel Standards," here is the recommended structure for the official documentation. - -## 1. High-Level Goals -- **Eliminate Redundancy**: Merge `concepts`, `core-concepts`, `specifications`, and `protocols` into a unified hierarchy. -- **Align with Architecture**: Structure explicitly around the three pillars: **ObjectQL (Data)**, **ObjectUI (UI)**, and **ObjectOS (System)**. -- **Reference-Driven**: Ensure documentation maps directly to the Zod schemas (`field.zod.ts`, `view.zod.ts`, etc.). - -## 2. Proposed Directory Structure - -```text -content/docs/ -├── index.mdx (Landing Page) -├── introduction/ (Was: concepts, core-concepts) -│ ├── index.mdx -│ ├── manifesto.mdx (From concepts/manifesto.mdx) -│ ├── architecture.mdx (From core-concepts/the-stack.mdx) -│ ├── metadata-driven.mdx (From core-concepts/metadata-driven.mdx) -│ └── terminology.mdx -├── objectql/ (The Data Protocol) -│ ├── index.mdx (Overview) -│ ├── schema/ -│ │ ├── object.mdx (Maps to src/data/object.zod.ts) -│ │ ├── field.mdx (Maps to src/data/field.zod.ts) -│ │ ├── validation.mdx -│ │ └── relationships.mdx -│ ├── query/ -│ │ ├── index.mdx (Query syntax) -│ │ └── drivers.mdx -│ └── flow/ -│ └── logic.mdx (Maps to src/data/flow.zod.ts) -├── objectui/ (The UI Protocol) -│ ├── index.mdx -│ ├── app.mdx (Maps to src/ui/app.zod.ts) -│ ├── views/ -│ │ ├── index.mdx -│ │ ├── list-view.mdx (Maps to src/ui/view.zod.ts) -│ │ └── form-view.mdx -│ ├── components/ (Widgets, Dashboard) -│ └── actions.mdx (Maps to src/ui/action.zod.ts) -├── objectos/ (The System Protocol) -│ ├── index.mdx -│ ├── manifest.mdx (Maps to src/system/manifest.zod.ts) -│ ├── authentication.mdx -│ ├── api-reference.mdx (Maps to src/system/api.zod.ts) -│ └── plugins.mdx -└── developers/ (Guides & Tooling) - ├── quick-start.mdx - ├── cli.mdx - ├── testing.mdx - └── extensions.mdx -``` - -## 3. Detailed Actions - -### A. Cleanup & Consolidation -1. **Delete** `content/docs/specifications` folder (content is redundant with `protocols`). -2. **Delete** `content/docs/core-concepts` folder (move unique content to `introduction`). -3. **Archive** `content/docs/concepts` folder (it contains a flat list of protocols; move content to specific `object*` folders and then remove). - -### B. Rename & Move -1. Rename `content/docs/protocols` -> Explode this. - * Move `content/docs/protocols/objectql` -> `content/docs/objectql` - * Move `content/docs/protocols/objectui` -> `content/docs/objectui` - * Move `content/docs/protocols/objectos` -> `content/docs/objectos` - * *Reason*: These are the top-level products/protocols. They deserve root-level visibility in the docs URI (e.g., `docs/objectql/schema`). - -### C. Navigation Update (`meta.json`) -Update `content/docs/meta.json` to reflect the new simplified hierarchy: - -```json -{ - "title": "Documentation", - "pages": [ - "introduction", - "objectql", - "objectui", - "objectos", - "developers", - "references" - ] -} -``` - -## 4. Content Gaps to Fill -Based on `copilot-instructions.md`, ensure the following specific pages exist and map to their Zod definitions: -- [ ] **ObjectQL**: Ensure `field.mdx` documents all types (text, lookup, formula) defined in `field.zod.ts`. -- [ ] **ObjectUI**: Ensure `layout.mdx` covers the Grid/Kanban options defined in `view.zod.ts`. -- [ ] **ObjectOS**: Ensure `manifest.mdx` clearly documents `objectstack.config.ts`.