@h-ai/cli 0.1.0-alpha.54 → 0.1.0-alpha.56

package/templates/skills/hai-reldb/reference.md

@@ -0,0 +1,452 @@
+# hai-reldb — 详细用法
+
+从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
+
+> `@h-ai/reldb` 提供统一的数据库操作接口，支持 SQLite、PostgreSQL、MySQL，包含 DDL、SQL、CRUD 抽象、事务与分页。
+
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端请通过 `@h-ai/api-contract` + `@h-ai/serv` 暴露的 API 端点间接访问数据库。
+
+## 适用场景
+
+- 新增或修改数据库访问逻辑（SQL/DDL/CRUD/事务）
+- 使用 `reldb.crud.table` 或 `BaseReldbCrudRepository` 构建数据仓库
+- 处理分页查询与分页结果规范化
+- 基于 `HaiReldbError` 做错误分支处理
+- JSON 列的路径提取、设置、插入、删除、合并操作（跨数据库统一语法）
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_db.yml
+type: sqlite
+database: ./data/app.db
+# PostgreSQL/MySQL 额外字段：
+# host: localhost
+# port: 5432
+# user: postgres
+# password: ''
+operationLog:
+  read: false # query / get / queryPage
+  write: false # DDL, execute / batch, tx.begin / tx.commit / tx.rollback
+  maxLength: 1000
+  level: debug # info | debug | trace
+```
+
+约定环境变量优先于 YAML，例如 `HAI_DB_TYPE`、`HAI_DB_DATABASE`、
+`HAI_DB_OPERATIONLOG_LEVEL`。
+
+`operationLog` 在 reldb provider-base 的 DML 操作层统一输出日志，不要在 `reldb-main.ts`、各 raw provider 或调用方重复包装。`read` 覆盖 `query/get/queryPage`，`write` 覆盖 DDL、`execute/batch` 与 `tx.begin/commit/rollback`，`maxLength` 用于截断序列化后的 SQL 参数和批量语句，`level` 默认 `debug`。
+
+### 2. 初始化与关闭
+
+```typescript
+import { core } from '@h-ai/core'
+import { reldb } from '@h-ai/reldb'
+
+await reldb.init(core.config.get('db'))
+// ... 使用数据库
+await reldb.close()
+```
+
+`reldb.config` 返回的是脱敏后的配置快照；数据库密码与 URL 内嵌凭证会自动隐藏。
+
+### 3. 选择操作接口
+
+| 接口 | 用途               | 入口                         |
+| ---- | ------------------ | ---------------------------- |
+| DDL  | 建表/索引/字段变更 | `reldb.ddl`                     |
+| SQL  | 原始查询/执行/分页 | `reldb.sql`                     |
+| CRUD | 通用增删改查       | `reldb.crud.table(config)`      |
+| 仓库 | 业务数据仓库封装   | `extends BaseReldbCrudRepository` |
+| 事务 | 事务管理           | `reldb.tx`                      |
+| 分页 | 分页参数与结果     | `reldb.pagination`              |
+| JSON | JSON 路径操作      | `reldb.json`                    |
+
+## 核心 API
+
+事务边界：`tx.wrap` 对正常返回值一律提交，不识别失败 HaiResult；回调内检查每步结果，失败抛错以触发回滚（外层返回 TRANSACTION_FAILED）。需保留原错误码时使用手动事务。
+
+### DDL — `reldb.ddl`
+
+| 方法          | 签名                                                                    | 说明                       |
+| ------------- | ----------------------------------------------------------------------- | -------------------------- |
+| `createTable` | `(tableName, columns: ReldbTableDef, ifNotExists?: boolean) => HaiResult<void>` | 建表（默认 IF NOT EXISTS） |
+| `dropTable`   | `(tableName, ifExists?: boolean) => HaiResult<void>`                       | 删除表（默认 IF EXISTS）   |
+| `addColumn`   | `(tableName, columnName, columnDef: ReldbColumnDef) => HaiResult<void>`         | 添加列                     |
+| `dropColumn`  | `(tableName, columnName) => HaiResult<void>`                               | 删除列                     |
+| `renameTable` | `(oldName, newName) => HaiResult<void>`                                    | 重命名表                   |
+| `createIndex` | `(tableName, indexName, indexDef: ReldbIndexDef) => HaiResult<void>`            | 创建索引                   |
+| `dropIndex`   | `(indexName, ifExists?: boolean) => HaiResult<void>`                       | 删除索引                   |
+| `raw`         | `(sql: string) => HaiResult<void>`                                         | 执行原始 DDL               |
+
+> 所有方法均返回 `Promise<HaiResult<void>>`，上表省略异步与错误类型。
+
+**ReldbTableDef**（列名到列定义的映射）：
+
+```typescript
+const columns: ReldbTableDef = {
+  id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+  name: { type: 'TEXT', notNull: true },
+  email: { type: 'TEXT', unique: true },
+  score: { type: 'REAL', defaultValue: 0 },
+  active: { type: 'BOOLEAN' },
+  metadata: { type: 'JSON' },
+  created_at: { type: 'TIMESTAMP' },
+}
+```
+
+**ReldbColumnDef**（列类型与约束）：
+
+```typescript
+interface ReldbColumnDef {
+  type: 'TEXT' | 'INTEGER' | 'REAL' | 'BLOB' | 'BOOLEAN' | 'TIMESTAMP' | 'JSON'
+  primaryKey?: boolean
+  autoIncrement?: boolean
+  notNull?: boolean
+  unique?: boolean
+  defaultValue?: string | number | boolean | null
+  references?: { table: string, column: string, onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION', onUpdate?: '...' }
+}
+```
+
+**跨数据库类型映射**：
+
+| 类型      | SQLite  | PostgreSQL       | MySQL        |
+| --------- | ------- | ---------------- | ------------ |
+| TEXT      | TEXT    | TEXT             | VARCHAR(255) |
+| INTEGER   | INTEGER | INTEGER/SERIAL   | INT/BIGINT   |
+| REAL      | REAL    | DOUBLE PRECISION | DOUBLE       |
+| BLOB      | BLOB    | BYTEA            | BLOB         |
+| BOOLEAN   | INTEGER | BOOLEAN          | TINYINT(1)   |
+| TIMESTAMP | INTEGER | TIMESTAMP        | DATETIME     |
+| JSON      | TEXT    | JSONB            | JSON         |
+
+> MySQL 将 TEXT 映射为 VARCHAR(255) 以支持索引和 UNIQUE 约束。INTEGER + autoIncrement 在 MySQL 映射为 BIGINT。
+
+### SQL — `reldb.sql`
+
+| 方法        | 签名                                                              | 说明         |
+| ----------- | ----------------------------------------------------------------- | ------------ |
+| `query`     | `<T>(sql, params?) => HaiResult<T[]>`                                | 查询返回多行 |
+| `get`       | `<T>(sql, params?) => HaiResult<T \| null>`                          | 查询返回单行 |
+| `execute`   | `(sql, params?) => HaiResult<ExecuteResult>`                         | 执行写操作   |
+| `batch`     | `(statements: Array<{ sql, params? }>) => HaiResult<void>`           | 批量执行     |
+| `queryPage` | `<T>(options: PaginationQueryOptions) => HaiResult<PaginatedResult>` | 分页查询     |
+
+> 所有方法均返回 `Promise<HaiResult<T>>`，上表省略异步与错误类型。
+
+**参数占位符统一使用 `?`**（PostgreSQL 的 `$n` 由 Provider 自动转换）：
+
+```typescript
+const result = await reldb.sql.query<User>(
+  'SELECT * FROM users WHERE status = ? AND age > ?',
+  ['active', 18],
+)
+```
+
+**ExecuteResult**：
+
+```typescript
+interface ExecuteResult {
+  changes: number // 影响的行数
+  lastInsertRowid?: number | bigint // INSERT 时生效（PostgreSQL 不返回此字段）
+}
+```
+
+**分页查询**：
+
+```typescript
+const page = await reldb.sql.queryPage<User>({
+  sql: 'SELECT * FROM users WHERE status = ? ORDER BY id',
+  params: ['active'],
+  pagination: { page: 1, pageSize: 20 },
+  overrides: { maxPageSize: 100 }, // 可选：限制最大页大小
+})
+// page.data => { items, total, page, pageSize }
+```
+
+### CRUD — `reldb.crud.table(config)`
+
+通过配置创建单表 CRUD 仓库，免写 SQL：
+
+```typescript
+const userCrud = reldb.crud.table<{ id: number, name: string, email: string }>({
+  table: 'users',
+  idColumn: 'id',           // 主键列，默认 'id'
+  select: ['id', 'name', 'email'],   // 查询列，默认 '*'
+  createColumns: ['name', 'email'],   // 允许插入的列
+  updateColumns: ['name', 'email'],   // 允许更新的列
+})
+```
+
+返回的 ReldbCrudRepository 方法：
+
+| 方法         | 签名                                           | 说明         |
+| ------------ | ---------------------------------------------- | ------------ |
+| `create`     | `(data, tx?) => HaiResult<ExecuteResult>`         | 创建单条     |
+| `createMany` | `(items, tx?) => HaiResult<void>`                 | 批量创建     |
+| `findById`   | `(id, tx?) => HaiResult<T \| null>`               | 按 ID 查询   |
+| `findAll`    | `(options?, tx?) => HaiResult<T[]>`               | 条件查询     |
+| `findPage`   | `(options, tx?) => HaiResult<PaginatedResult<T>>` | 分页查询     |
+| `updateById` | `(id, data, tx?) => HaiResult<ExecuteResult>`     | 按 ID 更新   |
+| `deleteById` | `(id, tx?) => HaiResult<ExecuteResult>`           | 按 ID 删除   |
+| `count`      | `(options?, tx?) => HaiResult<number>`            | 计数         |
+| `exists`     | `(options?, tx?) => HaiResult<boolean>`           | 条件是否存在 |
+| `existsById` | `(id, tx?) => HaiResult<boolean>`                 | ID 是否存在  |
+
+> 所有方法均支持可选 `tx` 事务参数。`create`/`updateById` 中的 `data` 会根据 `createColumns`/`updateColumns` 白名单过滤列。
+
+**使用示例**：
+
+```typescript
+// 单条插入
+const result = await userCrud.create({ name: '张三', email: 'test@example.com' })
+// result.data → { changes: 1, lastInsertRowid: 1 }
+
+// 批量插入
+await userCrud.createMany([
+  { name: '用户A', email: 'a@test.com' },
+  { name: '用户B', email: 'b@test.com' },
+])
+
+// 主键查找
+const user = await userCrud.findById(1)
+// user.data → { id: 1, name: '张三', email: 'test@example.com' } | null
+
+// 条件查询（where + params 占位符）
+const actives = await userCrud.findAll({
+  where: 'name LIKE ?',
+  params: ['%张%'],
+  orderBy: 'id DESC',
+  limit: 10,
+  offset: 0,
+})
+
+// 分页查询
+const page = await userCrud.findPage({
+  where: 'name LIKE ?',
+  params: ['%张%'],
+  orderBy: 'id DESC',
+  pagination: { page: 1, pageSize: 20 },
+})
+// page.data → { items: [...], total: 100, page: 1, pageSize: 20 }
+
+// 更新 / 删除
+await userCrud.updateById(1, { name: '新名字' })
+await userCrud.deleteById(1)
+
+// 计数 / 存在性
+const total = await userCrud.count({ where: 'name LIKE ?', params: ['%张%'] })
+const has = await userCrud.exists({ where: 'email = ?', params: ['test@example.com'] })
+const found = await userCrud.existsById(1)
+
+// 事务中使用（所有方法均支持 tx 参数）
+await reldb.tx.wrap(async (tx) => {
+  const created = await userCrud.create({ name: '用户A', email: 'a@test.com' }, tx)
+  if (!created.success) throw new Error(created.error.message)
+  const updated = await userCrud.updateById(1, { name: '新名字' }, tx)
+  if (!updated.success) throw new Error(updated.error.message)
+  const user = await userCrud.findById(1, tx)
+  if (!user.success) throw new Error(user.error.message)
+  return user.data
+})
+```
+
+### BaseReldbCrudRepository
+
+业务仓库基类，提供字段映射、自动建表与类型转换能力：
+
+```typescript
+import { BaseReldbCrudRepository } from '@h-ai/reldb'
+
+interface User { id: number, name: string, email: string, createdAt: Date, updatedAt: Date }
+
+class UserRepository extends BaseReldbCrudRepository<User> {
+  constructor() {
+    super(db, {
+      table: 'users',
+      idColumn: 'id',
+      fields: [
+        { fieldName: 'id', columnName: 'id', def: { type: 'INTEGER', primaryKey: true, autoIncrement: true }, select: true, create: false, update: false },
+        { fieldName: 'name', columnName: 'name', def: { type: 'TEXT', notNull: true }, select: true, create: true, update: true },
+        { fieldName: 'email', columnName: 'email', def: { type: 'TEXT', notNull: true }, select: true, create: true, update: true },
+        { fieldName: 'createdAt', columnName: 'created_at', def: { type: 'TIMESTAMP', notNull: true }, select: true, create: true, update: false },
+        { fieldName: 'updatedAt', columnName: 'updated_at', def: { type: 'TIMESTAMP', notNull: true }, select: true, create: true, update: false },
+      ],
+    })
+  }
+
+  /** 自定义查询示例 */
+  async findByEmail(email: string, tx?: DmlWithTxOperations) {
+    return this.sql(tx).get<User>('SELECT * FROM users WHERE email = ?', [email])
+  }
+}
+```
+
+**`this.sql(tx?)`**：返回 `DmlOperations`（`reldb.sql` 或传入的事务句柄），自动适配事务场景。
+
+**自动能力**：
+
+- `createdAt` / `updatedAt` 字段自动填充时间戳
+- 主键生成（非 autoIncrement 主键默认使用随机 UUID，底层带安全上下文守卫，不可用时回退；业务侧手动生成 UUID 一律用 `core.id.uuid()`）
+- BOOLEAN → 1/0（SQLite/MySQL）或 true/false（PostgreSQL）
+- TIMESTAMP → 毫秒时间戳（SQLite）或 Date（PG/MySQL）
+- JSON → 字符串序列化（SQLite/MySQL）或原生 JSONB（PG）
+
+### 事务 — `reldb.tx`
+
+```typescript
+// 方式1：wrap（自动 commit/rollback）
+const result = await reldb.tx.wrap(async (tx) => {
+  const inserted = await tx.execute('INSERT INTO users (name) VALUES (?)', ['张三'])
+  if (!inserted.success) throw new Error(inserted.error.message)
+  const logged = await tx.execute('INSERT INTO logs (action) VALUES (?)', ['user_created'])
+  if (!logged.success) throw new Error(logged.error.message)
+  return 'done'
+})
+// result.data === 'done'（正常返回自动 commit）
+// 回调抛异常 → 自动 rollback → result.success === false
+
+// 方式2：手动管理，保留原领域错误（置于 async 函数内）
+const txResult = await reldb.tx.begin()
+if (!txResult.success) return txResult
+const tx = txResult.data
+const inserted = await tx.execute('INSERT INTO users (name) VALUES (?)', ['李四'])
+if (!inserted.success) {
+  const rollback = await tx.rollback()
+  if (!rollback.success) return rollback
+  return inserted
+}
+return tx.commit()
+```
+
+**事务内可用操作**：
+
+- `tx.query / tx.get / tx.execute / tx.batch / tx.queryPage`
+- `tx.crud.table(config)` — 事务内的 CRUD 仓库
+- `tx.commit() / tx.rollback()`
+
+### 分页 — `reldb.pagination`
+
+| 方法        | 签名                                                  | 说明                                   |
+| ----------- | ----------------------------------------------------- | -------------------------------------- |
+| `normalize` | `(options?, overrides?) => NormalizedPagination`      | 规范化分页参数（含 offset/limit 计算） |
+| `build`     | `<T>(items, total, pagination) => PaginatedResult<T>` | 构建分页结果对象                       |
+
+```typescript
+// PaginatedResult 结构
+interface PaginatedResult<T> {
+  items: T[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+// 默认值：page=1, pageSize=20, maxPageSize=200
+```
+
+### JSON — `reldb.json`
+
+通过 `reldb.json` 构建跨数据库统一的 JSON 路径操作 SQL 表达式，返回 `{ sql, params }` 可直接嵌入 `reldb.sql.*`。
+
+路径格式遵循 SQL/JSON Path 标准，以 `$` 开头（如 `$.key`、`$.key.subkey`、`$[0]`）。
+
+| 操作      | SQLite             | PostgreSQL               | MySQL                  |
+| --------- | ------------------ | ------------------------ | ---------------------- |
+| `extract` | `json_extract`     | `#>` (text[])            | `JSON_EXTRACT`         |
+| `set`     | `json_set`         | `jsonb_set`              | `JSON_SET`             |
+| `insert`  | `json_insert`      | `jsonb_insert`           | `JSON_INSERT`          |
+| `remove`  | `json_remove`      | `#-` (text[])            | `JSON_REMOVE`          |
+| `merge`   | `json_patch`       | `|| ::jsonb`              | `JSON_MERGE_PATCH`     |
+
+```typescript
+// 提取 JSON 字段值（用于 WHERE 条件）
+const { sql, params } = reldb.json.extract('settings', '$.theme')
+const rows = await reldb.sql.query(
+  `SELECT * FROM users WHERE ${sql} = ?`,
+  [...params, '"dark"'],
+)
+
+// 设置 JSON 字段路径（创建或替换）
+const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
+await reldb.sql.execute(
+  `UPDATE users SET settings = ${sql} WHERE id = ?`,
+  [...params, userId],
+)
+
+// 删除 JSON 字段路径
+const { sql, params } = reldb.json.remove('settings', '$.deprecated')
+await reldb.sql.execute(`UPDATE users SET settings = ${sql} WHERE id = ?`, [...params, id])
+
+// 合并 JSON 对象（RFC 7396：null 值表示删除对应键）
+const { sql, params } = reldb.json.merge('profile', { bio: '新简介', avatar: null })
+await reldb.sql.execute(`UPDATE users SET profile = ${sql} WHERE id = ?`, [...params, userId])
+```
+
+> `column` 参数为列名，**禁止传入用户输入**（开发者负责安全性）。
+
+## 错误码 — `HaiReldbError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiReldbError.CONNECTION_FAILED`    | `hai:reldb:001`  | 数据库连接失败     |
+| `HaiReldbError.QUERY_FAILED`         | `hai:reldb:002`  | 查询或执行失败     |
+| `HaiReldbError.CONSTRAINT_VIOLATION` | `hai:reldb:003`  | 约束违反           |
+| `HaiReldbError.TRANSACTION_FAILED`   | `hai:reldb:004`  | 事务失败           |
+| `HaiReldbError.MIGRATION_FAILED`     | `hai:reldb:005`  | 迁移失败           |
+| `HaiReldbError.RECORD_NOT_FOUND`     | `hai:reldb:006`  | 记录不存在         |
+| `HaiReldbError.DUPLICATE_ENTRY`      | `hai:reldb:007`  | 重复条目           |
+| `HaiReldbError.DEADLOCK`             | `hai:reldb:008`  | 死锁               |
+| `HaiReldbError.TIMEOUT`              | `hai:reldb:009`  | 超时               |
+| `HaiReldbError.NOT_INITIALIZED`      | `hai:reldb:010`  | 数据库未初始化     |
+| `HaiReldbError.POOL_EXHAUSTED`       | `hai:reldb:011`  | 连接池耗尽         |
+| `HaiReldbError.UNSUPPORTED_TYPE`     | `hai:reldb:012`  | 不支持的数据库类型 |
+| `HaiReldbError.CONFIG_ERROR`         | `hai:reldb:013`  | 配置错误           |
+| `HaiReldbError.DDL_FAILED`           | `hai:reldb:020`  | DDL 操作失败       |
+
+## 常见模式
+
+### API 端点中使用
+
+```typescript
+import { reldb, HaiReldbError } from '@h-ai/reldb'
+import { kit } from '@h-ai/kit'
+
+export const GET = kit.handler(async ({ url }) => {
+  // query 返回校验后的数据，失败抛 Response，由 kit.handler 处理。
+  const pagination = kit.validate.query(url, PageSchema)
+  const result = await userCrud.findPage({ pagination, orderBy: 'id ASC' })
+  if (!result.success)
+    return kit.response.error(result.error.code, result.error.message)
+  return kit.response.ok(result.data)
+})
+```
+
+### 事务跨仓库
+
+```typescript
+const result = await reldb.tx.wrap(async (tx) => {
+  const user = await userRepo.create(userData, tx)
+  if (!user.success)
+    throw new Error(user.error.message)
+
+  const profile = await profileRepo.create({ userId: user.data.lastInsertRowid, ...profileData }, tx)
+  if (!profile.success) throw new Error(profile.error.message)
+  return user.data
+})
+```
+
+### BaseReldbCrudRepository 事务集成
+
+与上述事务相同：每个 Repository 方法传入同一 tx，并检查每次 HaiResult；失败 rollback，全部成功后 commit。不要只等待 Promise 完成就提交。
+
+## 相关 Skills
+
+- `hai-build`：模块初始化顺序
+- `hai-core`：配置管理、HaiResult 模型
+- `hai-iam`：IAM 模块内部使用 reldb 进行用户/角色/权限存储
+- `hai-cache`：缓存穿透保护中配合 reldb 使用

package/templates/skills/hai-scheduler/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hai-scheduler
-description: 使用 @h-ai/scheduler 进行统一定时任务管理、任务持久化、手工触发、触发来源审计、全局生命周期回调与执行日志查询；当需求涉及 cron 调度、JS 函数字符串任务、API 任务、分布式锁或任务事件回调时使用。
+description: "使用 @h-ai/scheduler 注册 cron/API/JS/Hook 任务、手工触发并查询执行日志。"
 ---
 
 # hai-scheduler
@@ -19,11 +19,11 @@ API 任务 `timeout` 默认 30000 毫秒，覆盖请求及完整响应体读取
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 使用 @h-ai/scheduler 进行统一定时任务管理、任务持久化、手工触发、触发来源审计、全局生命周期回调与执行日志查询；当需求涉及 cron 调度、JS 函数字符串任务、API 任务、分布式锁或任务事件回调时使用。 |
-| 适用场景 | 当任务与 `hai-scheduler` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 模块配置、类型化业务参数、依赖初始化状态和目标运行环境 |
-| 输出 | 符合模块公共 API 的实现或示例；业务结果使用 HaiResult，并同步必要测试与文档 |
-| 限制 | 遵守 init → use → close 生命周期与运行环境边界；不绕过类型、授权、输入校验或敏感信息保护 |
+| 能力 | 使用 @h-ai/scheduler 注册 cron/API/JS/Hook 任务、手工触发并查询执行日志 |
+| 适用场景 | 服务端任务调度、持久化和手工触发 |
+| 输入 | SchedulerConfigInput、任务定义、已初始化依赖与 hooks |
+| 输出 | 任务管理、触发和日志查询的 HaiResult |
+| 限制 | 仅服务端；vm 不是安全沙箱，JS 任务只执行可信代码。多节点需要共享锁，关闭释放调度资源。 |
 
 > `@h-ai/scheduler` 使用统一任务模型管理 API / JS / Hook 三类执行路径，支持持久化、手工触发来源记录、分布式锁与全局生命周期回调。