midway-fatcms 0.0.6 → 0.0.7

package/src/service/curd/README.md

@@ -824,7 +824,30 @@ await sharding.insert({
 
 ### linkColumnRelationDatas
 
-独立于 CRUD 操作，直接对已有数据行执行关联填充：
+独立于 CRUD 操作，直接对已有数据行执行关联填充。适用于数据来自缓存、外部接口或其他非 CurdMixService 渠道，但仍需要字典翻译、用户信息等关联数据的场景。
+
+> ⚠️ 该方法会**原地修改** `rows` 数组中的对象，不会返回新数组。
+
+#### 方法签名
+
+```typescript
+linkColumnRelationDatas(rows: any[], param: ILinkColumnRelationParam): Promise<void>
+```
+
+#### 参数接口
+
+```typescript
+interface ILinkColumnRelationParam {
+  columnsRelations: ColumnRelation[];  // 关联配置数组
+}
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `rows` | `any[]` | 待填充的数据行数组；为空或非数组时直接返回 |
+| `param.columnsRelations` | `ColumnRelation[]` | 关联规则配置，与 CRUD 配置中的 `columnsRelation` 格式一致 |
+
+#### 基础用法
 
 ```typescript
 // 场景：从缓存或其他来源获取了数据行，仍需要关联填充
@@ -840,9 +863,85 @@ await curdMixService.linkColumnRelationDatas(rows, {
     },
   ],
 });
-// rows 中的每行会自动追加 sex_text 字段
+// rows 中的每行会原地追加 sex_text 字段
 ```
 
+#### 多关联类型组合
+
+```typescript
+const rows = await redisCache.get('order_list');
+
+await curdMixService.linkColumnRelationDatas(rows, {
+  columnsRelations: [
+    // 字典翻译
+    {
+      relatedType: 'dict',
+      relatedCode: 'OrderStatus',
+      sourceColumn: 'status',
+      targetColumns: [
+        { from: 'label', to: 'status_text' },
+        { from: 'color', to: 'status_color' },
+      ],
+    },
+    // 系统配置枚举
+    {
+      relatedType: 'sysCfgEnum',
+      relatedCode: 'PayMethod',
+      sourceColumn: 'pay_method',
+      targetColumns: [
+        { from: 'label', to: 'pay_method_info.label' },
+        { from: 'style', to: 'pay_method_info.style' },
+      ],
+    },
+    // 用户信息填充
+    {
+      relatedType: 'accountBasic',
+      sourceColumn: 'created_by',
+      targetColumns: [],  // 空 = 使用默认映射
+    },
+    // 工作台信息
+    {
+      relatedType: 'workbenchBasic',
+      sourceColumn: 'workbench_code',
+      targetColumns: [
+        { from: 'workbench_domain', to: 'workbench_info.workbench_domain' },
+        { from: 'workbench_name', to: 'workbench_info.workbench_name' },
+      ],
+    },
+  ],
+});
+```
+
+#### 与 CrudProQuick 配合使用
+
+```typescript
+const quick = curdProService.getQuickCrud('mydb', SqlDbType.mysql, 't_order');
+
+// 先用 CrudProQuick 获取原始数据（不带关联）
+const rows = await quick.getList({
+  condition: { status: 'paid' },
+});
+
+// 再用 linkColumnRelationDatas 补充关联数据
+await curdMixService.linkColumnRelationDatas(rows, {
+  columnsRelations: [
+    {
+      relatedType: 'dict',
+      relatedCode: 'OrderStatus',
+      sourceColumn: 'status',
+      targetColumns: [{ from: 'label', to: 'status_text' }],
+    },
+    {
+      relatedType: 'accountBasic',
+      sourceColumn: 'created_by',
+      targetColumns: [],
+    },
+  ],
+});
+```
+
+> **提示**：如果 CRUD 操作本身就需要关联填充，建议直接使用 `CurdMixService.executeCrudByCfg()` 配置 `columnsRelation`，一步完成查询和填充。`linkColumnRelationDatas` 适用于数据已存在的二次填充场景。
+
 ## ColumnRelation 配置
 
 ```typescript