midway-fatcms 0.0.7 → 0.0.9

package/.qoder/skills/midway-fatcms/01-quick-start.md

@@ -0,0 +1,231 @@
+# 快速入门
+
+## 安装
+
+```bash
+npm install midway-fatcms
+```
+
+## 服务注入
+
+midway-fatcms 提供两个核心服务：
+
+```typescript
+import { Provide, Inject } from '@midwayjs/core';
+import { CurdMixService, CurdProService } from 'midway-fatcms';
+
+@Provide()
+export class MyService {
+  @Inject()
+  curdMixService: CurdMixService;  // 协调层（带关联填充）
+
+  @Inject()
+  curdProService: CurdProService;  // 核心层
+}
+```
+
+## 数据库类型
+
+```typescript
+import { SqlDbType } from 'midway-fatcms';
+
+// 支持三种数据库
+SqlDbType.mysql      // MySQL
+SqlDbType.postgres   // PostgreSQL
+SqlDbType.sqlserver  // SQL Server
+```
+
+## 三种使用方式
+
+### 方式一：CrudProQuick（推荐入门）
+
+适用于单表 CRUD 操作：
+
+```typescript
+const quick = this.curdProService.getQuickCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  sqlTable: 't_user',
+});
+
+// 查询列表
+const result = await quick.findList({ condition: { status: 1 } });
+console.log(result.rows, result.count);
+
+// 分页查询
+const page = await quick.findPage({
+  condition: { status: 1 },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+console.log(page.rows, page.totalCount);
+
+// 插入
+const insertResult = await quick.insert({
+  data: { name: '张三', age: 20 },
+});
+console.log(insertResult.insertId);
+
+// 更新
+await quick.update({
+  condition: { id: 1 },
+  data: { age: 21 },
+});
+
+// 删除
+await quick.delete({ condition: { id: 1 } });
+```
+
+### 方式二：ShardingCrudPro（分表场景）
+
+适用于按时间、哈希分表的场景：
+
+```typescript
+import { ShardingType } from 'midway-fatcms';
+
+const sharding = this.curdProService.getShardingCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  shardingConfig: {
+    type: ShardingType.MONTH,      // 按月分表
+    baseTable: 't_order',          // 基础表名
+    timeColumn: 'created_at',      // 时间字段
+  },
+});
+
+// 插入（自动路由到 t_order_202401）
+await sharding.insert({
+  data: { order_id: '001', created_at: '2024-01-15' },
+});
+
+// 分页查询（自动合并多表结果）
+const page = await sharding.findPage({
+  condition: { status: 'paid' },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',  // 时间分表必须传
+});
+```
+
+### 方式三：CurdMixService（关联填充）
+
+适用于需要字典翻译、用户信息填充的场景：
+
+```typescript
+const cfgModel = {
+  method: 'order.list',
+  sqlTable: 't_order',
+  sqlSimpleName: 'SIMPLE_QUERY_PAGE',
+  columnsRelation: [
+    // 订单状态字典翻译
+    {
+      relatedType: 'dict',
+      relatedCode: 'OrderStatusEnum',
+      sourceColumn: 'status',
+      targetColumns: [{ from: 'label', to: 'status_text' }],
+    },
+    // 创建者信息填充
+    {
+      relatedType: 'accountBasic',
+      sourceColumn: 'created_by',
+      targetColumns: [],  // 使用默认映射
+    },
+  ],
+};
+
+const ctx = await this.curdMixService.executeCrudByCfg(
+  { condition: {}, pageNo: 1, pageSize: 10, orderBy: 'created_at DESC' },
+  cfgModel
+);
+
+const { rows } = ctx.getResModelForQueryPage();
+// rows 自动包含 status_text、created_by_nickname 等字段
+```
+
+## 常用配置
+
+### 软删除
+
+启用后，DELETE 操作会转为 UPDATE：
+
+```typescript
+quick.setBaseCfgModel({
+  enableSoftDelete: true,
+});
+
+// 实际执行：UPDATE t_user SET deleted_at=?, deleted_by=? WHERE id=1
+await quick.delete({ condition: { id: 1 } });
+
+// 查询时自动追加 deleted_at = 0
+const users = await quick.findList({ condition: { status: 1 } });
+```
+
+### 标准字段自动填充
+
+```typescript
+quick.setBaseCfgModel({
+  enableStandardUpdateCfg: true,
+});
+
+// INSERT 自动填充：created_by, created_at, created_nickname 等
+await quick.insert({ data: { name: '张三' } });
+
+// UPDATE 自动填充：modified_by, modified_at 等
+await quick.update({ condition: { id: 1 }, data: { age: 21 } });
+```
+
+## 条件查询示例
+
+```typescript
+// 简单条件
+{ status: 'active' }
+
+// 比较操作
+{ age: { $gt: 18, $lt: 60 } }
+{ score: { $gte: 60 } }
+
+// 范围操作
+{ id: { $in: [1, 2, 3] } }
+{ amount: { $range: [100, 500] } }
+
+// 模糊查询
+{ name: { $like: '张%' } }          // 前缀匹配
+{ name: { $likeInclude: '张三' } }  // 包含匹配
+
+// NULL 判断
+{ deleted_at: { $null: true } }
+{ phone: { $notNull: true } }
+
+// 逻辑组合
+{
+  $and: [
+    { status: 'active' },
+    { $or: [{ level: 'vip' }, { amount: { $gte: 1000 } }] }
+  ]
+}
+```
+
+## 排序语法
+
+```typescript
+// 字符串格式
+orderBy: 'created_at DESC'
+orderBy: 'created_at DESC, amount ASC'
+
+// 简写格式（+ 升序，- 降序）
+orderBy: 'created_at-'
+orderBy: 'age+,created_at-'
+
+// 数组格式
+orderBy: [
+  { fieldName: 'created_at', orderType: 'DESC' },
+  { fieldName: 'amount', orderType: 'ASC' },
+]
+```
+
+## 下一步
+
+- [CrudProQuick 单表操作](./02-crud-quick.md) - 完整 API 参考
+- [ShardingCrudPro 分表操作](./03-crud-sharding.md) - 分表路由详解
+- [条件操作符大全](./04-condition-operators.md) - 所有支持的查询条件

