refactor: 优化日历状态管理与首页输入框，添加API客户端抽象

2026-02-27 18:36:21 +08:00
parent 80d04688fc
commit 3d6ae7695f
20 changed files with 2146 additions and 801 deletions
@@ -0,0 +1,103 @@
+# 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 模式 |