note2any/docs/architecture-v1.4.0.md

Note2Any v1.4.0 Architecture Overview

重大架构升级: v1.4.0引入了全新的模块化核心系统，本文档描述升级后的完整架构。

相关文档：

• v1.3.x旧架构 - 升级前架构参考
• 优化报告 - 详细优化过程
• 模块设计图 - 架构可视化图表

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 - 统一错误处理

// 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 - 进度反馈系统

// 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 - 配置管理中心

// 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 - 发布平台抽象

// 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 - 内容处理流水线

// 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 - 图像处理引擎

// 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 - 图库处理器

// 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生成器

// 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 插件初始化流程

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 内容发布流程

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 平台扩展

// 新平台接入示例
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 处理器扩展

// 自定义内容处理器
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 错误分类

enum ErrorType {
  CONFIG_ERROR = 'config',
  NETWORK_ERROR = 'network', 
  PROCESSING_ERROR = 'processing',
  PLATFORM_ERROR = 'platform',
  USER_ERROR = 'user'
}

7.2 错误处理流程

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

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

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

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架构升级而创建，后续架构变更需同步更新。

相关文档:

• 发布接口规范
• 模块开发指南
• 扩展开发文档