增强钩子上下文，支持在更新和删除操作中访问先前数据

hotlong · hotlong · commit 5ae3f106d467 · 2026-01-11T01:19:44.000+08:00
diff --git a/docs/guide/logic-hooks.md b/docs/guide/logic-hooks.md
@@ -1,74 +1,184 @@
-# Logic: Hooks (Triggers)
+# Logic Hooks
 
-Hooks allow you to inject business logic into the database lifecycle. They are powerful, typed, and context-aware.
+Hooks (often called "Triggers" in SQL databases) allow you to intercept database operations to inject custom logic. They are transaction-aware and fully typed.
 
-## 1. File Structure
-Hooks live in `*.hook.ts` files alongside your object definitions. The loader automatically binds them based on the filename.
+## 1. Registration Methods
 
-*   `objects/todo.object.yml`
-*   `objects/todo.hook.ts`
+You can define hooks in two ways: **File-based** (Static) or **Programmatic** (Dynamic).
 
-## 2. Defining Hooks
+### A. File-based (Recommended)
+Place a `*.hook.ts` file next to your object definition. The loader automatically discovers it.
 
-Export a default object that satisfies the `ObjectHookDefinition<T>` interface.
+**File:** `src/objects/project.hook.ts`
 
 ```typescript
-// objects/todo.hook.ts
 import { ObjectHookDefinition } from '@objectql/types';
-import { Todo } from './types'; // Generated types
-
-const hooks: ObjectHookDefinition<Todo> = {
-    
-    // Validate data before insertion
-    beforeCreate: async ({ data, user }) => {
-        if (!data.title) {
-            throw new Error("Title is required");
-        }
-        data.owner_id = user?.id;
-    },
 
-    // Check state changes before update
-    // 'previousData' is automatically fetched for you!
-    beforeUpdate: async ({ id, data, previousData, isModified }) => {
-        if (isModified('status')) {
-             if (previousData.status === 'Archived') {
-                 throw new Error("Cannot modify archived todos");
-             }
-        }
+const hooks: ObjectHookDefinition = {
+    beforeCreate: async (ctx) => {
+        // ...
     },
-
-    // Side-effects after successful commitment
-    afterCreate: async ({ result, api }) => {
-        await api.create('log', {
-            message: `New Todo Created: ${result.title}`
-        });
+    afterUpdate: async (ctx) => {
+        // ...
     }
-}
+};
 
 export default hooks;
 ```
 
+### B. Programmatic (Dynamic)
+Use the `app.on()` API, typically inside a [Plugin](./plugins.md).
+
+```typescript
+app.on('before:create', 'project', async (ctx) => {
+    // ...
+});
+
+// Wildcard listener
+app.on('after:delete', '*', async (ctx) => {
+    console.log(`Object ${ctx.objectName} deleted record ${ctx.id}`);
+});
+```
+
+## 2. Event Lifecycle
+
+| Event Name | Description | Common Use Case |
+| :--- | :--- | :--- |
+| `before:create` | Before inserting a new record. | Validation, Default Values, ID generation. |
+| `after:create` | After insertion is committed. | Notifications, downstream sync. |
+| `before:update` | Before modifying an existing record. | Permission checks, Immutable field protection. |
+| `after:update` | After modification is committed. | Audit logging, history tracking. |
+| `before:delete` | Before removing a record. | Referential integrity checks. |
+| `after:delete` | After removal is committed. | Clean up related resources (e.g. S3 files). |
+| `before:find` | Before executing a query. | **Row-Level Security (RLS)**, Force filters. |
+| `after:find` | After fetching results. | Decryption, Sensitive data masking. |
+
 ## 3. The Hook Context
 
-The context passed to your function is **Operation-Specific**.
+The context object (`ctx`) changes based on the event type.
+
+### Common Properties (Available Everywhere)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `objectName` | `string` | The name of the object being operated on. |
+| `user` | `ObjectQLUser` | Current user session/context. |
+| `broker` | `IStation` | (If Microservices enabled) Station broker instance. |
+
+### Mutation Context (Create/Update/Delete)
+
+| Property | Type | Available In | Description |
+| :--- | :--- | :--- | :--- |
+| `data` | `Any` | Create/Update | The data payload being written. **Mutable**. |
+| `id` | `string` | Update/Delete | The ID of the record being acted upon. |
+| `previousData` | `Any` | Update/Delete | The existing record fetched from DB before operation. |
+| `result` | `Any` | After * | The final result returned from the driver. |
 
-| Property | Available In | Description |
+### Query Context (Find)
+
+| Property | Type | Description |
 | :--- | :--- | :--- |
-| `api` | All | Restricted driver API to perform DB operations (`find`, `create`, etc). |
-| `user` | All | The current user session. |
-| `state` | All | Shared storage to pass data from `before` -> `after` hooks. |
-| `data` | Create/Update | The payload being written. |
-| `previousData` | Update | The record as it exists in DB *before* this update. |
-| `isModified(field)`| Update | Helper to check if a field is changing. |
-| `query` | Find/Count | The query AST. Useful for row-level security. |
+| `query` | `steedos-filters` | The query AST (filters, fields, sort). **Mutable**. |
+| `result` | `Any[]` | (After Find) The array of records found. **Mutable**. |
+
+## 4. Common Patterns & Examples
 
