# 步骤 03：服务器配置页

> 实现服务器配置页 UI，包括输入验证、连接按钮状态机、最近连接列表。
> 对应流程：01 连接服务器（初始化配置部分）
> 依赖步骤：02（Bridge 层）

---

## 一、目标

- [ ] ServerConfigScreen 三段式页面布局（品牌区 / 输入区 / 最近连接）
- [ ] 输入框组件（地址、昵称、密码）
- [ ] 输入验证逻辑（必填校验、格式校验）
- [ ] 连接按钮状态机（空闲 → 连接中 → 成功/失败/超时）
- [ ] 最近连接列表（DataStore 持久化，快速连接）
- [ ] ServerViewModel 状态管理

---

## 二、任务清单

### 3.1 数据模型

**文件**：`android/app/src/main/java/com/tsmobile/app/data/Models.kt`

```kotlin
import kotlinx.serialization.Serializable

/**
 * 服务器连接配置。
 * 用于 ViewModel 状态和最近连接列表持久化。
 */
@Serializable
data class ServerConfig(
    val address: String = "",       // 服务器地址（域名/IP/TSDNS）
    val nickname: String = "",      // 昵称
    val password: String = "",      // 服务器密码（可选）
    val defaultChannel: String = "",         // 默认频道（可选）
    val defaultChannelPassword: String = "", // 默认频道密码（可选）
)

/**
 * 最近连接记录。
 * 点击可快速连接（复用 address/nickname/password）。
 */
@Serializable
data class RecentConnection(
    val address: String,
    val nickname: String,
    val password: String = "",
    val lastConnectedAt: Long = 0L,  // 最后连接时间戳（epoch ms）
    val lastSucceeded: Boolean = false, // 上次连接是否成功
)
```

### 3.2 最近连接存储

**文件**：`android/app/src/main/java/com/tsmobile/app/data/RecentConnectionsStore.kt`

使用 Jetpack DataStore Preferences 持久化最近连接列表。

```kotlin
import android.content.Context
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.*
import androidx.datastore.preferences.preferencesDataStore
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

// Context 扩展属性
private val Context.recentConnectionsDataStore: DataStore<Preferences>
    by preferencesDataStore(name = "recent_connections")

class RecentConnectionsStore(private val context: Context) {

    companion object {
        private const val MAX_RECENT = 10
        private val RECENTS_KEY = stringPreferencesKey("recents_json")
    }

    /**
     * 观察最近连接列表（按 lastConnectedAt 倒序）。
     */
    fun observeRecents(): Flow<List<RecentConnection>> {
        return context.recentConnectionsDataStore.data.map { prefs ->
            val json = prefs[RECENTS_KEY] ?: return@map emptyList()
            try {
                Json.decodeFromString<List<RecentConnection>>(json)
                    .sortedByDescending { it.lastConnectedAt }
            } catch (_: Exception) {
                emptyList()
            }
        }
    }

    /**
     * 记录一次连接（成功或失败）。
     * 相同 address + nickname 去重，保留最新记录。
     */
    suspend fun addRecent(recent: RecentConnection) {
        context.recentConnectionsDataStore.edit { prefs ->
            val current = try {
                Json.decodeFromString<List<RecentConnection>>(prefs[RECENTS_KEY] ?: "[]")
            } catch (_: Exception) {
                emptyList()
            }.toMutableList()

            // 去重：移除相同 address + nickname 的旧记录
            current.removeAll { it.address == recent.address && it.nickname == recent.nickname }
            current.add(0, recent) // 插入到头部

            // 限制最多 MAX_RECENT 条
            val trimmed = current.take(MAX_RECENT)
            prefs[RECENTS_KEY] = Json.encodeToString(trimmed)
        }
    }

    /**
     * 删除单条记录。
     */
    suspend fun removeRecent(address: String, nickname: String) {
        context.recentConnectionsDataStore.edit { prefs ->
            val current = try {
                Json.decodeFromString<List<RecentConnection>>(prefs[RECENTS_KEY] ?: "[]")
            } catch (_: Exception) {
                emptyList()
            }.toMutableList()

            current.removeAll { it.address == address && it.nickname == nickname }
            prefs[RECENTS_KEY] = Json.encodeToString(current)
        }
    }

    /**
     * 清空所有记录。
     */
    suspend fun clearAll() {
        context.recentConnectionsDataStore.edit { prefs ->
            prefs.remove(RECENTS_KEY)
        }
    }
}
```

