diff --git a/docs/archives/112-desktop-ipc-fixes/README.md b/docs/archives/112-desktop-ipc-fixes/README.md index 17117318..9bb60d5d 100644 --- a/docs/archives/112-desktop-ipc-fixes/README.md +++ b/docs/archives/112-desktop-ipc-fixes/README.md @@ -1,95 +1,31 @@ -# 112-desktop-ipc-fixes - 桌面端IPC修复合集 +# 112-Desktop IPC修复 -## 📋 项目概述 +## 📋 概述 -- **项目编号**: 112 -- **项目名称**: 桌面端IPC修复合集 -- **开发时间**: 2025-01-04 - 2025-07-03 -- **项目状态**: ✅ 已完成 -- **主要开发者**: AI Assistant +解决Desktop版本中的IPC相关问题，包括语言切换功能异常、IPC调用链不完整等问题。 -## 🎯 项目目标 +## 🎯 主要问题 -### 主要目标 -- 修复桌面端IPC通信相关的各种问题 -- 统一Web和Electron环境的异步接口调用 -- 确保跨环境架构的一致性和稳定性 +### 1. 语言切换按钮显示异常 +- **问题**: 显示"Object Promise"而不是正确的语言名称 +- **原因**: 异步接口被当作同步值使用 +- **解决**: 统一异步接口设计，完善IPC调用链 -### 具体修复内容 -1. **语言切换按钮修复** - 解决功能提示词管理语言切换按钮显示"Object Promise"问题 -2. **IPC架构分析与修复** - 修复Desktop版本中服务未初始化和方法不存在的问题 +### 2. IPC架构不完整 +- **问题**: 代理类方法缺失，IPC链路不完整 +- **原因**: 接口定义与实现不一致 +- **解决**: 建立完整的IPC开发流程和检查清单 -## ✅ 完成情况 +## 📁 文档结构 -### 核心功能完成情况 -- [x] **语言切换按钮修复** - 100% 完成 - - 语言切换按钮现在正确显示"中文"或"English" - - 完全解决了"Object Promise"显示问题 -- [x] **IPC调用一致性** - 100% 完成 - - 统一了Web和Electron环境的异步接口 - - 修复了所有IPC调用的异步处理问题 -- [x] **架构违规修复** - 100% 完成 - - 修复了preload.js中的功能自实现问题 - - 确保严格遵循IPC转发原则 -- [x] **类型安全改进** - 100% 完成 - - 统一使用接口类型，确保跨环境兼容性 - - 修复了所有TypeScript类型错误 - -### 技术实现完成情况 -- [x] **接口统一** - 创建了`ITemplateLanguageService`接口 -- [x] **调用链修复** - 从UI层到主进程的完整异步调用链 -- [x] **错误处理** - 应用立即错误原则，移除错误掩盖机制 -- [x] **代码清理** - 删除了冗余的`getTemplatesByType`方法 -- [x] **质量验证** - 所有构建和功能测试通过 - -## 🎉 主要成果 - -### 架构改进 -- **统一异步接口设计** - 创建了`ITemplateLanguageService`接口，确保跨环境一致性 -- **IPC架构规范化** - 修复了preload.js架构违规，确保严格遵循IPC转发原则 -- **接口驱动设计** - 统一使用接口类型而非具体类，确保跨环境类型兼容性 - -### 稳定性提升 -- **错误处理改进** - 应用立即错误原则，让错误自然传播，便于问题定位 -- **类型安全保障** - 利用TypeScript确保接口实现的完整性和一致性 -- **功能验证完整** - Electron应用正常启动，所有功能正常工作 - -### 开发体验优化 -- **代码简化** - 删除了冗余的`getTemplatesByType`方法，简化了接口 -- **架构清晰** - 建立了清晰的跨环境接口调用规范 -- **经验积累** - 形成了完整的IPC开发最佳实践 - -## 📊 影响范围 - -### 修改的文件 -- `packages/core/src/services/template/languageService.ts` - 接口定义和实现 -- `packages/core/src/services/template/electron-language-proxy.ts` - Electron代理实现 -- `packages/core/src/services/template/manager.ts` - 模板管理器实现 -- `packages/ui/src/components/BuiltinTemplateLanguageSwitch.vue` - UI组件 -- `packages/desktop/main.js` - 主进程IPC处理器 -- `packages/desktop/preload.js` - preload脚本 -- `packages/ui/src/composables/useAppInitializer.ts` - 服务初始化 -- `packages/core/src/services/template/types.ts` - 类型定义 - -### 影响的功能 -- **功能提示词管理** - 语言切换功能完全正常 -- **模板管理** - 所有模板相关功能正常工作 -- **跨环境兼容性** - Web和Electron环境行为一致 +- **language-switch-fix.md** - 语言切换功能修复详情 +- **ipc-architecture-analysis.md** - IPC架构分析和最佳实践 +- **desktop-development-experience.md** - Desktop开发经验总结 ## 🔗 相关文档 -- [语言切换修复详解](./language-switch-fix.md) - 语言切换按钮修复的详细过程 -- [IPC架构修复详解](./desktop-ipc-fix.md) - IPC架构问题分析与修复 -- [技术实现详解](./implementation.md) - 详细的技术实现过程 -- [开发经验总结](./experience.md) - 重要的开发经验和最佳实践 +- [115-IPC序列化修复](../115-ipc-serialization-fixes/) - Vue响应式对象序列化问题的解决方案 -## 🚀 后续工作 +## 💡 核心价值 -### 建议的改进方向 -- **持续监控** - 关注类似的异步接口一致性问题 -- **经验应用** - 将本次修复的经验应用到其他服务的接口设计中 -- **文档完善** - 将IPC开发规范整理成开发指南 - -## 相关功能点 -- 前置依赖：111-electron-preference-architecture -- 后续功能：113-full-service-refactoring +本目录专注于Desktop环境下的IPC架构问题，为建立完整的跨进程通信机制提供了经验和最佳实践。这些经验为后续的序列化优化（115）奠定了基础。 diff --git a/docs/archives/112-desktop-ipc-fixes/desktop-ipc-fix.md b/docs/archives/112-desktop-ipc-fixes/desktop-ipc-fix.md deleted file mode 100644 index c2507ad9..00000000 --- a/docs/archives/112-desktop-ipc-fixes/desktop-ipc-fix.md +++ /dev/null @@ -1,130 +0,0 @@ -# Desktop IPC 修复与架构分析 - -## 📝 归档说明 - -- **任务名称**: Desktop IPC 修复与架构分析 -- **完成日期**: 2025-07-03 -- **核心问题**: Desktop 版本中 `BuiltinTemplateLanguageSwitch` 组件因服务未初始化和方法不存在而出错。 - -## 🔍 根本原因分析 - -### 1. 架构差异 -- **Web环境（单进程）**: 可直接调用服务实例 -- **Desktop环境（多进程）**: 必须通过IPC进行进程间通信 - -### 2. 契约缺失 -- `ITemplateManager` 接口中缺少语言切换相关方法 -- 导致代理类无法转发调用 -- 接口定义与实际需求不匹配 - -### 3. 实现不完整 -- ElectronTemplateManagerProxy 缺少必要的方法实现 -- preload.js 和 main.js 中缺少完整的IPC通信链路 - -## 🛠️ 解决方案 - -### 1. 接口完善 -在 `ITemplateManager` 接口中补充缺失的方法定义： -```typescript -export interface ITemplateManager { - // 现有方法... - - // 新增语言切换相关方法 - getCurrentLanguage(): Promise; - setLanguage(language: BuiltinTemplateLanguage): Promise; - toggleLanguage(): Promise; - getSupportedLanguages(): Promise; -} -``` - -### 2. 代理类修正 -修正 `ElectronTemplateManagerProxy`，使其通过IPC正确转发调用： -```typescript -export class ElectronTemplateManagerProxy implements ITemplateManager { - // 缓存同步方法的结果 - private cache = new Map(); - - async getCurrentLanguage(): Promise { - return await this.electronAPI.getCurrentLanguage(); - } - - async setLanguage(language: BuiltinTemplateLanguage): Promise { - await this.electronAPI.setLanguage(language); - // 清除相关缓存 - this.cache.delete('currentLanguage'); - } - - // 其他方法实现... -} -``` - -### 3. IPC通信链路完善 -在 `preload.js` 中添加IPC方法： -```javascript -// preload.js -const electronAPI = { - // 现有方法... - - // 新增语言切换IPC方法 - getCurrentLanguage: () => ipcRenderer.invoke('template-getCurrentLanguage'), - setLanguage: (language) => ipcRenderer.invoke('template-setLanguage', language), - toggleLanguage: () => ipcRenderer.invoke('template-toggleLanguage'), - getSupportedLanguages: () => ipcRenderer.invoke('template-getSupportedLanguages'), -}; -``` - -在 `main.js` 中添加IPC处理器： -```javascript -// main.js -ipcMain.handle('template-getCurrentLanguage', async () => { - try { - const result = await templateManager.getCurrentLanguage(); - return { success: true, data: result }; - } catch (error) { - return { success: false, error: error.message }; - } -}); - -// 其他处理器... -``` - -## 💡 经验总结 - -### 接口驱动开发 -- **原则**: 所有跨模块、跨进程的调用都应依赖于接口（契约），而不是具体实现 -- **好处**: 确保不同环境下的实现一致性 -- **实践**: 先定义接口，再实现具体功能 - -### 代理模式规范 -- **原则**: IPC代理类应严格遵守接口，只做转发，不实现业务逻辑 -- **好处**: 保持架构清晰，避免逻辑分散 -- **实践**: 代理类只负责IPC调用和错误处理 - -### 环境差异处理 -- **原则**: 必须充分考虑Web和Desktop环境的架构差异（单/多进程） -- **避免**: 依赖特定环境的"捷径"实现 -- **实践**: 设计时优先考虑最复杂环境的需求 - -## 🔧 架构检查清单 - -### IPC接口完整性 -- [ ] 接口中是否定义了所有需要的方法？ -- [ ] 方法签名是否与实际需求匹配？ -- [ ] 是否考虑了异步调用的需求？ - -### 代理类实现 -- [ ] 代理类是否实现了接口的所有方法？ -- [ ] 是否正确处理了IPC调用的异步性？ -- [ ] 是否有适当的错误处理机制？ - -### IPC通信链路 -- [ ] preload.js中是否有对应的IPC方法？ -- [ ] main.js中是否有对应的IPC处理器？ -- [ ] IPC调用是否使用统一的错误处理格式？ - -### 环境兼容性 -- [ ] Web和Desktop环境是否使用相同的接口？ -- [ ] 是否避免了环境特定的实现依赖？ -- [ ] 是否有适当的环境检测和适配机制？ - -这次修复为后续的跨环境架构设计提供了重要的经验和规范。 diff --git a/docs/archives/112-desktop-ipc-fixes/experience.md b/docs/archives/112-desktop-ipc-fixes/experience.md deleted file mode 100644 index 7ba2d36e..00000000 --- a/docs/archives/112-desktop-ipc-fixes/experience.md +++ /dev/null @@ -1,286 +0,0 @@ -# 开发经验总结 - -## 🎯 核心经验 - -### 1. IPC 异步调用一致性原则 - -**核心发现**: Web 和 Electron 环境必须使用完全相同的异步接口签名。 - -**问题表现**: -- UI 显示 "Object Promise" 而不是实际值 -- 异步方法被当作同步使用 -- 跨环境行为不一致 - -**解决原则**: -```typescript -// ✅ 正确：统一的异步接口 -export interface ITemplateLanguageService { - getCurrentLanguage(): Promise; - getSupportedLanguages(): Promise; -} - -// ❌ 错误：混合同步/异步接口 -export interface ITemplateLanguageService { - getCurrentLanguage(): BuiltinTemplateLanguage; // 同步 - getSupportedLanguages(): Promise; // 异步 -} -``` - -**检查清单**: -- [ ] IPC 方法是否返回 Promise？ -- [ ] 代理类方法签名是否与 IPC 方法匹配？ -- [ ] 调用方是否正确使用 `await`？ -- [ ] 接口定义是否反映真实的异步性质？ -- [ ] Web 和 Electron 环境是否使用相同的接口？ - -### 2. preload.js 架构原则 - -**核心原则**: preload.js 严禁自己实现功能，所有方法都必须通过 IPC 调用主进程。 - -**错误模式**: -```javascript -// ❌ 错误：在 preload.js 中自己实现功能 -isInitialized: () => { - return true; // 硬编码返回值 -}, -``` - -**正确模式**: -```javascript -// ✅ 正确：通过 IPC 调用主进程 -isInitialized: async () => { - const result = await ipcRenderer.invoke('model-isInitialized'); - if (!result.success) throw new Error(result.error); - return result.data; -}, -``` - -**架构检查要点**: -- [ ] 是否所有方法都通过 `ipcRenderer.invoke()` 调用？ -- [ ] 是否没有任何硬编码的返回值？ -- [ ] 是否没有本地状态管理？ -- [ ] 是否使用统一的错误处理格式？ -- [ ] 是否与对应的 ElectronProxy 类方法签名一致？ - -### 3. 接口驱动设计原则 - -**核心原则**: 在服务注入和类型声明中必须使用接口类型，不能使用具体类类型。 - -**问题表现**: -```typescript -// ❌ 错误：使用具体类类型 -let dataManager: DataManager; -export interface AppServices { - dataManager: DataManager; -} -``` - -**正确实现**: -```typescript -// ✅ 正确：使用接口类型 -let dataManager: IDataManager; -export interface AppServices { - dataManager: IDataManager; -} -``` - -**设计优势**: -- **跨环境兼容性** - 接口确保 Web 和 Electron 环境的实现可以互换 -- **代理模式支持** - ElectronProxy 类可以正确实现接口而不需要继承具体类 -- **类型安全** - TypeScript 编译器确保接口实现的完整性 - -## 🛠️ 技术实现经验 - -### 1. Promise 对象显示问题诊断 - -**问题识别**: -当 UI 显示 "Object Promise" 时，通常表示异步方法被当作同步使用。 - -**诊断步骤**: -1. 检查显示异常的 UI 组件 -2. 追踪数据来源的方法调用 -3. 确认方法是否返回 Promise 对象 -4. 检查调用方是否使用 `await` - -**修复模式**: -```vue - - - - - - - - - -``` - -### 2. 接口实现完整性检查 - -**常见问题**: 在创建适配器时遗漏某些接口方法。 - -**检查方法**: -1. 利用 TypeScript 编译器检查接口实现 -2. 确保适配器实现接口的所有方法 -3. 验证方法签名与接口定义完全匹配 - -**修复示例**: -```typescript -// 修复前 - 缺失 getRecord 方法 -const historyManagerAdapter: IHistoryManager = { - getRecords: () => historyManagerInstance.getRecords(), - // ❌ 缺失 getRecord 方法 - addRecord: (record) => historyManagerInstance.addRecord(record), -}; - -// 修复后 - 完整实现 -const historyManagerAdapter: IHistoryManager = { - getRecords: () => historyManagerInstance.getRecords(), - getRecord: (id) => historyManagerInstance.getRecord(id), // ✅ 添加缺失方法 - addRecord: (record) => historyManagerInstance.addRecord(record), -}; -``` - -### 3. 冗余代码清理策略 - -**识别标准**: -- 方法标记为 `@deprecated` -- 实现只是简单转发到其他方法 -- 没有实际调用的代码 - -**清理步骤**: -1. 确认方法已被替代且无实际使用 -2. 从接口定义中删除 -3. 从所有实现类中删除 -4. 从代理类和适配器中删除 -5. 验证构建和功能正常 - -## 🚫 避坑指南 - -### 1. 异步接口设计陷阱 - -**陷阱**: 在不同环境中使用不同的方法签名（同步 vs 异步）。 - -**避免方法**: -- 设计接口时优先考虑最复杂环境的需求（通常是 Electron） -- 如果任何环境需要异步，所有环境都使用异步接口 -- 使用 TypeScript 接口确保实现一致性 - -### 2. preload.js 实现陷阱 - -**陷阱**: 为了简化而在 preload.js 中直接返回硬编码值。 - -**避免方法**: -- 严格遵循"只做 IPC 转发"原则 -- 所有业务逻辑都在主进程中实现 -- 使用统一的错误处理格式 - -### 3. 类型安全陷阱 - -**陷阱**: 在服务注入中混合使用接口类型和具体类类型。 - -**避免方法**: -- 统一使用接口类型进行服务注入 -- 在 AppServices 接口中只使用接口类型 -- 利用 TypeScript 编译器检查类型一致性 - -### 4. 错误处理陷阱 - -**陷阱**: 使用 try-catch 掩盖错误，静默处理异常。 - -**避免方法**: -- 应用立即错误原则，让错误自然传播 -- 只在确实需要处理的地方使用 try-catch -- 提供明确的错误信息，便于调试 - -## 🔄 架构设计经验 - -### 1. 跨环境接口设计 - -**设计原则**: -- **统一性优先** - 所有环境使用相同的接口 -- **异步优先** - 如果任何环境需要异步，全部使用异步 -- **类型安全** - 利用 TypeScript 确保实现一致性 - -**实现模式**: -```typescript -// 1. 定义统一接口 -export interface IService { - method(): Promise; -} - -// 2. Web 环境实现 -export class WebService implements IService { - async method(): Promise { - // 同步逻辑包装为异步 - return Promise.resolve(syncResult); - } -} - -// 3. Electron 环境实现 -export class ElectronServiceProxy implements IService { - async method(): Promise { - // 直接调用异步 IPC - return this.electronAPI.method(); - } -} -``` - -### 2. 错误处理架构 - -**立即错误原则**: -- 错误应该在发生的地方立即抛出 -- 不要使用默认值掩盖错误 -- 让调用者决定如何处理错误 - -**实现模式**: -```typescript -// ✅ 正确：立即抛出错误 -const refresh = async () => { - const service = getService(); - if (!service) { - throw new Error('Service not available'); - } - - return await service.getData(); // 让错误自然传播 -}; - -// ❌ 错误：掩盖错误 -const refresh = async () => { - try { - const service = getService(); - return await service.getData(); - } catch (error) { - console.error('Error:', error); - return []; // 掩盖了问题 - } -}; -``` - -### 3. 代码清理策略 - -**清理时机**: -- 功能完成后立即清理 -- 发现冗余代码时及时处理 -- 定期审查标记为 `@deprecated` 的代码 - -**清理原则**: -- 确保没有实际使用 -- 完整删除（接口、实现、调用） -- 验证删除后功能正常 - -这些经验为后续的 IPC 开发和跨环境架构设计提供了重要的参考和指导。 diff --git a/docs/archives/112-desktop-ipc-fixes/implementation.md b/docs/archives/112-desktop-ipc-fixes/implementation.md deleted file mode 100644 index 96c0988d..00000000 --- a/docs/archives/112-desktop-ipc-fixes/implementation.md +++ /dev/null @@ -1,224 +0,0 @@ -# 技术实现详解 - -## 🔧 架构设计 - -### 问题根因分析 - -**核心问题**: 功能提示词管理的语言切换按钮显示 "Object Promise" 而不是正确的语言名称。 - -**根本原因**: IPC 调用异步处理不一致 -- **Electron 环境**: `ElectronTemplateLanguageServiceProxy` 的方法调用异步 IPC 方法，但被定义为同步 -- **返回 Promise 对象**: 当 Promise 对象被用作字符串显示时，显示为 "Object Promise" -- **接口不匹配**: Web 环境和 Electron 环境的方法签名不一致 - -### 解决方案架构 - -#### 1. 统一异步接口设计 -```typescript -// 创建统一的异步接口 -export interface ITemplateLanguageService { - initialize(): Promise; - getCurrentLanguage(): Promise; - setLanguage(language: BuiltinTemplateLanguage): Promise; - toggleLanguage(): Promise; - isValidLanguage(language: string): Promise; - getSupportedLanguages(): Promise; - getLanguageDisplayName(language: BuiltinTemplateLanguage): string; - isInitialized(): boolean; -} -``` - -#### 2. 跨环境实现统一 -- **Web 环境**: `TemplateLanguageService` 实现异步接口 -- **Electron 环境**: `ElectronTemplateLanguageServiceProxy` 实现相同的异步接口 - -## 🐛 问题诊断与解决 - -### 问题1: 语言切换按钮显示 "Object Promise" - -**诊断过程**: -1. 发现 UI 组件中显示异常 -2. 追踪到 `getCurrentLanguage()` 方法返回 Promise 对象 -3. 确认 Electron 代理类方法签名与 IPC 异步性质不匹配 - -**解决方案**: -```typescript -// 修复前 - 错误的同步方法 -getCurrentLanguage(): BuiltinTemplateLanguage { - return this.electronAPI.getCurrentBuiltinTemplateLanguage(); // 返回 Promise -} - -// 修复后 - 正确的异步方法 -async getCurrentLanguage(): Promise { - return await this.electronAPI.getCurrentBuiltinTemplateLanguage(); -} -``` - -### 问题2: preload.js 架构违规 - -**诊断过程**: -1. 全面检查 IPC 实现发现 `model.isInitialized()` 方法违规 -2. 发现 preload.js 中硬编码返回值而非 IPC 调用 - -**解决方案**: -```javascript -// 修复前 - 架构违规 -isInitialized: () => { - return true; // 硬编码返回值 -}, - -// 修复后 - 正确的 IPC 调用 -isInitialized: async () => { - const result = await ipcRenderer.invoke('model-isInitialized'); - if (!result.success) throw new Error(result.error); - return result.data; -}, -``` - -### 问题3: TypeScript 类型不匹配 - -**诊断过程**: -1. 发现 `ElectronDataManagerProxy` 类型缺少 `DataManager` 类的属性 -2. 确认问题是使用具体类类型而非接口类型 - -**解决方案**: -```typescript -// 修复前 - 使用具体类类型 -let dataManager: DataManager; -export interface AppServices { - dataManager: DataManager; -} - -// 修复后 - 使用接口类型 -let dataManager: IDataManager; -export interface AppServices { - dataManager: IDataManager; -} -``` - -## 📝 实施步骤 - -### 步骤1: 创建统一接口 (2025-01-04 22:00) -1. 定义 `ITemplateLanguageService` 接口 -2. 将所有方法定义为异步版本 -3. 确保 Web 和 Electron 环境使用相同的接口 - -### 步骤2: 更新实现类 (2025-01-04 22:15) -1. 修改 `TemplateLanguageService` 实现 -2. 将 `getCurrentLanguage()` 和 `getSupportedLanguages()` 改为异步 -3. 修复 `isValidLanguage()` 中的异步调用 - -### 步骤3: 更新 Electron 代理 (2025-01-04 22:30) -1. 更新 `ElectronTemplateLanguageServiceProxy` -2. 实现 `ITemplateLanguageService` 接口 -3. 确保所有方法正确转发 IPC 调用 - -### 步骤4: 修复调用链 (2025-01-04 22:45) -1. 修复 `TemplateManager` 中的异步调用 -2. 更新 `BuiltinTemplateLanguageSwitch.vue` 组件 -3. 修复主进程 IPC 处理器 -4. 更新接口类型定义 - -### 步骤5: 全面 IPC 检查 (2025-01-04 23:15) -1. 检查所有 ElectronProxy 类的方法完整性 -2. 修复 preload.js 架构违规问题 -3. 统一异步接口规范 - -### 步骤6: 类型安全修复 (2025-01-04 23:45) -1. 修复服务注入中的类型不匹配 -2. 统一使用接口类型而非具体类 -3. 确保跨环境类型兼容性 - -### 步骤7: 代码清理 (2025-01-04 24:00) -1. 删除冗余的 `getTemplatesByType` 方法 -2. 简化接口设计 -3. 应用立即错误原则 - -## 🔍 调试过程 - -### 调试工具和方法 -1. **TypeScript 编译器** - 发现类型不匹配问题 -2. **Electron 开发者工具** - 检查 IPC 调用和错误 -3. **控制台日志** - 追踪异步调用流程 -4. **构建验证** - 确保修复不破坏现有功能 - -### 关键调试发现 -1. **Promise 对象显示** - 当异步方法被当作同步使用时会显示 "Object Promise" -2. **IPC 调用规范** - preload.js 严禁自己实现功能，必须通过 IPC 调用主进程 -3. **接口驱动重要性** - 使用接口类型确保跨环境兼容性 - -## 🧪 测试验证 - -### 构建测试 -- ✅ Core 包构建成功 -- ✅ UI 包构建成功 -- ✅ TypeScript 编译无错误 - -### 功能测试 -- ✅ Electron 应用成功启动 -- ✅ 语言切换按钮正确显示语言名称 -- ✅ 模板加载功能正常（7个模板） -- ✅ 模型管理功能正常（5个模型） -- ✅ IPC 调用正常工作 - -### 回归测试 -- ✅ 所有原有功能保持正常 -- ✅ Web 和 Electron 环境行为一致 -- ✅ 错误处理符合立即错误原则 - -## 🔧 技术细节 - -### 关键代码修改 - -#### 1. 接口定义统一 -```typescript -// packages/core/src/services/template/languageService.ts -export interface ITemplateLanguageService { - getCurrentLanguage(): Promise; - getSupportedLanguages(): Promise; - // ... 其他方法 -} -``` - -#### 2. 异步实现修复 -```typescript -// packages/core/src/services/template/languageService.ts -public async getCurrentLanguage(): Promise { - await this.initialize(); - return this.currentLanguage; -} -``` - -#### 3. IPC 调用修复 -```javascript -// packages/desktop/preload.js -getCurrentBuiltinTemplateLanguage: async () => { - const result = await ipcRenderer.invoke('template-getCurrentBuiltinTemplateLanguage'); - if (!result.success) throw new Error(result.error); - return result.data; -}, -``` - -#### 4. UI 组件修复 -```vue - - -``` - -### 架构改进要点 - -1. **统一异步接口** - 确保 Web 和 Electron 环境使用相同的异步接口签名 -2. **严格 IPC 转发** - preload.js 只做转发，不实现任何业务逻辑 -3. **接口驱动设计** - 使用接口类型而非具体类，确保跨环境兼容 -4. **立即错误原则** - 让错误自然传播，便于问题定位和调试 diff --git a/docs/archives/112-desktop-ipc-fixes/ipc-architecture-analysis.md b/docs/archives/112-desktop-ipc-fixes/ipc-architecture-analysis.md new file mode 100644 index 00000000..33853fb9 --- /dev/null +++ b/docs/archives/112-desktop-ipc-fixes/ipc-architecture-analysis.md @@ -0,0 +1,172 @@ +# IPC架构分析与开发经验 + +## 📝 背景 + +在Desktop版本开发中遇到的IPC架构问题分析和解决经验。 + +## 🔍 架构差异分析 + +### 1. Web环境 vs Desktop环境 + +**Web环境（单进程）**： +``` +Vue组件 → 直接调用 → 服务实例 +``` + +**Desktop环境（多进程）**： +``` +Vue组件 → ElectronProxy → IPC → Main进程 → 服务实例 +``` + +### 2. 常见问题模式 + +#### 问题1：接口契约缺失 +```typescript +// ❌ 接口定义不完整 +interface ITemplateManager { + getTemplate(id: string): Promise