midway-fatcms 0.0.7 → 0.0.9

package/.qoder/skills/midway-fatcms/07-examples.md

@@ -0,0 +1,504 @@
+# 完整示例集
+
+## 基础查询
+
+```typescript
+const quick = this.curdProService.getQuickCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  sqlTable: 't_order',
+});
+
+// 列表查询
+const list = await quick.findList({
+  condition: { status: 'paid' },
+  orderBy: 'created_at DESC',
+});
+
+// 指定列查询
+const list2 = await quick.findList({
+  condition: { status: 'paid' },
+  columns: ['id', 'order_no', 'amount'],
+  orderBy: 'created_at DESC',
+});
+
+// 分页查询
+const page = await quick.findPage({
+  condition: { status: 'paid' },
+  pageNo: 1,
+  pageSize: 20,
+  orderBy: 'created_at DESC',
+});
+console.log(page.rows, page.totalCount);
+
+// 查询单条（不保证唯一性）
+const order = await quick.findOne({
+  condition: { order_no: 'ORD001' },
+});
+
+// 唯一查询（多条时报错，推荐用于唯一索引）
+const order2 = await quick.findUniqueOne({
+  condition: { order_no: 'ORD001' },
+});
+
+// 根据主键 ID 查询单条（内部使用 findUniqueOne）
+const order3 = await quick.findOneById(1);
+const order4 = await quick.findOneById('ORD001');  // 字符串 ID
+
+// 根据主键 ID 列表查询多条
+const orders = await quick.findListByIds([1, 2, 3]);
+const orders2 = await quick.findListByIds(['ORD001', 'ORD002']);
+
+// 存在性判断
+const exists = await quick.isExist({
+  condition: { email: 'test@example.com' },
+});
+
+// 统计总数
+const count = await quick.findCount({
+  condition: { status: 'paid' },
+});
+console.log(count.count);
+```
+
+## 条件查询
+
+```typescript
+// 比较操作
+const adults = await quick.findList({
+  condition: { age: { $gt: 18, $lt: 60 } },
+  orderBy: 'age ASC',
+});
+
+// 大于等于 / 小于等于
+const recentOrders = await quick.findList({
+  condition: {
+    created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-12-31 23:59:59' },
+  },
+  orderBy: 'created_at DESC',
+});
+
+// 不等于
+const activeUsers = await quick.findList({
+  condition: { status: { $ne: 'deleted' } },
+  orderBy: 'id ASC',
+});
+
+// IN 查询
+const selectedOrders = await quick.findList({
+  condition: { id: { $in: [1, 2, 3, 4, 5] } },
+  orderBy: 'id ASC',
+});
+
+// NOT IN 查询
+const otherTypes = await quick.findList({
+  condition: { type: { $nin: ['test', 'demo'] } },
+  orderBy: 'id ASC',
+});
+
+// 范围查询（BETWEEN ... AND）
+const midRange = await quick.findList({
+  condition: { amount: { $range: [100, 500] } },
+  orderBy: 'amount DESC',
+});
+
+// 前缀匹配（LIKE '张%'）
+const zhangUsers = await quick.findList({
+  condition: { name: { $like: '张' } },
+  orderBy: 'name ASC',
+});
+
+// 包含匹配（LIKE '%张三%'）
+const containsName = await quick.findList({
+  condition: { name: { $likeInclude: '张三' } },
+  orderBy: 'name ASC',
+});
+
+// NULL 判断
+const noPhone = await quick.findList({
+  condition: { phone: { $null: true } },
+  orderBy: 'id ASC',
+});
+const hasPhone = await quick.findList({
+  condition: { phone: { $notNull: true } },
+  orderBy: 'id ASC',
+});
+
+// 逻辑或（OR）
+const pendingOrPaid = await quick.findList({
+  condition: {
+    $or: [{ status: 'pending' }, { status: 'paid' }],
+  },
+  orderBy: 'created_at DESC',
+});
+
+// 逻辑与（AND）+ 嵌套 OR
+const complexCondition = await quick.findList({
+  condition: {
+    $and: [
+      { department: 'tech' },
+      { $or: [{ level: 'senior' }, { years: { $gte: 5 } }] },
+    ],
+  },
+  orderBy: 'years DESC',
+});
+
+// 多条件组合
+const results = await quick.findList({
+  condition: {
+    status: 'active',
+    age: { $gte: 18 },
+    city: { $in: ['北京', '上海', '深圳'] },
+    phone: { $notNull: true },
+  },
+  orderBy: 'created_at DESC',
+  columns: ['id', 'name', 'age', 'city'],
+});
+```
+
+## 写入操作
+
+```typescript
+// 插入单条
+const result = await quick.insert({
+  data: { order_no: 'ORD001', amount: 199.99, status: 'pending' },
+});
+console.log(result.insertId, result.affectedRows);
+
+// 批量插入
+const batchResult = await quick.batchInsert({
+  data: [
+    { order_no: '001', amount: 100 },
+    { order_no: '002', amount: 200 },
+    { order_no: '003', amount: 300 },
+  ],
+});
+console.log(batchResult.affectedRows);
+
+// 更新
+await quick.update({
+  condition: { id: 1 },
+  data: { status: 'completed', amount: 299.99 },
+});
+
+// 删除
+await quick.delete({ condition: { id: 1 } });
+
+// 先查再插/更（insertOrUpdate）
+const upsertResult = await quick.insertOrUpdate({
+  condition: { email: 'test@example.com' },
+  data: { email: 'test@example.com', name: '用户', age: 25 },
+});
+console.log(upsertResult.isExist ? '已更新' : '已插入');
+
+// 原生 upsert（单条 SQL 完成）
+await quick.insertOnDuplicateUpdate(
+  { data: { id: 1, name: '用户', age: 25 } },
+  ['id']  // 唯一列，PostgreSQL/SQL Server 必填
+);
+
+// save - 自动判断 INSERT/UPDATE（只需 data）
+await quick.save({ data: { id: 1, name: '用户', age: 25 } });  // 有主键 → 先查后写
+await quick.save({ data: { name: '新用户', age: 20 } });       // 无主键 → 直接插入
+```
+
+## 软删除与恢复
+
+```typescript
+quick.setBaseCfgModel({
+  enableSoftDelete: true,
+});
+
+// 软删除（实际执行 UPDATE ... SET deleted_at=时间戳, deleted_by=用户ID）
+await quick.delete({ condition: { id: 1 } });
+
+// 查询时自动过滤 deleted_at != 0 的记录
+const activeUsers = await quick.findList({
+  condition: { status: 'active' },
+});
+
+// 恢复软删除的记录（重置 deleted_at=0, deleted_by=''）
+await quick.restore({ condition: { id: 1 } });
+
+// 批量恢复
+await quick.restore({ condition: { id: { $in: [1, 2, 3] } } });
+
+// 按条件批量恢复
+await quick.restore({ condition: { status: 'deleted' } });
+```
+
+## 标准字段自动填充
+
+```typescript
+quick.setBaseCfgModel({
+  enableStandardUpdateCfg: true,
+});
+
+// INSERT 自动填充：created_by, created_at, created_nickname 等
+await quick.insert({ data: { name: '张三', age: 20 } });
+
+// UPDATE 自动填充：modified_by, modified_at 等
+await quick.update({
+  condition: { id: 1 },
+  data: { age: 21 },
+});
+```
+
+## 分表操作 - 时间分表
+
+```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',
+    autoCreateTable: true,
+  },
+});
+sharding.setBaseCfg({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+});
+
+// 插入（自动路由到 t_order_202401）
+await sharding.insert({
+  data: { order_id: '001', amount: 100, created_at: '2024-01-15' },
+});
+
+// 批量插入（自动按月分组并行写入）
+const batchResult = await sharding.batchInsert({
+  data: [
+    { order_id: '001', created_at: '2024-01-15' },
+    { order_id: '002', created_at: '2024-02-10' },
+    { order_id: '003', created_at: '2024-03-05' },
+  ],
+});
+console.log(batchResult.totalAffected, batchResult.tableCount);
+
+// 更新（condition 必须包含 timeColumn）
+await sharding.update({
+  condition: { order_id: '001', created_at: '2024-01-15' },
+  data: { status: 'shipped' },
+});
+
+// 删除（condition 必须包含 timeColumn）
+await sharding.delete({
+  condition: { order_id: '001', created_at: '2024-01-15' },
+});
+
+// 分页查询（必须传 orderBy，时间分表必须是 timeColumn DESC/ASC）
+const page = await sharding.findPage({
+  condition: {
+    status: 'paid',
+    created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-03-31 23:59:59' },
+  },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+
+// 列表查询（跨分表自动合并）
+const list = await sharding.findList({
+  condition: {
+    created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-06-30 23:59:59' },
+  },
+  orderBy: 'created_at DESC',
+});
+
+// 无时间条件查询（自动查最近 N 张表，默认 MONTH=3）
+const recentOrders = await sharding.findList({
+  condition: { status: 'paid' },
+  orderBy: 'created_at DESC',
+});
+
+// ============ 按年分表 ============
+const yearlySharding = this.curdProService.getShardingCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  shardingConfig: {
+    type: ShardingType.YEAR,
+    baseTable: 't_log',
+    timeColumn: 'log_date',
+    recentTableCount: 5,  // 查询最近5年
+  },
+});
+
+// ============ 按日分表 ============
+const dailySharding = this.curdProService.getShardingCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  shardingConfig: {
+    type: ShardingType.DAY,
+    baseTable: 't_access_log',
+    timeColumn: 'access_time',
+    recentTableCount: 30,  // 查询最近30天
+  },
+});
+```
+
+## 分表操作 - 哈希分表
+
+```typescript
+const hashSharding = this.curdProService.getShardingCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  shardingConfig: {
+    type: ShardingType.HASH,
+    baseTable: 't_user',
+    shardingColumn: 'user_id',
+    tableCount: 16,  // t_user_01 ~ t_user_16
+  },
+});
+hashSharding.setBaseCfg({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+});
+
+// 插入（根据 user_id 哈希路由到对应分表）
+await hashSharding.insert({
+  data: { user_id: 10001, name: '张三' },
+});
+
+// 查询单个用户（根据 user_id 确定分表）
+const user = await hashSharding.findOne({
+  condition: { user_id: 10001 },
+});
+
+// 全表扫描（无 user_id 时扫描所有分表，必须传 orderBy）
+const allActiveUsers = await hashSharding.findList({
+  condition: { status: 'active' },
+  orderBy: 'user_id ASC',
+});
+```
+
+## 分表 + 软删除
+
+```typescript
+const sharding = this.curdProService
+  .getShardingCrud({
+    sqlDatabase: 'mydb',
+    sqlDbType: SqlDbType.mysql,
+    shardingConfig: {
+      type: ShardingType.MONTH,
+      baseTable: 't_order',
+      timeColumn: 'created_at',
+    },
+  })
+  .setBaseCfg({
+    sqlDatabase: 'mydb',
+    sqlDbType: SqlDbType.mysql,
+    enableSoftDelete: true,
+  });
+
+// 软删除
+await sharding.delete({
+  condition: { order_id: '001', created_at: '2024-03-15' },
+});
+
+// 恢复软删除
+await sharding.restore({
+  condition: { order_id: '001', created_at: '2024-03-15' },
+});
+```
+
+## 原生 SQL
+
+```typescript
+const quick = this.curdProService.getQuickCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  sqlTable: 't_order',
+});
+
+// 框架封装 SQL（参数绑定，更安全）
+const result = await quick.executeSQL(
+  'SELECT COUNT(*) as cnt FROM t_order WHERE status = ?',
+  ['completed']
+);
+
+// 原生 SQL（直接执行，支持泛型）
+const stats = await quick.executeNativeSQL<{ cnt: number }>(
+  'SELECT COUNT(*) as cnt FROM t_order WHERE status = ?',
+  ['completed']
+);
+```
+
+## 链式配置
+
+```typescript
+// CrudProQuick 链式配置
+const quick = this.curdProService.getQuickCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  sqlTable: 't_user',
+});
+quick.setBaseCfgModel({
+  enableSoftDelete: true,
+  enableStandardUpdateCfg: true,
+  maxLimit: 5000,
+});
+
+// ShardingCrudPro 链式配置
+const sharding = this.curdProService
+  .getShardingCrud({
+    sqlDatabase: 'mydb',
+    sqlDbType: SqlDbType.mysql,
+    shardingConfig: {
+      type: ShardingType.MONTH,
+      baseTable: 't_order',
+      timeColumn: 'created_at',
+      autoCreateTable: true,
+      recentTableCount: 6,
+    },
+  })
+  .setBaseCfg({
+    sqlDatabase: 'mydb',
+    sqlDbType: SqlDbType.mysql,
+    enableSoftDelete: true,
+  });
+```
+
+## 关联数据填充
+
+```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: [],
+    },
+    // 站点信息填充
+    {
+      relatedType: 'workbenchBasic',
+      sourceColumn: 'workbench_code',
+      targetColumns: [
+        { from: 'workbench_name', to: 'site_name' },
+      ],
+    },
+  ],
+};
+
+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、site_name 等字段
+```

