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>
---
 packages/docs/content/zh/architecture.mdx | 281 ------------------------------
 1 file changed, 281 deletions(-)
 delete mode 100644 packages/docs/content/zh/architecture.mdx

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

diff --git a/packages/docs/content/zh/architecture.mdx b/packages/docs/content/zh/architecture.mdx
deleted file mode 100644
index 6a2a2df..0000000
--- a/packages/docs/content/zh/architecture.mdx
+++ /dev/null
@@ -1,281 +0,0 @@
----
-title: 架构设计
-description: DropOut Minecraft 启动器的技术架构和设计
----
-
-# 架构设计
-
-DropOut 采用现代技术栈构建，旨在实现高性能、安全性和跨平台兼容性。
-
-## 技术栈
-
-### 后端（Rust）
-- **框架**: Tauri v2
-- **语言**: Rust（Edition 2021）
-- **异步运行时**: Tokio
-- **HTTP 客户端**: reqwest with native-tls
-
-### 前端（Svelte）
-- **框架**: Svelte 5（with runes）
-- **样式**: Tailwind CSS 4
-- **构建工具**: Vite with Rolldown
-- **包管理器**: pnpm
-
-### 文档
-- **框架**: Fumadocs with React Router v7
-- **内容**: MDX 文件
-- **样式**: Tailwind CSS 4
-
-## 系统架构
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                  前端（Svelte 5）                        │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
-│  │  Stores  │  │Components│  │ UI Views │  │Particles│ │
-│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
-│       │             │             │              │      │
-│       └─────────────┴─────────────┴──────────────┘      │
-│                          │                              │
-│                   Tauri 命令                            │
-│                    事件/发射器                          │
-└──────────────────────────┬──────────────────────────────┘
-                           │
-┌──────────────────────────┴──────────────────────────────┐
-│                后端（Rust/Tauri）                        │
-│  ┌─────────────────────────────────────────────────┐    │
-│  │               main.rs（命令）                    │    │
-│  └──────────────┬──────────────────────────────────┘    │
-│                 │                                        │
-│  ┌──────────────┴───────────────────────────────┐       │
-│  │               核心模块                       │       │
-│  │  ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐  │       │
-│  │  │ Auth │ │Download│ │ Java │ │ Instance │  │       │
-│  │  └──────┘ └────────┘ └──────┘ └──────────┘  │       │
-│  │  ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐  │       │
-│  │  │Fabric│ │ Forge  │ │Config│ │Manifest  │  │       │
-│  │  └──────┘ └────────┘ └──────┘ └──────────┘  │       │
-│  └──────────────────────────────────────────────┘       │
-│                                                          │
-│  ┌─────────────────────────────────────────────────┐    │
-│  │                工具和辅助函数                    │    │
-│  │  • ZIP 提取  • 路径工具                         │    │
-│  └─────────────────────────────────────────────────┘    │
-└──────────────────────────┬──────────────────────────────┘
-                           │
-                    外部 API
-                           │
-        ┌──────────────────┼──────────────────┐
-        │                  │                  │
-  ┌─────┴────┐      ┌──────┴─────┐    ┌──────┴─────┐
-  │  Mojang  │      │   Fabric   │    │   Forge    │
-  │   APIs   │      │    Meta    │    │   Maven    │
-  └──────────┘      └────────────┘    └────────────┘
-```
-
-## 核心组件
-
-### 前端状态管理
-
-DropOut 使用 **Svelte 5 runes** 进行响应式状态管理：
-
-```typescript
-// stores/auth.svelte.ts
-export class AuthState {
-  currentAccount = $state<Account | null>(null);  // 响应式
-  isLoginModalOpen = $state(false);
-  
-  $effect(() => {  // 副作用
-    // 依赖变化时自动运行
-  });
-}
-```
-
-**关键 Stores：**
-- `auth.svelte.ts`: 认证状态和登录流程
-- `settings.svelte.ts`: 启动器设置和 Java 检测
-- `game.svelte.ts`: 游戏运行状态和日志
-- `instances.svelte.ts`: 实例管理
-- `ui.svelte.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(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