package/.qoder/skills/midway-fatcms/02-crud-quick.md

@@ -0,0 +1,375 @@
+# CrudProQuick 单表操作
+
+CrudProQuick 是在 CrudPro 之上封装的便捷操作层，提供简洁的 API 进行单表 CRUD 操作。
+
+## 获取实例
+
+```typescript
+const quick = this.curdProService.getQuickCrud({
+  sqlDatabase: 'mydb',           // 数据库名（必填）
+  sqlDbType: SqlDbType.mysql,    // 数据库类型（必填）
+  sqlTable: 't_user',            // 表名（可选，调用时传入）
+});
+```
+
+## API 总览
+
+### 查询方法
+
+| 方法 | 返回类型 | 说明 |
+|------|----------|------|
+| `findOne(req, table?)` | `CrudQueryOneResult<T>` | 查询单条（无顺序保证） |
+| `findUniqueOne(req, table?)` | `CrudQueryOneResult<T>` | 唯一查询（多条报错） |
+| `findList(req, table?)` | `CrudQueryListResult<T>` | 列表查询 |
+| `findPage(req, table?)` | `CrudQueryPageResult<T>` | 分页查询 |
+| `isExist(req, table?)` | `CrudExistResult` | 存在性判断 |
+| `findCount(req, table?)` | `CrudCountResult` | 统计总数 |
+| `findOneById(id, table?)` | `CrudQueryOneResult<T>` | 根据主键 ID 查询单条（多条报错） |
+| `findListByIds(ids, table?)` | `CrudQueryListResult<T>` | 根据主键 ID 列表查询多条 |
+
+### 写入方法
+
+| 方法 | 返回类型 | 说明 |
+|------|----------|------|
+| `insert(req, table?)` | `CrudWriteResult` | 插入单条 |
+| `batchInsert(req, table?)` | `CrudWriteResult` | 批量插入 |
+| `update(req, table?)` | `CrudWriteResult` | 更新 |
+| `delete(req, table?)` | `CrudWriteResult` | 删除 |
+| `restore(req, table?)` | `CrudWriteResult` | 恢复软删除记录（重置 deleted_at/deleted_by） |
+| `insertOrUpdate(req, table?)` | `CrudUpsertResult` | 先查再插/更 |
+| `insertOnDuplicateUpdate(req, uniqueCols?, table?)` | `CrudWriteResult` | 原生 upsert |
+| `save(req, table?)` | `CrudUpsertResult` | 自动判断 INSERT/UPDATE |
+
+### SQL 方法
+
+| 方法 | 返回类型 | 说明 |
+|------|----------|------|
+| `executeSQL(sql, args?)` | `ExecuteSQLResult` | 框架封装 SQL |
+| `executeNativeSQL<T>(sql, args?)` | `ExecuteSQLResult<T>` | 原生 SQL |
+
+---
+
+## 查询方法详解
+
+### findOne - 查询单条
+
+返回第一条匹配记录，不保证顺序：
+
+```typescript
+const result = await quick.findOne({
+  condition: { status: 'active' },
+  orderBy: 'created_at DESC',
+});
+
+if (result.found) {
+  console.log(result.row);
+}
+```
+
+### findUniqueOne - 唯一查询
+
+期望结果为 0 条或 1 条，多条时报错：
+
+```typescript
+const result = await quick.findUniqueOne({
+  condition: { email: 'user@example.com' },
+});
+
+if (result.found) {
+  console.log(result.row);
+}
+// 多条时抛出异常
+```
+
+### findList - 列表查询
+
+```typescript
+const result = await quick.findList({
+  condition: { status: 'active' },
+  orderBy: 'created_at DESC',
+  columns: ['id', 'name', 'email'],
+});
+
+console.log(result.rows, result.count);
+```
+
+### findPage - 分页查询
+
+```typescript
+const page = await quick.findPage({
+  condition: { status: 'active' },
+  pageNo: 1,
+  pageSize: 20,
+  orderBy: 'created_at DESC',
+});
+
+console.log(page.rows, page.totalCount);
+```
+
+### isExist - 存在性判断
+
+```typescript
+const result = await quick.isExist({
+  condition: { email: 'user@example.com' },
+});
+console.log(result.exists);  // true / false
+```
+
+### findCount - 统计总数
+
+```typescript
+const result = await quick.findCount({
+  condition: { status: 'active' },
+});
+console.log(result.count);
+```
+
+### findOneById - 根据主键 ID 查询单条
+
+等价于 `findUniqueOne({ condition: { id } })`，但更简洁。如果查询到多条记录会抛出异常。
+
+```typescript
+// 根据 ID 查询单条
+const result = await quick.findOneById(1);
+if (result.found) {
+  console.log(result.row);
+}
+
+// 字符串 ID
+const result = await quick.findOneById('ORD001', 't_order');
+```
+
+### findListByIds - 根据主键 ID 列表查询多条
+
+等价于 `findList({ condition: { id: { $in: ids } } })`，但更简洁。
+
+```typescript
+// 根据 ID 列表查询
+const result = await quick.findListByIds([1, 2, 3]);
+console.log(result.rows, result.count);
+
+// 字符串 ID 列表
+const result = await quick.findListByIds(['ORD001', 'ORD002'], 't_order');
+```
+
+---
+
+## 写入方法详解
+
+### insert - 插入单条
+
+```typescript
+const result = await quick.insert({
+  data: { name: '张三', email: 'test@example.com', age: 25 },
+});
+console.log(result.insertId, result.affectedRows);
+```
+
+### batchInsert - 批量插入
+
+```typescript
+const result = await quick.batchInsert({
+  data: [
+    { name: '张三', age: 25 },
+    { name: '李四', age: 30 },
+  ],
+});
+console.log(result.affectedRows);
+```
+
+### update - 更新
+
+```typescript
+const result = await quick.update({
+  condition: { id: 1 },
+  data: { name: '张三更新', age: 26 },
+});
+```
+
+### delete - 删除
+
+```typescript
+const result = await quick.delete({
+  condition: { id: 1 },
+});
+```
+
+### restore - 恢复软删除
+
+恢复已软删除的记录，将 `deleted_at` 重置为 0，`deleted_by` 重置为空字符串。需要启用软删除（`setBaseCfgModel({ enableSoftDelete: true })`）。
+
+```typescript
+// 恢复指定 ID 的记录
+await quick.restore({ condition: { id: 1 } });
+
+// 恢复多条记录（使用 $in 操作符）
+await quick.restore({ condition: { id: { $in: [1, 2, 3] } } });
+
+// 按条件批量恢复记录
+await quick.restore({ condition: { status: 'deleted' } });
+```
+
+### insertOrUpdate - 先查再插/更
+
+```typescript
+const result = await quick.insertOrUpdate({
+  condition: { email: 'test@example.com' },
+  data: { email: 'test@example.com', name: '用户' },
+});
+console.log(result.isExist ? '更新' : '插入');
+```
+
+### insertOnDuplicateUpdate - 原生 Upsert
+
+> **前置条件**：目标表必须拥有 UNIQUE 索引（除自增主键外）。
+>
+> `INSERT ON DUPLICATE KEY UPDATE` 只在 UNIQUE 索引或 PRIMARY KEY 冲突时触发 UPDATE。
+> 如果表只有普通索引（KEY/INDEX），MySQL 不会报错，但**永远走 INSERT 路径，不会触发 UPDATE**，且每次调用都会插入新行。
+>
+> ```sql
+> -- 检查表是否有 UNIQUE 索引
+> SELECT DISTINCT INDEX_NAME FROM information_schema.STATISTICS
+> WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'your_table'
+>   AND NON_UNIQUE = 0 AND INDEX_NAME != 'PRIMARY';
+>
+> -- 添加 UNIQUE 索引
+> ALTER TABLE your_table ADD UNIQUE KEY uk_xxx (column_name);
+> ```
+
+```typescript
+const result = await quick.insertOnDuplicateUpdate(
+  { data: { id: 1, name: '用户' } },
+  ['id']  // 唯一列，PostgreSQL/SQL Server 必填
+);
+```
+
+### save - 自动判断 INSERT/UPDATE
+
+只需传入 `data`，无需手动指定 `condition`。方法会自动查询表的主键列，根据 `data` 中是否包含主键值来决定操作：
+
+- **data 包含主键且值不为 null/undefined** → 调用 `insertOrUpdate`（先查后写，存在则更新，不存在则插入）
+- **data 不包含主键或主键值为 null/undefined** → 调用 `insert`（直接插入）
+
+```typescript
+// 有主键 → 先查后写
+await quick.save({ data: { id: 1, name: '张三' } });
+
+// 无主键 → 直接 INSERT
+await quick.save({ data: { name: '李四' } });
+
+// 主键值为 null → 视为无主键，直接 INSERT
+await quick.save({ data: { id: null, name: '王五' } });
+```
+
+> **与 insertOrUpdate 的区别**：`save` 不需要传 `condition`，自动从 `data` 中提取主键组成 `condition`。本质是 `insertOrUpdate` 的便捷版。
+>
+> **性能说明**：首次调用 `save` 时会查询表的主键列信息，结果缓存 24 小时，后续调用无额外开销。
+
+---
+
+## SQL 方法详解
+
+### executeNativeSQL - 原生 SQL
+
+```typescript
+const users = await quick.executeNativeSQL<{ id: number; name: string }[]>(
+  'SELECT id, name FROM t_user WHERE age > ?',
+  [18]
+);
+```
+
+---
+
+## 配置方法
+
+### setBaseCfgModel
+
+```typescript
+quick.setBaseCfgModel({
+  enableSoftDelete: true,         // 启用软删除（delete 设置 deleted_at/deleted_by，而非物理删除）
+  enableStandardUpdateCfg: true,
+  maxLimit: 10000,
+});
+```
+
+启用软删除后，`delete` 操作会设置 `deleted_at`（当前时间戳）和 `deleted_by`（当前用户 ID），查询时自动过滤已删除记录。可通过 `restore` 方法恢复。
+
+---
+
+## 软删除
+
+启用软删除后，数据不会被物理删除，而是标记删除状态：
+
+```typescript
+const quick = this.curdProService.getQuickCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  sqlTable: 't_user',
+});
+
+// 启用软删除
+quick.setBaseCfgModel({ enableSoftDelete: true });
+
+// 软删除（设置 deleted_at 和 deleted_by）
+await quick.delete({ condition: { id: 1 } });
+
+// 恢复软删除记录
+await quick.restore({ condition: { id: 1 } });
+
+// 查询时自动过滤 deleted_at != 0 的记录
+const result = await quick.findList({ condition: { status: 'active' } });
+```
+
+---
+
+## 返回类型
+
+```typescript
+// 写操作结果
+interface CrudWriteResult {
+  affectedRows: number;
+  insertId?: string | number;
+}
+
+// 单条查询结果
+interface CrudQueryOneResult<T> {
+  row: T | null;
+  found: boolean;
+}
+
+// 列表查询结果
+interface CrudQueryListResult<T> {
+  rows: T[];
+  count: number;
+}
+
+// 分页查询结果
+interface CrudQueryPageResult<T> {
+  rows: T[];
+  totalCount: number;
+  count: number;
+}
+
+// 存在性结果
+interface CrudExistResult {
+  exists: boolean;
+}
+
+// 计数结果
+interface CrudCountResult {
+  count: number;
+}
+```
+
+---
+
+## 实例复用
+
+CrudProQuick **可以安全复用**：
+
+```typescript
+const quick = this.curdProService.getQuickCrud({...});
+await quick.findList({ condition: {...} });
+await quick.insert({ data: {...} });
+// 复用 OK！
+```