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

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

diff --git a/packages/docs/content/zh/features/authentication.mdx b/packages/docs/content/zh/features/authentication.mdx
deleted file mode 100644
index e83cc35..0000000
--- a/packages/docs/content/zh/features/authentication.mdx
+++ /dev/null
@@ -1,266 +0,0 @@
----
-title: 身份验证
-description: DropOut 中的 Microsoft OAuth 和离线身份验证
----
-
-# 身份验证
-
-DropOut 支持两种身份验证方法：Microsoft 账户（用于官方 Minecraft）和离线模式（用于测试和离线游玩）。
-
-## Microsoft 身份验证
-
-### 概述
-
-DropOut 使用 **Device Code Flow** 进行 Microsoft 身份验证，具有以下特点：
-- 无需重定向 URL（无需浏览器集成）
-- 适用于任何拥有浏览器的设备
-- 提供简单的基于代码的身份验证
-- 完全符合 Microsoft OAuth 2.0 标准
-
-### 身份验证流程
-
-身份验证链包含多个步骤：
-
-1. **Device Code** → 用户授权
-2. **MS Token** → 访问令牌 + 刷新令牌
-3. **Xbox Live** → Xbox 令牌 + UHS
-4. **XSTS** → 安全令牌
-5. **Minecraft** → 游戏访问令牌
-6. **Profile** → 用户名 + UUID
-
-#### 第 1 步：设备代码请求
-1. 单击"使用 Microsoft 登录"
-2. DropOut 从 Microsoft 请求设备代码
-3. 您会收到：
-   - 用户代码（例如 `A1B2-C3D4`）
-   - 验证 URL（通常为 `https://microsoft.com/link`）
-   - 设备代码（内部使用）
-
-#### 第 2 步：用户授权
-1. 在任何浏览器中访问验证 URL
-2. 输入用户代码
-3. 使用 Microsoft 账户登录
-4. 授权 DropOut 访问您的 Minecraft 个人资料
-
-#### 第 3 步：令牌交换
-- DropOut 轮询 Microsoft 检查授权完成
-- 授权后接收访问令牌和刷新令牌
-- 刷新令牌被存储以备将来登录使用
-
-#### 第 4 步：Xbox Live 身份验证
-- Microsoft 令牌被交换为 Xbox Live 令牌
-- 检索用户哈希 (UHS) 用于下一步
-
-#### 第 5 步：XSTS 授权
-- Xbox Live 令牌被用来获取 XSTS 令牌
-- 此令牌特定于 Minecraft 服务
-
-#### 第 6 步：Minecraft 登录
-- XSTS 令牌被交换为 Minecraft 访问令牌
-- 使用端点：`/launcher/login`
-
-#### 第 7 步：个人资料获取
-- 检索您的 Minecraft 用户名
-- 获取您的 UUID
-- 检查您是否拥有 Minecraft
-
-### 令牌管理
-
-**访问令牌：**
-- 短期有效（通常为 1 小时）
-- 用于游戏身份验证
-- 过期时自动刷新
-
-**刷新令牌：**
-- 长期有效（通常为 90 天）
-- 安全存储在 `accounts.json` 中
-- 用于获取新的访问令牌
-
-**自动刷新：**
-```rust
-// Automatic refresh when token expires
-if account.expires_at < current_time {
-    refresh_full_auth(&account).await?;
-}
-```
-
-### 安全考虑
-
-- 令牌存储在平台特定的应用数据目录中
-- 所有 API 调用仅使用 HTTPS
-- 不存储凭据（仅存储令牌）
-- 需要 User-Agent 标头（绕过 MS WAF）
-
-### Microsoft 登录故障排除
-
-**"Device code expired"（设备代码已过期）**
-- 代码在 15 分钟后过期
-- 重新开始登录流程
-
-**"Authorization pending"（授权待处理）**
-- 在等待阶段很正常
-- 在浏览器中完成授权
-
-**"Invalid token"（无效令牌）**
-- 令牌可能已过期
-- 登出后重新登录
-
-**"You don't own Minecraft"（您不拥有 Minecraft）**
-- 验证您的 Microsoft 账户拥有 Minecraft Java Edition
-- 在 https://www.minecraft.net/profile 检查
-
-## 离线身份验证
-
-### 概述
-
-离线模式创建一个不需要互联网连接或 Microsoft 账户的本地账户。这对以下情况很有用：
-- 测试和开发
-- 无网络游玩
-- LAN 多人游戏
-- Mod 开发
-
-### 创建离线账户
-
-1. 在登录屏幕单击"离线模式"
-2. 输入用户名（3-16 个字符）
-3. 单击"创建账户"
-
-### 工作原理
-
-**UUID 生成：**
-```rust
-// Deterministic UUID v3 from username
-let uuid = generate_offline_uuid(&username);
-```
-
-- 使用 UUID v3（基于命名空间）
-- 确定性：相同的用户名 = 相同的 UUID
-- 无需网络请求
-
-**身份验证：**
-- 返回 `"null"` 作为访问令牌
-- Minecraft 在离线模式下接受空令牌
-- 用户名和 UUID 本地存储
-
-### 限制
-
-- 无法加入在线服务器
-- 不支持皮肤
-- 不支持披风
-- 无法使用 Microsoft 账户功能
-
-### 用例
-
-**开发：**
-```bash
-# Testing mod development
-cargo tauri dev
-# Use offline mode to test quickly
-```
-
-**LAN 游玩：**
-- 无需身份验证即可加入 LAN 世界
-- 托管 LAN 世界
-
-**离线游玩：**
-- 单人游戏无需网络
-- 无需身份验证
-
-## 账户管理
-
-### 切换账户
-
-目前 DropOut 一次只支持一个活跃账户。多账户支持正在规划中。
-
-**切换账户的步骤：**
-1. 登出当前账户
-2. 使用新账户登录
-
-### 账户存储
-
-账户存储在 `accounts.json` 中：
-
-```json
-{
-  "current_account_id": "uuid-here",
-  "accounts": [
-    {
-      "id": "uuid",
-      "type": "Microsoft",
-      "username": "PlayerName",
-      "access_token": "...",
-      "refresh_token": "...",
-      "expires_at": 1234567890
-    }
-  ]
-}
-```
-
-### 删除账户
-
-删除账户的步骤：
-1. 打开设置
-2. 导航到账户
-3. 单击"登出"
-4. 或手动删除 `accounts.json`
-
-## API 参考
-
-### Tauri 命令
-
-**启动 Microsoft 登录：**
-```typescript
-const { user_code, verification_uri } = await invoke('start_microsoft_login');
-```
-
-**完成 Microsoft 登录：**
-```typescript
-const account = await invoke('complete_microsoft_login', { deviceCode });
-```
-
-**离线登录：**
-```typescript
-const account = await invoke('offline_login', { username: 'Player' });
-```
-
-**登出：**
-```typescript
-await invoke('logout');
-```
-
-**获取当前账户：**
-```typescript
-const account = await invoke('get_current_account');
-```
-
-### 事件
-
-**身份验证状态：**
-```typescript
-listen('auth-status', (event) => {
-  console.log(event.payload); // "logged_in" | "logged_out"
-});
-```
-
-## 最佳实践
-
-### 对于玩家
-
-1. **对官方服务器使用 Microsoft 账户**
-2. **保护令牌安全** - 不要分享 accounts.json
-3. **定期刷新令牌** - 通过登录来刷新
-4. **仅在测试时使用离线模式**
-
-### 对于开发者
-
-1. **优雅地处理令牌过期**
-2. **为网络故障实现重试逻辑**
-3. **缓存账户数据** 以减少 API 调用
-4. **在游戏启动前验证令牌**
-
-## 未来增强
-
-- **多账户支持**：轻松在账户之间切换
-- **账户配置文件**：保存每个账户的设置
-- **自动登录**：记住最后一个账户
-- **令牌加密**：为存储的令牌增强安全性
-- 
cgit v1.2.3-70-g09d2