**存储方案选择**：

| 方案 | 优缺点 | 结论 |
| --- | --- | --- |
| SharedPreferences | 简单，但已弃用 | ❌ |
| DataStore Preferences | 现代、协程友好、类型安全 | ✅ 采用 |
| Room DB | 过重，数据量小（最多 10 条） | ❌ |

### 3.3 页面布局

**文件**：`android/app/src/main/java/com/tsmobile/app/ui/screens/ServerConfigScreen.kt`

#### 三段式结构

```
┌──────────────────────────────┐
│           上：品牌区          │
│   [Logo]                     │
│   TeamSpeak Mobile           │
│   连接到你的 TeamSpeak 服务器 │
│                    [🌙 主题] │  ← 右上角主题切换
├──────────────────────────────┤
│           中：输入区          │
│  服务器地址                   │
│  ┌──────────────────────────┐│
│  │ ts.example.com           ││
│  └──────────────────────────┘│
│  昵称                        │
│  ┌──────────────────────────┐│
│  │ 我的昵称                  ││
│  └──────────────────────────┘│
│  密码（可选）                 │
│  ┌──────────────────────────┐│
│  │ ••••••                   ││
│  └──────────────────────────┘│
│  ┌──────────────────────────┐│
│  │      连接服务器           ││  ← 按钮状态见 3.5
│  └──────────────────────────┘│
├──────────────────────────────┤
│           下：最近连接        │
│  最近连接                     │
│  ┌──────────────────────────┐│
│  │ 🟢 ts.myserver.com       ││  ← 点击快速连接
│  │    MyNickname · 2小时前   ││
│  ├──────────────────────────┤│
│  │ 🔴 ts.other.com          ││
│  │    Bob · 昨天             ││
│  └──────────────────────────┘│
│  [清空最近记录]               │  ← 长按删除单条
└──────────────────────────────┘
```

#### Compose 结构

```kotlin
@Composable
fun ServerConfigScreen(
    viewModel: ServerViewModel,
    onNavigateToChannelList: () -> Unit, // 连接成功后跳转
) {
    val state by viewModel.state.collectAsState()
    val recents by viewModel.recents.collectAsState()

    Column(modifier = Modifier.fillMaxSize()) {
        // 上：品牌区
        BrandSection(
            onToggleTheme = { viewModel.toggleTheme() }
        )

        // 中：输入区
        InputSection(
            address = state.address,
            nickname = state.nickname,
            password = state.password,
            onAddressChange = viewModel::updateAddress,
            onNicknameChange = viewModel::updateNickname,
            onPasswordChange = viewModel::updatePassword,
            connectState = state.connectState,
            errorMessage = state.errorMessage,
            onConnect = { viewModel.connect() },
        )

        // 下：最近连接
        RecentConnectionsSection(
            recents = recents,
            onConnectRecent = { recent -> viewModel.quickConnect(recent) },
            onRemoveRecent = { recent -> viewModel.removeRecent(recent) },
            onClearAll = { viewModel.clearRecents() },
        )
    }

    // 连接成功后自动跳转
    LaunchedEffect(state.connectState) {
        if (state.connectState == ConnectState.SUCCESS) {
            onNavigateToChannelList()
        }
    }
}
```

#### 品牌区组件

