draftgo-cli 3.0.1 → 3.0.29

package/resources/skill/specs/custom-services.md

@@ -0,0 +1,199 @@
+---
+read_when: 编写、修改、调试或评审自定义服务时；使用服务 SDK、路由、事件、定时任务或服务依赖时
+---
+
+# Go 自定义服务契约
+
+DraftGo 的新自定义服务使用 Go。服务代码是完整的 `package main`，可以使用标准库和 `go.mod` 中声明的第三方库。平台在保存或发布时编译服务、运行 `Register` 并保存触发器清单；执行时在独立子进程中调用选定 handler。
+
+平台 SDK 的固定导入路径是 `draftgo/sdk`。它是 DraftGo 构建器注入的本地 module，不从 GitHub 或其他网络仓库下载，也不要在服务的 `go.mod` 中自行添加或 `replace` 此依赖。
+
+## 最小服务
+
+```go
+package main
+
+import "draftgo/sdk"
+
+func Register(app *sdk.App) {
+	app.Route("GET", "/health", health)
+	app.On("order.paid", afterPaid)
+	app.Schedule("0 9 * * 1-5", weekdayReport)
+}
+
+func health(ctx *sdk.Context) (any, error) {
+	return ctx.Respond(map[string]any{"ok": true}, 200, nil), nil
+}
+
+func afterPaid(ctx *sdk.Context) (any, error) {
+	ctx.Log.Info("order paid event received")
+	return nil, nil
+}
+
+func weekdayReport(ctx *sdk.Context) (any, error) { return nil, nil }
+```
+
+`Register` 必须没有业务副作用。它只注册 handler；网络请求、写数据库、发通知等操作放在 handler 内。
+
+## 本地资源
+
+```text
+.draftgo/custom_scripts/
+├── index.json
+└── script_<id>_<slug>.go
+```
+
+`index.json` 的 Go 服务字段：
+
+```json
+{
+  "name": "order-service",
+  "slug": "order-service",
+	"mode": "mixed",
+  "code_file": ".draftgo/custom_scripts/script_new_order-service.go",
+  "go_mod": "module example.com/order-service\n\ngo 1.26.0\n\nrequire github.com/google/uuid v1.6.0\n",
+  "go_sum": ""
+}
+```
+
+- 新服务使用 `mode=mixed`，允许同一个 `Register` 同时注册 route、event 和 scheduled。旧服务可继续使用单一 `route`、`event` 或 `scheduled` mode。
+- `go_mod` 和可选的 `go_sum` 随服务版本保存并由 `draftgo push custom_scripts` 推送。
+- 新依赖应锁定明确版本。构建错误会在保存/发布时返回，不会替换当前有效清单。
+
+## 触发器
+
+### Route
+
+```go
+func Register(app *sdk.App) {
+	app.Route("POST", "/orders", createOrder)
+}
+
+func createOrder(ctx *sdk.Context) (any, error) {
+	body, _ := ctx.Input["body"].(map[string]any)
+	return ctx.Respond(body, 201, nil), nil
+}
+```
+
+`slug=commerce` 时地址为 `POST /api/x/commerce/orders`。Route 精确匹配，不支持 `/orders/{id}` 模板；ID 使用 query 或 body。
+
+`ctx.Input` 的 Route 字段：`method`、`headers`、`body`、`query_params`、`path_params`。当前身份通过 `ctx.Auth.CurrentUser()` 获取，入站请求头通过 `ctx.Headers.Get("Authorization")` 等读取。
+
+Route 默认以请求调用者身份访问 `draftgo.DB`、`draftgo.Users` 和其他平台能力。服务由管理员创建、拥有 `scripts:*` 管理权限，或在请求中收到 SAT，都不会让普通 SDK 调用自动提升；`draftgo.Auth.RequireAdmin()` 也只检查当前调用者。
+
+可信服务需要管理员权限时，逐次显式使用 `draftgo.Admin.*`。这不是服务配置项，也不需要 `admin_access` 开关：调用 `Admin` 就是管理员调用声明。运行时为**这一次**平台 SDK 调用注入管理员身份，并把服务、版本、真实调用者、操作、资源和结果写进该次执行的审计日志；SAT、数据库连接和管理员凭据不会暴露给服务代码。
+
+```go
+func catalog(draftgo *sdk.Context) (any, error) {
+	// 继承调用者权限
+	owned, err := draftgo.DB.Query("order", sdk.QueryOptions{})
+	if err != nil { return nil, err }
+
+	// 显式管理员权限；仅此调用提升
+	internal, err := draftgo.Admin.DB.Query("internal_catalog", sdk.QueryOptions{})
+	if err != nil { return nil, err }
+
+	return draftgo.Respond(map[string]any{
+		"orders": owned.Items,
+		"catalog": internal.Items, // 生产代码应再按客户端可见字段组装
+	}, 200, nil)
+}
+```
+
+`draftgo.Admin` 提供与普通 SDK 对齐的 `DB`、`Users`、`Auth`、`Notify`、`HTTP`、`Cache`、`Config`、`AIHub` 能力。它等价于管理员在平台拥有的权限，不做资源级白名单；因此只能授予可信服务编辑者，并且 Route 返回值仍必须由代码负责脱敏。
+
+### Event
+
+```go
+app.On("user.registered", welcome)
+
+func welcome(ctx *sdk.Context) (any, error) {
+	payload, _ := ctx.Input["payload"].(map[string]any)
+	ctx.Log.Info("registered user: " + fmt.Sprint(payload["user_id"]))
+	return nil, nil
+}
+```
+
+事件异步且不阻塞原请求。事件输入含 `event`、`timestamp`、`payload`。
+
+事件 `payload` 含 `user_id` 或 `actor_user_id` 且该用户仍存在时，handler 继承该用户身份；无法解析用户时才以系统身份执行。事件服务应把事件数据视为业务输入，而不是把它当成绕过资源权限的通道。
+
+### Scheduled
+
+```go
+app.Schedule("0 2 * * *", cleanup)
+```
+
+cron 使用五字段表达式，也支持 `interval:5m`。定时 handler 的 `ctx.Input` 为空对象。
+
+定时任务没有调用者，会以系统身份执行。因此它只能由可信编辑者维护，写入范围应限制在明确的数据类型，并在 handler 中记录可审计的业务日志。
+
+## 平台 SDK
+
+所有资源访问经受控 RPC 返回 Go 主服务。不要自行读取数据库连接、服务 token 或宿主机环境变量。
+
+```go
+record, err := ctx.DB.Create("order", map[string]any{"title": "DraftGo"})
+records, err := ctx.DB.Query("order", sdk.QueryOptions{
+	Filters: map[string]any{"status": "paid"},
+	Page: 1, PageSize: 20, OrderBy: "id", Order: "desc",
+})
+
+user, err := ctx.Users.Get(12)
+err = ctx.Auth.RequireLogin()
+err = ctx.Notify.Send(12, "完成", "订单已创建", "info")
+
+cached, err := ctx.Cache.Get("daily-report")
+err = ctx.Cache.Set("daily-report", map[string]any{"ok": true}, time.Hour)
+
+value, err := ctx.Config.Get("feature_flag", false)
+response, err := ctx.HTTP.Get(ctx.Context(), "https://api.example.com/health", nil, 10*time.Second)
+
+reply, err := ctx.AIHub.Chat(ctx.Context(), sdk.AIChatRequest{AgentID: 12, Message: "总结订单"})
+ctx.Log.Info("service completed")
+```
+
+`ctx.DB` 支持 `Create`、`CreateMany`、`Get`、`Update`、`UpdateMany`、`Delete`、`Query`。`Query` 返回 `sdk.QueryResult{Items, Total, Page, PageSize}`。
+
+`ctx.Users` 支持 `Get`、`List`、`Update`。`ctx.Auth` 支持 `RequireLogin`、`RequireAdmin`、`RequireRole`、`CurrentUser`。
+
+`ctx.HTTP` 支持 `Get`、`Post`、`Put`、`Patch`、`Delete`；响应为 `sdk.HTTPResponse{StatusCode, Headers, Data}`。服务可使用 `config.http_allowed_hosts` 限制出站目标；HTTP timeout 最终限制为 1-30 秒，响应体最大 5 MB。
+
+`ctx.AIHub.Chat` 与 `ctx.AIHub.GenerateImage` 使用已配置的 Agent。AIHub 权限仍受服务配置与调用身份控制。
+
+日志每次执行最多 500 条、单条最多 4096 字符。不要记录 token、Cookie、密码或完整个人信息。
+
+## 权限与运行限制
+
+- `scripts:read/create/update/delete/execute` 控制可信人员管理服务。
+- Route 调用者仍由服务 `permission` 与 `config.route_security` 控制；管理权限不绕过 Route 调用权限。
+- Route 的普通 SDK 数据访问继承调用者权限；不要把“管理员创建服务”误写成自动提升。只有显式 `draftgo.Admin.*` 调用才以管理员执行并记录审计；定时任务和无可解析用户的事件是系统身份例外。
+- `config.timeout`、`max_concurrency`、`queue_timeout_ms` 适用于服务执行。Route 饱和时返回 HTTP 429。
+- Go 服务以独立进程运行，超时会终止该进程；它不是为不可信多租户代码准备的安全沙箱。只向可信编辑者授予服务编辑权限。
+- 每个保存版本按源码、依赖、SDK 和 Runner 协议生成不可变构建键。代码或依赖变更会生成新构建产物；旧版本可通过现有版本恢复接口重新激活。
+
+## 管理 API
+
+管理 API 使用 `{code, data, message}` 信封并受 `scripts:*` 权限控制：
+
+| 方法 | 路径 |
+|---|---|
+| `POST` / `GET` | `/api/scripts` |
+| `GET` | `/api/scripts/options/roles` |
+| `GET` / `PUT` / `DELETE` | `/api/scripts/{id}` |
+| `GET` | `/api/scripts/{id}/routes` |
+| `POST` | `/api/scripts/{id}/enable`、`/api/scripts/{id}/disable`、`/api/scripts/{id}/execute` |
+| `GET` | `/api/scripts/{id}/versions`、`/api/scripts/{id}/executions` |
+| `POST` | `/api/scripts/{id}/versions/{version_id}/restore` |
+| `GET` | `/api/scripts/{id}/executions/{execution_id}` |
+
+运行时 route 为 `ANY /api/x/{slug}/{path}`，不使用管理 API 信封。
+
+## 验收清单
+
+- [ ] `package main` 且实现 `Register(app *sdk.App)`。
+- [ ] 服务使用 `mode=mixed`，第三方库写入 `go_mod`。
+- [ ] 路由使用 `app.Route`，事件使用 `app.On`，定时任务使用 `app.Schedule`。
+- [ ] handler 返回 `(any, error)`，需要状态码时使用 `ctx.Respond`。
+- [ ] Route 显式设置 `permission` 与 `route_security`。
+- [ ] 推送后请求无副作用 GET Route，必要时运行 `draftgo push custom_scripts --probe-routes`。

