docs: cursor rules

Author: luoling8192

.cursor/rules/common-package.mdc

@@ -0,0 +1,43 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# Common Package
+
+[packages/common](mdc:packages/common) 是项目的公共包，包含各种共享工具和功能。
+
+## 主要组件
+
+### Composables
+
+[packages/common/src/composable](mdc:packages/common/src/composable) 包含可复用的组合式函数：
+
+- **useConfig.ts**: [packages/common/src/composable/useConfig.ts](mdc:packages/common/src/composable/useConfig.ts) 配置管理函数
+
+### Helper 工具
+
+[packages/common/src/helper](mdc:packages/common/src/helper) 包含各种辅助工具函数：
+
+- **logger.ts**: [packages/common/src/helper/logger.ts](mdc:packages/common/src/helper/logger.ts) 日志记录工具
+- **config-schema.ts**: [packages/common/src/helper/config-schema.ts](mdc:packages/common/src/helper/config-schema.ts) 配置模式定义
+- **default-config.ts**: [packages/common/src/helper/default-config.ts](mdc:packages/common/src/helper/default-config.ts) 默认配置
+
+## Logger 使用
+
+日志工具 `useLogger()` 基于 @guiiai/logg 构建，提供了便捷的日志记录功能：
+
+```ts
+import { useLogger } from 'packages/common'
+
+// 基本使用
+useLogger().log('日志消息')
+
+// 带字段记录
+useLogger().withFields({ user: 'admin', action: 'login' }).info('用户登录')
+
+// 错误记录
+useLogger().withErr(new Error('失败原因')).error('操作失败')
+```
+
+自动收集调用位置信息，无需手动指定日志来源。

.cursor/rules/core-package.mdc

@@ -0,0 +1,30 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# Core Package
+
+[packages/core](mdc:packages/core) 是项目的核心包，负责与 Telegram API 的交互以及数据库操作。
+
+## 主要组件
+
+- **Models**: [packages/core/src/models](mdc:packages/core/src/models) 包含了数据模型定义
+  - [chat-message.ts](mdc:packages/core/src/models/chat-message.ts): 聊天消息模型
+  - [chats.ts](mdc:packages/core/src/models/chats.ts): 聊天会话模型
+  - [common.ts](mdc:packages/core/src/models/common.ts): 通用模型定义
+
+- **Services**: [packages/core/src/services](mdc:packages/core/src/services) 包含核心服务
+  - [connection.ts](mdc:packages/core/src/services/connection.ts): Telegram 连接管理
+  - [message.ts](mdc:packages/core/src/services/message.ts): 消息处理服务
+  - [dialog.ts](mdc:packages/core/src/services/dialog.ts): 对话服务
+  - [session.ts](mdc:packages/core/src/services/session.ts): 会话管理
+
+- **Database**: [packages/core/src/db](mdc:packages/core/src/db) 包含数据库相关代码
+  - [schema.ts](mdc:packages/core/src/db/schema.ts): 数据库表结构
+
+- **事件处理**: [packages/core/src/event-handler.ts](mdc:packages/core/src/event-handler.ts) 和 [packages/core/src/event-handlers](mdc:packages/core/src/event-handlers) 负责事件处理
+
+## 上下文管理
+
+[context.ts](mdc:packages/core/src/context.ts) 提供了应用的上下文管理，包括 Telegram 客户端实例和数据库连接。

.cursor/rules/database-schema.mdc