-### Row-Level Security Example
+### A. Validation & Default Values
+Throwing an error inside a `before` hook aborts the transaction.
+
+```typescript
+beforeCreate: async ({ data, user }) => {
+    if (data.amount < 0) {
+        throw new Error("Amount cannot be negative");
+    }
+    // Set default owner if not provided
+    if (!data.owner) {
+        data.owner = user.userId;
+    }
+}
+```
+
+### B. Immutable Fields Protection
+Prevent users from changing critical fields during update.
+
+```typescript
+beforeUpdate: async ({ data, previousData }) => {
+    if (data.code !== undefined && data.code !== previousData.code) {
+        throw new Error("Cannot change project code once created.");
+    }
+}
+```
+
+### C. Row-Level Security (RLS)
+The most secure place to enforce permissions is `before:find`. This injects filters into *every* query (API, GraphQL, or internal).
 
 ```typescript
 beforeFind: async ({ query, user }) => {
-    // Forcefully filter all queries to only show user's own data
-    if (!user.isAdmin) {
-        query.filters.push(['owner_id', '=', user.id]);
+    if (!user.is_admin) {
+        // Enforce: owners can only see their own records
+        // Merging into existing filters
+        query.filters = [
+            (query.filters || []), 
+            ['owner', '=', user.userId]
+        ];
     }
 }
 ```
+
+### D. Side Effects (Notifications)
+Use `after` hooks for logic that strictly relies on success.
+
+```typescript
+afterCreate: async ({ data, objectName }) => {
+    await NotificationService.send({
+        to: data.owner,
+        message: `New ${objectName} created.`
+    });
+}
+```
+
+### E. Result Masking
+Hide sensitive fields based on rules.
+
+```typescript
+afterFind: async ({ result, user }) => {
+    if (!user.has_permission('view_salary')) {
+        result.forEach(record => {
+            delete record.salary;
+            delete record.bonus;
+        });
+    }
+}
+```
+
+### F. Auto-Numbering / ID Generation
+Generate complex business keys.
+
+```typescript
+beforeCreate: async ({ data }) => {
+    if (!data.code) {
+        data.code = await SequenceService.next('PROJECT_CODE');
+    }
+}
+```
+
+### G. Conditional Deletion
+Use `previousData` in delete hooks to prevent deleting records based on their state.
+
+```typescript
+beforeDelete: async ({ previousData, user }) => {
+    // Prevent deletion if project is active
+    if (previousData.status === 'active') {
+         throw new Error("Cannot delete an active project. Archive it first.");
+    }
+}
+```
+
+## 5. Transaction Safety
+
+Hooks participate in the database transaction.
+*   If a `before` hook throws -> The DB operation is never executed.
+*   If the DB operation fails -> `after` hooks are never executed.
+*   If an `after` hook throws -> **The entire transaction rolls back** (including the DB write).
+
+> **Tip:** If you want a "Fire and Forget" action that shouldn't rollback the transaction (e.g. sending an email), wrap your logic in a `try/catch` or execute it without `await`.
diff --git a/packages/core/src/repository.ts b/packages/core/src/repository.ts
@@ -122,6 +122,7 @@ export class ObjectRepository {
     }
 
     async update(id: string | number, doc: any, options?: any): Promise<any> {
+        const previousData = await this.findOne(id);
         const hookCtx: UpdateHookContext = {
             ...this.context,
             objectName: this.objectName,
@@ -130,6 +131,7 @@ export class ObjectRepository {
             api: this.getHookAPI(),
             id,
             data: doc,
+            previousData,
             isModified: (field) => hookCtx.data ? Object.prototype.hasOwnProperty.call(hookCtx.data, field) : false
         };
         await this.app.triggerHook('beforeUpdate', this.objectName, hookCtx);
@@ -142,13 +144,15 @@ export class ObjectRepository {
     }
 
     async delete(id: string | number): Promise<any> {
+        const previousData = await this.findOne(id);
         const hookCtx: MutationHookContext = {
             ...this.context,
             objectName: this.objectName,
             operation: 'delete',
             state: {},
             api: this.getHookAPI(),
-            id
+            id,
+            previousData
         };
         await this.app.triggerHook('beforeDelete', this.objectName, hookCtx);
 
diff --git a/packages/types/src/hook.ts b/packages/types/src/hook.ts
@@ -85,6 +85,12 @@ export interface MutationHookContext<T = any> extends BaseHookContext<T> {
      * Only available in 'after' hooks.
      */
     result?: T;
+
+    /**
+     * The existing record fetched from DB before operation.
+     * Available in 'update' and 'delete' hooks.
+     */
+    previousData?: T;
 }
 
 /**
@@ -93,13 +99,6 @@ export interface MutationHookContext<T = any> extends BaseHookContext<T> {
 export interface UpdateHookContext<T = any> extends MutationHookContext<T> {
     operation: 'update';
     
-    /** 
-     * The record state BEFORE the update.
-     * Useful for comparison logic (e.g. status changed from A to B).
-     * Note: This may require a pre-fetch lookup depending on engine configuration.
-     */
-    previousData?: T;
-    
     /**
      * Helper to check if a specific field is being modified.
      * Checks if the field exists in 'data' AND is different from 'previousData'.