package/resources/skill/specs/data.md

@@ -1,5 +1,5 @@
 ---
-read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检索时
+read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检索时 · 定义关联关系时
 ---
 
 # 动态 DB & 数据层
@@ -16,6 +16,7 @@ read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检
       "name":   { "type": "string",  "title": "姓名",   "required": true,  "searchable": "fuzzy" },
       "status": { "type": "string",  "title": "状态",   "required": false, "searchable": "exact" },
       "amount": { "type": "number",  "title": "金额",   "required": false, "searchable": "range" },
+      "paid_at": { "type": "datetime", "title": "支付时间", "required": false, "searchable": "range" },
       "tags":   { "type": "array",   "title": "标签",   "required": false, "searchable": "contains" },
       "note":   { "type": "string",  "title": "备注",   "required": false, "searchable": false }
     }
@@ -28,7 +29,180 @@ read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检
 }
 ```
 
-**searchable 模式**：`false`（不可检索）/ `"exact"`（精确）/ `"fuzzy"`（模糊）/ `"range"`（数值范围）/ `"contains"`（数组包含）
+**searchable 模式**：`false`（不可检索）/ `"exact"`（精确）/ `"fuzzy"`（模糊）/ `"range"`（数值/时间范围）/ `"contains"`（数组包含）
+
+`date` 字段保存为 `YYYY-MM-DD`；`datetime` 字段保存为 ISO 8601 字符串，带时区的输入会规范化为 UTC。`searchable: true` 对 `number` / `date` / `datetime` 会自动推断为 `range`。
+
+**系统字段**：以下系统字段**无需在 schema 中定义**，可直接用于检索和排序：
+
+| 字段 | 类型 | 检索模式 | 说明 |
+|---|---|---|---|
+| `id` | number | range | 记录 ID，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
+| `userid` | number | range | 所属用户 ID，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
+| `created_at` | datetime | range | 创建时间，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
+| `updated_at` | datetime | range | 更新时间，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
+
+⚠️ **注意**：虽然 DB 表有 `status` 系统列（1=正常 0=禁用 -1=删除），但由于业务常用此字段名，**需在 schema 中显式声明 `status` 的 searchable 才可检索**。
+
+---
+
+## 自定义服务内的 ctx.DB.Query
+
+Go 自定义服务使用 `ctx.DB.Query(type, sdk.QueryOptions{...})` 操作动态 DB，返回 `sdk.QueryResult`：
+
+```go
+result, err := ctx.DB.Query("order", sdk.QueryOptions{
+    Filters: map[string]any{"status": "paid"},
+    Page: 1, PageSize: 20, OrderBy: "id", Order: "desc",
+})
+items := result.Items
+```
+
+| 参数 | 说明 |
+|---|---|
+| `filters` | 字典形式结构化过滤；默认 `{field: value}` 是 `eq` 精确匹配 |
+| `Page` / `PageSize` | 分页参数；零值交由平台使用默认列表行为 |
+| `order_by` / `order` | 按 searchable 字段排序，`order` 为 `asc` / `desc` |
+
+⚠️ 返回结构为 `sdk.QueryResult{Items, Total, Page, PageSize}`。需要完整数据时必须按 `Total` 分页读取，不能用超大 `PageSize` 假装全量。
+
+普通用户调用时只读 `status=1` 数据；系统身份/管理员脚本可读全部状态数据，但仍受 db_meta permission 约束。不要把“拿不到禁用数据”和分页截断混在一起排查。
+
+`filters` 操作符示例：
+
+```go
+ctx.DB.Query("order", sdk.QueryOptions{Filters: map[string]any{
+    "status": "paid",
+    "customer_name": map[string]any{"op": "like", "value": "张"},
+    "amount": map[string]any{"op": "gte", "value": 100},
+    "id": map[string]any{"op": "in", "value": []int{1, 2, 3}},
+}})
+```
+
+字段必须在 db_meta schema 中标记 `searchable`，系统字段 `id/userid/created_at/updated_at` 可直接检索和排序。`status` 若作为业务字段检索，仍需在 schema 中显式声明。
+
+---
+
+## 关联关系（ref）
+
+**完整示例**：`specs/db-relations.md`（随 skill 分发，不依赖项目根目录文档）
+
+### 基本配置
+
+```json
+{
+  "type": "order",
+  "schema": {
+    "properties": {
+      "user_id": {
+        "type": "number",
+        "label": "用户",
+        "ref": {
+          "type": "user",              // 关联的数据类型（必填）
+          "relation": "many-to-one",   // 关联类型（可选，默认 many-to-one）
+          "onDelete": "cascade"        // 删除策略（可选，默认 no_action）
+        }
+      }
+    }
+  }
+}
+```
+
+### 关联类型（relation）
+
+| 类型 | 字段类型 | 说明 | 示例 |
+|-----|---------|------|------|
+| `many-to-one` | number | 多个记录指向一个（默认） | 多个订单 → 一个用户 |
+| `one-to-many` | 虚拟字段 | 反向关系，需指定 `inverse_field` | 一个用户 → 多个订单 |
+| `many-to-many` | array | 字段存储 ID 数组 | 一篇文章 ↔ 多个标签 |
+
+### 删除策略（onDelete）
+
+| 策略 | 行为 | 适用场景 |
+|-----|------|----------|
+| `cascade` | 级联删除所有引用记录 | 订单依赖用户 |
+| `set_null` | 将引用字段置为 null | 删除分类后商品仍保留 |
+| `set_default` | 设为 `ref.default` 指定的值 | 删除自定义分类后归入"默认分类" |
+| `restrict` | 有引用时禁止删除，返回 400 | 防止误删有依赖的关键数据 |
+| `detach` | 仅多对多，从数组中移除 ID | 删除标签时从文章中移除 |
+| `no_action` | 不处理（默认） | 兼容旧数据 |
+
+**删除链路规则：**
+- `many-to-one` 和 `many-to-many` 是真实持有引用 ID 的字段，会参与 `onDelete` 处理。
+- `one-to-many` 是查询用虚拟反向关系，只用于 `populate`，删除链路会跳过它。
+- 需要删除 A 时自动处理引用 A 的 B，必须在 B 的真实引用字段上配置 `ref.onDelete`。
+
+### 关联查询（populate）
+
+```javascript
+// 多对一：查询订单，自动填充用户信息
+const res = await App.get(`db/order`, { populate: ['user_id'] });
+// 返回：data.user_id_obj = {id, data: {name, email}}
+
+// 多对多：查询文章，自动填充标签列表
+const res = await App.get(`db/article`, { populate: ['tag_ids'] });
+// 返回：data.tag_ids_objs = [{id, data}, {id, data}, ...]
+
+// 一对多：查询用户，自动填充订单列表
+const res = await App.get(`db/user/123`, { populate: ['orders'] });
+// 返回：data.orders_objs = [{id, data}, {id, data}, ...]
+
+// 多字段同时填充
+const res = await App.get(`db/order`, { populate: ['user_id', 'product_id'] });
+```
+
+### 完整示例
+
+```json
+{
+  "type": "order",
+  "label": "订单",
+  "schema": {
+    "properties": {
+      "user_id": {
+        "type": "number",
+        "label": "用户",
+        "required": true,
+        "ref": {
+          "type": "user",
+          "relation": "many-to-one",
+          "onDelete": "cascade"
+        }
+      },
+      "product_ids": {
+        "type": "array",
+        "label": "商品列表",
+        "ref": {
+          "type": "product",
+          "relation": "many-to-many",
+          "onDelete": "detach"
+        }
+      },
+      "category_id": {
+        "type": "number",
+        "label": "分类",
+        "ref": {
+          "type": "category",
+          "relation": "many-to-one",
+          "onDelete": "set_default",
+          "default": 0
+        }
+      }
+    }
+  }
+}
+```
+
+**行为演示：**
+- 删除用户 → 自动删除其所有订单（cascade）
+- 删除商品 → 从订单的 product_ids 数组中移除（detach）
+- 删除分类 → 订单的 category_id 设为 0（set_default）
+
+**⚠️ 注意事项：**
+- 级联删除会递归处理，深层级联可能影响性能
+- 级联操作继承当前用户权限，无权删除子记录会导致整个操作失败
+- 所有级联操作在同一事务中执行，失败会自动回滚
+- 不要在前端用多次 DELETE 手工模拟级联；优先用 DBMeta 的 `ref.onDelete` 让基座统一保证一致性
 
 ---
 
@@ -43,6 +217,20 @@ const res = await App.get(`db/order`, {
 });
 const { items, total } = res.data;
 
+// 非后台管理页面读取业务列表时，如果当前用户含 admin 角色，带 scope=mine
+// 这只影响 GET /api/db/{type} 列表，让管理员业务视角只看自己的 owner 数据
+const ownOrders = await App.get(`db/order`, {
+  page: 1,
+  page_size: 20,
+  scope: 'mine',
+});
+
+// 系统字段检索和排序（无需在 schema 中定义）
+const res = await App.get(`db/order`, {
+  filters: ['created_at:gte:2024-01-01', 'userid:eq:123'],
+  order_by: 'created_at', order: 'desc',
+});
+
 // 创建（业务字段必须放在 data 包裹里）
 await App.post(`db/order`, { data: { name: '张三', amount: 200 }, status: 1 });
 
@@ -67,13 +255,15 @@ await App.patch(`db/order/batch`, [
 |---|---|---|
 | `eq` | 精确等于 | exact / fuzzy / range |
 | `like` | 模糊包含 | fuzzy |
-| `gte` / `lte` / `gt` / `lt` | 数值范围 | range |
-| `in` | 枚举命中（值逗号分隔：`status:in:paid,pending`） | exact / fuzzy |
+| `gte` / `lte` / `gt` / `lt` | 数值/时间范围 | range |
+| `in` | 枚举命中（值逗号分隔：`status:in:paid,pending`） | exact / fuzzy / range |
 | `contains` | 数组字段包含某值 | contains |
 
 - 省略操作符（`filters: ['name:张三']`）默认 `like`
 - 多个 filters 为 AND
 - 字段未标 searchable 或操作符不匹配 → 后端返回 400
+- **系统字段**（`id` / `userid` / `created_at` / `updated_at`）无需在 schema 中声明，可直接使用
+- `scope=mine` 只对拥有 admin 角色的用户在 `GET /api/db/{type}` 列表请求中生效；非后台管理页面若当前用户是管理员，读取动态 DB 业务列表时应带该参数；后台管理页不要带，详情和写操作也不要带
 
 ---
 
@@ -102,7 +292,7 @@ await App.patch(`db/order/batch`, [
 
 | 参数 | 说明 |
 |---|---|
-| `page` / `page_size` | 分页（不传返回全量，超 10000 条后端拒绝） |
+| `page` / `page_size` | 分页（不传返回全量且无上限；任一传入则分页，缺失项按 `page=1` / `page_size=20` 兜底） |
 | `search` | 全文搜索（动态 DB 不用此参数） |
 | `status` | 状态过滤 |
 | `type` / `tag` | 类型/标签过滤 |

package/resources/skill/specs/db-relations.md

@@ -0,0 +1,227 @@
+---
+read_when: 需要 DB 关联关系完整示例时 · 设计 populate / onDelete 时
+---
+
+# DB 关联关系与级联操作
+
+DraftGo 动态 DB 通过 DBMeta.schema.properties.<field>.ref 定义关联关系，并支持删除一致性处理和 populate 关联查询。
+
+## 关联类型
+
+### many-to-one
+
+多个记录指向一个目标记录，字段真实保存目标记录 ID。
+
+```json
+{
+  "type": "order",
+  "schema": {
+    "properties": {
+      "user_id": {
+        "type": "number",
+        "label": "用户ID",
+        "ref": {
+          "type": "user",
+          "relation": "many-to-one",
+          "onDelete": "cascade"
+        }
+      }
+    }
+  }
+}
+```
+
+数据示例：
+
+```json
+{
+  "data": {
+    "user_id": 123,
+    "amount": 99.99
+  }
+}
+```
+
+### one-to-many
+
+一个目标记录反向查询多个引用它的记录。该字段是查询用虚拟字段，本身不保存 ID。
+
+```json
+{
+  "type": "user",
+  "schema": {
+    "properties": {
+      "orders": {
+        "type": "array",
+        "label": "订单列表",
+        "ref": {
+          "type": "order",
+          "relation": "one-to-many",
+          "inverse_field": "user_id"
+        }
+      }
+    }
+  }
+}
+```
+
+规则：
+
+- `inverse_field` 是对方类型中指向当前记录 ID 的字段。
+- one-to-many 只用于 populate，不参与删除链路。
+- 删除一致性要配置在真实持有引用 ID 的 many-to-one 或 many-to-many 字段上。
+
+### many-to-many
+
+字段保存目标记录 ID 数组。
+
+```json
+{
+  "type": "article",
+  "schema": {
+    "properties": {
+      "tag_ids": {
+        "type": "array",
+        "label": "标签列表",
+        "ref": {
+          "type": "tag",
+          "relation": "many-to-many",
+          "onDelete": "detach"
+        }
+      }
+    }
+  }
+}
+```
+
+数据示例：
+
+```json
+{
+  "data": {
+    "title": "Hello World",
+    "tag_ids": [1, 2, 3]
+  }
+}
+```
+
+## onDelete 策略
+
+| 策略 | 行为 | 适用场景 |
+|---|---|---|
+| `cascade` | 删除所有引用记录 | 子记录依赖父记录 |
+| `set_null` | 将引用字段置为 null | 删除分类后保留商品 |
+| `set_default` | 设为 `ref.default` 指定值 | 删除分类后归入默认分类 |
+| `restrict` | 有引用时禁止删除，返回 400 | 防止误删关键数据 |
+| `detach` | 仅多对多，从数组中移除 ID | 删除标签后从文章标签列表移除 |
+| `no_action` | 不处理，默认值 | 兼容旧数据 |
+
+删除链路规则：
+
+- many-to-one 和 many-to-many 是真实持有引用 ID 的字段，会参与 onDelete。
+- one-to-many 是虚拟反向关系，只用于 populate，删除链路跳过。
+- 需要删除 A 时自动处理引用 A 的 B，必须在 B 的真实引用字段上配置 `ref.onDelete`。
+
+## populate 查询
+
+### many-to-one
+
+```bash
+GET /api/db/order?populate=user_id
+```
+
+返回时保留原字段，并在 data 中追加 `<field>_obj`：
+
+```json
+{
+  "id": 1,
+  "data": {
+    "user_id": 123,
+    "amount": 99.99,
+    "user_id_obj": {
+      "id": 123,
+      "data": {
+        "name": "张三",
+        "email": "zhang@example.com"
+      }
+    }
+  }
+}
+```
+
+### many-to-many
+
+```bash
+GET /api/db/article?populate=tag_ids
+```
+
+返回时追加 `<field>_objs`：
+
+```json
+{
+  "id": 1,
+  "data": {
+    "title": "Hello World",
+    "tag_ids": [1, 2, 3],
+    "tag_ids_objs": [
+      { "id": 1, "data": { "name": "技术" } },
+      { "id": 2, "data": { "name": "编程" } }
+    ]
+  }
+}
+```
+
+### one-to-many
+
+```bash
+GET /api/db/user/123?populate=orders
+```
+
+返回时追加 `<field>_objs`：
+
+```json
+{
+  "id": 123,
+  "data": {
+    "name": "张三",
+    "orders_objs": [
+      { "id": 1, "data": { "amount": 99.99 } },
+      { "id": 2, "data": { "amount": 199.99 } }
+    ]
+  }
+}
+```
+
+## 字段配置速查
+
+```json
+{
+  "field_name": {
+    "type": "number",
+    "label": "显示名称",
+    "required": false,
+    "searchable": "range",
+    "ref": {
+      "type": "user",
+      "relation": "many-to-one",
+      "onDelete": "cascade",
+      "default": 0,
+      "inverse_field": "user_id"
+    }
+  }
+}
+```
+
+配置规则：
+
+- many-to-one：`type: "number"` + `relation: "many-to-one"`。
+- many-to-many：`type: "array"` + `relation: "many-to-many"`。
+- one-to-many：虚拟字段，必须配置 `inverse_field`。
+- `ref.type` 指向动态 DB 类型，例如 `user`、`doctor`、`order`，必须与 DBMeta.type 一致。
+
+## 注意事项
+
+- populate 只会填充 schema 中声明了 `ref` 的字段；普通的 `doctorid: 1` 不会自动展开。
+- 字段名不要求必须是 `*_id`，但要与 schema 和 populate 参数完全一致，例如字段叫 `doctorid` 就传 `populate=doctorid`。
+- 关联类型自身的 read 权限仍会生效；无权读取的关联记录不会作为可用数据返回。
+- 级联删除在同一事务中执行，失败会回滚。