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 模式，无需后端即可运行：

# 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

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

# 正式模式
flutter build apk --debug

Release Build

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

flutter build apk --release

---

调试运行

命令行调试

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

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

VSCode 调试配置

在 .vscode/launch.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 模式