@devflow-cc/react/README.md

一个功能强大的React库，用于构建数据驱动的应用程序，支持实时通信、身份验证和数据库操作

# @devflow-cc/react

一个功能强大的 React 库，用于构建数据驱动的应用程序，支持实时通信、身份验证和数据库操作。

## 🏗️ 模块架构

DevFlow 采用模块化设计，提供清晰的功能分离：

### 核心模块

- **`devflow.auth`** - 认证模块（登录、注册、用户信息管理）
- **`devflow.users`** - 用户管理模块（管理员功能）
- **`devflow.data`** - 数据操作模块（CRUD 操作）
- **`devflow.table`** - 表管理模块（表结构管理）
- **`devflow.audit`** - 审计日志模块（操作记录）
- **`devflow.websocket`** - 实时通信模块（WebSocket）

### 简化接口

- **`devflow.from()`** - 数据操作简化写法
- **`devflow.schema`** - 表管理简化写法（兼容旧版本）

## 🔧 最新更新

### v1.2.1

- ✅ **参数传递统一**: 统一使用 request_body 传递所有参数，包括分页参数
- ✅ **后端 API 优化**: 移除 Query 参数，简化后端代码逻辑
- ✅ **前端删除方法增强**: 支持 hard_delete 参数，支持软删除和硬删除
- ✅ **API 文档更新**: 更新参数传递方式说明，确保前后端对齐

### v1.2.0

- ✅ **TypeScript 重构**: 完全使用 TypeScript 重写，提供完整的类型安全
- ✅ **模块化架构**: 将大型文件拆分为小的模块，提高代码可维护性
- ✅ **数据模块优化**: 合并 DataModule 和 QueryBuilder，简化架构
- ✅ **客户端架构优化**: 合并 DevFlowClient 和 Factory，简化文件结构
- ✅ **文件命名优化**: 重命名 devflow-client.ts 为 client.ts，更简洁
- ✅ **文件结构优化**: 重命名 http-client.ts 为 http.ts，client.ts 提升到 src 根目录
- ✅ **Context 优化**: 重命名 context 目录为 provider，提供 React Provider 支持
- ✅ **Token 存储优化**: 支持自定义 token 存储键名，默认使用 localStorage 和'devflow-token'
- ✅ **新增用户管理模块**: 支持完整的用户 CRUD 操作
- ✅ **新增用户列表查询、激活/停用、角色设置功能**
- ✅ **分离认证模块和用户管理模块**: 避免功能冲突
- ✅ **新增管理员创建用户、重置密码等功能**
- ✅ **优化 API 设计**: 区分用户自己的操作和管理员操作
- ✅ **新增审计日志模块**: 支持完整的审计功能
- ✅ **新增表管理功能**: 支持表名验证和前缀配置
- ✅ **完善用户管理参数说明和响应格式**
- ✅ **新增 WebSocket 实时通信功能**
- ✅ **统一表结构管理 API 命名规范**

## 📦 安装

```bash
npm install @devflow-cc/react
```

## 🚀 快速开始

### 基础使用

```javascript
import { createClient, devflow } from "@devflow-cc/react";

const client = createClient({
  baseURL: "http://localhost:8000",
  apiVersion: "v1",
  timeout: 10000,
  language: "zh",
});

// 使用数据操作
const result = await client.data.from("users").eq("status", "active").select();
```

### 关于 baseURL 与 apiVersion

- baseURL 仅填写服务根地址（协议+主机+端口），不要包含 `/api` 路径。
- 实际请求地址由库自动拼接：`{baseURL}/api/{apiVersion}`。
- 示例：当 `baseURL = 'http://114.55.144.154'` 且 `apiVersion = 'v1'` 时，请求会发往 `http://114.55.144.154/api/v1`。

```javascript
// 正确
devflow.setConfig({ baseURL: "http://114.55.144.154", apiVersion: "v1" });

// 不推荐（会导致路径变为 http://.../api/v1/api/v1）
// devflow.setConfig({ baseURL: 'http://114.55.144.154/api/v1' });
```

### 运行时动态更新配置（即时生效）

`devflow.setConfig()` 现在会在任何配置更新后，自动重建内部 HTTP 客户端与模块，确保如 `baseURL`、`apiVersion`、`headers`、`timeout` 等变更立即生效。

