jinbi-utils 1.0.21 → 1.0.23

package/src/http/apiBuilder/README.md

@@ -1,648 +0,0 @@
-# API Builder (TypeScript)
-
-快速组装后端 JSON 格式请求参数的工具库。
-
-## ✨ 特性
-
-- TypeScript 编写，完整类型支持
-- ESM 模块
-- Knex 风格链式调用
-- 支持查询、新增、更新操作
-
-## 📦 安装
-
-复制 `api-builder.ts` 到你的项目：
-
-```bash
-cp api-builder-ts/api-builder.ts src/utils/
-```
-
-## 🚀 快速开始
-
-### 1. 准备 field_catalog（可选）
-
-从 API 文档中复制 `field_catalog`（后端提供的字段元数据）：
-
-```typescript
-const fieldCatalog = {
-  "sfs_cart.user_id": {
-    type: "number",
-    label: "用户ID",
-    allowed_field: "user_id",
-    nullable: false,
-    dict_field: false
-  },
-  "sfs_cart.goods_id": {
-    type: "number",
-    label: "商品ID",
-    allowed_field: "goods_id",
-    nullable: false,
-    dict_field: false
-  }
-  // ... 其他字段
-};
-```
-
-**注意：** `field_catalog` 是可选的。如果后端不需要这个字段，可以不传。
-
-### 2. 实例化 ApiBuilder
-
-```typescript
-import ApiBuilder from './utils/api-builder';
-
-// 方式 1：传入 fieldCatalog（生成的参数包含 field_catalog）
-const cartApi = new ApiBuilder(fieldCatalog);
-
-// 方式 2：不传 fieldCatalog（生成的参数不包含 field_catalog）
-const simpleApi = new ApiBuilder();
-```
-
-### 3. 开始使用
-
-```typescript
-// 查询
-const params = cartApi.query()
-  .where('user_id', 10086)
-  .where('is_deleted', 0)
-  .orderBy('created_time', 'desc')
-  .limit(20)
-  .build();
-
-// 发送请求
-const response = await axios.post('/api/cart/query', params);
-```
-
-**生成的参数示例：**
-
-```json
-// 传入 fieldCatalog
-{
-  "filters": { "logic": "and", "filters": [...] },
-  "order_by": [...],
-  "limit": 20,
-  "offset": 0,
-  "field_catalog": { ... }  // 包含 field_catalog
-}
-
-// 不传 fieldCatalog
-{
-  "filters": { "logic": "and", "filters": [...] },
-  "order_by": [...],
-  "limit": 20,
-  "offset": 0
-  // 不包含 field_catalog
-}
-```
-
-## 📚 完整 API 文档
-
-### QueryBuilder - 查询构建器
-
-#### 基础 WHERE 条件
-
-```typescript
-// 两参数形式（默认 = 操作符）
-.where('user_id', 10086)
-
-// 三参数形式（指定操作符）
-.where('age', '>', 18)
-.where('price', '>=', 100)
-.where('status', '!=', 0)
-
-// 对象形式（多个 AND 条件）
-.where({ user_id: 10086, is_deleted: 0, status: 1 })
-```
-
-#### OR 条件
-
-```typescript
-// OR WHERE
-.where('status', 1)
-.orWhere('status', 2)
-.orWhere('status', 3)
-
-// 对象形式
-.orWhere({ status: 1, type: 'A' })
-```
-
-#### IN / NOT IN
-
-```typescript
-// WHERE IN
-.whereIn('status', [1, 2, 3])
-
-// WHERE NOT IN
-.whereNotIn('status', [0, -1])
-```
-
-#### LIKE 查询
-
-```typescript
-// WHERE LIKE
-.whereLike('goods_name', '%手机%')
-.whereLike('title', '苹果%')  // 以"苹果"开头
-.whereLike('description', '%优惠')  // 以"优惠"结尾
-```
-
-#### NULL 查询
-
-```typescript
-// WHERE NULL
-.whereNull('deleted_at')
-
-// WHERE NOT NULL
-.whereNotNull('goods_price')
-```
-
-#### BETWEEN
-
-```typescript
-// WHERE BETWEEN
-.whereBetween('price', 100, 500)
-.whereBetween('created_time', '2024-01-01', '2024-12-31')
-```
-
-#### 排序
-
-```typescript
-// 升序（默认）
-.orderBy('created_time')
-
-// 降序
-.orderBy('created_time', 'desc')
-
-// 多个排序
-.orderBy('status', 'asc')
-.orderBy('created_time', 'desc')
-```
-
-#### 分页
-
-```typescript
-// 方式 1：limit + offset
-.limit(20)
-.offset(0)
-
-// 方式 2：paginate（便捷方法）
-.paginate(20, 0)
-```
-
-#### 完整示例
-
-``typescript
-const params = cartApi.query()
-  .where('user_id', 10086)
-  .whereIn('status', [1, 2, 3])
-  .whereLike('goods_name', '%手机%')
-  .whereNotNull('goods_price')
-  .whereBetween('price', 100, 1000)
-  .orderBy('created_time', 'desc')
-  .limit(20)
-  .offset(0)
-  .build();
-```
-
-#### 嵌套过滤条件
-
-对于复杂的查询需求，可以使用嵌套过滤条件来构建更复杂的逻辑结构：
-
-```typescript
-// 使用 whereNested 方法添加嵌套条件
-const params = cartApi.query()
-  .where('orderStatus', 'in', [1, 2])
-  .where('createdBy', '=', 2511261629388069)
-  .whereNested({
-    logic: 'or',
-    filters: [
-      { field: 'orderId', op: 'like', value: 'wwu' },
-      { field: 'goodNameGroup', op: 'like', value: 'wwu' },
-      { field: 'recipientName', op: 'like', value: 'wwu' },
-      { field: 'recipientPhone', op: 'like', value: 'wwu' }
-    ]
-  })
-  .build();
-```
-
-嵌套过滤条件允许构建如下结构的复杂查询：
-
-```
-{
-  "filters": {
-    "logic": "and",
-    "filters": [
-      {
-        "field": "orderStatus",
-        "op": "in",
-        "value": [1, 2]
-      },
-      {
-        "field": "createdBy",
-        "op": "=",
-        "value": 2511261629388069
-      },
-      {
-        "logic": "or",
-        "filters": [
-          {
-            "field": "orderId",
-            "op": "like",
-            "value": "wwu"
-          },
-          {
-            "field": "goodNameGroup",
-            "op": "like",
-            "value": "wwu"
-          },
-          {
-            "field": "recipientName",
-            "op": "like",
-            "value": "wwu"
-          },
-          {
-            "field": "recipientPhone",
-            "op": "like",
-            "value": "wwu"
-          }
-        ]
-      }
-    ]
-  },
-  "order_by": [],
-  "limit": 100,
-  "offset": 0
-}
-```
-
-#### 链式嵌套构建器
-
-为了更方便地构建多层嵌套条件，我们提供了链式嵌套构建器：
-
-```typescript
-// 使用 group 方法创建嵌套组并链式构建条件
-const params = cartApi.query()
-  .where('status', 'in', [1, 2, 3])
-  .group('or')
-    .where('category', '=', 'electronics')
-    .group('and')
-      .where('price', '>=', 100)
-      .group('or')
-        .where('brand', 'like', 'Apple')
-        .where('brand', 'like', 'Samsung')
-      .endGroup()  // 结束第三层嵌套
-    .endGroup()    // 结束第二层嵌套
-  .endGroup()      // 结束第一层嵌套
-  .orderBy('createdTime', 'desc')
-  .limit(20)
-  .build();
-```
-
-这种方式可以构建任意深度的嵌套结构，让复杂查询的构建更加直观和易于维护。
-
-更复杂的嵌套示例：
-
-``typescript
-const params = cartApi.query()
-  .where('userId', '=', 12345)
-  .group('or')
-    .where('orderType', 'in', ['online', 'offline'])
-    .group('and')
-      .where('amount', '>', 1000)
-      .group('or')
-        .where('region', '=', 'north')
-        .group('and')
-          .where('discount', '>', 0.1)
-          .where('vipLevel', '>=', 3)
-        .endGroup()  // 结束第四层嵌套
-      .endGroup()    // 结束第三层嵌套
-    .endGroup()      // 结束第二层嵌套
-  .endGroup()        // 结束第一层嵌套
-  .orderBy('createTime', 'desc')
-  .limit(50)
-  .build();
-```
-
-### InsertBuilder - 新增构建器
-
-#### 单条新增
-
-```typescript
-const params = cartApi.insert()
-  .add({
-    cart_id: 19,
-    user_id: 10086,
-    store_id: 2001,
-    goods_id: 30005,
-    quantity: 6,
-    goods_price: 50,
-    selected: 1
-  })
-  .build();
-```
-
-#### 批量新增
-
-```typescript
-const params = cartApi.insert()
-  .addBatch([
-    { user_id: 10086, goods_id: 30005, quantity: 6 },
-    { user_id: 10086, goods_id: 30006, quantity: 1 },
-    { user_id: 10086, goods_id: 30007, quantity: 3 }
-  ])
-  .build();
-```
-
-### UpdateBuilder - 更新构建器
-
-#### 单条更新
-
-```typescript
-// 对象形式
-const params = cartApi.update()
-  .set({ selected: 1 })
-  .where({ id: 1 })
-  .build();
-
-// 键值对形式
-const params = cartApi.update()
-  .set({ quantity: 5 })
-  .where('id', 1)
-  .build();
-```
-
-#### 多个条件
-
-```typescript
-const params = cartApi.update()
-  .set({ selected: 1 })
-  .where('user_id', 10086)
-  .where('goods_id', 30005)
-  .build();
-```
-
-#### 批量更新
-
-```typescript
-const params = cartApi.update()
-  .set({ selected: 0 })
-  .where({ id: 1 })
-  .and()  // 开始下一个更新操作
-  .set({ is_deleted: 1 })
-  .where({ id: 2 })
-  .and()
-  .set({ quantity: 10 })
-  .where({ id: 3 })
-  .build();
-```
-
-## 💡 实际应用示例
-
-### 购物车服务类
-
-``typescript
-import ApiBuilder from './utils/api-builder';
-import axios from 'axios';
-
-const CART_CATALOG = { /* field_catalog */ };
-
-class CartService {
-  private static api = new ApiBuilder(CART_CATALOG);
-
-  // 查询用户购物车
-  static async getCart(userId: number, page = 1, pageSize = 20) {
-    const params = this.api.query()
-      .where('user_id', userId)
-      .where('is_deleted', 0)
-      .orderBy('created_time', 'desc')
-      .limit(pageSize)
-      .offset((page - 1) * pageSize)
-      .build();
-
-    return axios.post('/api/sfs/cart/query/goods', params);
-  }
-
-  // 搜索商品
-  static async searchGoods(keyword: string) {
-    const params = this.api.query()
-      .whereLike('goods_name', `%${keyword}%`)
-      .where('is_deleted', 0)
-      .whereNotNull('goods_price')
-      .orderBy('created_time', 'desc')
-      .limit(50)
-      .build();
-
-    return axios.post('/api/sfs/cart/query/goods', params);
-  }
-
-  // 查询选中的商品
-  static async getSelectedItems(userId: number) {
-    const params = this.api.query()
-      .where({ user_id: userId, selected: 1, is_deleted: 0 })
-      .orderBy('created_time', 'desc')
-      .build();
-
-    return axios.post('/api/sfs/cart/query/goods', params);
-  }
-
-  // 查询特定状态的商品
-  static async getByStatus(userId: number, statuses: number[]) {
-    const params = this.api.query()
-      .where('user_id', userId)
-      .whereIn('status', statuses)
-      .where('is_deleted', 0)
-      .limit(100)
-      .build();
-
-    return axios.post('/api/sfs/cart/query/goods', params);
-  }
-
-  // 价格区间查询
-  static async getByPriceRange(userId: number, min: number, max: number) {
-    const params = this.api.query()
-      .where('user_id', userId)
-      .whereBetween('goods_price', min, max)
-      .where('is_deleted', 0)
-      .limit(100)
-      .build();
-
-    return axios.post('/api/sfs/cart/query/goods', params);
-  }
-
-  // 添加到购物车
-  static async addToCart(item: {
-    cart_id: number;
-    user_id: number;
-    store_id: number;
-    goods_id: number;
-    quantity: number;
-    goods_price: number;
-  }) {
-    const params = this.api.insert()
-      .add({ ...item, selected: 1 })
-      .build();
-
-    return axios.post('/api/sfs/cart/add', params);
-  }
-
-  // 批量添加
-  static async addBatch(items: any[]) {
-    const params = this.api.insert()
-      .addBatch(items)
-      .build();
-
-    return axios.post('/api/sfs/cart/add', params);
-  }
-
-  // 选中商品
-  static async selectItem(itemId: number) {
-    const params = this.api.update()
-      .set({ selected: 1 })
-      .where({ id: itemId })
-      .build();
-
-    return axios.post('/api/sfs/cart/update', params);
-  }
-
-  // 更新数量
-  static async updateQuantity(itemId: number, quantity: number) {
-    const params = this.api.update()
-      .set({ quantity })
-      .where({ id: itemId })
-      .build();
-
-    return axios.post('/api/sfs/cart/update', params);
-  }
-
-  // 删除商品（逻辑删除）
-  static async deleteItem(itemId: number) {
-    const params = this.api.update()
-      .set({ is_deleted: 1 })
-      .where({ id: itemId })
-      .build();
-
-    return axios.post('/api/sfs/cart/update', params);
-  }
-
-  // 批量删除
-  static async deleteBatch(itemIds: number[]) {
-    const builder = this.api.update();
-    
-    itemIds.forEach((id, index) => {
-      if (index > 0) builder.and();
-      builder.set({ is_deleted: 1 }).where({ id });
-    });
-
-    return axios.post('/api/sfs/cart/update', builder.build());
-  }
-}
-
-// 使用示例
-const cart = await CartService.getCart(10086, 1, 20);
-const searchResults = await CartService.searchGoods('手机');
-await CartService.selectItem(123);
-await CartService.deleteItem(456);
-```
-
-## 🎯 使用技巧
-
-### 1. fieldCatalog 可选
-
-如果后端不需要 `field_catalog` 字段，可以不传：
-
-```typescript
-// 不传 fieldCatalog
-const api = new ApiBuilder();
-
-const params = api.query()
-  .where('user_id', 10086)
-  .limit(20)
-  .build();
-
-// 生成的参数不包含 field_catalog
-// { filters: {...}, order_by: [], limit: 20, offset: 0 }
-```
-
-### 2. 为不同的表创建不同的实例
-
-```typescript
-const cartApi = new ApiBuilder(CART_CATALOG);
-const orderApi = new ApiBuilder(ORDER_CATALOG);
-const userApi = new ApiBuilder(USER_CATALOG);
-
-// 或者不传 fieldCatalog
-const simpleApi = new ApiBuilder();
-```
-
-### 3. 在服务类中使用
-
-```typescript
-class CartService {
-  private static api = new ApiBuilder(); // 不传 fieldCatalog
-
-  static getCart(userId: number) {
-    return this.api
-      .query()
-      .where("user_id", userId)
-      .where("is_deleted", 0)
-      .limit(20)
-      .build();
-  }
-
-  static addToCart(item: any) {
-    return this.api.insert().add(item).build();
-  }
-
-  static updateItem(itemId: number, data: any) {
-    return this.api.update().set(data).where({ id: itemId }).build();
-  }
-}
-```
-
-### 4. 组合查询条件
-
-``typescript
-// 根据条件动态构建查询
-const builder = cartApi.query().where('user_id', userId);
-
-if (keyword) {
-  builder.whereLike('goods_name', `%${keyword}%`);
-}
-
-if (minPrice) {
-  builder.where('goods_price', '>=', minPrice);
-}
-
-if (maxPrice) {
-  builder.where('goods_price', '<=', maxPrice);
-}
-
-const params = builder.limit(20).build();
-```
-
-## 🔄 向后兼容
-
-旧的静态方法仍然支持：
-
-``typescript
-// 旧用法
-ApiBuilder.query(fieldCatalog).where('user_id', '=', 10086).build();
-ApiBuilder.insert(fieldCatalog).add({...}).build();
-ApiBuilder.update(fieldCatalog).set({...}).where({...}).build();
-
-// 新用法（推荐）
-const api = new ApiBuilder(fieldCatalog);
-api.query().where('user_id', 10086).build();
-api.insert().add({...}).build();
-api.update().set({...}).where({...}).build();
-```
-
-## 💪 优势
-
-1. **代码简洁** - 实例化一次，多次使用
-2. **类型安全** - TypeScript 完整类型支持
-3. **易于上手** - 类似 Knex.js 的语法
-4. **灵活强大** - 支持各种查询条件
-5. **向后兼容** - 不破坏现有代码
-
-## 🎉 开始使用
-
-复制 `api-builder.ts` 到你的项目，开始享受简洁的 API 构建体验！