| `dao` | DAO 登记与表结构 | 登记清单、表/字段模型、已装载驱动 |# mm_sql

[中文](./README.md) | [English](./README_EN.md)

一个通用的SQL帮助类，支持通过切换db_type实现对不同数据库的操作，包括MySQL、SQLite和JSON等，提供统一的API接口。内置 **Dao 实时模型构建器**，支持嵌套对象属性修改后自动同步到数据库，特别适合游戏开发等层级数据场景。

## 安装

```bash
npm install mm_sql
```

## 依赖

- mm_mysql: ^2.1.1
- mm_sqlite: ^1.1.3

## 使用方法

### 0. 数据域（推荐入口）

DAO 层按数据域组织，用 `daoAdmin(域)` 取用：

```javascript
const { daoAdmin } = require('mm_dao');

// 系统 / 用户 / 机构 / 项目 / 客户端 / 应用
daoAdmin('os').load('./sys.sql');
daoAdmin('user').run('account', query, body);

// 某个域需要独立数据库时，随作用域一起给 sql 配置
daoAdmin('org', {
  sql: { way: 'mysql', mysql: { host: '127.0.0.1', database: 'org' } }
});
```

- 同一域复用同一管理器实例；`os` 为默认域。
- 域未单独配置 `sql` 时复用主库，便于同库分域、后续平滑拆库。
- 简单 CURD 允许直接 `sqlAdmin('os')` 访问，少一层封装、性能更好。

### 0.1 查询参数的字段过滤

生成 SQL 条件之前，查询参数会先按 `filter` 抽取一遍，确保进入 where 的只有真实表字段。
`filter` 是一张「参数名 → 数据管理器属性名」的映射表，默认包含：

| 参数 | 赋值给 | 说明 |
|---|---|---|
| `table` | `db.table` | 表名，`table` 配置含 `{0}` 时生效 |
| `page` | `db.page` | 页码 |
| `size` | `db.size` | 每页条数 |
| `method` | `db.method` | 操作方式 |
| `orderby` | `db.orderby` | 排序 |
| `field` | `db.field` | 返回字段 |
| `count_ret` | `db.count_ret` | 是否返回总数 |
| `groupby` | `db.groupby` | 分组（sum/avg/count 用） |
| `db` | — | 数据域，仅用于选择数据源（值为空表示只抽取不赋值） |

业务可在 dao.json 中追加自己的非表字段，例如机构ID只用于选择机构库，不参与查询条件：

```json
{
  "table": "ai_agent",
  "filter": { "org_id": "" }
}
```

- 声明与默认清单**合并**，追加业务字段不会丢掉通用控制参数。
- 抽取与取值真假无关：`page=0`、`size=''` 这类假值同样被抽走，不会被拼成 `` `page` = 0 ``。
- 只有真值才赋给数据管理器；`""`（空字符串）表示只抽取、不赋值。
- 未声明的字段仍按等值条件处理（`` `field` = value ``），保持与既有 dao 兼容。

### 0.2 默认条件（query_default）与增删改查的一致性

`query_default` 里形如 `{"user_id": "\`user_id\` = {user_id}"}` 的条件，在参数不含该字段时自动追加。
它通常是**数据隔离条件**（用户、机构），所以所有读写路径必须一致：

- `get`、`set`、`del`、`addOrSet`、`del_repeat` 都走同一个 `_buildQueryString`，都会追加默认条件；
- 条件用 `AND` 拼接而非 `&&`，MySQL 与 SQLite 通用；
- `del` 在最终条件为空时直接返回「删除条件不能为空」，不会退化成删全表；
- 前端显式传了同名字段（如 `user_id`）时按「参数优先」处理，不再追加默认条件 —— 这类字段应视为不可由前端覆盖的隔离字段，接口层需自行拦截。

**写入侧要配 `body_default`**：`query_default` 会在新增前校验隔离字段，`body_default` 负责把同样的字段值补进新记录。
两者取值模板相同（如都为 ``"`user_id` = {user_id}"``），否则新增出来的记录缺少隔离字段，按同一用户再也查不到，表现为**反复新增重复数据**。

```json
{
  "query_default": { "user_id": "`user_id` = {user_id}" },
  "body_default": { "user_id": "`user_id` = {user_id}" }
}
```

`addOrSet` 的「新增 / 更新」由 Dao 自己判定存在性后分派（`countSql` → `add` / `setSql`）：
部分适配器的 `addOrSet` 在新增时只写入 `body`，不会带上条件字段，会让新记录不满足条件、下次调用又插一条。
`del_repeat` 的分组查询与逐条取行同样叠加默认条件，只在本用户范围内去重。