package/.qoder/skills/midway-fatcms/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: midway-fatcms
+description: >-
+  midway-fatcms 是一个功能完善的 CMS 服务端框架，提供数据库 CRUD 操作、分表查询、
+  数据关联填充、权限验证等能力。支持 MySQL、PostgreSQL、SQL Server。
+  当用户需要执行数据库操作、分表查询、字典翻译、用户信息填充时使用本 Skill。
+---
+
+# midway-fatcms SDK 使用指南
+
+## 简介
+
+midway-fatcms 提供三个层次的 CRUD 操作能力：
+
+| 层次 | 类名 | 用途 | 获取方式 |
+|------|------|------|---------|
+| **便捷层** | `CrudProQuick` | 单表快速操作 | `curdProService.getQuickCrud()` |
+| **分表层** | `ShardingCrudPro` | 自动路由分表 | `curdProService.getShardingCrud()` |
+| **协调层** | `CurdMixService` | 带关联数据填充 | `curdMixService.executeCrud()` |
+
+## 章节导航
+
+| 章节 | 内容 | 适用场景 |
+|------|------|---------|
+| [01-quick-start](./01-quick-start.md) | 快速入门、安装配置 | 首次使用 |
+| [02-crud-quick](./02-crud-quick.md) | CrudProQuick 单表操作 | 基础增删改查 |
+| [03-crud-sharding](./03-crud-sharding.md) | ShardingCrudPro 分表操作 | 分库分表场景 |
+| [04-condition-operators](./04-condition-operators.md) | 条件操作符大全 | 复杂查询条件 |
+| [05-configuration](./05-configuration.md) | 配置模型、返回类型 | 高级配置 |
+| [06-builtin-functions](./06-builtin-functions.md) | 内置函数参考 | 自动字段填充 |
+| [07-examples](./07-examples.md) | 完整示例集 | 参考实现 |
+
+## 快速开始
+
+```typescript
+import { Provide, Inject } from '@midwayjs/core';
+import { CurdProService, SqlDbType } from 'midway-fatcms';
+
+@Provide()
+export class OrderService {
+  @Inject()
+  curdProService: CurdProService;
+
+  async getOrders() {
+    // 1. 获取 CrudProQuick 实例
+    const quick = this.curdProService.getQuickCrud({
+      sqlDatabase: 'mydb',
+      sqlDbType: SqlDbType.mysql,
+      sqlTable: 't_order',
+    });
+
+    // 2. 分页查询
+    const page = await quick.findPage({
+      condition: { status: 'paid' },
+      pageNo: 1,
+      pageSize: 20,
+      orderBy: 'created_at DESC',
+    });
+
+    return {
+      list: page.rows,
+      total: page.totalCount,
+    };
+  }
+}
+```
+
+## 核心特性
+
+- ✅ **三种数据库**：MySQL、PostgreSQL、SQL Server
+- ✅ **类型安全**：完整的 TypeScript 类型支持
+- ✅ **软删除**：自动将 DELETE 转为 UPDATE
+- ✅ **标准字段填充**：自动填充 created_by、modified_by 等
+- ✅ **分表路由**：时间分表、哈希分表、范围分表
+- ✅ **数据关联**：字典翻译、用户信息填充
+- ✅ **原生 SQL**：支持执行自定义 SQL 语句
+
+## 实例复用规则
+
+| 类 | 是否可复用 | 原因 |
+|----|-----------|------|
+| `CrudPro` | ❌ 禁止复用 | 有状态执行器，内部 Context 会累积 |
+| `CrudProQuick` | ✅ 可复用 | 内部每次获取新 CrudPro |
+| `ShardingCrudPro` | ✅ 可复用 | 内部每次获取新 CrudPro |
+
+```typescript
+// ✅ CrudProQuick 可复用
+const quick = this.curdProService.getQuickCrud({...});
+await quick.findList({ condition: {...} });
+await quick.insert({ data: {...} });  // 复用 OK
+
+// ❌ CrudPro 禁止复用
+const crudPro = new CrudPro();
+await crudPro.executeCrudByCfg(req1, cfg1);
+// 禁止再次使用同一个 crudPro 实例！
+```