@@ -0,0 +1,70 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# 数据库结构
+
+数据库使用 PostgreSQL 和 Drizzle ORM。主要表结构定义位于 [packages/core/src/db/schema.ts](mdc:packages/core/src/db/schema.ts)。
+
+## 主要表
+
+### 消息表
+
+[chatMessagesTable](mdc:packages/core/src/db/schema.ts) 存储所有聊天消息。
+
+关键字段：
+- `id`: UUID 主键
+- `platform`: 平台标识 (Telegram)
+- `platform_message_id`: 平台消息 ID
+- `from_id`: 发送者 ID
+- `from_name`: 发送者名称
+- `in_chat_id`: 聊天会话 ID
+- `content`: 消息内容
+- `content_vector_1536/1024/768`: 向量索引，用于语义搜索
+
+### 贴纸表
+
+[stickersTable](mdc:packages/core/src/db/schema.ts) 存储贴纸数据。
+
+关键字段：
+- `id`: UUID 主键
+- `name`: 贴纸名称
+- `emoji`: 关联表情
+- `file_id`: 文件 ID
+- `description`: 描述
+- `description_vector_1536/1024/768`: 向量索引，用于语义搜索
+
+### 贴纸包表
+
+[stickerPacksTable](mdc:packages/core/src/db/schema.ts) 存储贴纸包信息。
+
+### 照片表
+
+[photosTable](mdc:packages/core/src/db/schema.ts) 存储图片数据。
+
+关键字段：
+- `file_id`: 文件 ID
+- `caption`: 图片标题
+- `description`: 描述
+- `description_vector_1536/1024/768`: 向量索引，用于语义搜索
+
+### 聊天会话表
+
+[joinedChatsTable](mdc:packages/core/src/db/schema.ts) 存储已加入的聊天会话。
+
+关键字段：
+- `chat_id`: 会话 ID
+- `chat_name`: 会话名称
+- `chat_type`: 会话类型 (user/channel/group)
+
+## 视图
+
+[chatMessageStatsView](mdc:packages/core/src/db/schema.ts) 提供聊天统计信息，包括每个聊天的消息数量和最新消息时间。
+
+## 向量搜索
+
+数据库支持使用 pgvector 进行向量搜索，各表都有相应的向量字段和索引：
+- 消息内容向量索引
+- 贴纸描述向量索引
+- 图片描述向量索引

.cursor/rules/development-workflow.mdc

@@ -0,0 +1,140 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# 开发工作流
+
+项目使用 pnpm 作为包管理器，采用 monorepo 结构组织代码。开发流程和命令定义在 [package.json](mdc:package.json) 中。
+
+## 环境设置
+
+1. 安装依赖：
+
+```bash
+# 使用 pnpm 安装项目依赖
+pnpm install
+
+# 如果安装了 ni，也可以使用更简洁的命令
+# ni
+```
+
+2. 配置环境：
+
+```bash
+# 复制配置示例
+cp config/config.example.yaml config/config.yaml
+
+# 编辑配置文件，填入 Telegram API 凭据
+```
+
+3. 启动数据库：
+
+```bash
+# 启动 PostgreSQL 容器
+docker compose up -d
+```
+
+4. 初始化数据库：
+
+```bash
+# 运行数据库迁移（使用 pnpm）
+pnpm run db migrate
+
+# 如果安装了 nr，可以使用更简洁的命令
+# nr db migrate
+```
+
+## 开发命令
+
+### 构建
+
+```bash
+# 构建所有包
+pnpm run build
+# 或使用 nr：nr build
+
+# 构建特定包
+pnpm run packages:build
+# 或使用 nr：nr packages:build
+
+# 构建服务器
+pnpm run build:server
+# 或使用 nr：nr build:server
+```
+
+### 开发服务
+
+```bash
+# 启动后端服务
+pnpm run dev:server
+# 或使用 nr：nr dev:server
+
+# 启动前端开发服务器
+pnpm run dev:frontend
+# 或使用 nr：nr dev:frontend
+```
+
+### 数据库操作
+
+```bash
+# 生成迁移
+pnpm run db generate
+# 或使用 nr：nr db generate
+
+# 应用迁移
+pnpm run db migrate
+# 或使用 nr：nr db migrate
+
+# 检查迁移状态
+pnpm run db status
+# 或使用 nr：nr db status
+```
+
+### 代码质量
+
+```bash
+# 运行 ESLint
+pnpm run lint
+# 或使用 nr：nr lint
+
+# 修复 ESLint 问题
+pnpm run lint:fix
+# 或使用 nr：nr lint:fix
+
+# 类型检查
+pnpm run typecheck
+# 或使用 nr：nr typecheck
+
+# 运行测试
+pnpm run test
+# 或使用 nr：nr test
+
+# 生成测试覆盖率报告
+pnpm run test:coverage
+# 或使用 nr：nr test:coverage
+```
+
+### 版本管理
+
+```bash
+# 更新版本号
+pnpm run bump
+# 或使用 nr：nr bump
+
+# 更新依赖版本
+pnpm run bump:deps
+# 或使用 nr：nr bump:deps
+```
+
+## 代码提交
+
+项目使用 Husky 和 lint-staged 确保提交前进行代码检查：
+
+```bash
+# 提交代码
+git add .
+git commit -m "feat: 添加新功能"
+```
+
+提交前会自动运行 ESLint 检查。