### 1. 基本使用

```javascript
// 引入模块
const Sql = require('mm_sql/lib/sql.js');
const { Dao } = require('mm_sql/lib/dao.js');

// 创建实例（默认使用MySQL）
const sql = new Sql({
  db_type: 'mysql',
  host: 'localhost',
  port: 3306,
  user: 'root',
  password: 'password',
  database: 'test_db'
});

// 执行查询SQL
const users = await sql.run('SELECT * FROM users WHERE status = 1');

// 执行更新SQL
const result = await sql.exec('UPDATE users SET status = 0 WHERE id = 1');

// 关闭连接
await sql.close();
```

### 2. 切换数据库类型

```javascript
// 创建MySQL实例
const sql = new Sql({
  db_type: 'mysql',
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'mysql_db'
});

// 切换到SQLite
sql.setConfig({
  db_type: 'sqlite',
  dir: '/db/',
  database: 'sqlite.db'
});

// 使用SQLite进行操作
const data = await sql.run('SELECT * FROM users');
```

### 3. 主要方法

#### SQL执行方法

```javascript
// 执行查询操作（返回结果集）
const users = await sql.run('SELECT * FROM users WHERE status = 1');

// 执行带参数的查询
const user = await sql.run('SELECT * FROM users WHERE id = ?', [1]);

// 执行带超时的查询
const timeoutResult = await sql.run('SELECT * FROM users WHERE status = 1', [], 5000);

// 执行修改操作（返回影响行数）
const updateResult = await sql.exec('UPDATE users SET status = 0 WHERE id = 1');

// 执行带参数的修改
const updateWithParams = await sql.exec('UPDATE users SET name = ? WHERE id = ?', ['张三', 1]);

// 执行带超时的修改
const timeoutExec = await sql.exec('DELETE FROM users WHERE status = 0', [], 3000);

// 使用对象参数方式调用
const result = await sql.run({
  sql: 'SELECT * FROM users WHERE name LIKE ?',
  params: ['张%'],
  timeout: 5000
});
```

#### 连接管理方法

```javascript
// 手动打开数据库连接
await sql.open();

// 手动关闭数据库连接
await sql.close();

// 动态修改配置
sql.setConfig({
  host: 'new_host',
  database: 'new_database'
});
```

#### 模板方法

```javascript
// SQL模板查询生成
const query = sql.tplQuery({ name: '张', age: 20 }, {
  name: '`name` LIKE "{0}%"',
  age: '`age` > {0}'
});
// 生成: "`name` LIKE \"张%\" AND `age` > 20"

// SQL模板数据生成
const body = sql.tplBody({ name: '李四', age: 25 }, {
  name: '`name` = {0}',
  age: '`age` = {0}'
});
// 生成: "`name` = '李四', `age` = 25"

// 参数过滤
const filteredParams = sql.filter({ id: 1, name: '张三', password: '123' }, ['password']);
// 结果: { id: 1, name: '张三' }
```

#### 数据库适配器方法

```javascript
// 获取底层数据库适配器
const dbAdapter = sql.db();
// 可用于直接操作底层数据库接口
db.table = "user_account";
const user = await db.get({
  user_id: 1
});
```

### 4. 配置选项

```javascript
const sql = new Sql({
  // 数据库类型
  db_type: 'mysql', // 可选值: 'mysql', 'sqlite'
  
  // 作用域配置
  scope: 'sys', // 默认作用域
  
  // MySQL配置
  host: 'localhost',
  port: 3306,
  user: 'root',
  password: '',
  database: '',
  
  // SQLite配置
  dir: '/db/', // SQLite数据库文件存储目录
  database: 'db.sqlite' // SQLite数据库文件名
});
```

## 高级用法

### 1. SQL模板

```javascript
// 定义SQL模板
const sqlTemplate = {
  name: '`name` LIKE "{0}%"',
  age: '`age` > {0}'
};

// 使用模板构建查询条件
const query = sql.tplQuery({ name: '张', age: 20 }, sqlTemplate);
// 生成的查询条件: "`name` LIKE \"张%\" AND `age` > 20"

// 使用模板构建更新语句
const body = sql.tplBody({ name: '李四', age: 25 }, {
  name: '`name` = {0}',
  age: '`age` = {0}'
});
// 生成的更新语句: "`name` = '李四', `age` = 25"

// 使用配置文件定义SQL模板
const config = {
  "query": {
    "name": "`name` like '%{0}%'"
  },
  "where": {
    "uid": "`uid` = {0}"
  },
  "update": {
    "name": "`name` = {0}"
  }
};

// 使用配置文件中的模板
const queryFromConfig = sql.tplQuery({ name: '张' }, config.query);
```

