doc：完善doc

docs/plugins/api/database-api.md

@@ -0,0 +1,258 @@
+# 数据库API
+
+数据库API模块提供通用的数据库操作功能，支持查询、创建、更新和删除记录，采用Peewee ORM模型。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import database_api
+```
+
+## 主要功能
+
+### 1. 通用数据库查询
+
+#### `db_query(model_class, query_type="get", filters=None, data=None, limit=None, order_by=None, single_result=False)`
+执行数据库查询操作的通用接口
+
+**参数：**
+- `model_class`：Peewee模型类，如ActionRecords、Messages等
+- `query_type`：查询类型，可选值: "get", "create", "update", "delete", "count"
+- `filters`：过滤条件字典，键为字段名，值为要匹配的值
+- `data`：用于创建或更新的数据字典
+- `limit`：限制结果数量
+- `order_by`：排序字段列表，使用字段名，前缀'-'表示降序
+- `single_result`：是否只返回单个结果
+
+**返回：**
+根据查询类型返回不同的结果：
+- "get"：返回查询结果列表或单个结果
+- "create"：返回创建的记录
+- "update"：返回受影响的行数
+- "delete"：返回受影响的行数
+- "count"：返回记录数量
+
+### 2. 便捷查询函数
+
+#### `db_save(model_class, data, key_field=None, key_value=None)`
+保存数据到数据库（创建或更新）
+
+**参数：**
+- `model_class`：Peewee模型类
+- `data`：要保存的数据字典
+- `key_field`：用于查找现有记录的字段名
+- `key_value`：用于查找现有记录的字段值
+
+**返回：**
+- `Dict[str, Any]`：保存后的记录数据，失败时返回None
+
+#### `db_get(model_class, filters=None, order_by=None, limit=None)`
+简化的查询函数
+
+**参数：**
+- `model_class`：Peewee模型类
+- `filters`：过滤条件字典
+- `order_by`：排序字段
+- `limit`：限制结果数量
+
+**返回：**
+- `Union[List[Dict], Dict, None]`：查询结果
+
+### 3. 专用函数
+
+#### `store_action_info(...)`
+存储动作信息的专用函数
+
+## 使用示例
+
+### 1. 基本查询操作
+
+```python
+from src.plugin_system.apis import database_api
+from src.common.database.database_model import Messages, ActionRecords
+
+# 查询最近10条消息
+messages = await database_api.db_query(
+    Messages,
+    query_type="get",
+    filters={"chat_id": chat_stream.stream_id},
+    limit=10,
+    order_by=["-time"]
+)
+
+# 查询单条记录
+message = await database_api.db_query(
+    Messages,
+    query_type="get",
+    filters={"message_id": "msg_123"},
+    single_result=True
+)
+```
+
+### 2. 创建记录
+
+```python
+# 创建新的动作记录
+new_record = await database_api.db_query(
+    ActionRecords,
+    query_type="create",
+    data={
+        "action_id": "action_123",
+        "time": time.time(),
+        "action_name": "TestAction",
+        "action_done": True
+    }
+)
+
+print(f"创建了记录: {new_record['id']}")
+```
+
+### 3. 更新记录
+
+```python
+# 更新动作状态
+updated_count = await database_api.db_query(
+    ActionRecords,
+    query_type="update",
+    filters={"action_id": "action_123"},
+    data={"action_done": True, "completion_time": time.time()}
+)
+
+print(f"更新了 {updated_count} 条记录")
+```
+
+### 4. 删除记录
+
+```python
+# 删除过期记录
+deleted_count = await database_api.db_query(
+    ActionRecords,
+    query_type="delete",
+    filters={"time__lt": time.time() - 86400}  # 删除24小时前的记录
+)
+
+print(f"删除了 {deleted_count} 条过期记录")
+```
+
+### 5. 统计查询
+
+```python
+# 统计消息数量
+message_count = await database_api.db_query(
+    Messages,
+    query_type="count",
+    filters={"chat_id": chat_stream.stream_id}
+)
+
+print(f"该聊天有 {message_count} 条消息")
+```
+
+### 6. 使用便捷函数
+
+```python
+# 使用db_save进行创建或更新
+record = await database_api.db_save(
+    ActionRecords,
+    {
+        "action_id": "action_123",
+        "time": time.time(),
+        "action_name": "TestAction",
+        "action_done": True
+    },
+    key_field="action_id",
+    key_value="action_123"
+)
+
+# 使用db_get进行简单查询
+recent_messages = await database_api.db_get(
+    Messages,
+    filters={"chat_id": chat_stream.stream_id},
+    order_by="-time",
+    limit=5
+)
+```
+
+## 高级用法
+
+### 复杂查询示例
+
+```python
+# 查询特定用户在特定时间段的消息
+user_messages = await database_api.db_query(
+    Messages,
+    query_type="get",
+    filters={
+        "user_id": "123456",
+        "time__gte": start_time,  # 大于等于开始时间
+        "time__lt": end_time      # 小于结束时间
+    },
+    order_by=["-time"],
+    limit=50
+)
+
+# 批量处理
+for message in user_messages:
+    print(f"消息内容: {message['plain_text']}")
+    print(f"发送时间: {message['time']}")
+```
+
+### 插件中的数据持久化
+
+```python
+from src.plugin_system.base import BasePlugin
+from src.plugin_system.apis import database_api
+
+class DataPlugin(BasePlugin):
+    async def handle_action(self, action_data, chat_stream):
+        # 保存插件数据
+        plugin_data = {
+            "plugin_name": self.plugin_name,
+            "chat_id": chat_stream.stream_id,
+            "data": json.dumps(action_data),
+            "created_time": time.time()
+        }
+        
+        # 使用自定义表模型（需要先定义）
+        record = await database_api.db_save(
+            PluginData,  # 假设的插件数据模型
+            plugin_data,
+            key_field="plugin_name",
+            key_value=self.plugin_name
+        )
+        
+        return {"success": True, "record_id": record["id"]}
+```
+
+## 数据模型
+
+### 常用模型类
+系统提供了以下常用的数据模型：
+
+- `Messages`：消息记录
+- `ActionRecords`：动作记录
+- `UserInfo`：用户信息
+- `GroupInfo`：群组信息
+
+### 字段说明
+
+#### Messages模型主要字段
+- `message_id`：消息ID
+- `chat_id`：聊天ID
+- `user_id`：用户ID
+- `plain_text`：纯文本内容
+- `time`：时间戳
+
+#### ActionRecords模型主要字段
+- `action_id`：动作ID
+- `action_name`：动作名称
+- `action_done`：是否完成
+- `time`：创建时间
+
+## 注意事项
+
+1. **异步操作**：所有数据库API都是异步的，必须使用`await`
+2. **错误处理**：函数内置错误处理，失败时返回None或空列表
+3. **数据类型**：返回的都是字典格式的数据，不是模型对象
+4. **性能考虑**：使用`limit`参数避免查询大量数据
+5. **过滤条件**：支持简单的等值过滤，复杂查询需要使用原生Peewee语法
+6. **事务**：如需事务支持，建议直接使用Peewee的事务功能