draftgo-cli 3.0.1 → 3.0.33

package/resources/skill/references/data.md

@@ -0,0 +1,298 @@
+---
+read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检索时 · 定义关联关系时
+---
+
+# 动态 DB & 数据层
+
+## DB Meta 结构
+
+```json
+{
+  "type": "order",
+  "label": "订单",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "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 }
+    }
+  },
+  "permission": {
+    "public":  { "read": "none",  "create": "none",  "update": "none",  "delete": "none" },
+    "login":   { "read": "all",   "create": "all",   "update": "owner", "delete": "owner" },
+    "admin":   { "read": "all",   "create": "all",   "update": "all",   "delete": "all" }
+  }
+}
+```
+
+**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 才可检索**。
+
+---
+
+## 自定义服务内的 draftgo.DB.Query
+
+Go 自定义服务使用 `draftgo.DB.Query(type, sdk.QueryOptions{...})` 操作动态 DB，返回 `sdk.QueryResult`：
+
+```go
+result, err := draftgo.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
+draftgo.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）
+
+**完整示例**：`references/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` 让基座统一保证一致性
+
+---
+
+## CRUD 操作范式
+
+```javascript
+// 查询（分页 + 结构化检索）
+const res = await App.get(`db/order`, {
+  page: 1, page_size: 20,
+  filters: ['name:like:张', 'status:eq:paid', 'amount:gte:100'],
+  order_by: 'amount', order: 'desc',
+});
+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 });
+
+// 更新
+await App.put(`db/order/${id}`, { data: { amount: 250 } });
+
+// 删除
+await App.delete(`db/order/${id}`);
+
+// 批量更新（原子事务，任一失败全批回滚）
+await App.patch(`db/order/batch`, [
+  { id: 1, data: { status: 'paid' } },
+  { id: 2, data: { status: 'paid' } },
+]);
+```
+
+---
+
+## filters 操作符
+
+| 操作符 | 含义 | 适用 searchable 模式 |
+|---|---|---|
+| `eq` | 精确等于 | exact / fuzzy / range |
+| `like` | 模糊包含 | 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 业务列表时应带该参数；后台管理页不要带，详情和写操作也不要带
+
+---
+
+## db_meta 本地文件
+
+开发前先读 `.draftgo/db_meta/index.json` 了解可用 type 和字段：
+
+```json
+[
+  {
+    "id": 1,
+    "type": "order",
+    "label": "订单",
+    "schema": { ... }
+  }
+]
+```
+
+⚠️ **GET `/api/db-meta/{type}` 用 type（如 `order`），不是 id。PUT/DELETE 才用 id。**
+
+---
+
+## 通用筛选参数（非动态 DB）
+
+用于 users / roles / pages / navigations / feedback 等标准资源：
+
+| 参数 | 说明 |
+|---|---|
+| `page` / `page_size` | 分页（不传返回全量且无上限；任一传入则分页，缺失项按 `page=1` / `page_size=20` 兜底） |
+| `search` | 全文搜索（动态 DB 不用此参数） |
+| `status` | 状态过滤 |
+| `type` / `tag` | 类型/标签过滤 |

package/resources/skill/references/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 权限仍会生效；无权读取的关联记录不会作为可用数据返回。
+- 级联删除在同一事务中执行，失败会回滚。