```kotlin
@Composable
private fun BrandSection(onToggleTheme: () -> Unit) {
    Box(modifier = Modifier.fillMaxWidth().padding(top = 48.dp)) {
        Column(
            modifier = Modifier.align(Alignment.Center),
            horizontalAlignment = Alignment.CenterHorizontally,
        ) {
            // Logo（使用 drawable 资源或 placeholder）
            Icon(
                imageVector = Icons.Default.Dns, // 临时图标
                contentDescription = "TeamSpeak",
                modifier = Modifier.size(72.dp),
                tint = MaterialTheme.colorScheme.primary,
            )
            Spacer(Modifier.height(12.dp))
            Text(
                text = "TeamSpeak Mobile",
                style = MaterialTheme.typography.headlineMedium,
                fontWeight = FontWeight.Bold,
            )
            Text(
                text = "连接到你的 TeamSpeak 服务器",
                style = MaterialTheme.typography.bodyMedium,
                color = MaterialTheme.colorScheme.onSurfaceVariant,
            )
        }
        // 主题切换按钮（右上角）
        IconButton(
            onClick = onToggleTheme,
            modifier = Modifier.align(Alignment.TopEnd).padding(end = 8.dp),
        ) {
            Icon(Icons.Default.DarkMode, contentDescription = "切换主题")
        }
    }
}
```

#### 输入区组件

```kotlin
@Composable
private fun InputSection(
    address: String,
    nickname: String,
    password: String,
    onAddressChange: (String) -> Unit,
    onNicknameChange: (String) -> Unit,
    onPasswordChange: (String) -> Unit,
    connectState: ConnectState,
    errorMessage: String?,
    onConnect: () -> Unit,
) {
    Column(
        modifier = Modifier
            .fillMaxWidth()
            .padding(horizontal = 24.dp, vertical = 16.dp),
    ) {
        // 服务器地址
        OutlinedTextField(
            value = address,
            onValueChange = onAddressChange,
            label = { Text("服务器地址") },
            placeholder = { Text("ts.example.com") },
            singleLine = true,
            isError = connectState == ConnectState.FAILED && address.isBlank(),
            modifier = Modifier.fillMaxWidth(),
            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
        )

        Spacer(Modifier.height(12.dp))

        // 昵称
        OutlinedTextField(
            value = nickname,
            onValueChange = onNicknameChange,
            label = { Text("昵称") },
            placeholder = { Text("我的昵称") },
            singleLine = true,
            isError = connectState == ConnectState.FAILED && nickname.isBlank(),
            modifier = Modifier.fillMaxWidth(),
            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
        )

        Spacer(Modifier.height(12.dp))

        // 密码（可选）
        OutlinedTextField(
            value = password,
            onValueChange = onPasswordChange,
            label = { Text("密码（可选）") },
            placeholder = { Text("••••••") },
            singleLine = true,
            visualTransformation = PasswordVisualTransformation(),
            modifier = Modifier.fillMaxWidth(),
            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
        )

        Spacer(Modifier.height(24.dp))

        // 连接按钮（状态机驱动）
        ConnectButton(
            state = connectState,
            errorMessage = errorMessage,
            onClick = onConnect,
        )
    }
}
```

#### 最近连接组件

```kotlin
@Composable
private fun RecentConnectionsSection(
    recents: List<RecentConnection>,
    onConnectRecent: (RecentConnection) -> Unit,
    onRemoveRecent: (RecentConnection) -> Unit,
    onClearAll: () -> Unit,
) {
    if (recents.isEmpty()) return

    Column(
        modifier = Modifier
            .fillMaxWidth()
            .padding(horizontal = 24.dp, vertical = 8.dp),
    ) {
        Text(
            text = "最近连接",
            style = MaterialTheme.typography.titleSmall,
            color = MaterialTheme.colorScheme.onSurfaceVariant,
        )
        Spacer(Modifier.height(8.dp))

        recents.forEach { recent ->
            RecentConnectionItem(
                recent = recent,
                onClick = { onConnectRecent(recent) },
                onLongClick = { onRemoveRecent(recent) },
            )
            Spacer(Modifier.height(4.dp))
        }

        Spacer(Modifier.height(8.dp))
        TextButton(
            onClick = onClearAll,
            modifier = Modifier.align(Alignment.CenterHorizontally),
        ) {
            Text("清空最近记录")
        }
    }
}

@OptIn(ExperimentalFoundationApi::class)
@Composable
private fun RecentConnectionItem(
    recent: RecentConnection,
    onClick: () -> Unit,
    onLongClick: () -> Unit,
) {
    Card(
        modifier = Modifier
            .fillMaxWidth()
            .combinedClickable(onClick = onClick, onLongClick = onLongClick),
    ) {
        Row(
            modifier = Modifier.padding(12.dp),
            verticalAlignment = Alignment.CenterVertically,
        ) {
            // 状态指示灯
            Box(
                modifier = Modifier
                    .size(8.dp)
                    .background(
                        color = if (recent.lastSucceeded)
                            MaterialTheme.colorScheme.primary
                        else
                            MaterialTheme.colorScheme.error,
                        shape = CircleShape,
                    ),
            )
            Spacer(Modifier.width(12.dp))
            Column {
                Text(
                    text = recent.address,
                    style = MaterialTheme.typography.bodyMedium,
                    fontWeight = FontWeight.Medium,
                )
                Text(
                    text = "${recent.nickname} · ${formatRelativeTime(recent.lastConnectedAt)}",
                    style = MaterialTheme.typography.bodySmall,
                    color = MaterialTheme.colorScheme.onSurfaceVariant,
                )
            }
        }
    }
}
```