package/README.md

@@ -102,7 +102,7 @@ const ctx = await crudPro.executeCrudByCfg(reqJson, cfgJson);
 const { rows, total_count } = ctx.getResModelForQueryPage();
 ```
 
-> Full CRUD-Pro documentation: [src/libs/crud-pro/README.md](src/libs/crud-pro/README.md) · Built-in Functions: [src/libs/crud-pro/README_FUNC.md](src/libs/crud-pro/README_FUNC.md)
+> Full CRUD-Pro documentation: [src/libs/crud-pro/README.md](doc/skills/CrudPro使用指南.md) · Built-in Functions: [src/libs/crud-pro/README_FUNC.md](doc/skills/CrudPro内置函数参考.md)
 
 ---
 
@@ -155,7 +155,7 @@ const page = await sharding.queryPage({
 });
 ```
 
-> Full Sharding documentation: [src/libs/crud-sharding/ROUTING_LOGIC.md](src/libs/crud-sharding/ROUTING_LOGIC.md)
+> Full Sharding documentation: [src/libs/crud-sharding/ROUTING_LOGIC.md](doc/skills/分表CRUD使用指南.md)
 
 ---
 
@@ -408,7 +408,7 @@ Business Code
         └── fixSoftDelete()   → Soft delete handling
 ```
 
-> Full service layer documentation: [src/service/curd/README.md](src/service/curd/README.md)
+> Full service layer documentation: [src/service/curd/README.md](doc/skills/Curd服务层.md)
 
 ---
 
@@ -433,7 +433,7 @@ const result = await quick.insertObject({ data: { name: 'Alice', email: 'a@b.com
 const batch = await quick.batchInsert({ data: [{ name: 'A' }, { name: 'B' }] });
 const updated = await quick.updateObject({ condition: { id: 1 }, data: { name: 'Bob' } });
 const deleted = await quick.deleteObject({ condition: { id: 1 } });
-const upserted = await quick.insertOnDuplicate({ data: { id: 1, name: 'A' } }, ['id']);
+const upserted = await quick.insertOnDuplicateUpdate({ data: { id: 1, name: 'A' } }, ['id']);
 
 // Raw SQL
 const rows = await quick.executeSQL('SELECT * FROM t_user WHERE status = ?', ['active']);
@@ -499,7 +499,7 @@ CrudPro provides 30+ built-in functions for `updateCfg`, `validateCfg`, `execute
 
 **Type Check:** `isBasicType`, `isBoolean`, `isString`, `isInteger`, `isNumber`, `isNumeric`, `isValidName`, `isChinesePhone`, `isEmailStrValid`, `pickNumber`
 
