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

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

@@ -1,6 +1,6 @@
 ---
 name: hai-reldb
-description: 使用 @h-ai/reldb 进行 SQLite/PostgreSQL/MySQL 的初始化、SQL/DDL/CRUD/事务与分页操作；当需求涉及数据库访问、CRUD 仓库、事务处理、分页查询或 HaiReldbError 分支处理时使用。
+description: "使用 @h-ai/reldb 访问 SQLite/PostgreSQL/MySQL，编写 SQL、CRUD、DDL、事务和分页。"
 ---
 
 # hai-reldb
@@ -9,479 +9,26 @@ description: 使用 @h-ai/reldb 进行 SQLite/PostgreSQL/MySQL 的初始化、SQ
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 使用 @h-ai/reldb 进行 SQLite/PostgreSQL/MySQL 的初始化、SQL/DDL/CRUD/事务与分页操作；当需求涉及数据库访问、CRUD 仓库、事务处理、分页查询或 HaiReldbError 分支处理时使用。 |
-| 适用场景 | 当任务与 `hai-reldb` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 模块配置、类型化业务参数、依赖初始化状态和目标运行环境 |
-| 输出 | 符合模块公共 API 的实现或示例；业务结果使用 HaiResult，并同步必要测试与文档 |
-| 限制 | 遵守 init → use → close 生命周期与运行环境边界；不绕过类型、授权、输入校验或敏感信息保护 |
+| 能力 | 使用 @h-ai/reldb 访问 SQLite/PostgreSQL/MySQL，编写 SQL、CRUD、DDL、事务和分页 |
+| 适用场景 | 关系数据读写、仓库封装或事务一致性 |
+| 输入 | ReldbConfigInput、参数化 SQL、CRUD 配置、事务句柄 |
+| 输出 | DB 操作为 HaiResult；crud.table 和分页/JSON 工具按签名返回 |
+| 限制 | 仅服务端；tx.wrap 只在回调抛错时回滚，返回失败 HaiResult 不会触发回滚。动态值参数化，标识符用白名单。 |
 
-> `@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
-
-### DDL — `reldb.ddl`
-
-| 方法          | 签名                                                                    | 说明                       |
-| ------------- | ----------------------------------------------------------------------- | -------------------------- |
-| `createTable` | `(tableName, columns: TableDef, ifNotExists?: boolean) => HaiResult<void>` | 建表（默认 IF NOT EXISTS） |
-| `dropTable`   | `(tableName, ifExists?: boolean) => HaiResult<void>`                       | 删除表（默认 IF EXISTS）   |
-| `addColumn`   | `(tableName, columnName, columnDef: ColumnDef) => HaiResult<void>`         | 添加列                     |
-| `dropColumn`  | `(tableName, columnName) => HaiResult<void>`                               | 删除列                     |
-| `renameTable` | `(oldName, newName) => HaiResult<void>`                                    | 重命名表                   |
-| `createIndex` | `(tableName, indexName, indexDef: IndexDef) => HaiResult<void>`            | 创建索引                   |
-| `dropIndex`   | `(indexName, ifExists?: boolean) => HaiResult<void>`                       | 删除索引                   |
-| `raw`         | `(sql: string) => HaiResult<void>`                                         | 执行原始 DDL               |
-
-> 所有方法均返回 `Promise<HaiResult<void>>`，上表省略异步与错误类型。
-
-**TableDef**（列名到列定义的映射）：
-
-```typescript
-const columns: TableDef = {
-  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' },
-}
-```
-
-**ColumnDef**（列类型与约束）：
-
-```typescript
-interface ColumnDef {
-  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
+- `_db.yml` 对应 core.config 的 db；先校验 ReldbConfigSchema，再 init 并检查 success。
+- 事务每步检查结果，避免把失败当普通返回值提交；同一事务操作须共享 tx。
+- SQL 值参数化；where/orderBy/json 列名不是任意用户输入。分页使用 PaginatedResult。
 
-// 条件查询（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) => {
-  await userCrud.create({ name: '用户A', email: 'a@test.com' }, tx)
-  await userCrud.updateById(1, { name: '新名字' }, tx)
-  const user = await userCrud.findById(1, tx)
-})
-```
-
-### 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) => {
-  await tx.execute('INSERT INTO users (name) VALUES (?)', ['张三'])
-  await tx.execute('INSERT INTO logs (action) VALUES (?)', ['user_created'])
-  return 'done'
-})
-// result.data === 'done'（正常返回自动 commit）
-// 回调抛异常 → 自动 rollback → result.success === false
-
-// 方式2：手动管理
-const txResult = await reldb.tx.begin()
-if (txResult.success) {
-  const tx = txResult.data
-  try {
-    await tx.execute('INSERT INTO users (name) VALUES (?)', ['李四'])
-    await tx.commit()
-  }
-  catch {
-    await tx.rollback()
-  }
-}
-```
-
-**事务内可用操作**：
-
-- `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 async function GET(event) {
-  const { valid, data } = kit.validate.query(event.url, PageSchema)
-  if (!valid)
-    return kit.response.badRequest('Invalid params')
-
-  const result = await userCrud.findPage({
-    pagination: data,
-    orderBy: 'id ASC',
-  })
-  if (!result.success)
-    return kit.response.internalError()
-
-  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)
-
-  await profileRepo.create({ userId: user.data.lastInsertRowid, ...profileData }, tx)
-  return user.data
-})
-```
-
-### BaseReldbCrudRepository 事务集成
-
-```typescript
-const txResult = await reldb.tx.begin()
-if (txResult.success) {
-  const tx = txResult.data
-  await userRepo.create({ name: '用户A', email: 'a@test.com' }, tx)
-  await userRepo.create({ name: '用户B', email: 'b@test.com' }, tx)
-  await tx.commit()
-}
-```
-
----
+## 按需参考
 
-## 相关 Skills
+详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
 
-- `hai-build`：模块初始化顺序
-- `hai-core`：配置管理、HaiResult 模型
-- `hai-iam`：IAM 模块内部使用 reldb 进行用户/角色/权限存储
-- `hai-cache`：缓存穿透保护中配合 reldb 使用
+- 运行环境
+- 适用场景
+- 使用步骤
+- 核心 API
+- 错误码 — `HaiReldbError`
+- 常见模式
+- 相关 Skills