```javascript
// 初始化后可随时切换后端地址或版本
devflow.setConfig({ baseURL: "http://localhost:8000" });
// ... 一段时间后
devflow.setConfig({ baseURL: "http://114.55.144.154", apiVersion: "v2" });
```

### Token 存储配置

DevFlow 默认将 token 存储在 localStorage 中，键名为 `devflow-token`。你可以通过 `tokenKey` 配置自定义键名：

### 错误处理配置

DevFlow 提供了强大的错误处理机制，支持自定义错误处理器和自动重试功能：

```javascript
import { createClient } from "@devflow-cc/react";

// 自定义错误处理器
const customErrorHandler = (error) => {
  console.error("请求错误:", {
    message: error.detail,
    code: error.error_code,
    status: error.status_code,
    timestamp: error.timestamp,
  });

  // 根据错误类型执行不同处理逻辑
  switch (error.status_code) {
    case 401:
      // 处理未授权错误
      console.log("需要重新登录");
      break;
    case 403:
      // 处理权限不足错误
      console.log("权限不足");
      break;
    case 500:
      // 处理服务器错误
      console.log("服务器错误，请稍后重试");
      break;
    default:
      console.log("其他错误");
  }
};

const client = createClient({
  baseURL: "http://localhost:8000",
  apiVersion: "v1",
  timeout: 10000,
  language: "zh",
  errorHandler: {
    onError: customErrorHandler,
    retry: 3, // 自动重试3次
  },
});

// 动态更新错误处理器
client.config.setErrorHandler((error) => {
  console.log("新的错误处理器:", error.detail);
}, 2);

// 清除错误处理器
client.config.clearErrorHandler();
```

**错误处理特性：**

- ✅ **自定义错误处理器**: 可以设置自定义的错误处理函数
- ✅ **自动重试机制**: 支持配置重试次数，使用指数退避策略
- ✅ **错误分类处理**: 根据 HTTP 状态码执行不同的处理逻辑
- ✅ **动态更新**: 可以在运行时动态更新错误处理器
- ✅ **错误信息国际化**: 支持多语言错误消息

```javascript
// 创建客户端时配置
const client = createClient({
  baseURL: "http://localhost:8000",
  tokenKey: "myapp-auth-token", // 自定义token键名
});

// 或者动态更新配置
devflow.setConfig({
  tokenKey: "custom-token-key",
});
```

### React Provider 使用

```jsx
import { DevFlowProvider, useDevFlow } from "@devflow-cc/react";

function App() {
  return (
    <DevFlowProvider
      config={{
        baseURL: "http://localhost:8000",
        tokenKey: "myapp-token",
      }}
    >
      <MyComponent />
    </DevFlowProvider>
  );
}

function MyComponent() {
  const { client } = useDevFlow();

  const handleLogin = async () => {
    const result = await client.auth.signInWithPassword({
      username: "user",
      password: "password",
    });
  };

  return <button onClick={handleLogin}>登录</button>;
}
```

### 2. 身份验证

```typescript
// 登录
const { data, error } = await devflow.auth.signInWithPassword({
  username: "your-username",
  password: "your-password",
});

if (data) {
  console.log("登录成功:", data.user);
} else {
  console.error("登录失败:", error);
}

// 注册
const { data, error } = await devflow.auth.signUp({
  username: "new-user",
  email: "user@example.com",
  password: "password123",
  full_name: "New User",
});

// 获取当前用户信息
const { data, error } = await devflow.auth.getUser();

// 更新自己的用户信息
const { data, error } = await devflow.auth.updateUser({
  full_name: "Updated Name",
  bio: "Updated bio",
});

// 修改密码
const { data, error } = await devflow.auth.changePassword({
  current_password: "oldpassword",
  new_password: "newpassword",
});
```

### 3. 用户管理（管理员功能）

```typescript
// 获取用户列表
const { items, total, page, page_size } = await devflow.users.getUsers({
  page: 1,
  page_size: 20,
  search: "john",
  is_active: true,
  role: "user",
});

// 获取用户详情
const { data, error } = await devflow.users.getUser("user-id");

// 管理员创建用户
const { data, error } = await devflow.users.createUser({
  username: "newuser",
  email: "newuser@example.com",
  password: "password123",
  full_name: "New User",
  is_active: true,
});

// 管理员更新用户
const { data, error } = await devflow.users.updateUser("user-id", {
  full_name: "Updated Name",
  is_active: false,
  bio: "Updated bio",
});

// 删除用户
const { error } = await devflow.users.deleteUser("user-id");

// 激活用户
const { data, error } = await devflow.users.activateUser("user-id");

// 停用用户
const { data, error } = await devflow.users.deactivateUser("user-id");

// 设置用户角色
const { data, error } = await devflow.users.setUserRoles("user-id", [
  "admin",
  "user",
]);

// 重置用户密码
const { data, error } = await devflow.users.resetUserPassword(
  "user-id",
  "newpassword"
);
```