### 2. 自定义SQL执行

```javascript
// 执行自定义查询SQL
const result = await sql.run('SELECT * FROM users WHERE status = 1');

// 执行自定义更新SQL
const updateResult = await sql.exec('UPDATE users SET status = 0 WHERE id = 1');

// 执行带参数的SQL
const user = await sql.run('SELECT * FROM users WHERE id = ?', [1]);

// 执行带超时的SQL
const timeoutResult = await sql.run('SELECT * FROM users WHERE status = 1', [], 5000);

// 执行事务操作（MySQL）
const mysqlTransactionResult = await sql.exec(`
  START TRANSACTION;
  INSERT INTO users (name, age) VALUES ('测试用户', 30);
  UPDATE users SET status = 1 WHERE id = LAST_INSERT_ID();
  COMMIT;
`);

// 执行事务操作（SQLite）
const sqliteTransactionResult = await sql.exec(`
  BEGIN TRANSACTION;
  INSERT INTO users (name, age) VALUES ('测试用户', 30);
  UPDATE users SET status = 1 WHERE id = last_insert_rowid();
  COMMIT;
`);
```

## 实时模型（Dao）

Dao 是内置的实时模型构建器，用于处理**层级嵌套数据**。定义模型树后，可通过嵌套属性直接修改数据，修改会自动同步到数据库。

### 适用场景

| 场景 | 典型数据层级 | 说明 |
|------|-------------|------|
| 🎮 **游戏开发** | 账户 → 角色 → 背包/道具/属性/技能 | 玩家数据天然多层嵌套，修改道具属性即自动存档 |
| ⚙️ **配置管理** | 项目 → 模块 → 配置项 | 层级化配置，修改深层配置自动持久化 |
| 📝 **CMS系统** | 站点 → 栏目 → 文章 → 评论 | 树形内容结构，编辑嵌套内容自动保存 |
| 🛒 **电商系统** | 用户 → 订单 → 商品 → SKU | 关联数据层级，修改订单商品属性自动同步 |
| 📡 **IoT设备管理** | 网关 → 设备 → 传感器 | 层级设备树，修改传感器配置自动更新 |

### 基本使用

```javascript
const Sql = require('mm_sql/lib/sql.js');
const { Dao } = require('mm_sql/lib/dao.js');

const sql = new Sql({ db_type: 'mysql', ... });
const dao = new Dao(sql);

// 定义模型层级：账户 → 角色 → 道具
// 模型名用作关系名，table 指定实际表名
dao.model('account', {
  table: 'game_account',       // 实际表名（可选，默认等于模型名）
  key: 'username',
  children: {
    role: {
      table: 'game_role',      // 表名带前缀
      key: 'name',
      children: {
        tool: {
          table: 'game_tool',
          key: 'id'
        }
      }
    }
  }
});
```

对应三张表的建表语句：

```sql
CREATE TABLE game_account (
  username VARCHAR(50) PRIMARY KEY,
  password  VARCHAR(100),
  email     VARCHAR(100)
);

CREATE TABLE game_role (
  name              VARCHAR(50) PRIMARY KEY,
  game_account_id   VARCHAR(50),   -- 外键：父表名_id
  level             INT DEFAULT 1,
  exp               INT DEFAULT 0
);

CREATE TABLE game_tool (
  id          VARCHAR(50) PRIMARY KEY,
  game_role_id VARCHAR(50),         -- 外键：父表名_id
  name        VARCHAR(50),
  atk         INT DEFAULT 0,
  def         INT DEFAULT 0
);
```

现在可以像操作普通对象一样修改嵌套属性：

```javascript
const account = await dao.account('player1');

// 模型名用作关系名，table 才是实际表名
account.role['战士'].tool['sword_001'].atk = 100;  // → UPDATE game_tool SET atk=100 WHERE id='sword_001'
account.role['战士'].level = 15;                     // → UPDATE game_role SET level=15 WHERE name='战士'
account.email = 'new@test.com';                      // → UPDATE game_account SET email='new@test.com' WHERE username='player1'
```

### 工作原理

