@seaverse/data-sdk 0.3.0 → 0.3.1

package/README.md

@@ -5,6 +5,22 @@
 
 高性能数据服务 SDK，基于 PostgreSQL/AlloyDB + PostgREST + RLS 架构。
 
+## 🚀 核心概念
+
+### App ID 是什么？
+
+**App ID** 是您在 SeaVerse 平台上创建的应用的唯一标识符。它用于：
+- ✅ 多租户数据隔离（每个应用的数据互不干扰）
+- ✅ 权限控制（RLS 策略基于 app_id）
+- ✅ 资源配额管理
+
+**如何获取 App ID？**
+1. 登录 [SeaVerse 控制台](https://console.seaverse.ai)
+2. 进入"应用管理"
+3. 复制您的 App ID
+
+> ⚠️ **重要**：所有 SDK 操作都需要提供有效的 `appId`，否则无法访问数据。
+
 ## 特性
 
 - ✅ TypeScript 类型支持
@@ -16,6 +32,7 @@
 - ✅ 支持过滤、排序、分页
 - ✅ 支持标签和 JSONB 字段查询
 - ✅ **零配置使用** - 自动从 PostMessage 获取配置
+- ✅ **自动配额限制** - 数据库层强制执行配额，防止资源滥用
 
 ## 安装
 
@@ -25,58 +42,64 @@ npm install @seaverse/data-sdk
 
 ## 快速开始
 
-### 方式 1: 函数式 API（推荐 ⭐）
+### 方式1: 函数式 API（推荐 ⭐）
 
-最简单的使用方式，零配置，自动初始化：
+最简单的使用方式 - 零配置，直接调用函数：
 
 ```typescript
 import { query, create, update, deleteData } from '@seaverse/data-sdk';
 
-// 首次调用会自动初始化 SDK（从 PostMessage 获取 appId 和 token）
+// 第一次调用自动初始化 SDK（从 PostMessage 获取 appId 和 token）
 // 无需任何配置代码！
 
 // 查询数据
 const notes = await query({
   table_name: 'notes',
   filters: { category: 'work' },
-  order: { field: 'created_at', direction: 'desc' },
+  order: { field: 'created_at', direction: 'desc' }
 });
 
 // 创建数据
 const newNote = await create({
   table_name: 'notes',
   data_value: { title: 'My Note', content: '...' },
-  visibility: 'private',
+  visibility: 'private'
 });
 
 // 更新数据
-await update('note-id-123', {
-  data_value: { title: 'Updated' },
+await update(newNote.id, {
+  data_value: { title: 'Updated Title' }
 });
 
 // 删除数据
-await deleteData('note-id-123');
+await deleteData(newNote.id);
 ```
 
-**✨ 为什么推荐函数式 API？**
-
+**为什么推荐函数式 API：**
 - ✅ **零配置** - 无需创建客户端实例，直接调用函数
-- ✅ **自动初始化** - 首次调用自动获取配置（通过 PostMessage）
-- ✅ **简洁易用** - 代码更简洁，AI 更容易理解
+- ✅ **自动初始化** - 第一次调用自动获取配置（PostMessage）
+- ✅ **代码简洁** - 代码更简洁，更易理解
 - ✅ **单例管理** - SDK 自动管理全局实例，避免重复初始化
 
-### 方式 2: DataClient 类 API（高级场景）
+---
 
-适合需要多实例或自定义配置的场景：
+### 方式2: DataClient 类 API（高级场景）
+
+适用于需要多个实例或自定义配置的场景：
 
 ```typescript
 import { DataClient } from '@seaverse/data-sdk';
 
-// 零配置（推荐）
-const client = await DataClient.connect();
+// 方式2a: 零配置（推荐）- 自动从 PostMessage 获取 appId 和 token
+const client = await DataClient.create();
+
+// 方式2b: 只提供 appId，token 自动获取
+const client = await DataClient.create({
+  appId: 'my-app-123',
+});
 
-// 或者指定配置
-const client = await DataClient.connect({
+// 方式2c: 显式提供所有配置
+const client = new DataClient({
   appId: 'my-app-123',
   token: 'user-jwt-token',
 });
@@ -88,12 +111,6 @@ const notes = await client.query({
 });
 ```
 
-**🎯 何时使用 DataClient 类？**
-
-- 需要管理多个应用的实例
-- 需要动态切换 token 或 appId
-- 需要自定义配置（如 baseURL、timeout）
-
 **配置选项说明：**
 
 | 参数 | 类型 | 必需 | 说明 |
@@ -129,61 +146,9 @@ environment?: 'production' | 'staging' | 'development' | 'local'
 
 ## API 文档
 
-### 函数式 API（推荐 ⭐）
-
-零配置，直接导入使用：
+### DataClient 方法
 
-```typescript
-import {
-  query,              // 查询数据
-  get,                // 获取单条数据
-  create,             // 创建数据
-  update,             // 更新数据
-  deleteData,         // 删除单条数据
-  batchDelete,        // 批量删除
-  queryWithPagination,// 分页查询
-  isAdmin,            // 检查管理员权限
-  reinit,             // 重新初始化（切换用户/应用）
-  getClientStatus,    // 获取客户端状态
-} from '@seaverse/data-sdk';
-```
-
-| 函数 | 说明 | 参数 | 返回值 |
-|------|------|------|--------|
-| `query(options)` | 查询数据列表 | `QueryOptions` | `Promise<DataRecord[]>` |
-| `get(id)` | 获取单条数据 | `id: string` | `Promise<DataRecord \| null>` |
-| `create(options)` | 创建数据 | `CreateDataOptions` | `Promise<DataRecord>` |
-| `update(id, options)` | 更新数据 | `id: string`, `UpdateDataOptions` | `Promise<DataRecord>` |
-| `deleteData(id)` | 删除数据 | `id: string` | `Promise<void>` |
-| `batchDelete(ids)` | 批量删除 | `ids: string[]` | `Promise<void>` |
-| `queryWithPagination(options)` | 查询带分页信息 | `QueryOptions` | `Promise<PaginatedResponse<DataRecord>>` |
-| `isAdmin()` | 检查管理员权限 | - | `Promise<boolean>` |
-| `reinit(options?)` | 重新初始化 | `DataClientOptions?` | `Promise<void>` |
-| `getClientStatus()` | 获取客户端状态 | - | `ClientStatus` |
-
-**使用示例：**
-
-```typescript
-// 查询数据
-const notes = await query({ table_name: 'notes' });
-
-// 创建数据
-const note = await create({
-  table_name: 'notes',
-  data_value: { title: 'Hello' },
-});
-
-// 重新初始化（用户登录后切换 token）
-await reinit({ token: newToken });
-
-// 检查初始化状态
-const status = getClientStatus();
-console.log('已初始化:', status.initialized);
-```
-
-### DataClient 类 API（高级场景）
-
-使用 `DataClient.connect()` 创建实例后可用的方法：
+使用 `DataClient.create()` 或 `new DataClient(options)` 创建实例后可用的方法：
 
 | 方法 | 说明 | 参数 | 返回值 |
 |------|------|------|--------|
@@ -461,43 +426,7 @@ const notes = await client.query({ table_name: 'notes' });
 
 ### 无缝接入场景
 
-#### React 应用中使用（推荐：函数式 API）
-
-```typescript
-import { query, create, update } from '@seaverse/data-sdk';
-import { useEffect, useState } from 'react';
-
-function NotesApp() {
-  const [notes, setNotes] = useState([]);
-
-  useEffect(() => {
-    // 直接调用函数，首次调用会自动初始化 SDK
-    loadNotes();
-  }, []);
-
-  const loadNotes = async () => {
-    // 无需初始化，直接使用
-    const data = await query({
-      table_name: 'notes',
-      order: { field: 'created_at', direction: 'desc' },
-    });
-    setNotes(data);
-  };
-
-  const addNote = async (title: string) => {
-    const newNote = await create({
-      table_name: 'notes',
-      data_value: { title },
-      visibility: 'private',
-    });
-    setNotes([newNote, ...notes]);
-  };
-
-  return <div>...</div>;
-}
-```
-
-**React 应用中使用（DataClient 类 - 多实例场景）：**
+#### React 应用中使用
 
 ```typescript
 import { DataClient } from '@seaverse/data-sdk';
@@ -508,15 +437,18 @@ function App() {
 
   useEffect(() => {
     // 应用启动时初始化客户端
-    DataClient.connect({ debug: true }).then(setClient);
+    // SDK 会自动通过 PostMessage 从父页面获取配置
+    DataClient.create({ debug: true }).then(setClient);
   }, []);
 
   const loadNotes = async () => {
     if (!client) return [];
-    return await client.query({
+
+    const notes = await client.query({
       table_name: 'notes',
       order: { field: 'created_at', direction: 'desc' },
     });
+    return notes;
   };
 
   return <div>...</div>;
@@ -573,27 +505,13 @@ window.addEventListener('message', (event) => {
 });
 ```
 
-**iframe 页面（自动获取） - 推荐：函数式 API：**
-
-```typescript
-import { query, create } from '@seaverse/data-sdk';
-
-// 直接使用，SDK 会自动通过 PostMessage 从父页面获取 appId 和 token
-const notes = await query({ table_name: 'notes' });
-
-const newNote = await create({
-  table_name: 'notes',
-  data_value: { title: 'Hello' },
-});
-```
-
-**iframe 页面 - DataClient 类：**
+**iframe 页面（自动获取）：**
 
 ```typescript
 import { DataClient } from '@seaverse/data-sdk';
 
-// 零配置创建客户端
-const client = await DataClient.connect();
+// 零配置创建客户端，SDK 会自动通过 PostMessage 从父页面获取 appId 和 token
+const client = await DataClient.create();
 const notes = await client.query({ table_name: 'notes' });
 ```
 
@@ -628,20 +546,6 @@ export async function getServerSideProps() {
 
 ### 动态更新 Token
 
-**函数式 API（推荐）：**
-
-```typescript
-import { reinit } from '@seaverse/data-sdk';
-
-// 用户登录后，使用新 token
-await reinit({ token: newToken });
-
-// 完全重置（重新从 PostMessage 获取）
-await reinit();
-```
-
-**DataClient 类：**
-
 ```typescript
 // JWT 过期后更新 token
 client.updateToken('new-jwt-token');
@@ -649,31 +553,96 @@ client.updateToken('new-jwt-token');
 
 ### 切换应用
 
-**函数式 API（推荐）：**
-
 ```typescript
-import { reinit } from '@seaverse/data-sdk';
-
 // 切换到其他应用
-await reinit({ appId: 'another-app', token: anotherToken });
+client.updateAppId('another-app-id');
 ```
 
-**DataClient 类：**
+### 配额限制
+
+Data SDK 在数据库层实现了自动配额限制，防止单个应用占用过多资源。
+
+#### 配额说明
+
+SDK 支持以下配额限制（在数据库层通过触发器强制执行，无法绕过）：
+
+| 配额类型 | 默认值 | 说明 |
+|---------|-------|------|
+| 总数据条数 | 100,000 条 | 单个应用的最大数据总量 |
+| 单表数据条数 | 50,000 条 | 单个 table_name 的最大数据量 |
+| 存储空间 | 1 GB | 单个应用的最大存储空间 |
+| 每分钟操作 | 1,000 次 | 防止短时间内大量操作 |
+| 每小时操作 | 10,000 次 | 防止持续高频操作 |
+| 每天操作 | 100,000 次 | 防止每日滥用 |
+
+**配额检查机制：**
+- 创建操作（CREATE）：检查数据总量、单表数据量、存储空间、操作频率
+- 更新操作（UPDATE）：检查存储空间变化、操作频率
+- 删除操作（DELETE）：检查操作频率
+
+超限时会自动抛出错误，操作被拒绝并回滚。
+
+#### 错误处理
 
 ```typescript
-// 切换到其他应用
-client.updateAppId('another-app-id');
+try {
+  await client.create({
+    table_name: 'notes',
+    data_value: { title: 'New Note' },
+  });
+} catch (error) {
+  // 检查是否是配额超限错误
+  if (error.message && error.message.includes('Quota exceeded')) {
+    console.error('配额超限:', error.message);
+    // 示例错误信息：
+    // "Quota exceeded: Total records quota exceeded: 100000/100000 records"
+    // "Quota exceeded: Storage quota exceeded: 1024.5 MB/1024 MB"
+    // "Quota exceeded: Rate limit exceeded: 1234/1000 operations in last minute"
+  } else {
+    console.error('操作失败:', error);
+  }
+}
 ```
 
-### JSONB 字段查询
+#### 平台管理员监控
+
+配额的监控和调整由平台管理员通过数据库查询完成：
+
+```sql
+-- 查看所有应用的使用情况
+SELECT
+  u.app_id,
+  u.total_records,
+  ROUND(u.total_storage_bytes::numeric / 1024 / 1024, 2) as storage_mb,
+  q.max_total_records,
+  ROUND((u.total_records::numeric / q.max_total_records * 100), 2) as usage_percent
+FROM app_usage_stats u
+LEFT JOIN app_quotas q ON u.app_id = q.app_id
+ORDER BY usage_percent DESC;
+
+-- 查找接近配额的应用（预警）
+SELECT app_id, usage_percent
+FROM (
+  SELECT
+    u.app_id,
+    ROUND((u.total_records::numeric / q.max_total_records * 100), 2) as usage_percent
+  FROM app_usage_stats u
+  INNER JOIN app_quotas q ON u.app_id = q.app_id
+) t
+WHERE usage_percent > 80;
+
+-- 为应用调整配额
+UPDATE app_quotas
+SET max_total_records = 500000,
+    max_storage_bytes = 5368709120  -- 5GB
+WHERE app_id = 'your-app-id';
+```
 
-**函数式 API（推荐）：**
+### JSONB 字段查询
 
 ```typescript
-import { query } from '@seaverse/data-sdk';
-
 // 查询 data_value 中的字段
-const results = await query({
+const results = await client.query({
   table_name: 'posts',
   filters: {
     data_value: {
@@ -684,26 +653,11 @@ const results = await query({
 });
 ```
 
-**DataClient 类：**
-
-```typescript
-const results = await client.query({
-  table_name: 'posts',
-  filters: {
-    data_value: { title: 'Hello World', author: 'Alice' },
-  },
-});
-```
-
 ### 标签查询
 
-**函数式 API（推荐）：**
-
 ```typescript
-import { query } from '@seaverse/data-sdk';
-
 // 查询包含指定标签的数据
-const results = await query({
+const results = await client.query({
   table_name: 'posts',
   filters: {
     tags: ['javascript', 'typescript'], // 包含任一标签
@@ -713,13 +667,9 @@ const results = await query({
 
 ### 时间范围查询
 
-**函数式 API（推荐）：**
-
 ```typescript
-import { query } from '@seaverse/data-sdk';
-
 // 查询指定时间范围的数据
-const results = await query({
+const results = await client.query({
   table_name: 'logs',
   filters: {
     created_after: '2026-01-01T00:00:00Z',
@@ -730,13 +680,9 @@ const results = await query({
 
 ### 分页查询
 
-**函数式 API（推荐）：**
-
 ```typescript
-import { queryWithPagination } from '@seaverse/data-sdk';
-
 // 查询带总数的分页数据
-const result = await queryWithPagination({
+const result = await client.queryWithPagination({
   table_name: 'posts',
   pagination: { limit: 10, offset: 0 },
 });
@@ -745,15 +691,6 @@ console.log(`总共 ${result.total} 条，当前返回 ${result.data.length} 条
 console.log(`是否还有更多: ${result.hasMore}`);
 ```
 
-**DataClient 类：**
-
-```typescript
-const result = await client.queryWithPagination({
-  table_name: 'posts',
-  pagination: { limit: 10, offset: 0 },
-});
-```
-
 ## 性能说明
 
 基于新的 RLS 架构，SDK 具有以下性能特性：
@@ -763,22 +700,6 @@ const result = await client.queryWithPagination({
 - ⚡ **短路求值**：优先检查 visibility 和 owner
 - ⚡ **哈希分区**：256 个分区，支持并行查询
 
-## 核心概念
-
-### App ID 是什么？
-
-**App ID** 是您在 SeaVerse 平台上创建的应用的唯一标识符。它用于：
-- ✅ 多租户数据隔离（每个应用的数据互不干扰）
-- ✅ 权限控制（RLS 策略基于 app_id）
-- ✅ 资源配额管理
-
-**如何获取 App ID？**
-1. 登录 [SeaVerse 控制台](https://console.seaverse.ai)
-2. 进入"应用管理"
-3. 复制您的 App ID
-
-> ⚠️ **重要**：所有 SDK 操作都需要提供有效的 `appId`，否则无法访问数据。
-
 ## 架构说明
 
 ### JWT Token 架构
@@ -820,43 +741,6 @@ psql -h <host> -U postgres -d <database> -f init/init-schema.sql
 
 ## 版本历史
 
-### v0.3.0 (2026-01-19)
-
-**🎉 重大功能更新**
-
-- ✅ **新增函数式 API**（推荐使用 ⭐）：提供 `query()`, `create()`, `update()`, `deleteData()` 等零配置便捷函数
-- ✅ **零配置优先**：首次调用函数时自动初始化 SDK（通过 PostMessage 获取配置）
-- ✅ **全局单例管理**：自动懒加载初始化，防止并发初始化问题
-- ✅ **新增 `DataClient.connect()`**：语义更清晰的连接方法（推荐使用，`create()` 保留作为别名）
-- ✅ **新增 `reinit()` 函数**：支持重新初始化（用于切换用户 token 或应用 appId）
-- ✅ **新增 `getClientStatus()` 函数**：查询客户端初始化状态
-
-**使用方式对比：**
-
-```typescript
-// ⭐ 方式 1: 函数式 API（推荐 - 最简单）
-import { query, create } from '@seaverse/data-sdk';
-const notes = await query({ table_name: 'notes' });
-
-// 方式 2: DataClient 类（高级场景 - 多实例）
-import { DataClient } from '@seaverse/data-sdk';
-const client = await DataClient.connect();
-const notes = await client.query({ table_name: 'notes' });
-```
-
-**架构改进：**
-
-- 新增 `src/singleton.ts` - 全局单例管理
-- 新增 `src/api.ts` - 函数式 API 封装
-- 优化 `src/client.ts` - 添加 `connect()` 方法
-- 更新 `src/index.ts` - 统一导出函数式 API 和类 API
-
-**向后兼容：**
-
-- ✅ `DataClient.create()` 方法保留（现为 `connect()` 的别名）
-- ✅ 所有原有的类方法继续支持
-- ✅ 无需修改现有代码，完全向后兼容
-
 ### v0.2.0 (2026-01-15)
 
 **🔄 重大变更（Breaking Changes）**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seaverse/data-sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "SeaVerse Data SDK - PostgreSQL/AlloyDB data operations with RLS-based permissions",
   "keywords": [
     "seaverse",