From 81a62402ef6f8900ff092366121a9b7a4263ba52 Mon Sep 17 00:00:00 2001
From: Natsuu <natsukawa247@outlook.com>
Date: Fri, 27 Feb 2026 17:18:25 +0800
Subject: Restructure docs into manual/development and add implementation docs
 (#94)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary by Sourcery

Restructure documentation into separate manual and development sections,
introduce detailed internal implementation docs for auth/Java/mod
loaders, and update site navigation, landing page links, and MDX tooling
(Mermaid, card styling) to match the new structure and tech stack.

Enhancements:
- Enable Mermaid rendering support in the docs app and add a reusable
Mermaid React component.
- Refine Docs page rendering by customizing Card styling and removing
redundant in-page titles/descriptions rendered by the layout.
- Align docs source configuration and routing comments with the new
manual-based default paths.

Documentation:
- Split user-facing docs under a new manual section and move contributor
content into a dedicated development section for both English and
Chinese.
- Add comprehensive internal implementation documentation covering
authentication, Java management, mod loader/version merging, event bus,
and architecture patterns in both English and Chinese.
- Update existing feature docs (mod loaders, Java, authentication) and
getting-started/troubleshooting pages to be more conceptual, pointing to
implementation docs for technical details.
- Refresh architecture docs to reflect the React/Zustand frontend stack
and add Mermaid-based architecture diagrams.
- Adjust navigation labels, home-page CTAs, and doc links to target the
new manual/development structure and routes.

---------

Co-authored-by: 简律纯 <i@jyunko.cn>
---
 .../docs/content/zh/development/architecture.mdx   | 311 +++++++++++++++++++++
 1 file changed, 311 insertions(+)
 create mode 100644 packages/docs/content/zh/development/architecture.mdx

(limited to 'packages/docs/content/zh/development/architecture.mdx')

diff --git a/packages/docs/content/zh/development/architecture.mdx b/packages/docs/content/zh/development/architecture.mdx
new file mode 100644
index 0000000..4f47115
--- /dev/null
+++ b/packages/docs/content/zh/development/architecture.mdx
@@ -0,0 +1,311 @@
+---
+title: 架构设计
+description: DropOut Minecraft 启动器的技术架构和设计
+---
+
+# 架构设计
+
+DropOut 采用现代技术栈构建，旨在实现高性能、安全性和跨平台兼容性。
+
+## 技术栈
+
+### 后端（Rust）
+
+- **框架**: Tauri v2
+- **语言**: Rust（Edition 2021）
+- **异步运行时**: Tokio
+- **HTTP 客户端**: reqwest with native-tls
+
+### 前端（React）
+
+- **框架**: React 19
+- **状态管理**: Zustand
+- **路由**: React Router v7
+- **样式**: Tailwind CSS 4
+- **构建工具**: Vite (with Rolldown)
+- **包管理器**: pnpm
+
+### 文档
+
+- **框架**: Fumadocs with React Router v7
+- **内容**: MDX 文件
+- **样式**: Tailwind CSS 4
+
+## 系统架构
+
+```mermaid
+graph TB
+    subgraph Frontend["前端 (React 19)"]
+        direction LR
+        Stores[Zustand Stores] ~~~ Components[Components] ~~~ Pages[Pages] ~~~ Router[Router] ~~~ Particles[Particle Background]
+    end
+
+    subgraph TauriLayer["Tauri 通信层"]
+        direction LR
+        Commands[命令] ~~~ Events[事件/发射器]
+    end
+
+    subgraph Backend["后端 (Rust/Tauri)"]
+        direction TB
+        MainRS[main.rs 命令处理]
+
+        subgraph CoreModules["核心模块"]
+            direction LR
+            Auth[Auth] ~~~ Download[Download] ~~~ Java[Java] ~~~ Instance[Instance]
+            Fabric[Fabric] ~~~ Forge[Forge] ~~~ Config[Config] ~~~ Manifest[Manifest]
+            Auth ~~~ Fabric
+        end
+
+        subgraph Utils["工具和辅助函数"]
+            direction LR
+            ZipExtract[ZIP 提取] ~~~ PathUtils[路径工具]
+        end
+
+        MainRS --> CoreModules
+        CoreModules --> Utils
+    end
+
+    subgraph ExternalAPIs["外部 API"]
+        direction LR
+        Mojang[Mojang APIs] ~~~ FabricMeta[Fabric Meta] ~~~ ForgeMaven[Forge Maven]
+    end
+
+    Frontend <--> TauriLayer
+    TauriLayer <--> Backend
+    Backend <--> ExternalAPIs
+
+    style Frontend fill:#e3f2fd
+    style Backend fill:#fff3e0
+    style TauriLayer fill:#f3e5f5
+    style ExternalAPIs fill:#e8f5e9
+```
+
+## 核心组件
+
+### 前端状态管理
+
+DropOut 使用 **Zustand** 进行全局状态管理：
+
+```typescript
+// models/auth.ts
+import { create } from "zustand";
+
+interface AuthState {
+  account: Account | null;
+  loginMode: LoginMode | null;
+  // ...
+  setAccount: (account: Account | null) => void;
+}
+
+export const useAuthStore = create<AuthState>((set) => ({
+  account: null,
+  loginMode: null,
+  setAccount: (account) => set({ account }),
+  // ...
+}));
+```
+
+**关键 Stores：**
+
+- `models/auth.ts`: 认证状态和登录流程
+- `models/settings.ts`: 启动器设置和 Java 检测
+- `models/instance.ts`: 实例管理
+- `stores/game-store.ts`: 游戏运行状态
+- `stores/logs-store.ts`: 游戏日志流管理
+- `stores/ui-store.ts`: UI 状态（提示、模态框、活动视图）
+
+### 后端架构
+
+#### 命令模式
+
+所有 Tauri 命令遵循此结构：
+
+```rust
+#[tauri::command]
+async fn command_name(
+    window: Window,
+    state: State<'_, SomeState>,
+    param: Type,
+) -> Result<ReturnType, String> {
+    emit_log!(window, "状态消息");
+    // 异步逻辑
+    Ok(result)
+}
+```
+
+#### 事件通信
+
+**Rust → 前端（进度更新）：**
+
+```rust
+window.emit("launcher-log", "正在下载...")?;
+window.emit("download-progress", progress_struct)?;
+```
+
+**前端 → Rust（命令）：**
+
+```typescript
+import { invoke } from "@tauri-apps/api/core";
+const result = await invoke("start_game", { versionId: "1.20.4" });
+```
+
+### 核心模块
+
+#### 认证（`core/auth.rs`）
+
+- **微软 OAuth 2.0**: 设备代码流
+- **离线认证**: 本地 UUID 生成
+- **令牌管理**: 刷新令牌存储和自动刷新
+- **Xbox Live 集成**: 完整认证链
+
+**认证流程：**
+
+1. 设备代码请求 → MS 令牌
+2. Xbox Live 认证
+3. XSTS 授权
+4. Minecraft 令牌交换
+5. 配置文件获取
+
+#### 下载器（`core/downloader.rs`）
+
+- **并发下载**: 可配置线程池
+- **断点续传**: `.part` 和 `.part.meta` 文件
+- **多段下载**: 大文件分割成块
+- **校验和验证**: SHA1/SHA256 验证
+- **进度跟踪**: 实时事件到前端
+
+#### Java 管理（`core/java.rs`）
+
+- **自动检测**: 扫描系统路径
+- **Adoptium 集成**: 按需下载 JDK/JRE
+- **目录缓存**: 版本列表 24 小时缓存
+- **安装**: 提取到应用数据目录
+- **取消**: 下载取消的原子标志
+
+#### Fabric 支持（`core/fabric.rs`）
+
+- **Meta API 集成**: 获取加载器版本
+- **配置文件生成**: 创建版本 JSON
+- **库解析**: Maven 构件处理
+
+#### Forge 支持（`core/forge.rs`）
+
+- **安装程序执行**: 运行 Forge 安装程序
+- **配置文件解析**: 提取安装配置文件
+- **库管理**: 处理 Forge 特定库
+
+#### 实例系统（`core/instance.rs`）
+
+- **隔离**: 每个实例独立目录
+- **配置**: 每个实例的设置
+- **模组管理**: 实例特定模组
+- **版本锁定**: 可复现环境
+
+#### 版本管理
+
+- **清单解析**（`manifest.rs`）: Mojang 版本清单
+- **继承系统**（`version_merge.rs`）: 父版本合并
+- **游戏版本**（`game_version.rs`）: JSON 解析和验证
+- **规则引擎**（`rules.rs`）: 操作系统/功能条件逻辑
+
+### 文件结构
+
+```
+~/.local/share/com.dropout.launcher/  (Linux)
+~/Library/Application Support/com.dropout.launcher/  (macOS)
+%APPDATA%/com.dropout.launcher/  (Windows)
+├── versions/
+│   └── <version_id>/
+│       ├── <version_id>.json
+│       ├── <version_id>.jar
+│       └── natives/
+├── libraries/
+│   └── <maven-path>/
+├── assets/
+│   ├── indexes/
+│   └── objects/
+├── instances/
+│   └── <instance_name>/
+│       ├── mods/
+│       ├── config/
+│       └── saves/
+├── java/
+│   └── <version>/
+├── config.json
+└── accounts.json
+```
+
+## 数据流
+
+### 游戏启动序列
+
+1. **前端**: 用户点击"启动游戏"
+2. **命令**: 调用 `start_game(instance_id, version_id)`
+3. **后端处理**:
+   - 加载版本 JSON（带继承）
+   - 解析所有库
+   - 下载缺少的资源
+   - 提取原生库
+   - 构建类路径
+   - 构造 JVM 参数
+   - 替换占位符
+4. **进程生成**: 使用参数启动 Java
+5. **流日志**: 向前端发送 stdout/stderr
+6. **监视**: 跟踪游戏进程状态
+
+### 下载流程
+
+1. **队列创建**: 要下载的文件列表
+2. **并发处理**: 信号量限制线程
+3. **恢复检查**: 验证现有 `.part` 文件
+4. **下载**: 大文件多段
+5. **验证**: 校验和验证
+6. **进度事件**: 实时更新到 UI
+7. **完成**: 从 `.part` 移动到最终位置
+
+### 认证流程
+
+1. **设备代码请求**: 获取用户代码 + 设备代码
+2. **用户授权**: 用户访问 URL 并输入代码
+3. **令牌轮询**: 前端轮询完成
+4. **令牌交换**: MS 令牌 → Xbox → XSTS → Minecraft
+5. **配置文件获取**: 获取用户名和 UUID
+6. **存储**: 使用刷新令牌保存账户
+7. **自动刷新**: 过期时后台令牌刷新
+
+## 平台特定考虑
+
+### Linux
+
+- 使用 GTK WebView（`webkit2gtk`）
+- 从 `/usr/lib/jvm` 系统 Java 检测
+- 桌面文件集成
+
+### macOS
+
+- 使用系统 WebKit
+- 应用程序包结构
+- 钥匙串集成用于安全存储
+
+### Windows
+
+- 使用 WebView2 运行时
+- 注册表 Java 检测
+- MSI 安装程序支持
+- 发布版本中无控制台窗口
+
+## 性能优化
+
+- **并发下载**: 并行资源/库下载
+- **延迟加载**: 按需加载版本清单
+- **缓存**: Java 目录、版本清单
+- **原生代码**: 用于 CPU 密集型操作的 Rust
+- **异步 I/O**: 用于非阻塞操作的 Tokio
+
+## 安全功能
+
+- **令牌加密**: 安全存储认证令牌
+- **仅 HTTPS**: 所有外部 API 调用
+- **校验和验证**: 文件完整性验证
+- **沙箱执行**: Tauri 安全模型
+- **无任意代码**: 无 eval 或动态代码执行
-- 
cgit v1.2.3-70-g09d2

