Add ObjectStack Enterprise Framework documentation for Phase 1

[Copilot]

Documents the "Metadata as Code" development model for ObjectStack - a Git-centric, TypeScript-first alternative to visual configuration interfaces targeting professional development teams.

Architecture Documentation

Enterprise Framework Concept (concepts/enterprise-framework.mdx)

• Three-layer architecture: Creator (SDK/CLI) → Governance (CI/CD) → Execution (Kernel)
• Git repository as single source of truth
• Build-time metadata extraction and compilation workflow
• Bilingual (EN/CN)

Technical Specifications

SDK Reference (specifications/sdk/)

• TypeScript API for defineObject, field types, triggers, permissions
• Type-safe metadata definitions with full IntelliSense
• Compilation model: TS code → ObjectQL JSON protocols

CLI Reference (specifications/cli/)

• Complete command reference: init, generate, build, dev, migrate, deploy
• CI/CD integration patterns (GitHub Actions, GitLab)
• Configuration schema

Deployment Guide (specifications/deployment/)

• Docker/Kubernetes manifests
• Cloud platforms: AWS ECS/Fargate, GCP Cloud Run, Azure ACI
• Zero-downtime migration strategies
• HPA and resource scaling patterns

Example: Metadata as Code

// src/objects/contract.ts
import { defineObject, Field } from '@objectstack/sdk';

export const Contract = defineObject({
  name: 'contract',
  fields: {
    amount: Field.Currency({ precision: 18, scale: 2 }),
    status: Field.Select({ options: ['draft', 'signed'] })
  },
  triggers: {
    beforeInsert: async ({ doc }) => {
      if (doc.amount < 0) throw new Error("Invalid amount");
    }
  },
  permissions: {
    create: ['sales', 'admin'],
    update: ['admin']
  }
});

On git push, the build pipeline extracts metadata, generates migrations, and packages the runtime artifact (Docker/NPM).

Navigation

Updated meta.json files to integrate new documentation into site hierarchy under Concepts and Specifications sections.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>ObjectStack Enterprise Framework</issue_title>
<issue_description># ObjectStack Enterprise Framework

Phase 1: The Code-Driven Metadata Engine

"定义即应用 (Definition is Application)"

---

1. 核心理念 (Core Philosophy)

在第一阶段，我们将 ObjectStack 定义为**“面向专业开发者的企业级应用元框架”**。

• 没有黑盒: 所有的业务定义都在本地代码中，基于 TypeScript，清晰透明。
• Git 为中心: 使用 Git 仓库作为唯一真理来源 (Single Source of Truth)。
• 自带基建: 开发者只负责写“业务描述”，框架负责“数据库迁移、API 生成、界面渲染”。

---

2. 架构全景图 (The Architecture)

在这个阶段，我们不需要画复杂的云端图，而是画一张**“编译与运行时”**的流程图。

A. 创造层：ObjectStack SDK (The Creator)

"在 IDE 中定义世界"

开发者不再需要登录网页后台配置，而是直接在 VS Code 中工作。

• ObjectStack CLI: 命令行工具，用于快速生成代码模版。

• ostack init: 初始化标准项目结构。

• ostack g resource contract: 生成“合同”模块的标准目录。

• Metadata as Code (基于代码的元数据):

• 我们利用 TypeScript 的静态类型能力来定义元数据。

• Schema: 使用类似 Zod 或 TypeORM 的语法定义数据结构。

• Logic: 直接编写 TS 函数作为 Trigger。

• UI: 使用 JSON 或 TS 对象描述界面布局（通过我们提供的类型提示）。

代码示例:

// src/objects/contract.ts
import { defineObject, Field } from '@objectstack/sdk';

export const Contract = defineObject({
name: 'contract',
label: '销售合同',
fields: {
title: Field.String({ label: '标题', required: true }),
amount: Field.Currency({ label: '金额' }),
status: Field.Select({ options: ['draft', 'signed'] })
},
// 触发器逻辑直接写在这里
triggers: {
beforeInsert: async ({ doc }) => {
if (doc.amount < 0) throw new Error("金额不能为负");
}
}
});

B. 治理层：CI/CD Pipeline (The Compiler)