```
dao.account('player1')
  ├─ 查询 account 表 → 获取账户记录
  ├─ 批量查询 role 表（account_id = 'player1'）→ 预加载所有角色
  ├─ 批量查询 tool 表（role_id = '战士'）→ 预加载所有道具
  └─ 返回多层 Proxy 对象

// 修改属性时：
account.role['战士'].tool['sword_001'].atk = 100
  → ① 内存立即更新（同步）
  → ② 串行队列写入数据库（异步，防竞态）
```

### 配置选项

```javascript
dao.model('account', {
  table: 'game_account',       // 实际表名（可选，默认等于模型名）
  key: 'username',             // 主键字段名（必填）
  fk: 'parent_id',             // 外键字段名（可选，默认 父表名_id）
  children: {                  // 子模型定义（可选）
    role: {
      table: 'game_role',
      key: 'name',
      children: { ... }
    }
  }
});
```

### 注意事项

- **预加载机制**：`get()` 会递归预加载所有子孙节点，适合单条记录层级数据，不适合大批量数据
- **写入队列**：同一行的多次修改通过串行队列保证不丢失，但不同行之间并行
- **适用数据量**：单次加载的数据量建议控制在数百条以内，避免预加载开销过大
- **不适用场景**：大批量数据写入请使用 `table().setList()`，复杂 JOIN 查询请使用 `sql.run()`

## 注意事项

1. 系统会自动初始化连接，无需手动调用初始化方法
2. 使用完成后建议调用`close()`方法关闭连接，避免资源泄漏
3. 切换数据库类型时会重新创建适配器，原来的连接会被关闭
4. 不同数据库的SQL语法可能有所差异，请根据实际使用的数据库类型调整SQL语句
5. 事务操作需要根据具体数据库类型使用相应的SQL语法
6. 错误处理：所有方法都包含错误处理，会记录错误日志并抛出异常

## 错误处理

```javascript
try {
  const result = await sql.run('SELECT * FROM non_existent_table');
} catch (error) {
  console.error('SQL执行失败:', error);
  // 错误信息会被自动记录到日志
}
```

## 支持的数据库类型

- MySQL
- SQLite
- JSON（文件存储，适合静态配置数据）

## API参考

### Sql类

#### constructor(config)
创建Sql实例
- `config`: 配置对象

#### run(sql, params, timeout)
执行查询SQL
- `sql`: SQL语句或选项对象
- `params`: 参数数组（可选）
- `timeout`: 超时时间（毫秒，可选）

#### exec(sql, params, timeout)
执行修改SQL
- `sql`: SQL语句或选项对象
- `params`: 参数数组（可选）
- `timeout`: 超时时间（毫秒，可选）

#### open()
手动打开数据库连接

#### close()
手动关闭数据库连接

#### setConfig(config)
动态修改配置
- `config`: 新的配置对象

#### tplQuery(paramDt, sqlDt)
生成SQL查询条件
- `paramDt`: 参数对象
- `sqlDt`: SQL模板对象

#### tplBody(paramDt, sqlDt)
生成SQL数据部分
- `paramDt`: 参数对象
- `sqlDt`: SQL模板对象

#### filter(paramDt, arr)
过滤参数对象
- `paramDt`: 参数对象
- `arr`: 需要过滤的键数组

#### db()
获取底层数据库适配器

### Dao类

#### constructor(sql)
创建 Dao 实例
- `sql`: Sql 实例

#### model(name, options)
注册模型树，同时在 dao 实例上挂载同名方法
- `name`: 模型名（即方法名）
- `options.key`: 主键字段名（必填）
- `options.fk`: 外键字段名（可选，默认 `父表名_id`）
- `options.children`: 子模型定义对象（可选）

```javascript
dao.model('account', {
  key: 'username',
  children: {
    role: { key: 'name', children: { tool: { key: 'id' } } }
  }
});

// 使用注册的方法
const account = await dao.account('player1');
```

#### [name](keyValue)
动态方法，根据 `model()` 注册的名称自动生成。调用 `ModelNode.get(keyValue)` 获取记录及其所有子孙数据。
- `keyValue`: 主键值
- 返回：Proxy 包装对象（不存在返回 null）

## 许可证

MIT

## 工具契约（LLM 可调用）

本模块 `tool/` 下登记以下工具契约，实现位于 `lib/tools/<name>/`，`tool/<name>/index.js` 仅为薄适配层。
其它模块可直接 `require('<pkg>').tools.<name>` 复用实现，无需经过工具注册面。

| 工具名 | 标题 | 说明 |
| --- | --- | --- |
| `dao` | SQL 模板与 DAO 登记 | 模板清单、登记、重载、执行 |