### 3.4 输入验证逻辑

**验证规则**（依据 UI 架构设计 2.1 节）：

| 字段 | 必填 | 验证规则 | 错误提示 |
| --- | --- | --- | --- |
| 服务器地址 | 是 | 非空，格式合法（域名/IP/TSDNS） | "请输入有效的服务器地址" |
| 昵称 | 是 | 非空，满足服务器命名规则 | "请输入昵称" |
| 密码 | 否 | 仅当服务器需要密码时必填 | "该服务器需要密码"（连接时由服务端返回） |

**验证时机**：用户点击"连接"时一次性校验，不实时校验（避免打断输入流）。

```kotlin
data class ValidationErrors(
    val address: String? = null,
    val nickname: String? = null,
)

fun validate(config: ServerConfig): ValidationErrors {
    val errors = ValidationErrors()

    // 地址验证：非空 + 基本格式（包含字母或数字，含可选端口）
    if (config.address.isBlank()) {
        errors.copy(address = "请输入服务器地址")
    } else if (!isValidServerAddress(config.address)) {
        errors.copy(address = "请输入有效的服务器地址")
    }

    // 昵称验证：非空
    if (config.nickname.isBlank()) {
        errors.copy(nickname = "请输入昵称")
    }

    return errors
}

/**
 * 服务器地址格式验证。
 * 支持：域名、IP（v4/v6）、TSDNS、带端口号。
 */
private fun isValidServerAddress(address: String): Boolean {
    val trimmed = address.trim()
    if (trimmed.isBlank()) return false

    // 允许格式：
    // - example.com
    // - example.com:9987
    // - 192.168.1.1
    // - 192.168.1.1:9987
    // - [::1]:9987
    // - _ts3._udp.example.com (TSDNS SRV)
    val ip4Pattern = Regex("""^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}(:\d+)?$""")
    val domainPattern = Regex("""^[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?)*(:\d+)?$""")
    val ip6Pattern = Regex("""^\[?[a-fA-F0-9:]+\]?(:\d+)?$""")

    return ip4Pattern.matches(trimmed) ||
           domainPattern.matches(trimmed) ||
           ip6Pattern.matches(trimmed)
}
```

### 3.5 连接按钮状态机

**状态定义**（依据 UI 架构设计 5.1 节）：

```kotlin
enum class ConnectState {
    IDLE,       // 空闲：等待用户输入并点击
    CONNECTING, // 连接中：Connect + WaitConnected 进行中
    SUCCESS,    // 连接成功：跳转频道列表页
    FAILED,     // 连接失败：显示错误信息和重试
    TIMEOUT,    // 连接超时：显示超时提示
}
```

**按钮外观对应**：