"Git 仓库即控制台"

没有 Hub，Git Repository 就是 Hub。

• 构建时编排 (Build-Time Composition):

• 当代码提交时，ObjectStack 的构建工具（基于 Vite 或 Rollup）会扫描所有 .ts 文件。

• Extract: 提取其中的元数据定义（Schema/UI）。

• Compile: 将后端逻辑编译为优化的 JS 包。

• Bundle: 将这些打包成一个不可变的 Artifact (制品)。

• 版本管理:

• 利用 Git Tag 管理版本（v1.0, v1.1）。

• 利用 Pull Request 进行变更审批。

C. 执行层：ObjectStack Kernel (The Runtime)

"自带动力的单体引擎"

这是交付给客户的核心。它是一个标准的 Docker 镜像 或 NPM 包，客户将其部署在自己的服务器上。

这个 Kernel 包含了你尚未拆分的“三位一体”引擎：

1. ObjectQL (Auto-Migration):

• 应用启动时，Kernel 读取打包好的 Metadata。
• 自动同步 DB: 发现 Contract 对象多了 amount 字段 -> 自动对 Postgres 执行 ALTER TABLE。
• 自动生成 API: 自动挂载 GraphQL/REST 端点 /api/data/contract。

2. ObjectOS (Logic Sandbox):

• 负责加载并执行开发者编写的 triggers 函数。

3. ObjectUI (Renderer API):

• 向前端（React/Vue 客户端）提供 schema.json。
• Amis 集成: 如果使用 Amis，这里直接输出 Amis 标准的 JSON 配置，前端直接渲染。

---

3. 落地工作流 (Implementation Workflow)

这是客户采用该方案时的标准作业流程（SOP）：

步骤	角色	动作	产物
1. 初始化	架构师	npm create objectstack-app my-erp	包含核心依赖的 Git 仓库
2. 开发	开发者	编写 .ts 文件定义对象、逻辑和界面	源代码 (Source Code)
3. 提交	开发者	git push origin main	触发 CI 构建
4. 构建	CI Server	运行 ostack build	Docker Image (包含 Kernel + 业务代码)
5. 部署	运维	docker run -d my-erp:latest	运行中的企业应用
6. 迭代	全员	修改代码 -> Push -> 自动热更新	持续交付

---

4. 商业模式与交付物 (Deliverables)

在 Phase 1，你交付给客户的是一套 “开发底座”。

核心交付物清单:

1. @objectstack/cli: 命令行工具 (NPM)。
2. @objectstack/core: 核心运行时依赖 (包含 ObjectQL/OS/UI 的逻辑)。
3. Standard Template: 标准的企业级项目脚手架。
4. Documentation: 详细的 API 文档和最佳实践指南。

卖点话术:

• "不被厂商绑定": 代码在你们自己手里，Git 仓库在你们自己服务器上。
• "零技术债务": 你们只写业务逻辑，底层脏活累活（数据库连接、API 封装、权限校验）全部由框架处理。
• "类型安全": 全链路 TypeScript 支持，重构不再火葬场。

这就是 ObjectStack Enterprise Framework。
Code it locally. Run it globally.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes ObjectStack Enterprise Framework #51

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
docs	Ready	Preview, Comment	Jan 22, 2026 3:29am

[github-actions]

🚀 Preview Deployment

This pull request will be automatically deployed to Vercel.

Preview Links

• 📝 Documentation: Will be available once Vercel deployment completes
• 🌍 Languages: English (/en/docs) and Chinese (/cn/docs)

Build Status

Check the CI workflow for build status and any errors.

---

Automated preview information for PR #52

[hotlong]

@copilot 基于这个框架设定的目标重构整个文档

[Copilot]

Pull request overview

This pull request adds comprehensive Phase 1 documentation for the ObjectStack Enterprise Framework, introducing a "Metadata as Code" development model. The documentation targets professional development teams and presents ObjectStack as a code-driven alternative to visual configuration interfaces, with Git as the single source of truth and TypeScript as the primary development language.

Changes:

• Introduces the Enterprise Framework concept with bilingual (EN/CN) documentation explaining the three-layer architecture (Creator/SDK → Governance/CI-CD → Execution/Kernel)
• Adds detailed SDK specification documenting TypeScript APIs for defining business objects, triggers, permissions, and field types
• Adds comprehensive CLI reference covering all commands (init, generate, build, dev, migrate, deploy) with CI/CD integration patterns
• Adds deployment guide with Docker, Kubernetes, and cloud platform (AWS/GCP/Azure) deployment strategies
• Updates navigation structure to integrate new documentation sections

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
content/docs/concepts/enterprise-framework.mdx	English version of the enterprise framework concept documentation with architecture diagrams and workflow examples
content/docs/concepts/enterprise-framework.cn.mdx	Chinese version of the enterprise framework concept documentation (bilingual support)
content/docs/concepts/meta.json	Updated to include the new enterprise-framework page in the concepts navigation
content/docs/specifications/sdk/index.mdx	Complete SDK API reference with TypeScript interfaces, field types, triggers, and permissions
content/docs/specifications/sdk/meta.json	Navigation structure for SDK documentation
content/docs/specifications/cli/index.mdx	Full CLI command reference with usage examples and CI/CD integration patterns
content/docs/specifications/cli/meta.json	Navigation structure for CLI documentation
content/docs/specifications/deployment/index.mdx	Comprehensive deployment guide covering Docker, Kubernetes, and cloud platforms
content/docs/specifications/deployment/meta.json	Navigation structure for deployment documentation
content/docs/specifications/meta.json	Updated to add SDK, CLI, and deployment sections before existing ObjectQL/UI/OS specs

[Copilot]

The link reference to 'guides/best-practices' doesn't exist in the repository. The guides directory is not present in the codebase. Either remove this link or create placeholder documentation for this guide.

Suggested change

* **[Best Practices](../../guides/best-practices)**: Development guidelines

[Copilot]

The link reference to './migrations' (Migration Guide) doesn't exist in the specifications directory. There is no migrations subdirectory or index file. Either remove this link or create the corresponding documentation.

Suggested change

	* **[Migration Guide](./migrations)**: Handle database schema changes
	* **Migration Guide (planned)**: Handle database schema changes

[Copilot]

Incorrect relative path for CLI Reference link. The link uses './cli' but should be '../cli' since the CLI documentation is at the same level as the SDK directory (both under specifications/), not inside the SDK directory.

Suggested change

	* **[CLI Reference](./cli)**: Learn how to use the ObjectStack CLI
	* **[CLI Reference](../cli)**: Learn how to use the ObjectStack CLI

[Copilot]

Incorrect relative path for Deployment Guide link. The link uses './deployment' but should be '../deployment' since the deployment documentation is at the same level as the SDK directory (both under specifications/), not inside the SDK directory.

Suggested change

	* **[Deployment Guide](./deployment)**: Deploy your application
	* **[Deployment Guide](../deployment)**: Deploy your application

[Copilot]

Inconsistency between English and Chinese versions: In the English version, the amount field has required: false, but in the Chinese version it's missing this property entirely. The English version explicitly states required: false while the Chinese version defaults to no required constraint. These should match for consistency across bilingual documentation.

Suggested change

	label: '金额',
	label: '金额',
	required: false,

[Copilot]

The link references to guides that don't exist in the repository: 'guides/security', 'guides/monitoring', and 'guides/backup'. These directories are not present in the codebase. Either remove these links or create placeholder documentation for these guides.

Suggested change

	* **[Security Guide](../../guides/security)**: Secure your deployment
	* **[Monitoring Guide](../../guides/monitoring)**: Set up comprehensive monitoring
	* **[Backup & Recovery](../../guides/backup)**: Data protection strategies
	* **Security Guide**: Secure your deployment
	* **Monitoring Guide**: Set up comprehensive monitoring
	* **Backup & Recovery**: Data protection strategies

[Copilot]

The generated Dockerfile runs the Node.js application as root because no non-root USER is configured, which is risky for production deployments. If an attacker gains remote code execution in the container (through a framework or app vulnerability), running as root significantly increases the impact by making container breakout and host resource access easier. Adjust the Docker image to drop privileges and run the runtime under a dedicated non-root user to reduce the blast radius of any compromise.