### 4. 审计日志模块

```typescript
// 获取审计日志列表
const { data, error } = await devflow.audit.getLogs({
  user_id: "user-id",
  action: "user_login",
  resource_type: "user",
  status: "success",
  page: 1,
  page_size: 20,
});

// 获取我的审计日志
const { data, error } = await devflow.audit.getMyLogs({
  days: 30,
  action: "data_insert",
  page: 1,
  page_size: 20,
});

// 获取用户活动摘要
const { data, error } = await devflow.audit.getActivitySummary({
  user_id: "user-id",
  days: 30,
});

// 获取系统审计统计
const { data, error } = await devflow.audit.getSystemStats({
  days: 7,
});
```

### 5. 数据操作

DevFlow 提供了两种数据操作方式：

#### 方式一：简化写法（推荐）

```typescript
// 基础查询
const { items, total, page, pageSize } = await devflow
  .from("users")
  .eq("status", "active")
  .order("created_at", "desc")
  .select(["id", "name", "email"]);

// 分页查询
const { items, total, page, pageSize } = await devflow
  .from("users")
  .eq("status", "active")
  .order("created_at", "desc")
  .page(1, 10)
  .select();

// 获取单条记录
const { data, error } = await devflow.from("users").get("user-id");

// 插入数据
const { data, error } = await devflow.from("users").insert({
  username: "newuser",
  email: "newuser@example.com",
  full_name: "New User",
});

// 更新数据
const { data, error } = await devflow.from("users").eq("id", "user-id").update({
  full_name: "Updated Name",
});

// 删除数据（软删除）
const { data, error } = await devflow
  .from("users")
  .eq("status", "deleted")
  .delete();

// 删除数据（硬删除）
const { data, error } = await devflow
  .from("users")
  .eq("status", "deleted")
  .delete(false, true); // confirmAll=false, hardDelete=true
```

#### 方式二：模块化写法

```typescript
// 使用数据模块
const { items, total } = await devflow.data
  .from("users")
  .eq("status", "active")
  .select(["id", "name", "email"]);

// 插入数据
const { data, error } = await devflow.data.from("users").insert({
  username: "newuser",
  email: "newuser@example.com",
});

// 更新数据
const { data, error } = await devflow.data
  .from("users")
  .eq("id", "user-id")
  .update({
    full_name: "Updated Name",
  });

// 删除数据（软删除）
const { data, error } = await devflow.data
  .from("users")
  .eq("status", "deleted")
  .delete();

// 删除数据（硬删除）
const { data, error } = await devflow.data
  .from("users")
  .eq("status", "deleted")
  .delete(false, true); // confirmAll=false, hardDelete=true
```

**操作方法（终止方法）**：

- `insert()` - 插入数据
- `update()` - 更新数据
- `delete(confirmAll?, hardDelete?)` - 删除数据（支持软删除和硬删除）
- `select()` - 查询数据
- `get()` - 获取单条记录

### 6. 表结构管理

```typescript
// 创建表
const { data, error } = await devflow.table.createTable({
  name: "products",
  columns: [
    { name: "id", type: "uuid", primary_key: true },
    { name: "name", type: "varchar", length: 255, not_null: true },
    { name: "price", type: "decimal", precision: 10, scale: 2 },
    { name: "category_id", type: "uuid", foreign_key: "categories.id" },
  ],
});

// 获取表列表
const { data, error } = await devflow.table.getTables({
  page: 1,
  page_size: 20,
  search: "user",
});

// 获取表信息
const { data, error } = await devflow.table.getTableInfo("users");

// 更新表结构
const { data, error } = await devflow.table.updateTable("users", {
  add_columns: [{ name: "avatar", type: "varchar", length: 500 }],
  modify_columns: [{ name: "email", type: "varchar", length: 100 }],
});

// 删除表
const { data, error } = await devflow.table.deleteTable("temp_table");

// 获取表统计信息
const { data, error } = await devflow.table.getTableStats("users");

// 验证表名是否合法
const { data, error } = await devflow.table.validateTableName("my_table");

// 获取表前缀配置信息
const { data, error } = await devflow.table.getTablePrefixInfo();
```

