Cursor rule

1---
2alwaysApply: true
3---
4 
5# Telegram Search - Architecture & Development Guide
6 
7## 项目概述
8 
9这是一个把 Telegram 消息导入、导出到数据库中并提供搜索的服务。支持向量搜索和语义匹配，基于 OpenAI 的语义向量技术。
10 
11## Monorepo 结构
12 
13项目采用 pnpm workspace 管理，包含以下包：
14 
15### Apps
16 
17- **[apps/web](mdc:apps/web)**: 前端应用
18  - Vue 3 + Pinia + Vue Router
19  - 支持浏览器模式（PGlite）和服务器模式（PostgreSQL）
20  - 主入口：[apps/web/src/main.ts](mdc:apps/web/src/main.ts)
21  - 布局：[apps/web/src/layouts/default.vue](mdc:apps/web/src/layouts/default.vue)
22  
23- **[apps/server](mdc:apps/server)**: WebSocket 服务器
24  - 实时双向通信
25  - 事件路由和会话管理
26  - WebSocket 实现：[apps/server/src/ws](mdc:apps/server/src/ws)
27 
28### Packages
29 
30- **[packages/core](mdc:packages/core)**: 核心业务逻辑
31  - CoreContext 事件总线：[packages/core/src/context.ts](mdc:packages/core/src/context.ts)
32  - 事件处理器：[packages/core/src/event-handlers](mdc:packages/core/src/event-handlers)
33  - 服务层：[packages/core/src/services](mdc:packages/core/src/services)
34  - 消息解析器：[packages/core/src/message-resolvers](mdc:packages/core/src/message-resolvers)
35  - 数据库模型：[packages/core/src/models](mdc:packages/core/src/models)
36  - 数据库 Schema：[packages/core/src/schemas](mdc:packages/core/src/schemas)
37 
38- **[packages/client](mdc:packages/client)**: 客户端集成层
39  - WebSocket 适配器：[packages/client/src/adapters/websocket.ts](mdc:packages/client/src/adapters/websocket.ts)
40  - Core Bridge 适配器：[packages/client/src/adapters/core-bridge.ts](mdc:packages/client/src/adapters/core-bridge.ts)
41  - 客户端事件处理器：[packages/client/src/event-handlers](mdc:packages/client/src/event-handlers)
42  - Pinia Stores：[packages/client/src/stores](mdc:packages/client/src/stores)
43  - 组合式函数：[packages/client/src/composables](mdc:packages/client/src/composables)
44 
45- **[packages/common](mdc:packages/common)**: 共享工具
46  - 日志封装：使用 @guiiai/logg
47  - 通用工具函数
48 
49## 核心架构模式
50 
51### 事件驱动架构
52 
53整个系统基于事件驱动架构，使用 EventEmitter3 作为核心：
54 
55#### CoreContext（[packages/core/src/context.ts](mdc:packages/core/src/context.ts)）
56 
57- **ToCoreEvent**: 发送到核心系统的事件（如 `auth:login`, `message:query`）
58- **FromCoreEvent**: 从核心系统发出的事件（如 `message:data`, `auth:status`）
59- **Event Wrapping**: 自动错误处理和日志记录
60- **Session Management**: 每个客户端会话有独立的 CoreContext 实例
61 
62#### 事件流程
63 
64```
65Frontend (Vue Component)
66  ↓ 用户操作
67Client Store (Pinia)
68  ↓ sendEvent via WebSocket Adapter
69WebSocket Server
70  ↓ 路由事件
71CoreContext (Event Bus)
72  ↓ 分发到对应的
73Event Handler
74  ↓ 调用
75Service (Business Logic)
76  ↓ 执行操作（Telegram API / Database）
77  ↓ emit 结果事件
78CoreContext
79  ↓ 通过 WebSocket
80Client Event Handler
81  ↓ 更新
82Client Store
83  ↓ 响应式更新
84Frontend (UI Update)
85```
86 
87### 核心事件处理器
88 
89位于 [packages/core/src/event-handlers](mdc:packages/core/src/event-handlers)：
90 
91- **auth.ts**: 认证流程（登录、验证码、密码）
92- **message.ts**: 消息查询和处理
93- **dialog.ts**: 对话列表管理
94- **storage.ts**: 消息同步和存储
95- **entity.ts**: 用户、频道、群组信息
96- **config.ts**: 配置管理
97- **session.ts**: 会话管理
98- **gram-events.ts**: Telegram 事件监听
99- **message-resolver.ts**: 消息解析协调
100- **takeout.ts**: 大量数据导出
101 
102### 服务层
103 
104位于 [packages/core/src/services](mdc:packages/core/src/services)：
105 
106每个服务对应一个事件处理器，处理具体的业务逻辑。服务通过 CoreContext 发送和接收事件。
107 
108### 消息处理管道
109 
110位于 [packages/core/src/message-resolvers](mdc:packages/core/src/message-resolvers)：
111 
112- **embedding-resolver.ts**: 生成向量嵌入（OpenAI/Ollama）
113- **jieba-resolver.ts**: 中文分词
114- **link-resolver.ts**: 链接提取和处理
115- **media-resolver.ts**: 媒体文件处理
116- **user-resolver.ts**: 用户引用处理
117 
118消息通过多个 resolver 流式处理，每个 resolver 负责一个特定方面。
119 
120## 数据库
121 
122### ORM 和迁移
123 
124- **ORM**: Drizzle ORM
125- **Schema 定义**: [packages/core/src/schemas](mdc:packages/core/src/schemas)
126- **迁移文件**: [drizzle](mdc:drizzle)
127- **配置**: [drizzle.config.ts](mdc:drizzle.config.ts)
128 
129### 数据库支持
130 
1311. **PostgreSQL + pgvector**: 生产环境，完整向量搜索
1322. **PGlite**: 浏览器模式，实验性功能
133 
134### 主要表
135 
136- `chat_messages`: 消息主表
137- `chat_message_stats`: 消息统计
138- `joined_chats`: 已加入的聊天
139- `photos`: 照片资源
140- `stickers`: 贴纸
141- `sticker_packs`: 贴纸包
142- `recent_sent_stickers`: 最近发送的贴纸
143 
144## Telegram 集成
145 
146### 客户端管理
147 
148使用 [packages/core/src/context.ts](mdc:packages/core/src/context.ts) 进行 Telegram 客户端的上下文管理：
149 
150```typescript
151// 设置客户端
152ctx.setClient(telegramClient)
153 
154// 获取客户端（确保已设置）
155const client = ctx.getClient()
156```
157 
158### 重要细节
159 
160- **Message ID**: 递增的，优先使用 Message ID 而不是时间戳
161- **Telegram API**: 使用 gram.js 库
162- **事件监听**: 通过 GramEventsHandler 监听 Telegram 实时事件
163 
164## 日志系统
165 
166使用 @guiiai/logg，在 [packages/common](mdc:packages/common) 封装。
167 
168### 使用方式
169 
170```typescript
171import { useLogger } from '@guiiai/logg'
172 
173// 基本日志
174useLogger().log('Message')
175 
176// 带字段
177useLogger().withFields({ userId: 123 }).log('User action')
178 
179// 错误日志
180useLogger().withError(error).error('Operation failed')
181```
182 
183## 包管理
184 
185### 工具
186 
187- **包管理器**: pnpm
188- **Workspace**: pnpm workspace
189- **快捷命令**: 可使用 `ni` 和 `nr` (如果安装了 ni 工具)
190 
191### 常用脚本
192 
193查看 [package.json](mdc:package.json) 中的 scripts：
194 
195```bash
196# 开发模式
197pnpm run dev              # 浏览器模式（带 Core）
198pnpm run web:dev          # 仅前端
199pnpm run server:dev       # 仅后端
200 
201# 启动完整服务
202pnpm run start            # 后端 + 前端预览
203 
204# 构建
205pnpm run build            # 构建前端（浏览器模式）
206pnpm run web:build        # 构建前端（服务器模式）
207pnpm run packages:build   # 构建所有 packages
208 
209# 数据库
210pnpm run db:generate      # 生成迁移文件
211 
212# 代码质量
213pnpm run lint             # ESLint 检查
214pnpm run lint:fix         # 自动修复
215pnpm run typecheck        # 类型检查
216pnpm run test run         # 运行测试
217```
218 
219## 配置文件
220 
221### 环境配置
222 
223- **浏览器模式**: `.env` 文件
224  - `VITE_TELEGRAM_API_ID`
225  - `VITE_TELEGRAM_API_HASH`
226 
227- **服务器模式**: 通过环境变量配置，由 `.env` / `.env.local` 加载并通过 dotenvx 注入 `apps/server`
228  - `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`
229  - `DATABASE_TYPE`, `DATABASE_URL`
230  - `PROXY_URL`, `PROXY_MT_PROXY` 等代理相关配置
231 
232> [!NOTE]
233> Embedding / LLM 相关设置现在在应用内按账号配置（设置 → API）。  
234> 环境变量如 `EMBEDDING_API_KEY`, `EMBEDDING_MODEL` 等已废弃，仅保留向后兼容，不推荐新增依赖。
235 
236## 开发规范
237 
238### TypeScript
239 
240- 所有代码使用 TypeScript
241- 严格的类型检查
242- 优先使用接口和类型定义
243 
244### 代码风格
245 
246- ESLint 配置：[eslint.config.ts](mdc:eslint.config.ts)
247- 使用 @unbird/eslint-config
248- 自动格式化：运行 `pnpm run lint:fix`
249 
250### 命名规范
251 
252- **文件名**: kebab-case（如 `user-service.ts`）
253- **组件**: PascalCase（如 `UserProfile.vue`）
254- **函数/变量**: camelCase（如 `getUserData`）
255- **类型/接口**: PascalCase（如 `UserData`）
256- **常量**: UPPER_SNAKE_CASE（如 `API_BASE_URL`）
257 
258### 事件命名
259 
260- 格式：`<domain>:<action>`
261- 示例：`auth:login`, `message:query`, `dialog:fetch`
262- ToCore 事件：客户端 → 核心
263- FromCore 事件：核心 → 客户端
264 
265## 性能优化
266 
267### 消息处理
268 
269- 使用流式处理，避免一次性加载大量数据
270- Message Resolver 可并行处理
271- 数据库查询优化：使用索引和向量索引
272 
273### 前端优化
274 
275- 虚拟列表：[packages/client/src/composables/useVirtualList.ts](mdc:packages/client/src/composables/useVirtualList.ts)
276- 分页：[packages/common/src/pagination.ts](mdc:packages/common/src/pagination.ts)
277- 懒加载组件
278 
279## 测试
280 
281### 测试框架
282 
283- Vitest
284- 测试文件：`*.spec.ts` 或 `*.test.ts`
285 
286### 运行测试
287 
288```bash
289pnpm run test run
290```
291 
292## Docker 部署
293 
294### Docker Compose
295 
296[docker-compose.yml](mdc:docker-compose.yml) 包含：
297- PostgreSQL + pgvector
298- 应用服务
299 
300### Dockerfile
301 
302[Dockerfile](mdc:Dockerfile) 用于构建生产镜像。
303 
304## 常见问题
305 
306### Message ID 处理
307 
308Message ID 是递增的，涉及 Message 处理时：
309- ✅ 优先使用 Message ID
310- ❌ 避免仅依赖时间戳
311 
312### 错误处理
313 
314使用 CoreContext 的 `withError` 方法：
315 
316```typescript
317ctx.withError(error, 'Description')
318```
319 
320会自动：
321- 处理 FloodWaitError
322- 处理 RpcError
323- 记录日志
324- 发送 `core:error` 事件
325 
326### 日志记录
327 
328所有关键操作都应记录日志：
329 
330```typescript
331useLogger().withFields({ context }).debug('Debug info')
332useLogger().withFields({ context }).log('Info')
333useLogger().withFields({ context }).warn('Warning')
334useLogger().withError(error).error('Error')
335```
336 
337## 相关文档
338 
339- [README.md](mdc:README.md): 主要文档
340- [README_CN.md](mdc:docs/README_CN.md): 中文文档
341- [README_JA.md](mdc:docs/README_JA.md): 日文文档
342- [CONTRIBUTING.md](mdc:CONTRIBUTING.md): 贡献指南
343- [LICENSE](mdc:LICENSE): 许可证
344