| 状态 | 按钮文本 | 样式 | 可点击 |
| --- | --- | --- | --- |
| `IDLE` | "连接服务器" | Primary Filled | ✅ |
| `CONNECTING` | "连接中..." | Outlined + loading indicator | ❌ |
| `SUCCESS` | — | 自动跳转，按钮不显示 | — |
| `FAILED` | "连接失败，点击重试" | Error container 色 | ✅ |
| `TIMEOUT` | "连接超时，点击重试" | Orange container 色 | ✅ |

**错误信息分类**：

| 错误类型 | 判断方式 | 提示信息 |
| --- | --- | --- |
| 密码错误 | 含 "password" 或 "密码" | "服务器密码错误" |
| 昵称冲突 | 含 "nickname" 或 "昵称" | "昵称已被使用，请更换" |
| 网络不可达 | 含 "timeout"、"unreachable"、"network" | "无法连接到服务器，请检查网络" |
| 地址无效 | 含 "resolve"、"dns"、"lookup" | "服务器地址无法解析" |
| 服务器满 | 含 "full"、"limit" | "服务器已满" |
| 其他 | 默认 | 原始错误信息 |

```kotlin
@Composable
fun ConnectButton(
    state: ConnectState,
    errorMessage: String?,
    onClick: () -> Unit,
) {
    Button(
        onClick = onClick,
        enabled = state != ConnectState.CONNECTING,
        modifier = Modifier.fillMaxWidth().height(48.dp),
        colors = when (state) {
            ConnectState.FAILED -> ButtonDefaults.buttonColors(
                containerColor = MaterialTheme.colorScheme.errorContainer,
                contentColor = MaterialTheme.colorScheme.onErrorContainer,
            )
            ConnectState.TIMEOUT -> ButtonDefaults.buttonColors(
                containerColor = Color(0xFFFFF3E0), // 橙色背景
                contentColor = Color(0xFFE65100),
            )
            else -> ButtonDefaults.buttonColors()
        },
    ) {
        when (state) {
            ConnectState.IDLE -> Text("连接服务器")
            ConnectState.CONNECTING -> {
                CircularProgressIndicator(
                    modifier = Modifier.size(20.dp),
                    strokeWidth = 2.dp,
                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f),
                )
                Spacer(Modifier.width(8.dp))
                Text("连接中...")
            }
            ConnectState.SUCCESS -> { /* 不会到达，自动跳转 */ }
            ConnectState.FAILED -> {
                Text(errorMessage ?: "连接失败，点击重试")
            }
            ConnectState.TIMEOUT -> Text("连接超时，点击重试")
        }
    }
}
```

### 3.6 ViewModel 状态管理

**文件**：`android/app/src/main/java/com/tsmobile/app/viewmodel/ServerViewModel.kt`

