Initial commit of akmon project

components/supadb/SIMPLIFIED_API_GUIDE.md

@@ -0,0 +1,155 @@
+# AkSupa 简化API指南
+
+## 概述
+
+AkSupa 现在采用了**简化的单一方法**设计：只提供 `executeAs<T>()` 方法进行类型安全的数据访问，移除了所有冗余的类型转换方法。
+
+## 重要变化
+
+### 🚫 已移除的方法
+- `selectAs<T>()`
+- `insertAs<T>()`
+- `updateAs<T>()`
+- `deleteAs<T>()`
+- `rpcAs<T>()`
+
+### ✅ 统一的方法
+- `executeAs<T>()` - 唯一的类型转换方法
+
+## 设计理念
+
+### 简洁性原则
+- **一个方法解决所有问题**：所有查询操作最终都要调用 `execute()`，`executeAs<T>()` 是其类型安全版本
+- **减少API复杂性**：不需要记住多个不同的方法名
+- **保持一致性**：无论是查询、插入、更新还是删除，都使用相同的方法
+
+### 链式友好
+```typescript
+// 所有操作都遵循相同的模式
+const result = await supa
+  .from('table')
+  .operation() // select(), insert(), update(), delete(), rpc()
+  .conditions() // eq(), gt(), like(), etc.
+  .executeAs<T>(); // 统一的类型转换方法
+```
+
+## 使用示例
+
+### 查询数据
+```typescript
+// 多条记录
+const users = await supa
+  .from('users')
+  .select('*')
+  .eq('status', 'active')
+  .executeAs<User[]>();
+
+// 单条记录
+const user = await supa
+  .from('users')
+  .select('*')
+  .eq('id', 1)
+  .single()
+  .executeAs<User>();
+```
+
+### 插入数据
+```typescript
+const newUser = await supa
+  .from('users')
+  .insert({
+    name: 'John',
+    email: 'john@example.com'
+  })
+  .executeAs<User>();
+```
+
+### 更新数据
+```typescript
+const updatedUser = await supa
+  .from('users')
+  .update({ name: 'Jane' })
+  .eq('id', 1)
+  .executeAs<User>();
+```
+
+### 删除数据
+```typescript
+const deletedUser = await supa
+  .from('users')
+  .delete()
+  .eq('id', 1)
+  .executeAs<User>();
+```
+
+### RPC调用
+```typescript
+const result = await supa
+  .from('any_table')
+  .rpc('my_function', { param1: 'value1' })
+  .executeAs<ResultType>();
+```
+
+## 平台兼容性
+
+| 平台 | 类型转换机制 | 说明 |
+|------|-------------|------|
+| Android | `UTSJSONObject.parse<T>()` | 真正的类型转换 |
+| HarmonyOS | `UTSJSONObject.parse<T>()` | 真正的类型转换 |
+| Web/iOS | `as T` | 类型断言 |
+
+## 从旧版本迁移
+
+### 旧代码
+```typescript
+// 旧方式 - 多个方法
+const users = await supa.selectAs<User[]>('users', null, { limit: 10 });
+const newUser = await supa.insertAs<User>('users', userData);
+const updated = await supa.updateAs<User>('users', filter, updateData);
+```
+
+### 新代码
+```typescript
+// 新方式 - 统一方法
+const users = await supa
+  .from('users')
+  .select('*')
+  .limit(10)
+  .executeAs<User[]>();
+
+const newUser = await supa
+  .from('users')
+  .insert(userData)
+  .executeAs<User>();
+
+const updated = await supa
+  .from('users')
+  .update(updateData)
+  .eq('id', userId)
+  .executeAs<User>();
+```
+
+## 优势
+
+1. **API简洁**：只需要记住一个方法
+2. **类型安全**：TypeScript 编译时检查
+3. **平台兼容**：Android/HarmonyOS 使用真正的类型转换
+4. **链式友好**：与现有的链式方法无缝集成
+5. **维护性强**：单一方法，减少维护成本
+
+## 注意事项
+
+1. **泛型类型**：确保传入正确的类型参数 `<T>`
+2. **错误处理**：检查 `result.error` 和 `result.data` 的有效性
+3. **性能考虑**：Android 平台的类型转换有轻微性能开销
+4. **调试模式**：开发时会有转换过程的控制台输出
+
+## 总结
+
+通过采用单一的 `executeAs<T>()` 方法，AkSupa 现在提供了：
+- 更简洁的API
+- 更好的类型安全
+- 更一致的使用体验
+- 更容易维护的代码
+
+这个设计遵循了"简单就是美"的原则，让开发者能够更专注于业务逻辑而不是API的复杂性。