update at 2025-09-27 08:38:05

archives/v1.3.0/diagrams.md

@@ -0,0 +1,178 @@
+# Diagrams (Mermaid)
+
+> 动态架构与主要交互可视化。与文字说明对应：`architecture.md` / `image-pipeline.md` / `render-service-blueprint.md`。
+
+## 1. 模块类图 (当前实现概览)
+```mermaid
+classDiagram
+    class NotePreview {
+      +renderMarkdown()
+      +uploadImages()
+      +postArticle()
+      +postImages()
+      +exportHTML()
+    }
+    class ArticleRender {
+      +renderMarkdown(file)
+      +getMetadata()
+      +uploadImages(appid)
+      +postArticle(appid,cover?)
+      +postImages(appid)
+      +exportHTML()
+      +transformGalleryBlock()
+      +applyCustomInlineBlocks()
+    }
+    class LocalImageManager {
+      +setImage(path,info)
+      +uploadLocalImage(token,vault)
+      +uploadRemoteImage(root,token)
+      +replaceImages(root)
+    }
+    class LocalFile {
+      +markedExtension()
+    }
+    class AssetsManager {
+      +loadAssets()
+      +getTheme(name)
+      +getHighlight(name)
+    }
+    class NMPSettings {
+      +wxInfo
+      +authKey
+      +enableMarkdownImageToWikilink
+      +galleryPrePath
+      +galleryNumPic
+      +defaultCoverPic
+    }
+    class WeChatAPI {
+      +wxGetToken()
+      +wxAddDraft()
+      +wxUploadImage()
+    }
+
+    NotePreview --> ArticleRender
+    ArticleRender --> LocalImageManager
+    ArticleRender --> AssetsManager
+    ArticleRender --> NMPSettings
+    ArticleRender --> WeChatAPI
+    ArticleRender --> LocalFile
+    LocalFile --> LocalImageManager
+    NotePreview --> NMPSettings
+    NotePreview --> AssetsManager
+```
+
+## 2. 发布草稿时序图
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant NP as NotePreview
+    participant AR as ArticleRender
+    participant WX as WeChatAPI
+    participant LIM as LocalImageManager
+
+    U->>NP: 点击 发草稿
+    NP->>AR: postArticle(appid)
+    AR->>WX: wxGetToken(authKey, appid)
+    WX-->>AR: token
+    AR->>AR: cachedElementsToImages()
+    AR->>LIM: uploadLocalImage(token)
+    LIM-->>AR: local media_id(s)
+    AR->>LIM: uploadRemoteImage(token)
+    LIM-->>AR: remote media_id(s)
+    AR->>LIM: replaceImages()
+    AR->>AR: resolve cover (frontmatter / first image / default)
+    AR->>WX: wxAddDraft(draft JSON)
+    WX-->>AR: media_id | err
+    AR-->>NP: 结果
+    NP-->>U: 成功 / 失败提示
+```
+
+## 3. 图片上传流程图
+```mermaid
+graph TD
+  A[Start UploadImages] --> B{AuthKey/AppId?}
+  B -- No --> Z[Throw Error]
+  B -- Yes --> C[Get Token]
+  C --> D[cachedElementsToImages]
+  D --> E[uploadLocalImage]
+  E --> F[uploadRemoteImage]
+  F --> G[replaceImages]
+  G --> H[Copy HTML to Clipboard]
+  H --> I[End]
+```
+
+## 4. 自动封面推断逻辑
+```mermaid
+graph TD
+  A[Need Cover?] -->|No| Z[Skip]
+  A -->|Yes| B[Frontmatter cover?]
+  B -- Yes --> H[Use frontmatter]
+  B -- No --> C[Strip Frontmatter]
+  C --> D[Scan Markdown Images]
+  C --> E[Scan Wikilink Images]
+  D --> F[Collect Candidates]
+  E --> F[Collect Candidates]
+  F --> G{Any Body Image?}
+  G -- Yes --> H[Use first body image]
+  G -- No --> I[Gallery Expanded?]
+  I -- Yes --> H[Use first gallery image]
+  I -- No --> J[defaultCoverPic Config?]
+  J -- Yes --> H[Use defaultCoverPic]
+  J -- No --> Z[Cover stays empty]
+```
+
+## 4.1 行级轻语法与日志节流 (补充)
+```mermaid
+graph TD
+  M[Markdown Raw] --> P[Preprocess Gallery Shortcode]
+  P --> GB[Gallery Block Parse]
+  GB --> MD[Marked Parse]
+  MD --> IB[applyCustomInlineBlocks]
+  IB --> R[Render HTML]
+  R --> L{Log Throttle}
+  L --> R1[Path Log]
+  L --> R2[Cover Fallback Log]
+```
+
+## 5. 未来 RenderService Pipeline 图
+```mermaid
+graph TD
+  L[Loader] --> FM[Frontmatter]
+  FM --> PP[Preprocessors]
+  PP --> P[Parser]
+  P --> TR[Transformers]
+  TR --> RI[ResourceIndex]
+  RI --> R[Renderer]
+  R --> PO[Postprocessors]
+  PO --> EX[Exporters]
+```
+
+## 6. 并发上传示意 (未来优化)
+```mermaid
+graph TD
+  A[Images] --> B[Partition]
+  B --> C[Pool]
+  C --> D[Upload]
+  D --> E{Success?}
+  E -->|No| R[Retry]
+  E -->|Yes| F[Collect ids]
+  R --> C
+  F --> G[Done]
+```
+
+## 7. 状态机概览 (发布按钮)
+```mermaid
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Uploading : 点击 上传/发布
+  Uploading --> Publishing : 草稿模式
+  Uploading --> Completed : 仅上传
+  Publishing --> Completed : 响应成功
+  Publishing --> Failed : 接口错误
+  Uploading --> Failed : 资源错误
+  Failed --> Idle : 用户重试
+  Completed --> Idle : 新文件切换
+```
+
+---
+需要我将这些图嵌入到 README 的一个“开发者”章节吗？可以继续提出。