```kotlin
import android.app.Application
import androidx.lifecycle.AndroidViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.launch

data class ServerScreenState(
    val address: String = "",
    val nickname: String = "",
    val password: String = "",
    val connectState: ConnectState = ConnectState.IDLE,
    val errorMessage: String? = null,
    val validationErrors: ValidationErrors = ValidationErrors(),
)

class ServerViewModel(application: Application) : AndroidViewModel(application) {

    private val recentStore = RecentConnectionsStore(application)

    // 页面状态
    private val _state = MutableStateFlow(ServerScreenState())
    val state: StateFlow<ServerScreenState> = _state.asStateFlow()

    // 最近连接列表
    val recents: StateFlow<List<RecentConnection>> =
        recentStore.observeRecents()
            .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())

    // --- 输入更新 ---

    fun updateAddress(value: String) {
        _state.update { it.copy(address = value, errorMessage = null) }
    }

    fun updateNickname(value: String) {
        _state.update { it.copy(nickname = value, errorMessage = null) }
    }

    fun updatePassword(value: String) {
        _state.update { it.copy(password = value) }
    }

    // --- 连接 ---

    fun connect() {
        val current = _state.value
        if (current.connectState == ConnectState.CONNECTING) return

        // 输入验证
        val config = ServerConfig(
            address = current.address.trim(),
            nickname = current.nickname.trim(),
            password = current.password,
        )
        val errors = validate(config)
        if (errors.address != null || errors.nickname != null) {
            _state.update { it.copy(
                validationErrors = errors,
                connectState = ConnectState.IDLE,
                errorMessage = errors.address ?: errors.nickname,
            )}
            return
        }

        // 进入连接中状态
        _state.update { it.copy(
            connectState = ConnectState.CONNECTING,
            errorMessage = null,
            validationErrors = ValidationErrors(),
        )}

        // 异步连接（调用 TSBridge）
        viewModelScope.launch {
            val result = TSBridge.connect(
                host = config.address,
                nickname = config.nickname,
                password = config.password,
                callbacks = createBridgeCallbacks(),
            )

            if (result.isEmpty()) {
                // 连接成功（实际成功由 onConnected 回调确认）
                // 此处 Connect 已成功启动，等待 WaitConnected
            } else {
                // 连接失败
                val errorMsg = classifyError(result)
                _state.update { it.copy(
                    connectState = ConnectState.FAILED,
                    errorMessage = errorMsg,
                )}

                // 记录到最近连接（标记失败）
                recentStore.addRecent(RecentConnection(
                    address = config.address,
                    nickname = config.nickname,
                    password = config.password,
                    lastConnectedAt = System.currentTimeMillis(),
                    lastSucceeded = false,
                ))
            }
        }
    }

    /**
     * 最近连接快速连接。
     * 自动填充所有字段并触发连接。
     */
    fun quickConnect(recent: RecentConnection) {
        _state.update { it.copy(
            address = recent.address,
            nickname = recent.nickname,
            password = recent.password,
        )}
        connect()
    }

    fun removeRecent(recent: RecentConnection) {
        viewModelScope.launch {
            recentStore.removeRecent(recent.address, recent.nickname)
        }
    }

    fun clearRecents() {
        viewModelScope.launch {
            recentStore.clearAll()
        }
    }

    // --- Bridge 回调 ---

    private fun createBridgeCallbacks(): TSBridge.Callbacks = object : TSBridge.Callbacks {
        override fun onConnected() {
            _state.update { it.copy(connectState = ConnectState.SUCCESS) }

            // 记录到最近连接（标记成功）
            viewModelScope.launch {
                recentStore.addRecent(RecentConnection(
                    address = _state.value.address.trim(),
                    nickname = _state.value.nickname.trim(),
                    password = _state.value.password,
                    lastConnectedAt = System.currentTimeMillis(),
                    lastSucceeded = true,
                ))
            }
        }

        override fun onDisconnected(message: String) {
            // 连接阶段断开视为失败
            if (_state.value.connectState == ConnectState.CONNECTING) {
                _state.update { it.copy(
                    connectState = ConnectState.FAILED,
                    errorMessage = classifyError(message),
                )}
            }
        }

        override fun onTextMessage(msg: TextMsg) { /* 此阶段不处理 */ }
        override fun onClientEnter(client: Client) { /* 此阶段不处理 */ }
        override fun onClientLeave(id: Int, reasonMsg: String) { /* 此阶段不处理 */ }
        override fun onClientMoved(id: Int, targetChannelID: String) { /* 此阶段不处理 */ }
        override fun onKicked(reason: String) { /* 此阶段不处理 */ }
        override fun onVoiceData(clientID: Int, data: ByteArray, codec: Int) { /* 此阶段不处理 */ }
    }

    // --- 错误分类 ---

    private fun classifyError(raw: String): String {
        val lower = raw.lowercase()
        return when {
            "password" in lower || "密码" in lower -> "服务器密码错误"
            "nickname" in lower || "昵称" in lower -> "昵称已被使用，请更换"
            "timeout" in lower || "unreachable" in lower || "network" in lower ->
                "无法连接到服务器，请检查网络"
            "resolve" in lower || "dns" in lower || "lookup" in lower ->
                "服务器地址无法解析"
            "full" in lower || "limit" in lower -> "服务器已满"
            else -> raw
        }
    }
}
```

### 3.7 相对时间格式化

