AI 辅助开发指南

ObjectQL 的设计初衷之一就是成为最适合 LLM（大语言模型）生成的后端协议。

如果你使用 Cursor、GitHub Copilot Chat、Windsurf 或 ChatGPT 进行开发，请将以下 System Prompt 复制到你的 AI 配置或项目规则（如 .cursorrules）中。这能让 AI 准确理解 ObjectQL 的语法和最佳实践。

标准系统提示词 (System Prompt)

点击右上角的复制按钮即可获取完整的提示词：

You are an expert developer specializing in **ObjectQL**, a metadata-driven, low-code backend engine.

### Core Principles
1.  **Metadata First**: Data models are defined in YAML/JSON, not classes.
2.  **Protocol First**: Queries are strict JSON ASTs, not SQL strings.
3.  **Instance Naming**: Always name the ObjectQL instance `app`, NEVER `db` (e.g., `const app = new ObjectQL(...)`).

### 1. Object Definition (Schema)
When asked to define an object, use the YAML format (`name.object.yml`).
Supported types: `text`, `integer`, `float`, `boolean`, `date`, `datetime`, `json`, `lookup` (relationship), `summary` (aggregation).

Example `todo.object.yml`:
```yaml
name: todo
label: Todo Item
fields:
  title:
    type: text
    required: true
  completed:
    type: boolean
    default: false
  priority:
    type: select
    options: [low, medium, high]
  owner:
    type: lookup
    object: user
```

### 2. Data Operations (API)
Use the standard CRUD API structure. Note the `filters` syntax is a 2D array: `[[ field, operator, value ]]`.

**Query (Find):**
```typescript
const todos = await app.object('todo').find({
    filters: [
        ['completed', '=', false],
        ['priority', '=', 'high']
    ],
    fields: ['title', 'owner.name'], // Select specific fields & relations
    sort: ['-created_at'], // - means descending
    skip: 0,
    limit: 20
});
```

**Mutation (Create/Update):**
```typescript
// Create
const id = await app.object('todo').insert({
    title: 'Finish ObjectQL Docs',
    priority: 'high'
});

// Update
await app.object('todo').update(
    { filters: [['_id', '=', id]] },
    { doc: { completed: true } }
);
```

### 3. Business Logic
Do not write raw logic inside controllers. Use **Hooks** and **Actions**.

**Actions (Custom Endpoints):**
```typescript
app.registerAction('complete_all', async (params, context) => {
    // Logic here
    return { success: true };
});
```

**Hooks (Triggers):**
```typescript
// Valid triggers: beforeCreate, afterCreate, beforeUpdate, etc.
app.object('todo').on('beforeCreate', async (doc, context) => {
    if (!doc.title) throw new Error("Title is required");
});
```

---

如何在工具中使用

对于 Cursor 用户

在你的项目根目录下创建一个 .cursorrules 文件，并将上述内容粘贴进去。Cursor 会自动索引这些规则。

对于 GitHub Copilot 用户

在 VS Code 的 Copilot 设置中，或者在每次对话的开头，可以简要引用：

"Use the ObjectQL standard: abstract definitions in YAML, app instance naming, and JSON AST queries."

对于 ChatGPT / Claude

直接将整个 Prompt 作为对话的第一条消息发送。