-> Full function reference: [src/libs/crud-pro/README_FUNC.md](src/libs/crud-pro/README_FUNC.md)
+> Full function reference: [src/libs/crud-pro/README_FUNC.md](doc/skills/CrudPro内置函数参考.md)
 
 ### Soft Delete
 
@@ -656,10 +656,10 @@ http://127.0.0.1:7002/ns/api/helpers/cryptoAes128CBC?input=123
 
 | Document | Description |
 |----------|-------------|
-| [CRUD-Pro Guide](src/libs/crud-pro/README.md) | Configuration-driven CRUD operations, validation, permissions |
-| [Built-in Functions](src/libs/crud-pro/README_FUNC.md) | 30+ functions: date, compare, utility, type check |
-| [Service Layer Guide](src/service/curd/README.md) | Context injection, soft delete, quick CRUD, sharding, relations |
-| [Sharding Routing Logic](src/libs/crud-sharding/ROUTING_LOGIC.md) | Shard strategies, cross-shard pagination, COUNT cache |
+| [CRUD-Pro Guide](doc/skills/CrudPro使用指南.md) | Configuration-driven CRUD operations, validation, permissions |
+| [Built-in Functions](doc/skills/CrudPro内置函数参考.md) | 30+ functions: date, compare, utility, type check |
+| [Service Layer Guide](doc/skills/Curd服务层.md) | Context injection, soft delete, quick CRUD, sharding, relations |
+| [Sharding Routing Logic](doc/skills/分表CRUD使用指南.md) | Shard strategies, cross-shard pagination, COUNT cache |
 
 ---
 

package/dist/configuration.d.ts

@@ -3,5 +3,15 @@ export declare class ContainerLifeCycle {
     app: koa.Application;
     onConfigLoad(): Promise<any>;
     onReady(): Promise<void>;
+    /**
+     * 初始化表元数据缓存的 Redis Pub/Sub 广播
+     *
+     * - 发布客户端：复用已有的 RedisService 实例
+     * - 订阅客户端：通过 duplicate() 创建独立连接
+     *
+     * 集群部署时，任意节点调用 clearTableMetaCacheWithBroadcast()
+     * 会通过 Redis 广播通知所有节点清空本地缓存。
+     */
+    private initTableMetaCacheRedis;
     private startScheduleOnReady;
 }