### 7. WebSocket 实时通信

```typescript
// 建立WebSocket连接
const ws = devflow.websocket.connect({
  token: "your-jwt-token",
  onMessage: (data) => {
    console.log("收到实时数据:", data);
  },
  onError: (error) => {
    console.error("WebSocket错误:", error);
  },
  onClose: () => {
    console.log("WebSocket连接已关闭");
  },
});

// 订阅表变更
ws.subscribe("users", (data) => {
  console.log("users表数据变更:", data);
});

// 取消订阅
ws.unsubscribe("users");

// 关闭连接
ws.close();
```

## 🏗️ 架构设计

### 模块化结构

```
src/
├── core/                 # 核心模块
│   ├── config.ts        # 配置管理
│   └── http-client.ts   # HTTP客户端
├── modules/             # 功能模块
│   ├── auth.ts         # 认证模块
│   ├── users.ts        # 用户管理模块
│   ├── audit.ts        # 审计日志模块
│   ├── query-builder.ts # 数据查询构建器
│   ├── table.ts        # 表管理模块
│   └── websocket.ts    # WebSocket模块
├── client/             # 客户端
│   ├── devflow-client.ts # 主客户端类
│   └── factory.ts      # 工厂函数和单例
├── types/              # 类型定义
│   └── index.ts        # 所有类型定义
└── index.ts            # 主入口文件
```

### 核心特性

1. **TypeScript 支持**: 完整的类型安全，提供优秀的开发体验
2. **模块化设计**: 每个功能模块独立，便于维护和扩展
3. **智能过滤**: 自动忽略空值条件，提高代码简洁性
4. **标准字段管理**: 自动管理标准字段，避免用户误操作
5. **国际化支持**: 内置多语言支持
6. **错误处理**: 统一的错误处理机制
7. **实时通信**: WebSocket 实时数据推送
8. **审计日志**: 完整的操作审计功能

## 🧪 测试

```bash
# 运行所有测试
npm test

# 运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 运行端到端测试
npm run test:e2e

# 运行真实API测试
npm run test:real-api
```

## 📦 构建

```bash
# 开发模式构建
npm run dev

# 生产模式构建
npm run build

# 类型检查
npm run type-check
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 🚀 新功能

- **TypeScript 重构**: 完全使用 TypeScript 重写，提供完整的类型安全
- **模块化架构**: 将大型文件拆分为小的模块，提高代码可维护性
- **用户管理模块**: 添加完整的用户 CRUD 操作
- **审计日志模块**: 添加完整的审计功能
- **表管理模块**: 添加完整的表结构管理功能
- **WebSocket 模块**: 添加实时通信功能

### 📊 测试统计

- **总测试用例**: 111 个
- **语句覆盖率**: 98.37%
- **分支覆盖率**: 92.85%
- **函数覆盖率**: 95.74%
- **行覆盖率**: 99.14%

### 🔧 重要 API 变更

- **统一 API 设计**: 所有操作方法都采用前置调用方式，条件在前，操作在后
- **select 作为终止方法**: 将 `select()` 改为终止方法，移除 `query()` 方法
- **链式调用规则**: `insert()`, `update()`, `delete()`, `select()`, `get()` 必须在链式调用最后调用
- **错误消息格式**: 统一错误消息格式，包含 HTTP 状态码

## 📄 许可证

MIT License

## 🔗 相关链接

- [GitHub 仓库](https://github.com/wss-git/devflowbase)
- [问题反馈](https://github.com/wss-git/devflowbase/issues)
- [文档](https://github.com/wss-git/devflowbase#readme)

## �� 支持

如果你遇到任何问题或有疑问，请：

1. 查看[问题反馈](https://github.com/wss-git/devflowbase/issues)
2. 创建新的 Issue
3. 联系作者: wssgryx@163.com

## 📋 标准字段列表

- `id` - 主键 ID（自动生成）
- `created_by` - 创建者 ID（自动设置）
- `created_at` - 创建时间（自动设置）
- `updated_by` - 更新者 ID（自动设置）
- `updated_at` - 更新时间（自动设置）
- `deleted_by` - 删除者 ID（软删除时自动设置）
- `deleted_at` - 删除时间（软删除时自动设置）