.cursor/rules/event-handlers.mdc

@@ -0,0 +1,85 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# 事件处理系统
+
+项目使用基于事件的架构进行模块间通信。事件处理系统实现位于 [packages/core/src/event-handler.ts](mdc:packages/core/src/event-handler.ts) 和 [packages/core/src/event-handlers/](mdc:packages/core/src/event-handlers/) 目录。
+
+## 事件处理器结构
+
+事件处理器负责连接不同服务，并处理它们之间的通信。主要分为两类：
+
+1. **认证事件处理器** (`authEventHandler`): 处理连接和会话相关事件
+2. **连接后事件处理器** (`afterConnectedEventHandler`): 处理认证成功后的事件
+
+## 主要事件处理器
+
+项目包含多个专门的事件处理器模块：
+
+- [auth.ts](mdc:packages/core/src/event-handlers/auth.ts): 处理认证事件
+- [session.ts](mdc:packages/core/src/event-handlers/session.ts): 处理会话事件
+- [message.ts](mdc:packages/core/src/event-handlers/message.ts): 处理消息事件
+- [dialog.ts](mdc:packages/core/src/event-handlers/dialog.ts): 处理对话事件
+- [entity.ts](mdc:packages/core/src/event-handlers/entity.ts): 处理实体事件
+- [takeout.ts](mdc:packages/core/src/event-handlers/takeout.ts): 处理导出事件
+- [storage.ts](mdc:packages/core/src/event-handlers/storage.ts): 处理存储事件
+- [config.ts](mdc:packages/core/src/event-handlers/config.ts): 处理配置事件
+
+## 事件处理流程
+
+1. 初始化核心上下文 (`CoreContext`)
+2. 注册事件处理器
+3. 处理器监听特定事件
+4. 服务发出事件
+5. 处理器接收并处理事件，可能调用其他服务或发出新事件
+
+## 使用方式
+
+### 注册事件处理器
+
+```ts
+import { useEventHandler, authEventHandler, afterConnectedEventHandler } from '@tg-search/core'
+import { useConfig } from '@tg-search/common'
+
+const ctx = createCoreContext()
+const config = useConfig()
+const eventHandler = useEventHandler(ctx, config)
+
+// 注册认证事件处理器
+eventHandler.register(authEventHandler)
+
+// 注册连接后事件处理器
+eventHandler.register(afterConnectedEventHandler)
+```
+
+### 创建自定义事件处理器
+
+```ts
+function customEventHandler(ctx: CoreContext, config: Config): EventHandler {
+  const { emitter } = ctx
+  
+  // 注册事件监听
+  emitter.on('custom:event', (data) => {
+    // 处理事件
+    console.log('收到自定义事件:', data)
+    
+    // 可能发出其他事件
+    emitter.emit('custom:response', { success: true })
+  })
+  
+  return () => {}
+}
+```
+
+## 解析器注册
+
+事件处理系统与解析器注册表集成，用于管理特定类型的解析器：
+
+```ts
+// 在连接后注册解析器
+registry.register('embedding', createEmbeddingResolver())
+registry.register('link', createLinkResolver())
+registry.register('user', createUserResolver())
+```