```kotlin
/**
 * 格式化时间戳为相对时间描述。
 * 例：刚刚、5分钟前、2小时前、昨天、3天前、2024-01-15
 */
fun formatRelativeTime(timestamp: Long): String {
    if (timestamp <= 0) return ""
    val now = System.currentTimeMillis()
    val diff = now - timestamp

    return when {
        diff < 60_000L -> "刚刚"
        diff < 3_600_000L -> "${diff / 60_000}分钟前"
        diff < 86_400_000L -> "${diff / 3_600_000}小时前"
        diff < 172_800_000L -> "昨天"
        diff < 604_800_000L -> "${diff / 86_400_000}天前"
        else -> {
            val sdf = java.text.SimpleDateFormat("yyyy-MM-dd", java.util.Locale.getDefault())
            sdf.format(java.util.Date(timestamp))
        }
    }
}
```

---

## 三、连接流程数据流

```
用户点击 "连接服务器"
    │
    ▼
ServerViewModel.connect()
    │
    ├─ validate(config)
    │   ├─ 失败 → 显示验证错误，状态保持 IDLE
    │   └─ 通过 ↓
    │
    ├─ state → CONNECTING（按钮显示 "连接中..."，禁用）
    │
    ├─ TSBridge.connect(host, nickname, password, callbacks)
    │   │
    │   ▼
    │   Go: TSClient.Connect(...)
    │   │
    │   ├─ 返回 ""（启动成功）→ 等待回调
    │   │   ├─ callbacks.onConnected() → state → SUCCESS → 跳转频道列表页
    │   │   └─ callbacks.onDisconnected(msg) → state → FAILED → 显示错误
    │   │
    │   └─ 返回 "error msg"（启动失败）→ state → FAILED → 显示错误
    │
    ├─ 记录到 RecentConnectionsStore
    │   └─ 成功：lastSucceeded = true（绿色）
    │   └─ 失败：lastSucceeded = false（红色）
    │
    └─ 用户可重试（点击按钮，state 回到 IDLE → 重新走连接流程）
```

---

## 四、文件清单

| 文件 | 说明 |
| --- | --- |
| `data/Models.kt` | ServerConfig、RecentConnection 数据类 |
| `data/RecentConnectionsStore.kt` | DataStore 持久化最近连接 |
| `ui/screens/ServerConfigScreen.kt` | 页面 Composable（品牌区 + 输入区 + 最近连接） |
| `ui/components/ConnectButton.kt` | 连接按钮状态机组件 |
| `viewmodel/ServerViewModel.kt` | 状态管理、验证、连接、错误分类 |
| `ui/navigation/NavGraph.kt` | 导航路由（步骤 01 已建，此处补充配置页路由） |

---

## 五、验收标准

| # | 验证项 | 验证方法 |
| --- | --- | --- |
| 1 | 页面布局正确 | 启动应用，确认三段式布局（品牌/输入/最近连接） |
| 2 | 输入验证生效 | 地址为空点击连接 → 提示 "请输入服务器地址"；昵称为空 → 提示 "请输入昵称" |
| 3 | 按钮状态机正确 | 点击连接 → 按钮变为 "连接中..." 并禁用 → 成功跳转 / 失败显示错误 |
| 4 | 错误信息分类正确 | 输入错误密码连接 → 显示 "服务器密码错误" |
| 5 | 最近连接记录 | 连接成功/失败后返回配置页，列表显示对应记录 |
| 6 | 最近连接快速连接 | 点击最近连接条目 → 自动填充并触发连接 |
| 7 | 最近连接删除 | 长按条目 → 删除；点击 "清空" → 全部清空 |
| 8 | 最多 10 条记录 | 连接超过 10 个不同服务器，列表只保留最新 10 条 |
| 9 | 状态灯颜色 | 成功的记录显示绿色，失败的显示红色 |
| 10 | 主题切换 | 点击右上角 🌙 → 主题切换，状态持久化 |

---

## 六、参考文档

- `docs/UI架构设计.md` — 2.1 服务器配置页（布局、验证规则、最近连接）
- `docs/流程/01_连接服务器.md` — 初始化配置、状态树、连接时序
- `docs/implementation/02_Bridge层实现.md` — TSBridge API 接口