update at 2025-10-16 16:26:39

2025-10-16 16:26:39 +08:00
parent 00e9aea87f
commit 544c53d9db
5 changed files with 1665 additions and 622 deletions
--- a/docs/architecture-v1.4.0.md
+++ b/docs/architecture-v1.4.0.md
@@ -0,0 +1,488 @@
+# Note2Any v1.4.0 Architecture Overview
+
+> **重大架构升级**: v1.4.0引入了全新的模块化核心系统，本文档描述升级后的完整架构。
+> 
+> 相关文档：
+> - [v1.3.x旧架构](./architecture.md) - 升级前架构参考
+> - [优化报告](./OPTIMIZATION_REPORT_v1.3.12.md) - 详细优化过程
+> - [模块设计图](./diagrams.md) - 架构可视化图表
+
+## 1. 全新分层架构
+
+### 1.1 Core System Layer (新增)
+```
+┌─────────────────────────────────────────────┐
+│   Core System Layer - 核心支撑系统          │
+│                                             │
+│ ┌─────────────┐ ┌─────────────┐             │
+│ │ErrorHandler │ │ProgressInd. │ 错误&进度   │
+│ └─────────────┘ └─────────────┘             │
+│                                             │
+│ ┌─────────────┐ ┌─────────────┐             │
+│ │ConfigManager│ │PublisherMgr │ 配置&发布   │
+│ └─────────────┘ └─────────────┘             │
+│                                             │
+│ ┌─────────────┐ ┌─────────────┐             │
+│ │ContentProc. │ │ImageProc.   │ 内容&图像   │
+│ └─────────────┘ └─────────────┘             │
+│                                             │
+│ ┌─────────────┐ ┌─────────────┐             │
+│ │GalleryProc. │ │HtmlProc.    │ 图库&HTML   │
+│ └─────────────┘ └─────────────┘             │
+└─────────────────────────────────────────────┘
+```
+
+### 1.2 完整系统分层
+```
+┌─────────────────────────────────────────────┐
+│ UI/Interaction Layer                        │
+│ preview-view.ts - Obsidian视图容器          │
+│ preview-manager.ts - 业务逻辑调度器         │
+└──────────────┬──────────────────────────────┘
+               │ 支撑
+               ↓
+┌─────────────────────────────────────────────┐
+│ Core System Layer - 新增核心模块系统        │
+│ 统一错误处理、进度反馈、配置管理、发布抽象   │
+└──────────────┬──────────────────────────────┘
+               │ 支撑
+               ↓
+┌─────────────────────────────────────────────┐
+│ Business Logic Layer                        │
+│ article-render.ts - 内容渲染（重构中）      │
+│ platform-chooser.ts - 平台选择器           │
+└──────────────┬──────────────────────────────┘
+               │ 管理
+       ┌───────┼───────┐
+       ↓       ↓       ↓
+┌──────────┐ ┌──────────┐ ┌──────────┐
+│Wechat    │ │Xiaohong- │ │Future    │
+│Platform  │ │shu       │ │Platforms │
+│          │ │Platform  │ │...       │
+└──────────┘ └──────────┘ └──────────┘
+               │ 依赖
+               ↓
+┌─────────────────────────────────────────────┐
+│ Infrastructure Layer                        │
+│ Assets, Settings, Utils, External APIs      │
+└─────────────────────────────────────────────┘
+```
+
+## 2. 核心模块详解
+
+### 2.1 ErrorHandler - 统一错误处理
+```typescript
+// src/core/error-handler.ts
+class ErrorHandler {
+  static handle(error: Error, context: string): void
+  static log(level: LogLevel, message: string, data?: any): void
+  static getUserFriendlyMessage(error: Error): string
+}
+```
+
+**职责**:
+- 全局错误捕获和处理
+- 用户友好的错误提示
+- 错误日志记录和分类
+- 错误恢复策略
+
+**集成点**:
+- 所有模块的try-catch块
+- 异步操作的错误边界
+- 用户操作的失败回调
+
+### 2.2 ProgressIndicator - 进度反馈系统
+```typescript
+// src/core/progress-indicator.ts
+class ProgressIndicator {
+  start(message: string): void
+  update(message: string, progress?: number): void
+  finish(message: string): void
+  error(message: string): void
+}
+```
+
+**职责**:
+- 长时间操作的进度反馈
+- 统一的用户状态提示
+- 可视化进度显示
+- 操作状态管理
+
+**应用场景**:
+- 插件初始化
+- 图片上传进度
+- 内容渲染过程
+- 批量操作状态
+
+### 2.3 ConfigManager - 配置管理中心
+```typescript
+// src/core/config-manager.ts
+class ConfigManager {
+  static initialize(settings: NMPSettings): void
+  static getInstance(): ConfigManager
+  get<T>(key: string): T
+  set<T>(key: string, value: T): void
+  validate(): ValidationResult
+  onUpdate(callback: (config: any) => void): void
+}
+```
+
+**职责**:
+- 中心化配置管理
+- 运行时配置验证
+- 配置变更通知
+- 类型安全的配置访问
+
+**配置分类**:
+- 用户界面设置
+- 平台认证信息
+- 渲染参数配置
+- 功能开关控制
+
+### 2.4 PublisherInterface & PublisherManager - 发布平台抽象
+```typescript
+// src/core/publisher-interface.ts
+interface IPlatformPublisher {
+  id: string
+  name: string
+  initialize(config: PlatformConfig): Promise<void>
+  publish(content: PublishContent): Promise<PublishResult>
+  uploadImage(image: ImageData): Promise<string>
+  validateConfig(): ValidationResult
+}
+
+// src/core/publisher-manager.ts
+class PublisherManager {
+  registerPublisher(publisher: IPlatformPublisher): void
+  getPublisher(id: string): IPlatformPublisher
+  listAvailablePublishers(): IPlatformPublisher[]
+  publishTo(platformId: string, content: PublishContent): Promise<PublishResult>
+}
+```
+
+**职责**:
+- 统一的平台发布接口
+- 平台无关的业务逻辑
+- 可扩展的平台架构
+- 发布流程标准化
+
+**支持平台**:
+- 微信公众号 (已实现)
+- 小红书 (已实现)
+- 未来平台扩展
+
+### 2.5 ContentProcessor - 内容处理流水线
+```typescript
+// src/core/content-processor.ts
+class ContentProcessor {
+  addProcessor(processor: IContentProcessor): void
+  process(content: string, options: ProcessOptions): Promise<ProcessResult>
+  removeProcessor(id: string): void
+  getProcessors(): IContentProcessor[]
+}
+
+interface IContentProcessor {
+  id: string
+  process(content: string, context: ProcessContext): Promise<string>
+  priority: number
+}
+```
+
+**职责**:
+- 模块化内容处理
+- 可配置的处理管道
+- 处理器生命周期管理
+- 支持自定义扩展
+
+**内置处理器**:
+- FrontmatterProcessor: 元数据解析
+- GalleryProcessor: 图库短代码
+- ImageProcessor: 图片处理
+- MathProcessor: 数学公式
+- SyntaxProcessor: 语法扩展
+
+### 2.6 专业化处理模块
+
+#### ImageProcessor - 图像处理引擎
+```typescript
+// src/core/image-processor.ts
+class ImageProcessor {
+  initialize(): Promise<void>
+  convertWebpToJpg(data: ArrayBuffer): Promise<ArrayBuffer>
+  uploadToWechat(data: ArrayBuffer, filename: string, token: string): Promise<string>
+  processImage(data: ArrayBuffer, filename: string, options: ImageProcessOptions): Promise<ArrayBuffer>
+  htmlToPng(element: HTMLElement, options?: any): Promise<Blob>
+  isReady(): boolean
+}
+```
+
+#### GalleryProcessor - 图库处理器
+```typescript
+// src/core/gallery-processor.ts
+class GalleryProcessor {
+  processGalleryShortcodes(content: string): Promise<string>
+  private processDirectoryGalleries(content: string): Promise<string>
+  private processBlockGalleries(content: string): Promise<string>
+}
+```
+
+#### HtmlProcessor - HTML生成器
+```typescript
+// src/core/html-processor.ts
+class HtmlProcessor {
+  generateFullHtml(content: string, options: HtmlProcessOptions): string
+  processInlineCSS(html: string): Promise<string>
+  sanitizeHtml(html: string): DocumentFragment
+  applyStylesToElement(html: string, css: string): string
+  optimizeForMobile(html: string): string
+}
+```
+
+## 3. 架构升级对比
+
+### 3.1 升级前 (v1.3.x)
+```
+❌ 问题点:
+- 单体式大文件 (article-render.ts 864行)
+- 分散的错误处理
+- 缺乏进度反馈
+- 配置管理混乱
+- 平台耦合严重
+- 代码复用度低
+```
+
+### 3.2 升级后 (v1.4.0)
+```
+✅ 改进点:
+- 模块化设计 (9个核心模块)
+- 统一错误处理系统
+- 实时进度反馈
+- 中心化配置管理
+- 标准化平台接口
+- 高代码复用率
+```
+
+## 4. 数据流与交互
+
+### 4.1 插件初始化流程
+```mermaid
+sequenceDiagram
+    participant Main as main.ts
+    participant Progress as ProgressIndicator
+    participant Config as ConfigManager
+    participant Assets as AssetsManager
+    participant Error as ErrorHandler
+
+    Main->>Progress: start('初始化插件')
+    Main->>Config: initialize(settings)
+    Config->>Config: validate configuration
+    Main->>Assets: loadAssets()
+    Assets-->>Error: handle errors if any
+    Main->>Progress: finish('插件初始化完成')
+```
+
+### 4.2 内容发布流程
+```mermaid
+sequenceDiagram
+    participant UI as PreviewView
+    participant Progress as ProgressIndicator
+    participant Content as ContentProcessor
+    participant Publisher as PublisherManager
+    participant Platform as IPlatformPublisher
+
+    UI->>Progress: start('处理内容')
+    UI->>Content: process(markdown)
+    Content->>Progress: update('处理图片')
+    Content->>Content: processImages()
+    UI->>Publisher: publishTo(platformId, content)
+    Publisher->>Platform: publish(content)
+    Platform-->>Publisher: PublishResult
+    Publisher-->>UI: PublishResult
+    UI->>Progress: finish('发布完成')
+```
+
+## 5. 性能优化
+
+### 5.1 模块化加载
+- **懒加载**: 按需初始化核心模块
+- **依赖注入**: 减少模块间耦合
+- **单例模式**: 避免重复实例化
+
+### 5.2 异步处理优化
+- **并发处理**: 图片处理并行化
+- **队列管理**: 批量操作队列化
+- **错误恢复**: 优雅的失败处理
+
+### 5.3 缓存机制
+- **配置缓存**: 避免重复读取
+- **资源缓存**: CSS和主题缓存
+- **结果缓存**: 处理结果缓存
+
+## 6. 扩展性设计
+
+### 6.1 平台扩展
+```typescript
+// 新平台接入示例
+class MyPlatformPublisher implements IPlatformPublisher {
+  id = 'my-platform'
+  name = 'My Platform'
+  
+  async initialize(config: PlatformConfig): Promise<void> {
+    // 平台初始化逻辑
+  }
+  
+  async publish(content: PublishContent): Promise<PublishResult> {
+    // 发布逻辑实现
+  }
+  
+  async uploadImage(image: ImageData): Promise<string> {
+    // 图片上传逻辑
+  }
+  
+  validateConfig(): ValidationResult {
+    // 配置验证逻辑
+  }
+}
+
+// 注册新平台
+publisherManager.registerPublisher(new MyPlatformPublisher())
+```
+
+### 6.2 处理器扩展
+```typescript
+// 自定义内容处理器
+class MyContentProcessor implements IContentProcessor {
+  id = 'my-processor'
+  priority = 100
+  
+  async process(content: string, context: ProcessContext): Promise<string> {
+    // 自定义处理逻辑
+    return processedContent
+  }
+}
+
+// 注册处理器
+contentProcessor.addProcessor(new MyContentProcessor())
+```
+
+## 7. 错误处理策略
+
+### 7.1 错误分类
+```typescript
+enum ErrorType {
+  CONFIG_ERROR = 'config',
+  NETWORK_ERROR = 'network', 
+  PROCESSING_ERROR = 'processing',
+  PLATFORM_ERROR = 'platform',
+  USER_ERROR = 'user'
+}
+```
+
+### 7.2 错误处理流程
+```mermaid
+flowchart TD
+    A[Error Occurs] --> B[ErrorHandler.handle()]
+    B --> C{Error Type}
+    C -->|Config| D[Show Config Help]
+    C -->|Network| E[Retry Strategy]
+    C -->|Processing| F[Fallback Processing]
+    C -->|Platform| G[Platform Error Guide]
+    C -->|User| H[User Action Guide]
+    D --> I[Log Error]
+    E --> I
+    F --> I
+    G --> I
+    H --> I
+    I --> J[User Notification]
+```
+
+## 8. 测试策略
+
+### 8.1 单元测试覆盖
+- ✅ 核心模块单元测试
+- ✅ 错误处理测试
+- ✅ 配置管理测试
+- ✅ 内容处理器测试
+
+### 8.2 集成测试
+- ✅ 平台发布流程测试
+- ✅ 端到端功能测试
+- ✅ 性能基准测试
+
+## 9. 未来路线图
+
+### 9.1 短期目标 (v1.4.x)
+- [ ] 完成article-render.ts重构
+- [ ] 实现更多内容处理器
+- [ ] 优化性能和稳定性
+- [ ] 完善错误处理覆盖
+
+### 9.2 中期目标 (v1.5.x)
+- [ ] 新平台支持 (知乎、CSDN等)
+- [ ] 插件化处理器市场
+- [ ] AI内容优化集成
+- [ ] 批量操作增强
+
+### 9.3 长期目标 (v1.6+)
+- [ ] 云端内容同步
+- [ ] 协作编辑功能
+- [ ] 智能内容推荐
+- [ ] 多媒体内容支持
+
+## 10. 技术债务清理
+
+### 10.1 已解决
+- ✅ 大文件拆分为模块
+- ✅ 统一错误处理机制
+- ✅ 配置管理标准化
+- ✅ 平台抽象层建立
+
+### 10.2 进行中
+- 🔄 article-render.ts模块化
+- 🔄 图片处理管道优化
+- 🔄 测试覆盖率提升
+
+### 10.3 待处理
+- ⏳ 旧代码兼容性清理
+- ⏳ 性能监控集成
+- ⏳ 文档完善
+
+---
+
+## 附录: 核心模块API参考
+
+### A.1 ErrorHandler API
+```typescript
+ErrorHandler.handle(error: Error, context: string): void
+ErrorHandler.log(level: LogLevel, message: string, data?: any): void
+ErrorHandler.getUserFriendlyMessage(error: Error): string
+ErrorHandler.registerErrorType(type: string, handler: ErrorTypeHandler): void
+```
+
+### A.2 ProgressIndicator API
+```typescript
+progress.start(message: string): void
+progress.update(message: string, progress?: number): void
+progress.finish(message: string): void
+progress.error(message: string): void
+progress.setTotal(total: number): void
+progress.increment(message?: string): void
+```
+
+### A.3 ConfigManager API
+```typescript
+ConfigManager.initialize(settings: NMPSettings): void
+ConfigManager.getInstance(): ConfigManager
+config.get<T>(key: string): T
+config.set<T>(key: string, value: T): void
+config.validate(): ValidationResult
+config.onUpdate(callback: (config: any) => void): void
+```
+
+---
+> **维护说明**: 本文档随v1.4.0架构升级而创建，后续架构变更需同步更新。
+> 
+> **相关文档**: 
+> - [发布接口规范](./publisher-interface-spec.md)
+> - [模块开发指南](./module-development-guide.md)
+> - [扩展开发文档](./extension-development.md)