social-app/docs/runtime/runtime-frontend.md

# Frontend Runtime Runbook

**Date:** 2026-02-27
**Status:** Active
**Audience:** 前端开发

---

## 开发环境

### Mock 模式

前端开发时可通过 `--dart-define` 切换 Mock 模式，无需后端即可运行：

```bash
# Mock 模式（本地开发，无需后端）
flutter run --dart-define=MOCK_API=true

# 正式模式（需要后端运行）
flutter run
```

### Mock 自动登录

Mock 模式下，启动 App 时会自动使用测试账号登录并跳转到首页。

**测试账号（Mock）:**

| 场景 | 邮箱 | 密码 | 说明 |
|------|------|------|------|
| 正常登录 | 任意非 error@test.com | 任意 | 登录成功 |
| 登录失败 | error@test.com | 任意 | 返回 401 |

**验证码:** 任意 6 位数字（建议使用 `123456`）

---

## 打包构建

### Debug Build

```bash
# Mock 模式
flutter build apk --debug --dart-define=MOCK_API=true

# 正式模式
flutter build apk --debug
```

### Release Build

Release 构建强制使用正式 API，不受 `MOCK_API` 影响：

```bash
flutter build apk --release
```

---

## 调试运行

### 命令行调试

```bash
# Mock 模式（无需后端，自动登录）
flutter run --dart-define=MOCK_API=true -d emulator-5554

# 正式模式（需要后端运行）
flutter run -d emulator-5554
```

### VSCode 调试配置

在 `.vscode/launch.json` 中添加配置：

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Mock Mode",
      "request": "launch",
      "type": "dart",
      "args": ["--dart-define=MOCK_API=true"]
    },
    {
      "name": "正式模式",
      "request": "launch",
      "type": "dart"
    }
  ]
}
```

配置完成后，在 VSCode 左侧 Debug 面板的 dropdown 中选择 "Mock Mode" 或 "正式模式" 进行调试。

---

## Change Log

| 日期 | 变更 |
|------|------|
| 2026-02-27 | 新增 Frontend Runbook，支持 --dart-define=MOCK_API=true 切换 Mock 模式 |