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

# Frontend Runtime

**Date:** 2026-03-06  
**Status:** Active  
**Audience:** 前端开发

---

## 技术栈

- **Framework:** Flutter (Dart)
- **Routing:** go_router
- **State Management:** BLoC + Cubit
- **API Client:** Dio + Retrofit
- **Mock Mode:** 支持 `--dart-define=MOCK_API=true`

---

## 开发环境

### 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`）

---

## 路由结构

### 认证路由（无需登录）

| 路由 | 页面 | 说明 |
|------|------|------|
| `/` | LoginScreen | 登录页（默认首页） |
| `/register` | RegisterScreen | 注册页 |
| `/register/verification` | RegisterVerificationScreen | 注册验证码页 |
| `/reset-password` | ResetPasswordScreen | 重置密码页 |

### 受保护路由（需要登录）

| 路由 | 页面 | 说明 |
|------|------|------|
| `/home` | HomeScreen | 首页（AI 助手） |
| `/contacts` | ContactsScreen | 通讯录 |
| `/contacts/add` | AddContactScreen | 添加联系人 |
| `/calendar/month` | CalendarMonthScreen | 月视图 |
| `/calendar/dayweek` | CalendarDayweekScreen | 日/周视图 |
| `/calendar/events/:id` | CalendarEventDetailScreen | 日程详情 |
| `/todo` | TodoQuadrantsScreen | 待办四象限 |
| `/messages/invites` | MessageInviteListScreen | 消息邀请列表 |
| `/messages/invites/:id` | MessageInviteDetailScreen | 消息邀请详情 |
| `/settings` | SettingsScreen | 设置首页 |
| `/settings/features` | FeaturesScreen | 功能开关 |
| `/settings/memory` | MemoryScreen | 记忆管理 |
| `/settings/account` | AccountScreen | 账号设置 |

---

## 功能模块

### Auth（认证）

**路径:** `apps/lib/features/auth/`

| 文件 | 说明 |
|------|------|
| `presentation/bloc/auth_bloc.dart` | 认证状态管理 |
| `presentation/cubits/` | 登录/注册/重置密码 Cubit |
| `ui/screens/` | 认证相关页面 |
| `data/repositories/auth_repository.dart` | 认证 API 调用 |

**流程：**
1. 注册： `/register` → 输入邮箱/用户名/密码 → `/register/verification` → 输入验证码 → `/home`
2. 登录: `/` → 输入邮箱/密码 → `/home`
3. 重置密码: `/reset-password` → 输入邮箱 → 收到邮件 → 输入验证码+新密码 → `/`

---

### Home（首页/AI 助手）

**路径:** `apps/lib/features/home/`

| 文件 | 说明 |
|------|------|
| `ui/screens/home_screen.dart` | 首页（AI 助手入口） |
| `ui/screens/home_sheet.dart` | 首页底部弹出面板 |

**功能：**
- AI 助手对话入口
- 快速访问常用功能

---

### Calendar（日历）

**路径:** `apps/lib/features/calendar/`

| 文件 | 说明 |
|------|------|
| `ui/screens/calendar_month_screen.dart` | 月视图 |
| `ui/screens/calendar_dayweek_screen.dart` | 日/周视图 |
| `ui/screens/calendar_event_detail_screen.dart` | 日程详情 |
| `ui/calendar_time_utils.dart` | 时间工具函数 |

**功能：**
- 月/日/周三视图切换
- 日程创建/编辑/删除
- 日程分享

---

### Todo（待办）

**路径:** `apps/lib/features/todo/`

| 文件 | 说明 |
|------|------|
| `ui/screens/todo_quadrants_screen.dart` | 四象限视图 |
| `ui/screens/todo_detail_screen.dart` | 待办详情 |

**功能：**
- 四象限管理（重要/紧急矩阵）
- 待办创建/编辑/完成/删除

---

### Contacts（通讯录）

**路径:** `apps/lib/features/contacts/`

| 文件 | 说明 |
|------|------|
| `ui/screens/contacts_screen.dart` | 通讯录列表 |
| `ui/screens/add_contact_screen.dart` | 添加联系人 |

**功能：**
- 好友列表
- 搜索用户
- 添加好友

---

### Messages（消息）

**路径:** `apps/lib/features/messages/`

| 文件 | 说明 |
|------|------|
| `ui/screens/message_invite_list_screen.dart` | 邀请消息列表 |
| `ui/screens/message_invite_detail_screen.dart` | 邀请详情 |

**功能：**
- 日程邀请通知
- 好友请求通知
- 群组邀请通知

---

### Settings（设置）

**路径:** `apps/lib/features/settings/`

| 文件 | 说明 |
|------|------|
| `ui/screens/settings_screen.dart` | 设置首页 |
| `ui/screens/features_screen.dart` | 功能开关 |
| `ui/screens/memory_screen.dart` | 记忆管理 |
| `ui/screens/account_screen.dart` | 账号设置 |

**功能：**
- 个人资料编辑
- 记忆管理（用户/工作记忆）
- 功能开关
- 账号安全设置

---

## 打包构建

### 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-03-06 | 完善路由结构、功能模块说明，补充技术栈信息 |
| 2026-02-27 | 新增 Frontend Runbook，支持 --dart-define=MOCK_API=true 切换 Mock 模式 |