From e9c7059ee3615791e196d81f18a0bd43606f1e2b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 30 Jan 2026 15:14:48 +0000 Subject: [PATCH 1/4] Initial plan From 6c667909d9b6464935ac3ae76a6c41641bc29a19 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 30 Jan 2026 15:21:33 +0000 Subject: [PATCH 2/4] Add comprehensive GitHub organization structure documentation Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- GITHUB_ORGANIZATION_STRUCTURE.md | 849 ++++++++++++++++++++++++++++ GITHUB_ORGANIZATION_STRUCTURE_CN.md | 808 ++++++++++++++++++++++++++ README.md | 17 + 3 files changed, 1674 insertions(+) create mode 100644 GITHUB_ORGANIZATION_STRUCTURE.md create mode 100644 GITHUB_ORGANIZATION_STRUCTURE_CN.md diff --git a/GITHUB_ORGANIZATION_STRUCTURE.md b/GITHUB_ORGANIZATION_STRUCTURE.md new file mode 100644 index 00000000000..c01f443b0bd --- /dev/null +++ b/GITHUB_ORGANIZATION_STRUCTURE.md @@ -0,0 +1,849 @@ +# ObjectStack GitHub Organization Structure +# ObjectStack GitHub 组织架构 + +**Document Version / 文档版本**: 1.0 +**Created / 创建日期**: 2026-01-30 +**Author / 作者**: ObjectStack Core Team +**Purpose / 目的**: Define GitHub organization structure for microkernel architecture with plugin ecosystem + +--- + +## 📋 Table of Contents / 目录 + +1. [Architecture Overview / 架构概览](#1-architecture-overview) +2. [Repository Categories / 仓库分类](#2-repository-categories) +3. [Repository Matrix / 仓库矩阵](#3-repository-matrix) +4. [Repository Structure Templates / 仓库结构模板](#4-repository-structure-templates) +5. [Development Workflow / 开发工作流](#5-development-workflow) +6. [Naming Conventions / 命名规范](#6-naming-conventions) +7. [Quality Standards / 质量标准](#7-quality-standards) + +--- + +## 1. Architecture Overview / 架构概览 + +### 1.1 Microkernel Design Philosophy / 微内核设计哲学 + +ObjectStack adopts a **microkernel + plugin architecture** inspired by: +- **Kubernetes**: Extensibility through CRDs and operators +- **VS Code**: Extension marketplace model +- **Linux Kernel**: Driver and module system +- **Salesforce**: AppExchange ecosystem + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ PROTOCOL LAYER / 协议层 │ +│ objectstack-ai/spec (Single Source of Truth) │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Zod Schemas │ TypeScript Types │ JSON Schemas │ Docs │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ + ↓ imports +┌─────────────────────────────────────────────────────────────────┐ +│ MICROKERNEL LAYER / 微内核层 │ +│ objectstack-ai/core objectstack-ai/objectql │ +│ objectstack-ai/runtime objectstack-ai/client │ +│ objectstack-ai/cli │ +└─────────────────────────────────────────────────────────────────┘ + ↓ plugins +┌─────────────────────────────────────────────────────────────────┐ +│ PLUGIN LAYER / 插件层 │ +│ ┌──────────────┬──────────────┬──────────────┬──────────────┐ │ +│ │ Drivers │ Connectors │ Services │ Templates │ │ +│ │ 驱动 │ 连接器 │ 服务 │ 模板 │ │ +│ └──────────────┴──────────────┴──────────────┴──────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 1.2 Repository Organization Principles / 仓库组织原则 + +| Principle / 原则 | Description / 描述 | +|---|---| +| **Single Responsibility** | Each repository has ONE clear purpose | +| **Independent Versioning** | Each plugin can version independently | +| **Dependency Clarity** | All repos depend on `@objectstack/spec` | +| **Testing Isolation** | Each repo has its own CI/CD pipeline | +| **Documentation Decentralization** | Each repo maintains its own docs | +| **Community Contribution** | Lower barrier for external contributors | + +--- + +## 2. Repository Categories / 仓库分类 + +### 2.1 Core Repositories / 核心仓库 (7 repos) + +**Ownership**: Core Team +**Stability**: High +**Breaking Changes**: Require RFC process + +| Repository Name | Purpose | Key Components | +|---|---|---| +| **spec** | Protocol definitions | Zod schemas, TypeScript types, JSON schemas | +| **core** | Microkernel | Plugin loader, dependency injection, lifecycle | +| **objectql** | Query engine | SQL builder, query optimizer, AST parser | +| **runtime** | Runtime environment | Server, workers, event bus, middleware | +| **client** | Client SDK | API client, type-safe queries, React hooks | +| **cli** | Command-line tools | Scaffolding, migrations, code generation | +| **types** | Shared types | Runtime environment interfaces | + +### 2.2 Driver Repositories / 驱动仓库 (12+ repos) + +**Ownership**: Core Team + Community +**Stability**: Medium +**Breaking Changes**: Follow semver, coordinate with spec + +| Category | Repository Name | Purpose | Status | +|---|---|---|---| +| **SQL** | `driver-postgres` | PostgreSQL driver | 🟡 Planned | +| **SQL** | `driver-mysql` | MySQL/MariaDB driver | 🟡 Planned | +| **SQL** | `driver-sqlite` | SQLite driver | 🟡 Planned | +| **SQL** | `driver-mssql` | Microsoft SQL Server driver | 🟡 Planned | +| **SQL** | `driver-oracle` | Oracle Database driver | 🟡 Planned | +| **NoSQL** | `driver-mongodb` | MongoDB driver | 🟡 Planned | +| **NoSQL** | `driver-redis` | Redis driver | 🟡 Planned | +| **NoSQL** | `driver-dynamodb` | AWS DynamoDB driver | 🟡 Planned | +| **Cache** | `driver-memcached` | Memcached driver | 🟡 Planned | +| **Search** | `driver-elasticsearch` | Elasticsearch driver | 🟡 Planned | +| **Search** | `driver-meilisearch` | Meilisearch driver | 🟡 Planned | +| **Memory** | `driver-memory` | In-memory driver (reference) | 🟢 Exists | + +### 2.3 Connector Repositories / 连接器仓库 (10+ repos) + +**Ownership**: Community (with core team guidance) +**Stability**: Variable +**Breaking Changes**: Independent versioning + +| Category | Repository Name | Purpose | Priority | +|---|---|---|---| +| **CRM** | `connector-salesforce` | Salesforce integration | ⭐⭐⭐ | +| **CRM** | `connector-hubspot` | HubSpot integration | ⭐⭐ | +| **Collaboration** | `connector-slack` | Slack integration | ⭐⭐⭐ | +| **Collaboration** | `connector-teams` | Microsoft Teams integration | ⭐⭐ | +| **Accounting** | `connector-quickbooks` | QuickBooks integration | ⭐⭐ | +| **Accounting** | `connector-xero` | Xero integration | ⭐ | +| **ERP** | `connector-sap` | SAP integration | ⭐⭐ | +| **HRIS** | `connector-workday` | Workday integration | ⭐⭐ | +| **Marketing** | `connector-mailchimp` | Mailchimp integration | ⭐ | +| **Payment** | `connector-stripe` | Stripe integration | ⭐⭐⭐ | + +### 2.4 Service Plugin Repositories / 服务插件仓库 (15+ repos) + +**Ownership**: Core Team +**Stability**: Medium to High +**Breaking Changes**: Coordinated releases + +| Category | Repository Name | Purpose | Priority | +|---|---|---|---| +| **Security** | `plugin-encryption` | Field-level encryption | ⭐⭐⭐ | +| **Security** | `plugin-masking` | PII masking | ⭐⭐⭐ | +| **Security** | `plugin-compliance` | GDPR/HIPAA compliance toolkit | ⭐⭐⭐ | +| **Multi-tenant** | `plugin-multitenancy` | Tenant isolation | ⭐⭐⭐ | +| **Caching** | `plugin-cache` | Multi-tier caching | ⭐⭐⭐ | +| **Search** | `plugin-fulltext-search` | Full-text search | ⭐⭐ | +| **Files** | `plugin-file-storage` | File/attachment management | ⭐⭐ | +| **Workflow** | `plugin-workflow` | Advanced workflow engine | ⭐⭐ | +| **Approval** | `plugin-approval` | Approval process | ⭐⭐ | +| **Notification** | `plugin-notification` | Multi-channel notifications | ⭐⭐ | +| **Analytics** | `plugin-analytics` | Business intelligence | ⭐⭐ | +| **AI** | `plugin-ai-agent` | AI agent orchestration | ⭐⭐⭐ | +| **AI** | `plugin-ai-rag` | RAG pipeline | ⭐⭐⭐ | +| **Observability** | `plugin-logging` | Structured logging | ⭐⭐ | +| **Observability** | `plugin-tracing` | Distributed tracing | ⭐⭐ | + +### 2.5 Server Plugin Repositories / 服务器插件仓库 (8+ repos) + +**Ownership**: Core Team +**Stability**: High +**Breaking Changes**: Coordinated releases + +| Repository Name | Purpose | Framework | Status | +|---|---|---|---| +| `plugin-hono-server` | Hono server adapter | Hono | 🟢 Exists | +| `plugin-express-server` | Express server adapter | Express | 🟡 Planned | +| `plugin-fastify-server` | Fastify server adapter | Fastify | 🟡 Planned | +| `plugin-nestjs-server` | NestJS server adapter | NestJS | 🟡 Planned | +| `plugin-nextjs-server` | Next.js API routes adapter | Next.js | 🟡 Planned | +| `plugin-cloudflare-workers` | Cloudflare Workers adapter | Workers | 🟡 Planned | +| `plugin-aws-lambda` | AWS Lambda adapter | Serverless | 🟡 Planned | +| `plugin-msw` | Mock Service Worker | MSW | 🟢 Exists | + +### 2.6 Template Repositories / 模板仓库 (10+ repos) + +**Ownership**: Community (with core team curation) +**Stability**: Variable +**Breaking Changes**: Independent + +| Repository Name | Purpose | Industry | Status | +|---|---|---|---| +| `template-crm` | CRM application | Sales | 🟡 Planned | +| `template-helpdesk` | Customer support system | Service | 🟡 Planned | +| `template-project-management` | Project management | Operations | 🟡 Planned | +| `template-hr-system` | Human resources | HR | 🟡 Planned | +| `template-inventory` | Inventory management | Supply Chain | 🟡 Planned | +| `template-ecommerce` | E-commerce platform | Retail | 🟡 Planned | +| `template-healthcare` | Healthcare management | Healthcare | 🟡 Planned | +| `template-education` | Learning management | Education | 🟡 Planned | +| `template-iot-platform` | IoT data platform | IoT | 🟡 Planned | +| `template-ai-saas` | AI-powered SaaS | AI/ML | 🟡 Planned | + +### 2.7 Tool Repositories / 工具仓库 (5+ repos) + +**Ownership**: Core Team +**Stability**: Medium +**Breaking Changes**: Independent + +| Repository Name | Purpose | Users | +|---|---|---| +| `devtools` | Browser DevTools extension | Developers | +| `vscode-extension` | VS Code extension | Developers | +| `jetbrains-plugin` | JetBrains IDE plugin | Developers | +| `metadata-validator` | Metadata linting/validation | DevOps | +| `migration-tool` | Migration from other platforms | Admins | + +### 2.8 Documentation & Infrastructure Repositories / 文档与基础设施仓库 (5+ repos) + +**Ownership**: Core Team +**Stability**: High +**Breaking Changes**: Content only + +| Repository Name | Purpose | Content | +|---|---|---| +| `docs` | Official documentation | Guides, tutorials, API reference | +| `examples` | Example applications | Sample code, demos | +| `awesome-objectstack` | Curated resources | Community plugins, tools, articles | +| `.github` | Organization-wide configs | Templates, workflows, community health | +| `registry` | Plugin registry service | Plugin metadata, versions, reviews | + +--- + +## 3. Repository Matrix / 仓库矩阵 + +### 3.1 By Development Priority / 按开发优先级 + +| Priority | Phase | Repositories | Timeline | +|---|---|---|---| +| **P0** | Foundation | spec, core, objectql, runtime, client, cli | Q1 2026 | +| **P1** | Essential Drivers | driver-postgres, driver-mysql, driver-mongodb, driver-redis | Q2 2026 | +| **P2** | Essential Plugins | plugin-encryption, plugin-masking, plugin-multitenancy, plugin-cache | Q2 2026 | +| **P3** | Key Connectors | connector-salesforce, connector-slack, connector-stripe | Q3 2026 | +| **P4** | Server Adapters | plugin-express, plugin-fastify, plugin-nextjs | Q3 2026 | +| **P5** | Templates | template-crm, template-helpdesk, template-project-management | Q4 2026 | +| **P6** | Tools | devtools, vscode-extension, migration-tool | Q4 2026 | + +### 3.2 By Ownership Model / 按所有权模型 + +| Ownership | Repositories | Maintenance | Support Level | +|---|---|---|---| +| **Core Team** | spec, core, objectql, runtime, client, cli | Daily | Enterprise SLA | +| **Core + Community** | All drivers, server plugins | Weekly | Community + Premium | +| **Community** | Connectors, templates, tools | Best effort | Community only | +| **Third-party** | Custom plugins, integrations | Independent | Self-support | + +### 3.3 By Technology Stack / 按技术栈 + +| Tech Stack | Repositories | Language | Runtime | +|---|---|---|---| +| **TypeScript** | spec, core, objectql, runtime, client, cli | TypeScript | Node.js | +| **Database** | All driver-* repos | TypeScript | Node.js | +| **Integration** | All connector-* repos | TypeScript | Node.js | +| **Plugin** | All plugin-* repos | TypeScript | Node.js | +| **Frontend** | devtools, vscode-extension | TypeScript | Browser/Electron | + +--- + +## 4. Repository Structure Templates / 仓库结构模板 + +### 4.1 Core Repository Template / 核心仓库模板 + +``` +objectstack-ai/[core|objectql|runtime|client|cli]/ +├── .github/ +│ ├── workflows/ +│ │ ├── ci.yml # Continuous integration +│ │ ├── release.yml # Release automation +│ │ └── security.yml # Security scanning +│ ├── ISSUE_TEMPLATE/ +│ ├── PULL_REQUEST_TEMPLATE.md +│ └── CODEOWNERS +├── src/ +│ ├── index.ts # Main entry point +│ ├── types/ # TypeScript type definitions +│ ├── core/ # Core functionality +│ ├── utils/ # Utility functions +│ └── __tests__/ # Unit tests +├── docs/ +│ ├── README.md # Getting started +│ ├── API.md # API reference +│ └── ARCHITECTURE.md # Architecture docs +├── examples/ +│ └── basic/ # Example usage +├── package.json +├── tsconfig.json +├── tsup.config.ts # Build configuration +├── vitest.config.ts # Test configuration +├── README.md +├── CHANGELOG.md +├── LICENSE +└── CONTRIBUTING.md +``` + +### 4.2 Driver Repository Template / 驱动仓库模板 + +``` +objectstack-ai/driver-[postgres|mysql|mongodb|redis]/ +├── .github/ +│ └── workflows/ +│ ├── ci.yml +│ ├── integration-test.yml # Database integration tests +│ └── release.yml +├── src/ +│ ├── index.ts +│ ├── driver.ts # Driver implementation +│ ├── connection.ts # Connection manager +│ ├── query-builder.ts # Query builder +│ ├── migrations.ts # Migration support +│ └── __tests__/ +│ ├── unit/ # Unit tests +│ └── integration/ # Integration tests +├── docker/ +│ └── docker-compose.yml # Test database setup +├── docs/ +│ ├── README.md +│ ├── CONFIGURATION.md # Configuration guide +│ └── MIGRATION.md # Migration guide +├── package.json +├── README.md +└── CHANGELOG.md +``` + +### 4.3 Plugin Repository Template / 插件仓库模板 + +``` +objectstack-ai/plugin-[encryption|masking|cache]/ +├── .github/ +│ └── workflows/ +│ ├── ci.yml +│ └── release.yml +├── src/ +│ ├── index.ts +│ ├── plugin.ts # Plugin entry point +│ ├── config.ts # Configuration schema +│ ├── hooks/ # Lifecycle hooks +│ ├── services/ # Service implementations +│ └── __tests__/ +├── docs/ +│ ├── README.md +│ ├── CONFIGURATION.md +│ └── EXAMPLES.md +├── examples/ +│ └── basic/ +├── package.json +├── README.md +└── CHANGELOG.md +``` + +### 4.4 Connector Repository Template / 连接器仓库模板 + +``` +objectstack-ai/connector-[salesforce|slack|stripe]/ +├── .github/ +│ └── workflows/ +│ ├── ci.yml +│ └── integration-test.yml +├── src/ +│ ├── index.ts +│ ├── connector.ts # Connector implementation +│ ├── auth.ts # Authentication +│ ├── api-client.ts # API client +│ ├── mapping.ts # Field mapping +│ ├── sync.ts # Sync engine +│ └── __tests__/ +├── docs/ +│ ├── README.md +│ ├── AUTHENTICATION.md # Auth setup guide +│ ├── FIELD-MAPPING.md # Mapping guide +│ └── SYNC-CONFIGURATION.md # Sync configuration +├── examples/ +│ └── sync-contacts/ +├── package.json +├── README.md +└── CHANGELOG.md +``` + +### 4.5 Template Repository Template / 模板仓库模板 + +``` +objectstack-ai/template-[crm|helpdesk|project-management]/ +├── .github/ +│ └── workflows/ +│ └── ci.yml +├── src/ +│ ├── domains/ # Business domains +│ │ ├── account/ +│ │ │ ├── account.object.ts +│ │ │ ├── account.view.ts +│ │ │ └── account.hook.ts +│ │ └── contact/ +│ ├── ui/ +│ │ ├── apps.ts +│ │ ├── dashboards.ts +│ │ └── reports.ts +│ ├── workflows/ +│ └── index.ts +├── docs/ +│ ├── README.md +│ ├── INSTALLATION.md +│ ├── CUSTOMIZATION.md +│ └── DATA-MODEL.md +├── screenshots/ +├── objectstack.config.ts # Stack configuration +├── package.json +└── README.md +``` + +--- + +## 5. Development Workflow / 开发工作流 + +### 5.1 Release Process / 发布流程 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 1. Protocol Update (spec repo) │ +│ - Update Zod schemas │ +│ - Increment version │ +│ - Publish @objectstack/spec@x.y.z │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 2. Core Update (core repos) │ +│ - Update to latest @objectstack/spec │ +│ - Implement new features │ +│ - Publish core packages │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 3. Plugin Update (plugin repos) │ +│ - Update dependencies │ +│ - Implement new protocol support │ +│ - Publish plugin packages │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 4. Template Update (template repos) │ +│ - Update dependencies │ +│ - Use new features │ +│ - Update documentation │ +└─────────────────────────────────────────────────────────┘ +``` + +### 5.2 Dependency Management / 依赖管理 + +**Dependency Rules**: +1. All repos MUST depend on `@objectstack/spec` (protocol definitions) +2. Driver/Plugin repos MAY depend on `@objectstack/core` (if using kernel features) +3. Template repos SHOULD depend on `@objectstack/runtime` or `@objectstack/client` +4. Connectors SHOULD be independent (only spec dependency) + +**Version Constraints**: +```json +{ + "dependencies": { + "@objectstack/spec": "^0.6.0", // Protocol - accept minor updates + "@objectstack/core": "~0.6.1", // Core - patch updates only + "@objectstack/runtime": "^0.6.0" // Runtime - accept minor updates + } +} +``` + +### 5.3 CI/CD Pipeline / CI/CD 流水线 + +**Standard Pipeline for ALL Repositories**: + +```yaml +# .github/workflows/ci.yml +name: CI + +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v2 + - uses: actions/setup-node@v4 + - run: pnpm install + - run: pnpm lint + - run: pnpm typecheck + - run: pnpm test + - run: pnpm build + + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run CodeQL + uses: github/codeql-action/analyze@v2 + - name: Run npm audit + run: npm audit --audit-level=high +``` + +### 5.4 Cross-Repository Testing / 跨仓库测试 + +**Integration Test Strategy**: + +```typescript +// In driver-postgres repository +import { test } from 'vitest'; +import { ObjectQLEngine } from '@objectstack/objectql'; +import { PostgresDriver } from './src/driver'; + +test('PostgreSQL driver with ObjectQL engine', async () => { + const engine = new ObjectQLEngine({ + driver: new PostgresDriver({ + connectionString: 'postgres://...' + }) + }); + + // Test integration + const result = await engine.query({ + object: 'account', + select: ['name', 'email'], + filter: { status: 'active' } + }); + + expect(result).toBeDefined(); +}); +``` + +--- + +## 6. Naming Conventions / 命名规范 + +### 6.1 Repository Naming / 仓库命名 + +| Type | Pattern | Examples | +|---|---|---| +| **Core** | `[name]` | `spec`, `core`, `runtime`, `client`, `cli` | +| **Driver** | `driver-[database]` | `driver-postgres`, `driver-mongodb` | +| **Connector** | `connector-[service]` | `connector-salesforce`, `connector-slack` | +| **Plugin** | `plugin-[feature]` | `plugin-encryption`, `plugin-cache` | +| **Template** | `template-[domain]` | `template-crm`, `template-helpdesk` | +| **Tool** | `[tool-name]` | `devtools`, `vscode-extension` | + +### 6.2 Package Naming / 包命名 + +| Type | Pattern | Examples | +|---|---|---| +| **Core** | `@objectstack/[name]` | `@objectstack/core`, `@objectstack/runtime` | +| **Driver** | `@objectstack/driver-[name]` | `@objectstack/driver-postgres` | +| **Connector** | `@objectstack/connector-[name]` | `@objectstack/connector-salesforce` | +| **Plugin** | `@objectstack/plugin-[name]` | `@objectstack/plugin-encryption` | +| **Template** | `@objectstack/template-[name]` | `@objectstack/template-crm` | + +### 6.3 Branch Naming / 分支命名 + +| Type | Pattern | Examples | +|---|---|---| +| **Feature** | `feature/[issue-number]-[description]` | `feature/123-add-postgres-driver` | +| **Fix** | `fix/[issue-number]-[description]` | `fix/456-connection-leak` | +| **Release** | `release/v[version]` | `release/v0.7.0` | +| **Hotfix** | `hotfix/[version]` | `hotfix/0.6.2` | + +--- + +## 7. Quality Standards / 质量标准 + +### 7.1 Code Quality Requirements / 代码质量要求 + +| Metric | Core Repos | Driver Repos | Plugin Repos | Template Repos | +|---|:---:|:---:|:---:|:---:| +| **Test Coverage** | ≥ 90% | ≥ 80% | ≥ 75% | ≥ 60% | +| **TypeScript Strict Mode** | ✅ Required | ✅ Required | ✅ Required | ⚠️ Recommended | +| **ESLint** | ✅ Required | ✅ Required | ✅ Required | ✅ Required | +| **Prettier** | ✅ Required | ✅ Required | ✅ Required | ✅ Required | +| **Documentation** | ✅ Comprehensive | ✅ Comprehensive | ✅ Required | ⚠️ Basic | +| **Examples** | ✅ Required | ✅ Required | ✅ Required | N/A (is example) | + +### 7.2 Security Standards / 安全标准 + +**ALL repositories MUST**: +- ✅ Enable GitHub Dependabot +- ✅ Enable GitHub CodeQL scanning +- ✅ Enable GitHub Secret scanning +- ✅ Use npm audit in CI/CD +- ✅ Follow OWASP security guidelines +- ✅ Document security policies in SECURITY.md + +### 7.3 Documentation Standards / 文档标准 + +**ALL repositories MUST include**: +- ✅ `README.md` - Overview, installation, quick start +- ✅ `CHANGELOG.md` - Version history (Keep a Changelog format) +- ✅ `CONTRIBUTING.md` - Contribution guidelines +- ✅ `LICENSE` - Apache 2.0 license file +- ✅ `SECURITY.md` - Security policy and reporting + +**Driver/Plugin/Connector repositories SHOULD include**: +- ✅ `docs/CONFIGURATION.md` - Configuration reference +- ✅ `docs/API.md` - API documentation +- ✅ `examples/` - Usage examples + +### 7.4 Accessibility Standards / 可访问性标准 + +**Repository Settings**: +- ✅ Public visibility (unless enterprise-only) +- ✅ Enable Issues +- ✅ Enable Discussions (for major repos) +- ✅ Enable Wiki (optional) +- ✅ Enable Projects (for roadmap) +- ✅ Protected `main` branch +- ✅ Require PR reviews (≥1 reviewer) +- ✅ Require status checks to pass +- ✅ Require signed commits (core repos) + +--- + +## 8. Migration Path / 迁移路径 + +### 8.1 Current State / 当前状态 + +**Existing Structure (Monorepo)**: +``` +objectstack-ai/spec/ +├── packages/ +│ ├── spec/ ← Keep (protocol definitions) +│ ├── core/ ← Extract to objectstack-ai/core +│ ├── objectql/ ← Extract to objectstack-ai/objectql +│ ├── runtime/ ← Extract to objectstack-ai/runtime +│ ├── client/ ← Extract to objectstack-ai/client +│ ├── cli/ ← Extract to objectstack-ai/cli +│ ├── types/ ← Keep or merge into spec +│ ├── ai-bridge/ ← Keep or extract +│ └── plugins/ +│ ├── driver-memory/ ← Extract to objectstack-ai/driver-memory +│ ├── plugin-hono-server/ ← Extract to objectstack-ai/plugin-hono-server +│ └── plugin-msw/ ← Extract to objectstack-ai/plugin-msw +└── examples/ ← Keep for now +``` + +### 8.2 Target State / 目标状态 + +**Distributed Repositories**: +``` +GitHub Organization: objectstack-ai/ +├── spec (protocol definitions only) +├── core (microkernel) +├── objectql (query engine) +├── runtime (runtime environment) +├── client (client SDK) +├── cli (CLI tools) +├── types (shared types) +├── ai-bridge (AI bridge - optional) +├── driver-memory (reference driver) +├── driver-postgres (new) +├── driver-mysql (new) +├── driver-mongodb (new) +├── plugin-hono-server (existing) +├── plugin-msw (existing) +├── plugin-encryption (new) +├── plugin-multitenancy (new) +├── connector-salesforce (new) +├── template-crm (new) +├── docs (documentation site) +└── .github (org-wide configs) +``` + +### 8.3 Migration Strategy / 迁移策略 + +**Phase 1: Extract Core Repositories (Month 1-2)** +1. Create new repositories with proper structure +2. Copy code from monorepo to new repos +3. Set up CI/CD for each repo +4. Publish initial versions to npm +5. Update monorepo to use published packages + +**Phase 2: Extract Plugins (Month 2-3)** +1. Extract existing plugins (driver-memory, plugin-hono-server, plugin-msw) +2. Create new driver repositories +3. Create new plugin repositories +4. Update dependency chains + +**Phase 3: Create Ecosystem (Month 3-12)** +1. Develop connectors +2. Create templates +3. Build developer tools +4. Establish community contribution process + +**Phase 4: Deprecate Monorepo (Month 12+)** +1. Archive monorepo or keep as workspace +2. Redirect traffic to individual repos +3. Update all documentation + +--- + +## 9. Community & Governance / 社区与治理 + +### 9.1 Repository Ownership / 仓库所有权 + +| Level | Repositories | Maintainers | Decision Authority | +|---|---|---|---| +| **Tier 1** | spec, core | Core team only | Requires RFC + voting | +| **Tier 2** | objectql, runtime, client, cli | Core team + trusted contributors | Requires PR review | +| **Tier 3** | Drivers, server plugins | Core team + community | Standard PR process | +| **Tier 4** | Connectors, templates, tools | Community-led | Community maintainers | + +### 9.2 Contribution Workflow / 贡献工作流 + +``` +1. Fork repository +2. Create feature branch +3. Implement changes + tests +4. Submit pull request +5. Code review +6. CI/CD passes +7. Merge to main +8. Automated release (if applicable) +``` + +### 9.3 RFC Process / RFC 流程 + +**Required for**: +- Breaking changes in spec +- New protocols or major protocol changes +- Architecture changes in core +- New repository creation (Tier 1-2) + +**Process**: +1. Submit RFC in `spec` repository discussions +2. Community discussion (2 weeks) +3. Core team review +4. Vote (for Tier 1 changes) +5. Implementation in feature branch +6. Final review and merge + +--- + +## 10. Success Metrics / 成功指标 + +### 10.1 Ecosystem Health / 生态系统健康度 + +| Metric | Q2 2026 Target | Q4 2026 Target | 2027 Target | +|---|:---:|:---:|:---:| +| **Core Repositories** | 7 | 7 | 7 | +| **Driver Repositories** | 5 | 8 | 12+ | +| **Plugin Repositories** | 5 | 10 | 20+ | +| **Connector Repositories** | 3 | 8 | 15+ | +| **Template Repositories** | 2 | 5 | 10+ | +| **Community Contributors** | 10 | 30 | 100+ | +| **Total GitHub Stars** | 500 | 2,000 | 5,000+ | +| **NPM Weekly Downloads** | 1,000 | 10,000 | 50,000+ | + +### 10.2 Quality Metrics / 质量指标 + +| Metric | Target | +|---|:---:| +| **Average Test Coverage** | ≥ 80% | +| **Security Vulnerabilities** | 0 high/critical | +| **Documentation Coverage** | ≥ 90% | +| **Issue Response Time** | < 48 hours | +| **PR Review Time** | < 72 hours | +| **Release Frequency** | Weekly (minor), Monthly (major) | + +--- + +## 11. Implementation Checklist / 实施检查清单 + +### 11.1 Infrastructure Setup / 基础设施设置 + +- [ ] Create GitHub organization if not exists +- [ ] Set up organization-wide settings +- [ ] Configure organization secrets (NPM_TOKEN, etc.) +- [ ] Set up GitHub Discussions +- [ ] Create `.github` repository for templates +- [ ] Set up organization project boards +- [ ] Configure GitHub Pages for docs + +### 11.2 Repository Creation / 仓库创建 + +**Phase 1: Core (Q1 2026)** +- [ ] Extract `objectstack-ai/core` +- [ ] Extract `objectstack-ai/objectql` +- [ ] Extract `objectstack-ai/runtime` +- [ ] Extract `objectstack-ai/client` +- [ ] Extract `objectstack-ai/cli` +- [ ] Keep `objectstack-ai/spec` (refactor to protocol-only) +- [ ] Keep `objectstack-ai/types` + +**Phase 2: Essential Drivers (Q2 2026)** +- [ ] Create `objectstack-ai/driver-postgres` +- [ ] Create `objectstack-ai/driver-mysql` +- [ ] Create `objectstack-ai/driver-mongodb` +- [ ] Create `objectstack-ai/driver-redis` +- [ ] Extract `objectstack-ai/driver-memory` + +**Phase 3: Essential Plugins (Q2 2026)** +- [ ] Create `objectstack-ai/plugin-encryption` +- [ ] Create `objectstack-ai/plugin-masking` +- [ ] Create `objectstack-ai/plugin-multitenancy` +- [ ] Create `objectstack-ai/plugin-cache` +- [ ] Extract `objectstack-ai/plugin-hono-server` +- [ ] Extract `objectstack-ai/plugin-msw` + +**Phase 4: Ecosystem (Q3-Q4 2026)** +- [ ] Create connector repositories (3+) +- [ ] Create template repositories (2+) +- [ ] Create tool repositories (2+) +- [ ] Create `objectstack-ai/docs` +- [ ] Create `objectstack-ai/registry` + +### 11.3 Documentation / 文档 + +- [ ] Create organization README +- [ ] Create contribution guidelines (org-wide) +- [ ] Create security policy (org-wide) +- [ ] Create code of conduct +- [ ] Create developer documentation site +- [ ] Create plugin development guide +- [ ] Create connector development guide +- [ ] Create template creation guide + +--- + +## 12. Appendix / 附录 + +### 12.1 Reference Ecosystems / 参考生态系统 + +**Kubernetes**: +- Core: `kubernetes/kubernetes` +- Operators: `kubernetes-sigs/*` +- Helm Charts: `helm/charts` +- Community: `kubernetes/community` + +**Prisma**: +- Core: `prisma/prisma` +- Engines: `prisma/prisma-engines` +- Client: `prisma/prisma-client-js` +- Examples: `prisma/prisma-examples` + +**Nx**: +- Core: `nrwl/nx` +- Plugins: `nrwl/nx-*` +- Recipes: `nrwl/nx-recipes` +- Examples: `nrwl/nx-examples` + +### 12.2 Useful Links / 有用链接 + +- [GitHub Organization Best Practices](https://docs.github.com/en/organizations) +- [Monorepo vs Multi-repo](https://earthly.dev/blog/monorepo-vs-polyrepo/) +- [Semantic Versioning](https://semver.org/) +- [Conventional Commits](https://www.conventionalcommits.org/) +- [Keep a Changelog](https://keepachangelog.com/) + +--- + +**Document Maintained By**: ObjectStack Core Team +**Review Cycle**: Quarterly +**Next Review**: 2026-04-30 +**Feedback**: Create issue in `objectstack-ai/spec` repository diff --git a/GITHUB_ORGANIZATION_STRUCTURE_CN.md b/GITHUB_ORGANIZATION_STRUCTURE_CN.md new file mode 100644 index 00000000000..ad3fff49f38 --- /dev/null +++ b/GITHUB_ORGANIZATION_STRUCTURE_CN.md @@ -0,0 +1,808 @@ +# ObjectStack GitHub 组织架构 +# ObjectStack GitHub Organization Structure + +**文档版本**: 1.0 +**创建日期**: 2026-01-30 +**作者**: ObjectStack 核心团队 +**目的**: 为采用微内核架构和插件生态系统的企业管理软件定义 GitHub 组织结构 + +--- + +## 📋 目录 + +1. [架构概览](#1-架构概览) +2. [仓库分类](#2-仓库分类) +3. [仓库矩阵](#3-仓库矩阵) +4. [仓库结构模板](#4-仓库结构模板) +5. [开发工作流](#5-开发工作流) +6. [命名规范](#6-命名规范) +7. [质量标准](#7-质量标准) + +--- + +## 1. 架构概览 + +### 1.1 微内核设计哲学 + +ObjectStack 采用**微内核 + 插件架构**，灵感来自: +- **Kubernetes**: 通过 CRD 和 Operator 实现可扩展性 +- **VS Code**: 扩展市场模型 +- **Linux 内核**: 驱动和模块系统 +- **Salesforce**: AppExchange 生态系统 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 协议层 │ +│ objectstack-ai/spec (单一数据源) │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Zod 模式 │ TypeScript 类型 │ JSON 模式 │ 文档 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ + ↓ 导入 +┌─────────────────────────────────────────────────────────────────┐ +│ 微内核层 │ +│ objectstack-ai/core objectstack-ai/objectql │ +│ objectstack-ai/runtime objectstack-ai/client │ +│ objectstack-ai/cli │ +└─────────────────────────────────────────────────────────────────┘ + ↓ 插件 +┌─────────────────────────────────────────────────────────────────┐ +│ 插件层 │ +│ ┌──────────────┬──────────────┬──────────────┬──────────────┐ │ +│ │ 驱动 │ 连接器 │ 服务 │ 模板 │ │ +│ │ Drivers │ Connectors │ Services │ Templates │ │ +│ └──────────────┴──────────────┴──────────────┴──────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 1.2 仓库组织原则 + +| 原则 | 描述 | +|---|---| +| **单一职责** | 每个仓库只有一个明确的目的 | +| **独立版本** | 每个插件可以独立进行版本控制 | +| **依赖清晰** | 所有仓库都依赖 `@objectstack/spec` | +| **测试隔离** | 每个仓库有自己的 CI/CD 流水线 | +| **文档去中心化** | 每个仓库维护自己的文档 | +| **社区贡献** | 降低外部贡献者的门槛 | + +--- + +## 2. 仓库分类 + +### 2.1 核心仓库 (7个) + +**所有权**: 核心团队 +**稳定性**: 高 +**破坏性变更**: 需要 RFC 流程 + +| 仓库名称 | 用途 | 关键组件 | +|---|---|---| +| **spec** | 协议定义 | Zod 模式、TypeScript 类型、JSON 模式 | +| **core** | 微内核 | 插件加载器、依赖注入、生命周期 | +| **objectql** | 查询引擎 | SQL 构建器、查询优化器、AST 解析器 | +| **runtime** | 运行时环境 | 服务器、工作器、事件总线、中间件 | +| **client** | 客户端 SDK | API 客户端、类型安全查询、React Hooks | +| **cli** | 命令行工具 | 脚手架、迁移、代码生成 | +| **types** | 共享类型 | 运行时环境接口 | + +### 2.2 驱动仓库 (12+个) + +**所有权**: 核心团队 + 社区 +**稳定性**: 中等 +**破坏性变更**: 遵循语义化版本，与 spec 协调 + +| 分类 | 仓库名称 | 用途 | 状态 | +|---|---|---|---| +| **SQL** | `driver-postgres` | PostgreSQL 驱动 | 🟡 计划中 | +| **SQL** | `driver-mysql` | MySQL/MariaDB 驱动 | 🟡 计划中 | +| **SQL** | `driver-sqlite` | SQLite 驱动 | 🟡 计划中 | +| **SQL** | `driver-mssql` | Microsoft SQL Server 驱动 | 🟡 计划中 | +| **SQL** | `driver-oracle` | Oracle 数据库驱动 | 🟡 计划中 | +| **NoSQL** | `driver-mongodb` | MongoDB 驱动 | 🟡 计划中 | +| **NoSQL** | `driver-redis` | Redis 驱动 | 🟡 计划中 | +| **NoSQL** | `driver-dynamodb` | AWS DynamoDB 驱动 | 🟡 计划中 | +| **缓存** | `driver-memcached` | Memcached 驱动 | 🟡 计划中 | +| **搜索** | `driver-elasticsearch` | Elasticsearch 驱动 | 🟡 计划中 | +| **搜索** | `driver-meilisearch` | Meilisearch 驱动 | 🟡 计划中 | +| **内存** | `driver-memory` | 内存驱动（参考实现） | 🟢 已存在 | + +### 2.3 连接器仓库 (10+个) + +**所有权**: 社区（核心团队指导） +**稳定性**: 可变 +**破坏性变更**: 独立版本控制 + +| 分类 | 仓库名称 | 用途 | 优先级 | +|---|---|---|---| +| **CRM** | `connector-salesforce` | Salesforce 集成 | ⭐⭐⭐ | +| **CRM** | `connector-hubspot` | HubSpot 集成 | ⭐⭐ | +| **协作** | `connector-slack` | Slack 集成 | ⭐⭐⭐ | +| **协作** | `connector-teams` | Microsoft Teams 集成 | ⭐⭐ | +| **财务** | `connector-quickbooks` | QuickBooks 集成 | ⭐⭐ | +| **财务** | `connector-xero` | Xero 集成 | ⭐ | +| **ERP** | `connector-sap` | SAP 集成 | ⭐⭐ | +| **HRIS** | `connector-workday` | Workday 集成 | ⭐⭐ | +| **营销** | `connector-mailchimp` | Mailchimp 集成 | ⭐ | +| **支付** | `connector-stripe` | Stripe 集成 | ⭐⭐⭐ | + +### 2.4 服务插件仓库 (15+个) + +**所有权**: 核心团队 +**稳定性**: 中到高 +**破坏性变更**: 协调发布 + +| 分类 | 仓库名称 | 用途 | 优先级 | +|---|---|---|---| +| **安全** | `plugin-encryption` | 字段级加密 | ⭐⭐⭐ | +| **安全** | `plugin-masking` | PII 掩码 | ⭐⭐⭐ | +| **安全** | `plugin-compliance` | GDPR/HIPAA 合规工具包 | ⭐⭐⭐ | +| **多租户** | `plugin-multitenancy` | 租户隔离 | ⭐⭐⭐ | +| **缓存** | `plugin-cache` | 多层缓存 | ⭐⭐⭐ | +| **搜索** | `plugin-fulltext-search` | 全文搜索 | ⭐⭐ | +| **文件** | `plugin-file-storage` | 文件/附件管理 | ⭐⭐ | +| **工作流** | `plugin-workflow` | 高级工作流引擎 | ⭐⭐ | +| **审批** | `plugin-approval` | 审批流程 | ⭐⭐ | +| **通知** | `plugin-notification` | 多渠道通知 | ⭐⭐ | +| **分析** | `plugin-analytics` | 商业智能 | ⭐⭐ | +| **AI** | `plugin-ai-agent` | AI 代理编排 | ⭐⭐⭐ | +| **AI** | `plugin-ai-rag` | RAG 管道 | ⭐⭐⭐ | +| **可观测性** | `plugin-logging` | 结构化日志 | ⭐⭐ | +| **可观测性** | `plugin-tracing` | 分布式追踪 | ⭐⭐ | + +### 2.5 服务器插件仓库 (8+个) + +**所有权**: 核心团队 +**稳定性**: 高 +**破坏性变更**: 协调发布 + +| 仓库名称 | 用途 | 框架 | 状态 | +|---|---|---|---| +| `plugin-hono-server` | Hono 服务器适配器 | Hono | 🟢 已存在 | +| `plugin-express-server` | Express 服务器适配器 | Express | 🟡 计划中 | +| `plugin-fastify-server` | Fastify 服务器适配器 | Fastify | 🟡 计划中 | +| `plugin-nestjs-server` | NestJS 服务器适配器 | NestJS | 🟡 计划中 | +| `plugin-nextjs-server` | Next.js API 路由适配器 | Next.js | 🟡 计划中 | +| `plugin-cloudflare-workers` | Cloudflare Workers 适配器 | Workers | 🟡 计划中 | +| `plugin-aws-lambda` | AWS Lambda 适配器 | Serverless | 🟡 计划中 | +| `plugin-msw` | Mock Service Worker | MSW | 🟢 已存在 | + +### 2.6 模板仓库 (10+个) + +**所有权**: 社区（核心团队策划） +**稳定性**: 可变 +**破坏性变更**: 独立 + +| 仓库名称 | 用途 | 行业 | 状态 | +|---|---|---|---| +| `template-crm` | CRM 应用 | 销售 | 🟡 计划中 | +| `template-helpdesk` | 客户支持系统 | 服务 | 🟡 计划中 | +| `template-project-management` | 项目管理 | 运营 | 🟡 计划中 | +| `template-hr-system` | 人力资源 | HR | 🟡 计划中 | +| `template-inventory` | 库存管理 | 供应链 | 🟡 计划中 | +| `template-ecommerce` | 电子商务平台 | 零售 | 🟡 计划中 | +| `template-healthcare` | 医疗管理 | 医疗 | 🟡 计划中 | +| `template-education` | 学习管理 | 教育 | 🟡 计划中 | +| `template-iot-platform` | IoT 数据平台 | IoT | 🟡 计划中 | +| `template-ai-saas` | AI 驱动的 SaaS | AI/ML | 🟡 计划中 | + +### 2.7 工具仓库 (5+个) + +**所有权**: 核心团队 +**稳定性**: 中等 +**破坏性变更**: 独立 + +| 仓库名称 | 用途 | 用户 | +|---|---|---| +| `devtools` | 浏览器开发工具扩展 | 开发者 | +| `vscode-extension` | VS Code 扩展 | 开发者 | +| `jetbrains-plugin` | JetBrains IDE 插件 | 开发者 | +| `metadata-validator` | 元数据校验/验证 | DevOps | +| `migration-tool` | 从其他平台迁移 | 管理员 | + +### 2.8 文档与基础设施仓库 (5+个) + +**所有权**: 核心团队 +**稳定性**: 高 +**破坏性变更**: 仅内容 + +| 仓库名称 | 用途 | 内容 | +|---|---|---| +| `docs` | 官方文档 | 指南、教程、API 参考 | +| `examples` | 示例应用 | 示例代码、演示 | +| `awesome-objectstack` | 精选资源 | 社区插件、工具、文章 | +| `.github` | 组织级配置 | 模板、工作流、社区健康 | +| `registry` | 插件注册服务 | 插件元数据、版本、评论 | + +--- + +## 3. 仓库矩阵 + +### 3.1 按开发优先级 + +| 优先级 | 阶段 | 仓库 | 时间线 | +|---|---|---|---| +| **P0** | 基础 | spec, core, objectql, runtime, client, cli | 2026 Q1 | +| **P1** | 核心驱动 | driver-postgres, driver-mysql, driver-mongodb, driver-redis | 2026 Q2 | +| **P2** | 核心插件 | plugin-encryption, plugin-masking, plugin-multitenancy, plugin-cache | 2026 Q2 | +| **P3** | 关键连接器 | connector-salesforce, connector-slack, connector-stripe | 2026 Q3 | +| **P4** | 服务器适配器 | plugin-express, plugin-fastify, plugin-nextjs | 2026 Q3 | +| **P5** | 模板 | template-crm, template-helpdesk, template-project-management | 2026 Q4 | +| **P6** | 工具 | devtools, vscode-extension, migration-tool | 2026 Q4 | + +### 3.2 按所有权模型 + +| 所有权 | 仓库 | 维护 | 支持级别 | +|---|---|---|---| +| **核心团队** | spec, core, objectql, runtime, client, cli | 每日 | 企业 SLA | +| **核心+社区** | 所有驱动、服务器插件 | 每周 | 社区 + 高级 | +| **社区** | 连接器、模板、工具 | 尽力而为 | 仅社区 | +| **第三方** | 自定义插件、集成 | 独立 | 自助支持 | + +### 3.3 按技术栈 + +| 技术栈 | 仓库 | 语言 | 运行时 | +|---|---|---|---| +| **TypeScript** | spec, core, objectql, runtime, client, cli | TypeScript | Node.js | +| **数据库** | 所有 driver-* 仓库 | TypeScript | Node.js | +| **集成** | 所有 connector-* 仓库 | TypeScript | Node.js | +| **插件** | 所有 plugin-* 仓库 | TypeScript | Node.js | +| **前端** | devtools, vscode-extension | TypeScript | Browser/Electron | + +--- + +## 4. 仓库结构模板 + +### 4.1 核心仓库模板 + +``` +objectstack-ai/[core|objectql|runtime|client|cli]/ +├── .github/ +│ ├── workflows/ +│ │ ├── ci.yml # 持续集成 +│ │ ├── release.yml # 发布自动化 +│ │ └── security.yml # 安全扫描 +│ ├── ISSUE_TEMPLATE/ +│ ├── PULL_REQUEST_TEMPLATE.md +│ └── CODEOWNERS +├── src/ +│ ├── index.ts # 主入口 +│ ├── types/ # TypeScript 类型定义 +│ ├── core/ # 核心功能 +│ ├── utils/ # 工具函数 +│ └── __tests__/ # 单元测试 +├── docs/ +│ ├── README.md # 入门指南 +│ ├── API.md # API 文档 +│ └── ARCHITECTURE.md # 架构文档 +├── examples/ +│ └── basic/ # 使用示例 +├── package.json +├── tsconfig.json +├── tsup.config.ts # 构建配置 +├── vitest.config.ts # 测试配置 +├── README.md +├── CHANGELOG.md +├── LICENSE +└── CONTRIBUTING.md +``` + +### 4.2 驱动仓库模板 + +``` +objectstack-ai/driver-[postgres|mysql|mongodb|redis]/ +├── .github/ +│ └── workflows/ +│ ├── ci.yml +│ ├── integration-test.yml # 数据库集成测试 +│ └── release.yml +├── src/ +│ ├── index.ts +│ ├── driver.ts # 驱动实现 +│ ├── connection.ts # 连接管理器 +│ ├── query-builder.ts # 查询构建器 +│ ├── migrations.ts # 迁移支持 +│ └── __tests__/ +│ ├── unit/ # 单元测试 +│ └── integration/ # 集成测试 +├── docker/ +│ └── docker-compose.yml # 测试数据库设置 +├── docs/ +│ ├── README.md +│ ├── CONFIGURATION.md # 配置指南 +│ └── MIGRATION.md # 迁移指南 +├── package.json +├── README.md +└── CHANGELOG.md +``` + +### 4.3 插件仓库模板 + +``` +objectstack-ai/plugin-[encryption|masking|cache]/ +├── .github/ +│ └── workflows/ +│ ├── ci.yml +│ └── release.yml +├── src/ +│ ├── index.ts +│ ├── plugin.ts # 插件入口 +│ ├── config.ts # 配置模式 +│ ├── hooks/ # 生命周期钩子 +│ ├── services/ # 服务实现 +│ └── __tests__/ +├── docs/ +│ ├── README.md +│ ├── CONFIGURATION.md +│ └── EXAMPLES.md +├── examples/ +│ └── basic/ +├── package.json +├── README.md +└── CHANGELOG.md +``` + +### 4.4 连接器仓库模板 + +``` +objectstack-ai/connector-[salesforce|slack|stripe]/ +├── .github/ +│ └── workflows/ +│ ├── ci.yml +│ └── integration-test.yml +├── src/ +│ ├── index.ts +│ ├── connector.ts # 连接器实现 +│ ├── auth.ts # 认证 +│ ├── api-client.ts # API 客户端 +│ ├── mapping.ts # 字段映射 +│ ├── sync.ts # 同步引擎 +│ └── __tests__/ +├── docs/ +│ ├── README.md +│ ├── AUTHENTICATION.md # 认证设置指南 +│ ├── FIELD-MAPPING.md # 映射指南 +│ └── SYNC-CONFIGURATION.md # 同步配置 +├── examples/ +│ └── sync-contacts/ +├── package.json +├── README.md +└── CHANGELOG.md +``` + +### 4.5 模板仓库模板 + +``` +objectstack-ai/template-[crm|helpdesk|project-management]/ +├── .github/ +│ └── workflows/ +│ └── ci.yml +├── src/ +│ ├── domains/ # 业务域 +│ │ ├── account/ +│ │ │ ├── account.object.ts +│ │ │ ├── account.view.ts +│ │ │ └── account.hook.ts +│ │ └── contact/ +│ ├── ui/ +│ │ ├── apps.ts +│ │ ├── dashboards.ts +│ │ └── reports.ts +│ ├── workflows/ +│ └── index.ts +├── docs/ +│ ├── README.md +│ ├── INSTALLATION.md +│ ├── CUSTOMIZATION.md +│ └── DATA-MODEL.md +├── screenshots/ +├── objectstack.config.ts # Stack 配置 +├── package.json +└── README.md +``` + +--- + +## 5. 开发工作流 + +### 5.1 发布流程 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 1. 协议更新 (spec 仓库) │ +│ - 更新 Zod 模式 │ +│ - 增加版本 │ +│ - 发布 @objectstack/spec@x.y.z │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 2. 核心更新 (核心仓库) │ +│ - 更新到最新 @objectstack/spec │ +│ - 实现新功能 │ +│ - 发布核心包 │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 3. 插件更新 (插件仓库) │ +│ - 更新依赖 │ +│ - 实现新协议支持 │ +│ - 发布插件包 │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 4. 模板更新 (模板仓库) │ +│ - 更新依赖 │ +│ - 使用新功能 │ +│ - 更新文档 │ +└─────────────────────────────────────────────────────────┘ +``` + +### 5.2 依赖管理 + +**依赖规则**: +1. 所有仓库必须依赖 `@objectstack/spec`（协议定义） +2. 驱动/插件仓库可以依赖 `@objectstack/core`（如果使用内核功能） +3. 模板仓库应该依赖 `@objectstack/runtime` 或 `@objectstack/client` +4. 连接器应该是独立的（仅依赖 spec） + +**版本约束**: +```json +{ + "dependencies": { + "@objectstack/spec": "^0.6.0", // 协议 - 接受次版本更新 + "@objectstack/core": "~0.6.1", // 核心 - 仅补丁更新 + "@objectstack/runtime": "^0.6.0" // 运行时 - 接受次版本更新 + } +} +``` + +### 5.3 CI/CD 流水线 + +**所有仓库的标准流水线**: + +```yaml +# .github/workflows/ci.yml +name: CI + +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v2 + - uses: actions/setup-node@v4 + - run: pnpm install + - run: pnpm lint + - run: pnpm typecheck + - run: pnpm test + - run: pnpm build + + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: 运行 CodeQL + uses: github/codeql-action/analyze@v2 + - name: 运行 npm audit + run: npm audit --audit-level=high +``` + +--- + +## 6. 命名规范 + +### 6.1 仓库命名 + +| 类型 | 模式 | 示例 | +|---|---|---| +| **核心** | `[name]` | `spec`, `core`, `runtime`, `client`, `cli` | +| **驱动** | `driver-[database]` | `driver-postgres`, `driver-mongodb` | +| **连接器** | `connector-[service]` | `connector-salesforce`, `connector-slack` | +| **插件** | `plugin-[feature]` | `plugin-encryption`, `plugin-cache` | +| **模板** | `template-[domain]` | `template-crm`, `template-helpdesk` | +| **工具** | `[tool-name]` | `devtools`, `vscode-extension` | + +### 6.2 包命名 + +| 类型 | 模式 | 示例 | +|---|---|---| +| **核心** | `@objectstack/[name]` | `@objectstack/core`, `@objectstack/runtime` | +| **驱动** | `@objectstack/driver-[name]` | `@objectstack/driver-postgres` | +| **连接器** | `@objectstack/connector-[name]` | `@objectstack/connector-salesforce` | +| **插件** | `@objectstack/plugin-[name]` | `@objectstack/plugin-encryption` | +| **模板** | `@objectstack/template-[name]` | `@objectstack/template-crm` | + +### 6.3 分支命名 + +| 类型 | 模式 | 示例 | +|---|---|---| +| **功能** | `feature/[issue-number]-[description]` | `feature/123-add-postgres-driver` | +| **修复** | `fix/[issue-number]-[description]` | `fix/456-connection-leak` | +| **发布** | `release/v[version]` | `release/v0.7.0` | +| **热修复** | `hotfix/[version]` | `hotfix/0.6.2` | + +--- + +## 7. 质量标准 + +### 7.1 代码质量要求 + +| 指标 | 核心仓库 | 驱动仓库 | 插件仓库 | 模板仓库 | +|---|:---:|:---:|:---:|:---:| +| **测试覆盖率** | ≥ 90% | ≥ 80% | ≥ 75% | ≥ 60% | +| **TypeScript 严格模式** | ✅ 必需 | ✅ 必需 | ✅ 必需 | ⚠️ 推荐 | +| **ESLint** | ✅ 必需 | ✅ 必需 | ✅ 必需 | ✅ 必需 | +| **Prettier** | ✅ 必需 | ✅ 必需 | ✅ 必需 | ✅ 必需 | +| **文档** | ✅ 全面 | ✅ 全面 | ✅ 必需 | ⚠️ 基本 | +| **示例** | ✅ 必需 | ✅ 必需 | ✅ 必需 | N/A (本身是示例) | + +### 7.2 安全标准 + +**所有仓库必须**: +- ✅ 启用 GitHub Dependabot +- ✅ 启用 GitHub CodeQL 扫描 +- ✅ 启用 GitHub 密钥扫描 +- ✅ 在 CI/CD 中使用 npm audit +- ✅ 遵循 OWASP 安全指南 +- ✅ 在 SECURITY.md 中记录安全策略 + +### 7.3 文档标准 + +**所有仓库必须包含**: +- ✅ `README.md` - 概述、安装、快速开始 +- ✅ `CHANGELOG.md` - 版本历史（Keep a Changelog 格式） +- ✅ `CONTRIBUTING.md` - 贡献指南 +- ✅ `LICENSE` - Apache 2.0 许可文件 +- ✅ `SECURITY.md` - 安全策略和报告 + +**驱动/插件/连接器仓库应包含**: +- ✅ `docs/CONFIGURATION.md` - 配置参考 +- ✅ `docs/API.md` - API 文档 +- ✅ `examples/` - 使用示例 + +--- + +## 8. 迁移路径 + +### 8.1 当前状态 + +**现有结构（Monorepo）**: +``` +objectstack-ai/spec/ +├── packages/ +│ ├── spec/ ← 保留（协议定义） +│ ├── core/ ← 提取到 objectstack-ai/core +│ ├── objectql/ ← 提取到 objectstack-ai/objectql +│ ├── runtime/ ← 提取到 objectstack-ai/runtime +│ ├── client/ ← 提取到 objectstack-ai/client +│ ├── cli/ ← 提取到 objectstack-ai/cli +│ ├── types/ ← 保留或合并到 spec +│ ├── ai-bridge/ ← 保留或提取 +│ └── plugins/ +│ ├── driver-memory/ ← 提取到 objectstack-ai/driver-memory +│ ├── plugin-hono-server/ ← 提取到 objectstack-ai/plugin-hono-server +│ └── plugin-msw/ ← 提取到 objectstack-ai/plugin-msw +└── examples/ ← 暂时保留 +``` + +### 8.2 目标状态 + +**分布式仓库**: +``` +GitHub 组织: objectstack-ai/ +├── spec (仅协议定义) +├── core (微内核) +├── objectql (查询引擎) +├── runtime (运行时环境) +├── client (客户端 SDK) +├── cli (CLI 工具) +├── types (共享类型) +├── ai-bridge (AI 桥接 - 可选) +├── driver-memory (参考驱动) +├── driver-postgres (新) +├── driver-mysql (新) +├── driver-mongodb (新) +├── plugin-hono-server (现有) +├── plugin-msw (现有) +├── plugin-encryption (新) +├── plugin-multitenancy (新) +├── connector-salesforce (新) +├── template-crm (新) +├── docs (文档站点) +└── .github (组织级配置) +``` + +### 8.3 迁移策略 + +**阶段 1: 提取核心仓库 (第 1-2 个月)** +1. 使用适当结构创建新仓库 +2. 从 monorepo 复制代码到新仓库 +3. 为每个仓库设置 CI/CD +4. 发布初始版本到 npm +5. 更新 monorepo 以使用发布的包 + +**阶段 2: 提取插件 (第 2-3 个月)** +1. 提取现有插件 (driver-memory, plugin-hono-server, plugin-msw) +2. 创建新驱动仓库 +3. 创建新插件仓库 +4. 更新依赖链 + +**阶段 3: 创建生态系统 (第 3-12 个月)** +1. 开发连接器 +2. 创建模板 +3. 构建开发工具 +4. 建立社区贡献流程 + +**阶段 4: 弃用 Monorepo (第 12 个月+)** +1. 归档 monorepo 或保留为工作空间 +2. 将流量重定向到各个仓库 +3. 更新所有文档 + +--- + +## 9. 社区与治理 + +### 9.1 仓库所有权 + +| 级别 | 仓库 | 维护者 | 决策权限 | +|---|---|---|---| +| **Tier 1** | spec, core | 仅核心团队 | 需要 RFC + 投票 | +| **Tier 2** | objectql, runtime, client, cli | 核心团队 + 受信任的贡献者 | 需要 PR 审查 | +| **Tier 3** | 驱动、服务器插件 | 核心团队 + 社区 | 标准 PR 流程 | +| **Tier 4** | 连接器、模板、工具 | 社区主导 | 社区维护者 | + +### 9.2 贡献工作流 + +``` +1. Fork 仓库 +2. 创建功能分支 +3. 实现更改 + 测试 +4. 提交 Pull Request +5. 代码审查 +6. CI/CD 通过 +7. 合并到 main +8. 自动发布（如适用） +``` + +### 9.3 RFC 流程 + +**需要 RFC 的情况**: +- spec 中的破坏性更改 +- 新协议或主要协议更改 +- core 中的架构更改 +- 新仓库创建（Tier 1-2） + +**流程**: +1. 在 `spec` 仓库讨论中提交 RFC +2. 社区讨论（2 周） +3. 核心团队审查 +4. 投票（针对 Tier 1 更改） +5. 在功能分支中实现 +6. 最终审查和合并 + +--- + +## 10. 成功指标 + +### 10.1 生态系统健康度 + +| 指标 | 2026 Q2 目标 | 2026 Q4 目标 | 2027 目标 | +|---|:---:|:---:|:---:| +| **核心仓库** | 7 | 7 | 7 | +| **驱动仓库** | 5 | 8 | 12+ | +| **插件仓库** | 5 | 10 | 20+ | +| **连接器仓库** | 3 | 8 | 15+ | +| **模板仓库** | 2 | 5 | 10+ | +| **社区贡献者** | 10 | 30 | 100+ | +| **GitHub 总星数** | 500 | 2,000 | 5,000+ | +| **NPM 周下载量** | 1,000 | 10,000 | 50,000+ | + +### 10.2 质量指标 + +| 指标 | 目标 | +|---|:---:| +| **平均测试覆盖率** | ≥ 80% | +| **安全漏洞** | 0 高/严重 | +| **文档覆盖率** | ≥ 90% | +| **Issue 响应时间** | < 48 小时 | +| **PR 审查时间** | < 72 小时 | +| **发布频率** | 每周（次要），每月（主要） | + +--- + +## 11. 实施检查清单 + +### 11.1 基础设施设置 + +- [ ] 创建 GitHub 组织（如不存在） +- [ ] 设置组织级设置 +- [ ] 配置组织密钥（NPM_TOKEN 等） +- [ ] 设置 GitHub 讨论 +- [ ] 创建 `.github` 仓库用于模板 +- [ ] 设置组织项目看板 +- [ ] 配置 GitHub Pages 用于文档 + +### 11.2 仓库创建 + +**阶段 1: 核心 (2026 Q1)** +- [ ] 提取 `objectstack-ai/core` +- [ ] 提取 `objectstack-ai/objectql` +- [ ] 提取 `objectstack-ai/runtime` +- [ ] 提取 `objectstack-ai/client` +- [ ] 提取 `objectstack-ai/cli` +- [ ] 保留 `objectstack-ai/spec`（重构为仅协议） +- [ ] 保留 `objectstack-ai/types` + +**阶段 2: 核心驱动 (2026 Q2)** +- [ ] 创建 `objectstack-ai/driver-postgres` +- [ ] 创建 `objectstack-ai/driver-mysql` +- [ ] 创建 `objectstack-ai/driver-mongodb` +- [ ] 创建 `objectstack-ai/driver-redis` +- [ ] 提取 `objectstack-ai/driver-memory` + +**阶段 3: 核心插件 (2026 Q2)** +- [ ] 创建 `objectstack-ai/plugin-encryption` +- [ ] 创建 `objectstack-ai/plugin-masking` +- [ ] 创建 `objectstack-ai/plugin-multitenancy` +- [ ] 创建 `objectstack-ai/plugin-cache` +- [ ] 提取 `objectstack-ai/plugin-hono-server` +- [ ] 提取 `objectstack-ai/plugin-msw` + +**阶段 4: 生态系统 (2026 Q3-Q4)** +- [ ] 创建连接器仓库 (3+) +- [ ] 创建模板仓库 (2+) +- [ ] 创建工具仓库 (2+) +- [ ] 创建 `objectstack-ai/docs` +- [ ] 创建 `objectstack-ai/registry` + +### 11.3 文档 + +- [ ] 创建组织 README +- [ ] 创建贡献指南（组织级） +- [ ] 创建安全策略（组织级） +- [ ] 创建行为准则 +- [ ] 创建开发者文档站点 +- [ ] 创建插件开发指南 +- [ ] 创建连接器开发指南 +- [ ] 创建模板创建指南 + +--- + +## 12. 附录 + +### 12.1 参考生态系统 + +**Kubernetes**: +- 核心: `kubernetes/kubernetes` +- Operators: `kubernetes-sigs/*` +- Helm Charts: `helm/charts` +- 社区: `kubernetes/community` + +**Prisma**: +- 核心: `prisma/prisma` +- 引擎: `prisma/prisma-engines` +- 客户端: `prisma/prisma-client-js` +- 示例: `prisma/prisma-examples` + +**Nx**: +- 核心: `nrwl/nx` +- 插件: `nrwl/nx-*` +- 配方: `nrwl/nx-recipes` +- 示例: `nrwl/nx-examples` + +### 12.2 有用链接 + +- [GitHub 组织最佳实践](https://docs.github.com/en/organizations) +- [Monorepo vs Multi-repo](https://earthly.dev/blog/monorepo-vs-polyrepo/) +- [语义化版本](https://semver.org/lang/zh-CN/) +- [约定式提交](https://www.conventionalcommits.org/zh-hans/) +- [保持更新日志](https://keepachangelog.com/zh-CN/) + +--- + +**文档维护者**: ObjectStack 核心团队 +**审查周期**: 季度 +**下次审查**: 2026-04-30 +**反馈**: 在 `objectstack-ai/spec` 仓库创建 issue diff --git a/README.md b/README.md index d91effdd898..88987d95e42 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,23 @@ pnpm docs:dev | [`examples/crm`](examples/crm) | Full-featured CRM example | 🟢 Complete | | [`examples/todo`](examples/todo) | Simple todo app example | 🟢 Active | +## 🏗️ Architecture & Planning + +**Strategic Planning Documents:** +- **[GitHub Organization Structure](./GITHUB_ORGANIZATION_STRUCTURE.md)** ([中文版](./GITHUB_ORGANIZATION_STRUCTURE_CN.md)) - Complete repository architecture for the ObjectStack ecosystem +- **[Transformation Plan V2](./TRANSFORMATION_PLAN_V2.md)** - 12-month protocol development roadmap +- **[Technical Recommendations V2](./TECHNICAL_RECOMMENDATIONS_V2.md)** - Missing protocols and enhancement recommendations +- **[Evaluation Summary](./EVALUATION_SUMMARY.md)** - Current state analysis and next steps + +**Repository Organization:** +- 🎯 **Core Repositories** (7): spec, core, objectql, runtime, client, cli, types +- 🔌 **Driver Repositories** (12+): PostgreSQL, MySQL, MongoDB, Redis, etc. +- 🔗 **Connector Repositories** (10+): Salesforce, Slack, Stripe, etc. +- ⚡ **Plugin Repositories** (15+): Encryption, caching, multi-tenancy, AI, etc. +- 📦 **Template Repositories** (10+): CRM, helpdesk, project management, etc. + +See the **[GitHub Organization Structure](./GITHUB_ORGANIZATION_STRUCTURE.md)** document for complete details on repository architecture, naming conventions, and development workflows. + ## 🤝 Contributing We welcome contributions! Please read our **[Contributing Guide](./CONTRIBUTING.md)** for: From 02f254245396361d3b93f98c22d315b67cfa8fa6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 30 Jan 2026 15:23:37 +0000 Subject: [PATCH 3/4] Add project structure implementation summary Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md | 484 ++++++++++++++++++++ README.md | 1 + 2 files changed, 485 insertions(+) create mode 100644 PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md diff --git a/PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md b/PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md new file mode 100644 index 00000000000..4d84780b60c --- /dev/null +++ b/PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md @@ -0,0 +1,484 @@ +# ObjectStack 项目实施总结 +# ObjectStack Project Implementation Summary + +**文档版本 / Version**: 1.0 +**创建日期 / Created**: 2026-01-30 +**作者 / Author**: ObjectStack 核心团队 / ObjectStack Core Team + +--- + +## 📝 任务概要 / Task Summary + +根据 ObjectStack 的微内核和插件架构设计，结合全球最佳实践（Kubernetes、Salesforce、VS Code），为 GitHub 组织创建了完整的仓库架构规划。 + +Based on ObjectStack's microkernel and plugin architecture design, and following global best practices (Kubernetes, Salesforce, VS Code), created a comprehensive repository architecture plan for the GitHub organization. + +--- + +## 📚 交付成果 / Deliverables + +### 1. GitHub 组织架构文档 / GitHub Organization Structure Document + +**文件 / Files**: +- `GITHUB_ORGANIZATION_STRUCTURE.md` (English, 29,901 characters) +- `GITHUB_ORGANIZATION_STRUCTURE_CN.md` (Chinese, 21,173 characters) + +**内容概览 / Content Overview**: + +#### 1.1 仓库分类体系 / Repository Categorization System + +定义了 7 大类仓库，共计 60+ 个仓库规划： + +Defined 7 major repository categories, totaling 60+ planned repositories: + +| 类别 / Category | 数量 / Count | 说明 / Description | +|---|:---:|---| +| **核心仓库** | 7 | spec, core, objectql, runtime, client, cli, types | +| **驱动仓库** | 12+ | PostgreSQL, MySQL, MongoDB, Redis, SQLite, etc. | +| **连接器仓库** | 10+ | Salesforce, Slack, Stripe, HubSpot, etc. | +| **服务插件仓库** | 15+ | Encryption, caching, multi-tenancy, AI, etc. | +| **服务器插件仓库** | 8+ | Hono, Express, Fastify, Next.js adapters | +| **模板仓库** | 10+ | CRM, helpdesk, project management, etc. | +| **工具仓库** | 5+ | DevTools, VS Code extension, migration tools | +| **文档与基础设施** | 5+ | Docs, examples, registry, .github | + +#### 1.2 架构设计原则 / Architecture Design Principles + +``` +协议层 (Protocol Layer) + ↓ +微内核层 (Microkernel Layer) + ↓ +插件层 (Plugin Layer) +``` + +**关键原则 / Key Principles**: +- ✅ 单一职责 / Single Responsibility +- ✅ 独立版本 / Independent Versioning +- ✅ 依赖清晰 / Clear Dependencies +- ✅ 测试隔离 / Testing Isolation +- ✅ 文档去中心化 / Decentralized Documentation +- ✅ 社区友好 / Community-Friendly + +#### 1.3 仓库结构模板 / Repository Structure Templates + +为每种仓库类型提供了标准化的目录结构模板： + +Provided standardized directory structure templates for each repository type: + +- **核心仓库模板** / Core Repository Template +- **驱动仓库模板** / Driver Repository Template +- **插件仓库模板** / Plugin Repository Template +- **连接器仓库模板** / Connector Repository Template +- **模板仓库模板** / Template Repository Template + +每个模板包含： + +Each template includes: +- GitHub Actions 工作流配置 / GitHub Actions workflows +- 源代码组织结构 / Source code organization +- 测试目录结构 / Test directory structure +- 文档要求 / Documentation requirements +- 配置文件标准 / Configuration file standards + +#### 1.4 开发工作流 / Development Workflows + +**发布流程 / Release Process**: +``` +1. 协议更新 (spec) → 发布 @objectstack/spec +2. 核心更新 (core, runtime, etc.) → 发布核心包 +3. 插件更新 (drivers, plugins) → 发布插件包 +4. 模板更新 (templates) → 更新示例 +``` + +**CI/CD 标准 / CI/CD Standards**: +- ✅ 所有仓库必须配置 CI 流水线 +- ✅ 自动化测试（单元测试、集成测试） +- ✅ 自动化安全扫描（CodeQL、npm audit） +- ✅ 自动化发布（Changesets） + +#### 1.5 质量标准 / Quality Standards + +| 指标 / Metric | 核心仓库 / Core | 驱动仓库 / Drivers | 插件仓库 / Plugins | 模板仓库 / Templates | +|---|:---:|:---:|:---:|:---:| +| **测试覆盖率** | ≥ 90% | ≥ 80% | ≥ 75% | ≥ 60% | +| **TypeScript 严格模式** | ✅ | ✅ | ✅ | ⚠️ | +| **ESLint + Prettier** | ✅ | ✅ | ✅ | ✅ | +| **文档** | 全面 | 全面 | 必需 | 基本 | + +#### 1.6 迁移路径 / Migration Path + +**当前状态 / Current State**: Monorepo（单体仓库） +- packages/spec, core, objectql, runtime, client, cli, types +- packages/plugins (driver-memory, plugin-hono-server, plugin-msw) + +**目标状态 / Target State**: Multi-repo（多仓库） +- 7 个核心仓库（独立版本控制） +- 40+ 个插件/驱动/连接器仓库（生态系统） +- 10+ 个模板仓库（最佳实践示例） + +**迁移策略 / Migration Strategy**: +- 阶段 1 (Q1 2026): 提取核心仓库 +- 阶段 2 (Q2 2026): 提取现有插件，创建核心驱动 +- 阶段 3 (Q3-Q4 2026): 创建生态系统（连接器、模板、工具） +- 阶段 4 (2027): 弃用或归档 monorepo + +#### 1.7 命名规范 / Naming Conventions + +| 类型 / Type | 模式 / Pattern | 示例 / Examples | +|---|---|---| +| **核心仓库** | `[name]` | `spec`, `core`, `runtime` | +| **驱动** | `driver-[database]` | `driver-postgres`, `driver-mongodb` | +| **连接器** | `connector-[service]` | `connector-salesforce`, `connector-slack` | +| **插件** | `plugin-[feature]` | `plugin-encryption`, `plugin-cache` | +| **模板** | `template-[domain]` | `template-crm`, `template-helpdesk` | +| **NPM 包** | `@objectstack/[repo-name]` | `@objectstack/driver-postgres` | + +#### 1.8 优先级与时间线 / Priorities & Timeline + +| 优先级 / Priority | 阶段 / Phase | 仓库 / Repositories | 时间线 / Timeline | +|---|---|---|---| +| **P0** | 基础 | 7 个核心仓库 | 2026 Q1 | +| **P1** | 核心驱动 | 4 个数据库驱动 | 2026 Q2 | +| **P2** | 核心插件 | 4 个安全/性能插件 | 2026 Q2 | +| **P3** | 关键连接器 | 3 个 SaaS 连接器 | 2026 Q3 | +| **P4** | 服务器适配器 | 3 个框架适配器 | 2026 Q3 | +| **P5** | 模板 | 3 个行业模板 | 2026 Q4 | +| **P6** | 工具 | 3 个开发工具 | 2026 Q4 | + +#### 1.9 成功指标 / Success Metrics + +**2026 年目标 / 2026 Targets**: +- ✅ 核心仓库: 7 个 +- ✅ 驱动仓库: 8 个 +- ✅ 插件仓库: 10 个 +- ✅ 连接器仓库: 8 个 +- ✅ 模板仓库: 5 个 +- ✅ 社区贡献者: 30+ 人 +- ✅ GitHub 总星数: 2,000+ +- ✅ NPM 周下载量: 10,000+ + +**2027 年目标 / 2027 Targets**: +- ✅ 驱动仓库: 12+ 个 +- ✅ 插件仓库: 20+ 个 +- ✅ 连接器仓库: 15+ 个 +- ✅ 模板仓库: 10+ 个 +- ✅ 社区贡献者: 100+ 人 +- ✅ GitHub 总星数: 5,000+ +- ✅ NPM 周下载量: 50,000+ + +#### 1.10 社区与治理 / Community & Governance + +**仓库所有权模型 / Repository Ownership Model**: + +| 级别 / Tier | 仓库 / Repositories | 维护者 / Maintainers | 决策 / Decision | +|---|---|---|---| +| **Tier 1** | spec, core | 核心团队 | RFC + 投票 | +| **Tier 2** | objectql, runtime, client, cli | 核心团队 + 受信任贡献者 | PR 审查 | +| **Tier 3** | 驱动、服务器插件 | 核心团队 + 社区 | 标准 PR | +| **Tier 4** | 连接器、模板、工具 | 社区主导 | 社区维护 | + +**RFC 流程 / RFC Process**: +- 适用于破坏性更改、新协议、架构变更 +- 社区讨论 2 周 → 核心团队审查 → 投票（如需）→ 实现 + +--- + +## 🎯 核心贡献 / Core Contributions + +### 1. 完整的架构规划 / Complete Architecture Planning + +- ✅ 定义了 60+ 个仓库的完整生态系统 +- ✅ 每个仓库都有明确的职责和边界 +- ✅ 遵循微内核 + 插件的最佳实践 + +### 2. 标准化的开发流程 / Standardized Development Processes + +- ✅ 统一的 CI/CD 流水线 +- ✅ 统一的代码质量标准 +- ✅ 统一的文档规范 +- ✅ 统一的安全审查流程 + +### 3. 清晰的迁移路径 / Clear Migration Path + +- ✅ 从当前 monorepo 到目标 multi-repo 的详细步骤 +- ✅ 4 个阶段的分步实施计划 +- ✅ 明确的时间线和优先级 + +### 4. 可扩展的生态系统 / Scalable Ecosystem + +- ✅ 降低社区贡献门槛 +- ✅ 独立版本控制，避免耦合 +- ✅ 清晰的依赖关系 +- ✅ 易于维护和测试 + +--- + +## 📊 与全球最佳实践对标 / Benchmarking Against Global Best Practices + +### Kubernetes 生态系统 / Kubernetes Ecosystem + +**学习借鉴 / Lessons Learned**: +- ✅ 核心与扩展分离（kubernetes/kubernetes vs kubernetes-sigs/*） +- ✅ CRD 模式（Custom Resource Definitions） +- ✅ Operator 模式（自定义控制器） +- ✅ 社区治理模型 + +**ObjectStack 应用 / ObjectStack Application**: +- ✅ spec (协议) vs drivers/plugins (实现) +- ✅ Object 定义 = CRD +- ✅ Plugin 系统 = Operator +- ✅ Tier-based 治理模型 + +### Salesforce 生态系统 / Salesforce Ecosystem + +**学习借鉴 / Lessons Learned**: +- ✅ AppExchange 市场模式 +- ✅ 元数据驱动架构 +- ✅ 多租户设计 +- ✅ ISV 合作伙伴生态 + +**ObjectStack 应用 / ObjectStack Application**: +- ✅ Plugin Registry (类似 AppExchange) +- ✅ ObjectQL 元数据定义 +- ✅ Multi-tenancy 插件 +- ✅ Community + Enterprise 模式 + +### VS Code 生态系统 / VS Code Ecosystem + +**学习借鉴 / Lessons Learned**: +- ✅ 扩展市场 +- ✅ Extension API +- ✅ 语言服务器协议（LSP） +- ✅ 主题和配置系统 + +**ObjectStack 应用 / ObjectStack Application**: +- ✅ Plugin Marketplace +- ✅ Plugin API (hook system) +- ✅ Driver Protocol +- ✅ Theme 配置 + +### Prisma 生态系统 / Prisma Ecosystem + +**学习借鉴 / Lessons Learned**: +- ✅ Schema-first 设计 +- ✅ 类型安全查询 +- ✅ 多数据库支持 +- ✅ 迁移系统 + +**ObjectStack 应用 / ObjectStack Application**: +- ✅ Zod Schema (运行时验证 + 类型推导) +- ✅ Type-safe ObjectQL +- ✅ Driver abstraction +- ✅ Schema sync protocol + +--- + +## 🔄 与现有文档的关系 / Relationship with Existing Documents + +新创建的文档补充了现有的评估和规划文档： + +The newly created documents complement the existing evaluation and planning documents: + +| 文档 / Document | 作用 / Purpose | 关系 / Relationship | +|---|---|---| +| **GITHUB_ORGANIZATION_STRUCTURE.md** | 仓库架构规划 | **新建** - 实现层面的具体规划 | +| **TRANSFORMATION_PLAN_V2.md** | 协议改造计划 | 互补 - 协议定义 vs 仓库组织 | +| **TECHNICAL_RECOMMENDATIONS_V2.md** | 技术建议 | 互补 - 协议设计 vs 仓库实现 | +| **EVALUATION_SUMMARY.md** | 评估总结 | 基础 - 问题诊断 → 解决方案 | + +**信息流 / Information Flow**: +``` +EVALUATION_SUMMARY.md (问题诊断) + ↓ +TECHNICAL_RECOMMENDATIONS_V2.md (协议设计建议) + ↓ +TRANSFORMATION_PLAN_V2.md (协议改造路线图) + ↓ +GITHUB_ORGANIZATION_STRUCTURE.md (仓库架构与实施) ← 本次新增 +``` + +--- + +## ✅ 实施建议 / Implementation Recommendations + +### 立即行动 / Immediate Actions (本周 / This Week) + +1. **审查文档** / Review Documents + - [ ] 核心团队审查 GitHub 组织架构文档 + - [ ] 讨论和确认仓库分类和命名 + - [ ] 确定 Q1 2026 的核心仓库提取计划 + +2. **准备基础设施** / Prepare Infrastructure + - [ ] 确认 GitHub 组织设置 + - [ ] 配置组织级密钥（NPM_TOKEN、CI secrets） + - [ ] 创建 `.github` 仓库和模板 + +3. **启动 RFC 流程** / Start RFC Process + - [ ] 发起 RFC: Monorepo to Multi-repo Migration + - [ ] 社区讨论（2 周） + - [ ] 核心团队投票决策 + +### 短期计划 / Short-term Plans (Q1 2026) + +1. **提取核心仓库 / Extract Core Repositories** + - [ ] objectstack-ai/core + - [ ] objectstack-ai/objectql + - [ ] objectstack-ai/runtime + - [ ] objectstack-ai/client + - [ ] objectstack-ai/cli + - [ ] 保留并重构 objectstack-ai/spec + +2. **建立标准 / Establish Standards** + - [ ] 创建仓库模板 + - [ ] 配置 CI/CD 流水线 + - [ ] 编写贡献指南 + - [ ] 设置安全策略 + +3. **发布初版 / Initial Releases** + - [ ] 发布所有核心包到 npm + - [ ] 更新文档和示例 + - [ ] 发布公告 + +### 中期计划 / Medium-term Plans (Q2-Q3 2026) + +1. **驱动开发 / Driver Development** + - [ ] driver-postgres + - [ ] driver-mysql + - [ ] driver-mongodb + - [ ] driver-redis + +2. **插件开发 / Plugin Development** + - [ ] plugin-encryption + - [ ] plugin-masking + - [ ] plugin-multitenancy + - [ ] plugin-cache + +3. **连接器开发 / Connector Development** + - [ ] connector-salesforce + - [ ] connector-slack + - [ ] connector-stripe + +### 长期计划 / Long-term Plans (Q4 2026 - 2027) + +1. **生态系统建设 / Ecosystem Building** + - [ ] 创建 10+ 模板仓库 + - [ ] 开发工具套件 + - [ ] 建立插件注册中心 + - [ ] 启动社区贡献计划 + +2. **商业化准备 / Commercialization Preparation** + - [ ] Enterprise 版本规划 + - [ ] 支持和培训体系 + - [ ] 合作伙伴计划 + - [ ] 认证体系 + +--- + +## 📈 预期收益 / Expected Benefits + +### 技术收益 / Technical Benefits + +1. **更好的代码组织 / Better Code Organization** + - 每个仓库职责清晰 + - 降低耦合度 + - 提高可维护性 + +2. **独立的版本控制 / Independent Versioning** + - 插件可独立发布 + - 避免不必要的版本升级 + - 更灵活的发布节奏 + +3. **更好的测试隔离 / Better Test Isolation** + - 每个仓库独立测试 + - 更快的 CI/CD 反馈 + - 更容易定位问题 + +### 社区收益 / Community Benefits + +1. **降低贡献门槛 / Lower Contribution Barrier** + - 贡献者只需 fork 相关仓库 + - 不需要理解整个 monorepo + - 更快的 PR 审查周期 + +2. **更好的文档 / Better Documentation** + - 每个仓库自己的文档 + - 更聚焦、更易理解 + - 易于维护 + +3. **生态系统增长 / Ecosystem Growth** + - 第三方开发者可创建自己的插件 + - 社区驱动的创新 + - 更丰富的解决方案 + +### 商业收益 / Business Benefits + +1. **市场定位 / Market Positioning** + - 与 Kubernetes/Salesforce 对标 + - 体现专业性和成熟度 + - 吸引企业客户 + +2. **可扩展性 / Scalability** + - 支持多团队并行开发 + - 支持外包和合作伙伴 + - 支持多产品线 + +3. **商业模式 / Business Model** + - 开源核心 + 商业插件 + - 社区版 + 企业版 + - Marketplace 收入分成 + +--- + +## 🎓 参考资料 / References + +### 架构设计 / Architecture Design + +1. **Microkernel Architecture** + - [微内核架构模式](https://en.wikipedia.org/wiki/Microkernel) + - [Eclipse Plugin Architecture](https://www.eclipse.org/articles/Article-Plug-in-architecture/plugin_architecture.html) + - [VS Code Extension Architecture](https://code.visualstudio.com/api/extension-guides/overview) + +2. **Monorepo vs Multi-repo** + - [Monorepo vs Polyrepo](https://earthly.dev/blog/monorepo-vs-polyrepo/) + - [Google's Monorepo Experience](https://cacm.acm.org/magazines/2016/7/204032-why-google-stores-billions-of-lines-of-code-in-a-single-repository/) + - [Lerna (Monorepo Tool)](https://lerna.js.org/) + +### 生态系统案例 / Ecosystem Case Studies + +1. **Kubernetes** + - [Kubernetes GitHub Organization](https://github.com/kubernetes) + - [Kubernetes SIGs](https://github.com/kubernetes-sigs) + - [CNCF Landscape](https://landscape.cncf.io/) + +2. **Prisma** + - [Prisma GitHub Organization](https://github.com/prisma) + - [Prisma Ecosystem](https://www.prisma.io/ecosystem) + +3. **Nx** + - [Nx GitHub Organization](https://github.com/nrwl) + - [Nx Plugin System](https://nx.dev/extending-nx/intro/getting-started) + +### 最佳实践 / Best Practices + +1. **GitHub Organization Management** + - [GitHub Organization Best Practices](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations) + - [Open Source Guides](https://opensource.guide/) + +2. **Versioning & Releases** + - [Semantic Versioning](https://semver.org/) + - [Conventional Commits](https://www.conventionalcommits.org/) + - [Keep a Changelog](https://keepachangelog.com/) + +--- + +## 📞 联系方式 / Contact + +**文档维护者 / Document Maintainer**: ObjectStack 核心团队 / ObjectStack Core Team +**问题反馈 / Feedback**: 在 `objectstack-ai/spec` 仓库创建 issue +**讨论 / Discussion**: GitHub Discussions (启用后) + +--- + +**最后更新 / Last Updated**: 2026-01-30 +**下次审查 / Next Review**: 2026-02-28 (每月审查 / Monthly review) diff --git a/README.md b/README.md index 88987d95e42..032cd3ab53e 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,7 @@ pnpm docs:dev **Strategic Planning Documents:** - **[GitHub Organization Structure](./GITHUB_ORGANIZATION_STRUCTURE.md)** ([中文版](./GITHUB_ORGANIZATION_STRUCTURE_CN.md)) - Complete repository architecture for the ObjectStack ecosystem +- **[Implementation Summary](./PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md)** - Summary of architecture planning and next steps - **[Transformation Plan V2](./TRANSFORMATION_PLAN_V2.md)** - 12-month protocol development roadmap - **[Technical Recommendations V2](./TECHNICAL_RECOMMENDATIONS_V2.md)** - Missing protocols and enhancement recommendations - **[Evaluation Summary](./EVALUATION_SUMMARY.md)** - Current state analysis and next steps From 8c76e39a6f5d5fe9306e50ba0614b7183b4f024f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 30 Jan 2026 15:25:21 +0000 Subject: [PATCH 4/4] Add architecture quick reference guide Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- ARCHITECTURE_QUICK_REFERENCE.md | 357 ++++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 358 insertions(+) create mode 100644 ARCHITECTURE_QUICK_REFERENCE.md diff --git a/ARCHITECTURE_QUICK_REFERENCE.md b/ARCHITECTURE_QUICK_REFERENCE.md new file mode 100644 index 00000000000..f1c46aeb935 --- /dev/null +++ b/ARCHITECTURE_QUICK_REFERENCE.md @@ -0,0 +1,357 @@ +# ObjectStack 项目架构规划 - 快速参考 +# ObjectStack Project Architecture Planning - Quick Reference + +**📅 创建日期 / Created**: 2026-01-30 + +--- + +## 📊 一图看懂 ObjectStack 生态系统架构 / ObjectStack Ecosystem Architecture at a Glance + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ObjectStack GitHub Organization │ +│ (objectstack-ai/*) │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ + ┌───────────────────────────┼───────────────────────────┐ + │ │ │ +┌───────▼────────┐ ┌────────▼────────┐ ┌────────▼────────┐ +│ 协议层 / Protocol │ │ 微内核层 / Microkernel │ │ 插件层 / Plugin │ +│ Layer (1 repo) │ │ Layer (6 repos) │ │ Layer (50+ repos)│ +└──────────────────┘ └──────────────────────┘ └──────────────────┘ +│ │ │ +│ • spec │ • core │ • Drivers (12+) +│ │ • objectql │ - driver-postgres +│ │ • runtime │ - driver-mysql +│ │ • client │ - driver-mongodb +│ │ • cli │ - driver-redis +│ │ • types │ - ... +│ │ │ +│ │ │ • Connectors (10+) +│ │ │ - connector-salesforce +│ │ │ - connector-slack +│ │ │ - connector-stripe +│ │ │ - ... +│ │ │ +│ │ │ • Plugins (15+) +│ │ │ - plugin-encryption +│ │ │ - plugin-cache +│ │ │ - plugin-multitenancy +│ │ │ - plugin-ai-agent +│ │ │ - ... +│ │ │ +│ │ │ • Server Adapters (8+) +│ │ │ - plugin-hono-server +│ │ │ - plugin-express-server +│ │ │ - plugin-nextjs-server +│ │ │ - ... +│ │ │ +│ │ │ • Templates (10+) +│ │ │ - template-crm +│ │ │ - template-helpdesk +│ │ │ - template-hr-system +│ │ │ - ... +│ │ │ +│ │ │ • Tools (5+) +│ │ │ - devtools +│ │ │ - vscode-extension +│ │ │ - migration-tool +│ │ │ - ... +``` + +--- + +## 🎯 核心数字 / Key Numbers + +| 指标 / Metric | 数量 / Count | +|---|:---:| +| **总仓库数 / Total Repositories** | **60+** | +| 核心仓库 / Core Repositories | 7 | +| 驱动仓库 / Driver Repositories | 12+ | +| 连接器仓库 / Connector Repositories | 10+ | +| 插件仓库 / Plugin Repositories | 15+ | +| 服务器插件 / Server Plugins | 8+ | +| 模板仓库 / Template Repositories | 10+ | +| 工具仓库 / Tool Repositories | 5+ | +| 文档与基础设施 / Docs & Infrastructure | 5+ | + +--- + +## 📚 文档导航 / Document Navigation + +| 文档 / Document | 用途 / Purpose | 阅读时间 / Reading Time | +|---|---|:---:| +| **[GITHUB_ORGANIZATION_STRUCTURE.md](./GITHUB_ORGANIZATION_STRUCTURE.md)** | 完整的仓库架构规划（英文） | 45 分钟 | +| **[GITHUB_ORGANIZATION_STRUCTURE_CN.md](./GITHUB_ORGANIZATION_STRUCTURE_CN.md)** | 完整的仓库架构规划（中文） | 45 分钟 | +| **[PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md](./PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md)** | 实施总结与行动计划（中英双语） | 20 分钟 | + +**推荐阅读顺序 / Recommended Reading Order**: +1. 快速参考（本文档）→ 5 分钟 +2. 实施总结 → 20 分钟 +3. 完整架构文档（根据需要选择中英文版本）→ 45 分钟 + +--- + +## 🚀 快速理解：7 大仓库分类 / Quick Understanding: 7 Repository Categories + +### 1️⃣ 核心仓库 / Core Repositories (7 个) + +**职责**: 定义协议、提供内核、运行时、客户端、工具 +**所有权**: 核心团队 +**稳定性**: 高 + +| 仓库 | 用途 | NPM 包 | +|---|---|---| +| `spec` | 协议定义 | `@objectstack/spec` | +| `core` | 微内核 | `@objectstack/core` | +| `objectql` | 查询引擎 | `@objectstack/objectql` | +| `runtime` | 运行时环境 | `@objectstack/runtime` | +| `client` | 客户端 SDK | `@objectstack/client` | +| `cli` | 命令行工具 | `@objectstack/cli` | +| `types` | 共享类型 | `@objectstack/types` | + +### 2️⃣ 驱动仓库 / Driver Repositories (12+个) + +**职责**: 数据库和数据源适配器 +**所有权**: 核心团队 + 社区 +**稳定性**: 中等 + +**SQL 驱动**: +- `driver-postgres` - PostgreSQL +- `driver-mysql` - MySQL/MariaDB +- `driver-sqlite` - SQLite +- `driver-mssql` - SQL Server +- `driver-oracle` - Oracle + +**NoSQL 驱动**: +- `driver-mongodb` - MongoDB +- `driver-redis` - Redis +- `driver-dynamodb` - DynamoDB + +**其他**: +- `driver-elasticsearch` - Elasticsearch +- `driver-meilisearch` - Meilisearch +- `driver-memcached` - Memcached +- `driver-memory` - In-memory (参考实现) + +### 3️⃣ 连接器仓库 / Connector Repositories (10+个) + +**职责**: SaaS 服务集成 +**所有权**: 社区 +**稳定性**: 可变 + +**CRM 系统**: +- `connector-salesforce` - Salesforce +- `connector-hubspot` - HubSpot + +**协作工具**: +- `connector-slack` - Slack +- `connector-teams` - Microsoft Teams + +**支付系统**: +- `connector-stripe` - Stripe + +**其他**: +- `connector-quickbooks` - QuickBooks (财务) +- `connector-sap` - SAP (ERP) +- `connector-workday` - Workday (HRIS) +- `connector-mailchimp` - Mailchimp (营销) +- `connector-xero` - Xero (财务) + +### 4️⃣ 服务插件仓库 / Service Plugin Repositories (15+个) + +**职责**: 核心功能增强 +**所有权**: 核心团队 +**稳定性**: 中到高 + +**安全插件**: +- `plugin-encryption` - 字段级加密 +- `plugin-masking` - PII 掩码 +- `plugin-compliance` - 合规工具包 + +**性能插件**: +- `plugin-cache` - 多层缓存 +- `plugin-fulltext-search` - 全文搜索 + +**多租户插件**: +- `plugin-multitenancy` - 租户隔离 + +**AI 插件**: +- `plugin-ai-agent` - AI 代理编排 +- `plugin-ai-rag` - RAG 管道 + +**工作流插件**: +- `plugin-workflow` - 高级工作流 +- `plugin-approval` - 审批流程 +- `plugin-notification` - 多渠道通知 + +**文件插件**: +- `plugin-file-storage` - 文件管理 + +**分析插件**: +- `plugin-analytics` - 商业智能 + +**可观测性插件**: +- `plugin-logging` - 结构化日志 +- `plugin-tracing` - 分布式追踪 + +### 5️⃣ 服务器插件仓库 / Server Plugin Repositories (8+个) + +**职责**: 服务器框架适配 +**所有权**: 核心团队 +**稳定性**: 高 + +| 仓库 | 框架 | 状态 | +|---|---|:---:| +| `plugin-hono-server` | Hono | 🟢 已存在 | +| `plugin-express-server` | Express | 🟡 计划中 | +| `plugin-fastify-server` | Fastify | 🟡 计划中 | +| `plugin-nestjs-server` | NestJS | 🟡 计划中 | +| `plugin-nextjs-server` | Next.js | 🟡 计划中 | +| `plugin-cloudflare-workers` | Cloudflare Workers | 🟡 计划中 | +| `plugin-aws-lambda` | AWS Lambda | 🟡 计划中 | +| `plugin-msw` | MSW (Mock) | 🟢 已存在 | + +### 6️⃣ 模板仓库 / Template Repositories (10+个) + +**职责**: 行业解决方案示例 +**所有权**: 社区 +**稳定性**: 可变 + +**企业应用**: +- `template-crm` - CRM 系统 +- `template-helpdesk` - 客户支持 +- `template-project-management` - 项目管理 +- `template-hr-system` - 人力资源 + +**行业应用**: +- `template-inventory` - 库存管理 +- `template-ecommerce` - 电子商务 +- `template-healthcare` - 医疗管理 +- `template-education` - 教育管理 + +**技术应用**: +- `template-iot-platform` - IoT 平台 +- `template-ai-saas` - AI SaaS + +### 7️⃣ 工具仓库 / Tool Repositories (5+个) + +**职责**: 开发工具 +**所有权**: 核心团队 +**稳定性**: 中等 + +- `devtools` - 浏览器开发工具 +- `vscode-extension` - VS Code 扩展 +- `jetbrains-plugin` - JetBrains 插件 +- `metadata-validator` - 元数据校验 +- `migration-tool` - 迁移工具 + +**文档与基础设施**: +- `docs` - 官方文档站点 +- `examples` - 示例应用 +- `awesome-objectstack` - 精选资源 +- `.github` - 组织级配置 +- `registry` - 插件注册中心 + +--- + +## 🗓️ 实施时间线 / Implementation Timeline + +``` +2026 Q1 (基础 / Foundation) +├─ 提取 7 个核心仓库 +├─ 建立 CI/CD 标准 +└─ 发布初版到 npm + +2026 Q2 (核心驱动与插件 / Core Drivers & Plugins) +├─ 创建 4 个数据库驱动 (PostgreSQL, MySQL, MongoDB, Redis) +├─ 创建 4 个核心插件 (Encryption, Masking, Multi-tenancy, Cache) +└─ 提取现有插件 (driver-memory, plugin-hono-server, plugin-msw) + +2026 Q3 (生态系统扩展 / Ecosystem Extension) +├─ 创建 3 个关键连接器 (Salesforce, Slack, Stripe) +├─ 创建 3 个服务器适配器 (Express, Fastify, Next.js) +└─ 启动社区贡献计划 + +2026 Q4 (模板与工具 / Templates & Tools) +├─ 创建 3 个行业模板 (CRM, Helpdesk, Project Management) +├─ 开发 3 个开发工具 (DevTools, VS Code Extension, Migration Tool) +└─ 建立插件注册中心 + +2027+ (规模化 / Scale) +├─ 扩展到 60+ 仓库 +├─ 建立合作伙伴生态 +└─ 企业版与商业化 +``` + +--- + +## 📊 成功指标 / Success Metrics + +### 2026 年目标 / 2026 Targets + +| 维度 / Dimension | Q2 | Q4 | +|---|:---:|:---:| +| 核心仓库 | 7 | 7 | +| 驱动仓库 | 5 | 8 | +| 插件仓库 | 5 | 10 | +| 连接器仓库 | 3 | 8 | +| 模板仓库 | 2 | 5 | +| 社区贡献者 | 10 | 30 | +| GitHub Stars | 500 | 2,000 | +| NPM 周下载 | 1,000 | 10,000 | + +### 2027 年目标 / 2027 Targets + +| 维度 / Dimension | 目标 / Target | +|---|:---:| +| 总仓库数 | 60+ | +| 社区贡献者 | 100+ | +| GitHub Stars | 5,000+ | +| NPM 周下载 | 50,000+ | +| 生产部署 | 100+ | + +--- + +## ✅ 立即行动 / Immediate Actions + +### 本周 / This Week + +- [ ] 审查 GitHub 组织架构文档 +- [ ] 讨论并确认仓库分类和命名 +- [ ] 准备 GitHub 组织基础设施 +- [ ] 启动 RFC: Monorepo to Multi-repo Migration + +### 本月 / This Month (Q1 2026) + +- [ ] 提取第一个核心仓库 (core) +- [ ] 建立仓库模板和 CI/CD 标准 +- [ ] 发布核心包到 npm +- [ ] 更新文档和示例 + +--- + +## 🎓 参考最佳实践 / Reference Best Practices + +ObjectStack 借鉴了以下生态系统的最佳实践: + +| 生态系统 / Ecosystem | 借鉴要点 / Key Learnings | +|---|---| +| **Kubernetes** | 核心与扩展分离、CRD 模式、社区治理 | +| **Salesforce** | AppExchange 市场、元数据驱动、多租户 | +| **VS Code** | 扩展市场、Extension API、配置系统 | +| **Prisma** | Schema-first、类型安全、多数据库支持 | + +--- + +## 📞 获取帮助 / Get Help + +- **完整文档**: [GITHUB_ORGANIZATION_STRUCTURE.md](./GITHUB_ORGANIZATION_STRUCTURE.md) +- **实施总结**: [PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md](./PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md) +- **问题反馈**: 在 `objectstack-ai/spec` 仓库创建 issue +- **讨论**: GitHub Discussions (启用后) + +--- + +**最后更新 / Last Updated**: 2026-01-30 +**文档维护 / Maintained By**: ObjectStack 核心团队 diff --git a/README.md b/README.md index 032cd3ab53e..586e0be9bd9 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ pnpm docs:dev ## 🏗️ Architecture & Planning **Strategic Planning Documents:** +- **[Quick Reference](./ARCHITECTURE_QUICK_REFERENCE.md)** - Visual overview of the 60+ repository ecosystem ⭐ **Start Here!** - **[GitHub Organization Structure](./GITHUB_ORGANIZATION_STRUCTURE.md)** ([中文版](./GITHUB_ORGANIZATION_STRUCTURE_CN.md)) - Complete repository architecture for the ObjectStack ecosystem - **[Implementation Summary](./PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md)** - Summary of architecture planning and next steps - **[Transformation Plan V2](./TRANSFORMATION_PLAN_V2.md)** - 12-month protocol development roadmap