midway-fatcms 0.0.7 → 0.0.8

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

@@ -1,375 +0,0 @@
----
-name: midway-fatcms-crud
-description: >-
-  帮助用户在 midway-fatcms 项目中使用 CRUD 数据库操作能力（CurdMixService、CurdProService、CrudProQuick、ShardingCrudPro）。
-  支持 MySQL、PostgreSQL、SQL Server 数据库的增删改查、批量插入、Upsert、分表查询、关联数据填充、软删除等特性。
-  当用户需要执行数据库查询、插入、更新、删除操作，或处理分表、字典翻译、用户信息填充时使用本 Skill。
----
-
-# midway-fatcms CRUD 使用指南
-
-## 核心架构
-
-三层架构，从高到低：
-
-```
-CurdMixService (协调层 - 带数据关联/字典翻译)
-  └── CurdProService (核心层 - 带权限/验证/上下文)
-        ├── CrudProQuick (便捷层 - 单表快速操作)
-        ├── ShardingCrudPro (分表层 - 自动路由分表)
-        └── CrudPro (底层引擎 - SQL生成与执行)
-```
-
-**服务选择指南：**
-- 需要字典翻译/用户信息填充 → **CurdMixService**
-- 仅需单表 CURD → **CrudProQuick** via `curdMixService.getBbUtil()` 或 `curdProService.getQuickCrud()`
-- 分表场景 → **ShardingCrudPro** via `curdProService.getShardingCrud()`
-- 配置驱动 CRUD（数据库存 method）→ **CurdMixService.executeCrud()** 或 **CurdProService.executeCrudByCfg()`
-- 自定义 SQL → **CrudProQuick.executeSQL()** 或 **CrudProQuick.executeNativeSQL()`
-
-## 快速开始
-
-### 1. 安装 npm 包
-
-```bash
-npm install midway-fatcms
-```
-
-### 2. 注入服务
-
-```typescript
-import { Provide, Inject } from '@midwayjs/core';
-import { CurdMixService, CurdProService } from 'midway-fatcms';
-import { SqlDbType } from 'midway-fatcms';
-
-@Provide()
-export class MyService {
-  @Inject()
-  curdMixService: CurdMixService;
-
-  @Inject()
-  curdProService: CurdProService;
-}
-```
-
-### 3. 获取 QuickCrud 实例
-
-```typescript
-// 方式1：通过 CurdMixService（推荐，自动注册关联数据处理器）
-const quick = this.curdMixService.getBbUtil('mydb', SqlDbType.mysql, 't_user');
-
-// 方式2：通过 CurdProService
-const quick = this.curdProService.getQuickCrud('mydb', SqlDbType.mysql, 't_user');
-
-// 设置基础配置（软删除、标准字段填充）
-quick.setBaseCfgModel({
-  enableSoftDelete: true,
-  enableStandardUpdateCfg: true,
-});
-```
-
-## 基础 CURD 操作
-
-### 查询类方法
-
-```typescript
-const quick = this.curdMixService.getBbUtil('mydb', SqlDbType.mysql, 't_order');
-
-// 列表查询
-const list = await quick.getList({
-  condition: { status: 'paid', amount: { $gt: 100 } },
-  orderBy: 'created_at DESC',
-  columns: ['id', 'order_no', 'amount'],
-});
-
-// 分页查询
-const page = await quick.getListPage({
-  condition: { status: 'paid' },
-  pageNo: 1,
-  pageSize: 20,
-  orderBy: 'created_at DESC',
-});
-// 返回：{ rows: [], total_count: number }
-
-// 唯一查询（0条返回 null，多条抛出异常）
-const order = await quick.getUniqueOne({
-  condition: { order_no: 'ORD2024001' },
-});
-
-// 存在性判断（比 COUNT 高效）
-const exists = await quick.isExist({
-  condition: { order_no: 'ORD2024001' },
-});
-
-// 统计总数
-const count = await quick.getTotalCount({
-  condition: { status: 'active' },
-});
-```
-
-### 写入类方法
-
-```typescript
-// 插入单条
-const result = await quick.insertObject({
-  data: {
-    order_no: 'ORD001',
-    amount: 199.99,
-    status: 'pending',
-  },
-});
-// 返回：{ insertId, affectedRows }
-
-// 批量插入（效率更高）
-const result = await quick.batchInsert({
-  data: [
-    { order_no: '001', amount: 100 },
-    { order_no: '002', amount: 200 },
-  ],
-});
-
-// 更新（必须带 condition）
-await quick.updateObject({
-  condition: { id: 1 },
-  data: { status: 'completed', updated_at: new Date() },
-});
-
-// 插入或更新（先查询存在性，再决定插入或更新）
-await quick.insertOrUpdate({
-  condition: { order_no: 'ORD001' },
-  data: { order_no: 'ORD001', amount: 150 },
-});
-
-// 原生 Upsert（MySQL: ON DUPLICATE KEY UPDATE，更高效）
-await quick.insertOnDuplicate(
-  { data: { id: 1, order_no: 'ORD001', amount: 150 } },
-  ['id'],  // 唯一列，PostgreSQL/SQL Server 必填
-);
-
-// 删除（受软删除配置影响）
-await quick.deleteObject({
-  condition: { id: 1 },
-});
-```
-
-### 条件操作符
-
-```typescript
-const condition = {
-  // 基础等于
-  status: 'active',
-
-  // 比较操作
-  age: { $gt: 18, $lt: 60 },      // 大于且小于
-  score: { $gte: 60 },             // 大于等于
-  level: { $ne: 'deleted' },       // 不等于
-
-  // 范围操作
-  id: { $in: [1, 2, 3] },         // IN
-  amount: { $between: [100, 500] }, // BETWEEN
-
-  // 模糊查询
-  name: { $like: '张%' },          // 前缀匹配（LIKE '张%'）
-  name: { $likeInclude: '%张三%' }, // 包含匹配（LIKE '%张三%'）
-  name: { $notLike: 'test%' },     // 不匹配前缀
-
-  // NULL 判断
-  deleted_at: { $isNull: true },   // IS NULL
-  phone: { $isNotNull: true },     // IS NOT NULL
-
-  // 逻辑组合
-  $and: [{ status: 'active' }, { age: { $gte: 18 } }],
-  $or: [{ status: 'pending' }, { status: 'processing' }],
-};
-```
-
-## 分表操作
-
-### 获取分表实例
-
-```typescript
-import { ShardingType } from 'midway-fatcms';
-
-// 按月分表（如 t_order_202401, t_order_202402）
-const sharding = this.curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
-  type: ShardingType.MONTH,
-  baseTable: 't_order',
-  timeColumn: 'created_at',
-  autoCreateTable: true,  // 自动创建月表
-});
-
-// 哈希分表（如 t_user_01 ~ t_user_16）
-const sharding = this.curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
-  type: ShardingType.HASH,
-  baseTable: 't_user',
-  shardingColumn: 'user_id',
-  tableCount: 16,
-});
-```
-
-### 分表 CURD
-
-```typescript
-// 插入（自动路由到对应分表）
-await sharding.insert({
-  data: { order_id: '001', amount: 100, created_at: '2024-03-15' },
-});
-
-// 批量插入（自动分组并行写入）
-const result = await sharding.batchInsert({
-  data: [
-    { order_id: '001', created_at: '2024-01-15' }, // → t_order_202401
-    { order_id: '002', created_at: '2024-02-10' }, // → t_order_202402
-  ],
-});
-// 返回：{ totalAffected, tableCount, tableResults }
-
-// 查询（自动合并多表结果）
-const orders = await sharding.query({
-  condition: {
-    status: 'paid',
-    created_at: { $gte: '2024-01-01', $lte: '2024-03-31' },
-  },
-  orderBy: 'created_at DESC', // 时间分表必须传
-});
-
-// 分页查询（跨分表自动处理）
-const page = await sharding.queryPage({
-  condition: { status: 'paid' },
-  pageNo: 1,
-  pageSize: 10,
-  orderBy: 'created_at DESC',
-});
-```
-
-### 分表重要约束
-
-1. **时间分表查询**必须传 `orderBy: '{timeColumn} DESC/ASC'`
-2. **插入/更新/删除**必须在 data 或 condition 中包含分表字段
-3. **批量插入**支持跨分表并行写入
-
-## 关联数据填充
-
-使用 `CurdMixService` 执行配置，自动填充关联数据：
-
-```typescript
-// 配置 columnsRelation
-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 等字段
-```
-
-### 关联类型
-
-| 类型 | 说明 | sourceColumn |
-|------|------|--------------|
-| `dict` | 数据字典 | 字典 value 字段 |
-| `sysCfgEnum` | 系统配置枚举 | 配置 code |
-| `accountBasic` | 用户基本信息 | 用户 ID |
-| `workbenchBasic` | 工作台站点信息 | workbench_code |
-| `linkToCustom` | 自定义表关联 | 关联字段 |
-
-### 独立关联填充
-
-```typescript
-// 对已有数据（如从缓存获取的）执行关联填充
-await this.curdMixService.linkColumnRelationDatas(rows, {
-  columnsRelations: [
-    {
-      relatedType: 'dict',
-      relatedCode: 'OrderStatusEnum',
-      sourceColumn: 'status',
-      targetColumns: [{ from: 'label', to: 'status_text' }],
-    },
-  ],
-});
-```
-
-## 高级配置
-
-### 标准字段自动填充
-
-```typescript
-quick.setBaseCfgModel({
-  // 自动填充 created_by、modified_by 等
-  enableStandardUpdateCfg: true,
-
-  // 查询条件自动注入 created_by（只能查自己的数据）
-  enableStandardUpdateCfgCondition: ['by'],
-});
-```
-
-**自动填充规则：**
-
-| 操作类型 | data 字段 | condition 字段 |
-|---------|-----------|---------------|
-| INSERT | `created_by`, `created_avatar`, `created_nickname`, `created_account_type` | — |
-| UPDATE | `modified_by`, `modified_avatar`, `modified_nickname`, `modified_account_type` | `created_by`, `created_account_type` |
-| DELETE | — | `created_by`, `created_account_type` |
-
-### 软删除
-
-```typescript
-quick.setBaseCfgModel({
-  enableSoftDelete: true,
-});
-
-// 删除时自动执行 UPDATE 设置 deleted_at 和 deleted_by
-await quick.deleteObject({ condition: { id: 1 } });
-
-// 查询时自动追加 condition.deleted_at = 0
-await quick.getList({ condition: { status: 1 } });
-```
-
-### 链式配置
-
-```typescript
-const sharding = this.curdProService
-  .getShardingCrud('mydb', SqlDbType.mysql, {
-    type: ShardingType.MONTH,
-    baseTable: 't_order',
-    timeColumn: 'created_at',
-  })
-  .setBaseCfg({
-    enableStandardUpdateCfg: true,
-    enableSoftDelete: true,
-  });
-```
-
-## 关键规则
-
-1. **sqlTable 必填**：CrudProQuick 构造函数或每个方法调用时必须传入表名
-2. **时间分表查询必须传 orderBy**：格式为 `timeColumn DESC/ASC`
-3. **软删除行为**：启用 `enableSoftDelete` 后，`deleteObject` 执行 UPDATE 而非 DELETE
-4. **insertOnDuplicate 参数**：PostgreSQL/SQL Server 必须传入 `uniqueColumn` 参数
-5. **batchInsert 限制**：`data` 必须是对象数组；`insertId` 只返回第一行的 ID
-
-## 进阶参考
-
-- **完整 API 参考**：[reference.md](reference.md) - 包含条件操作符、配置模型、分表配置、内置函数、错误码等
-- **使用示例大全**：[examples.md](examples.md) - 包含基础查询、分表操作、关联填充、业务场景等