chore: 添加 macOS/Web 平台支持 + 修复编译错误 + 开发环境文档

- 修复 CardTheme → CardThemeData（Flutter 3.41 API 变更） - 修复 finance_screen 缺少 FormDialog import - 修复工具栏 Row overflow（添加横向滚动） - flutter create --platforms=macos,web 生成平台配置 - 添加 docs/dev-setup.md：完整开发环境配置指南含 Go/Flutter/Docker 安装、已知 macOS 26 兼容问题及解决方案 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-04 13:36:39 +08:00
parent 76ab19ea47
commit 7849f6e7e5
47 changed files with 2537 additions and 3 deletions
@@ -0,0 +1,221 @@
+# 开发环境配置指南
+
+> 适用平台：macOS（Apple Silicon / Intel）
+
+---
+
+## 一、必备工具安装
+
+### 1. Homebrew（包管理器）
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+安装后确保 PATH 生效（Apple Silicon 路径为 `/opt/homebrew/bin`）：
+
+```bash
+echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+---
+
+### 2. Go（后端语言）
+
+```bash
+brew install go
+```
+
+验证：
+
+```bash
+export PATH="/opt/homebrew/bin:$PATH"
+go version   # 期望：go1.26.x
+```
+
+**注意**：每次运行 Go 命令前须确保 PATH 包含 Homebrew 路径：
+
+```bash
+export PATH="/opt/homebrew/bin:$PATH"
+go build ./...
+```
+
+---
+
+### 3. Flutter（前端框架）
+
+```bash
+brew install --cask flutter
+```
+
+验证：
+
+```bash
+flutter --version   # 期望：Flutter 3.41.x
+```
+
+#### 3.1 安装 CocoaPods（macOS 桌面版必须）
+
+```bash
+brew install cocoapods
+```
+
+#### 3.2 验证全部环境
+
+```bash
+flutter doctor
+```
+
+期望输出（Android 可以有警告，不影响 macOS/Web 开发）：
+
+```
+[✓] Flutter
+[✓] Xcode - develop for iOS and macOS
+[✓] Chrome - develop for the web
+[✓] Connected device
+```
+
+---
+
+### 4. Docker（本地数据库）
+
+```bash
+brew install --cask docker
+```
+
+安装后打开 Docker Desktop 应用完成初始化。
+
+---
+
+### 5. 其他工具（可选）
+
+```bash
+brew install git          # 版本管理
+brew install --cask vscode  # 代码编辑器（推荐安装 Go 和 Flutter 插件）
+```
+
+---
+
+## 二、项目初始化
+
+### 克隆 / 进入项目
+
+```bash
+cd /Users/wangjia/code/jiu
+```
+
+### 后端依赖
+
+```bash
+cd backend
+export PATH="/opt/homebrew/bin:$PATH"
+go mod download
+```
+
+### 前端依赖
+
+```bash
+cd client
+flutter pub get
+```
+
+---
+
+## 三、本地开发启动
+
+### 1. 启动数据库
+
+```bash
+cd deploy
+docker compose up -d
+```
+
+- MySQL 端口：`3306`
+- Adminer（数据库管理界面）：http://localhost:8888
+  - 服务器：`mysql`，用户：`root`，密码：`password`，数据库：`jiu_db`
+
+### 2. 启动后端
+
+```bash
+cd backend
+export PATH="/opt/homebrew/bin:$PATH"
+go run main.go
+```
+
+后端启动后监听 `http://localhost:8080`
+
+### 3. 启动 Flutter 前端
+
+#### Web（推荐开发时使用，稳定）
+
+```bash
+cd client
+flutter run -d chrome
+```
+
+> macOS 26（beta）下 debug 模式可能有 Flutter 框架断言 bug，加 `--profile` 规避：
+> ```bash
+> flutter run -d chrome --profile
+> ```
+
+#### macOS 桌面版
+
+```bash
+cd client
+flutter run -d macos --no-enable-impeller
+```
+
+> `--no-enable-impeller`：绕过 macOS 26 上 Impeller 着色器编译 OOM 问题
+
+---
+
+## 四、运行测试
+
+```bash
+cd backend
+export PATH="/opt/homebrew/bin:$PATH"
+go test ./... -cover
+```
+
+---
+
+## 五、已知问题（macOS 26 beta 环境）
+
+| 问题 | 原因 | 解决方式 |
+|------|------|---------|
+| Impeller 着色器编译 exit code -9 | macOS 26 内存压力 + OOM killer | `flutter run --no-enable-impeller` |
+| KeyDownEvent 断言失败（桌面版） | Flutter 3.41 + macOS 26 已知 bug | 改用 Chrome 运行，或等 Flutter 修复 |
+| mouse_tracker 断言失败（debug） | Flutter debug 断言 + hover 事件 | 用 `--profile` 模式运行 |
+
+---
+
+## 六、环境变量说明
+
+敏感配置放在 `~/.env`，通过 `.zshrc` 自动加载（无需手动 source）。
+
+后端本地开发配置在 `backend/config/config.yaml`（已被 `.gitignore` 排除）：
+
+```yaml
+database:
+  dsn: "root:password@tcp(localhost:3306)/jiu_db?charset=utf8mb4&parseTime=True&loc=Local"
+jwt:
+  secret: "dev-secret-change-in-prod"
+license:
+  hmac_secret: "dev-hmac-secret-change-in-prod"
+```
+
+---
+
+## 七、flutter doctor 完整检查（参考输出）
+
+```
+[✓] Flutter (Channel stable, 3.41.6, on macOS 26.x darwin-arm64)
+[!] Android toolchain  ← 不影响 macOS/Web 开发，可忽略
+[✓] Xcode - develop for iOS and macOS (Xcode 26.x)
+[✓] Chrome - develop for the web
+[✓] Connected device (2 available)
+    • macOS (desktop)
+    • Chrome (web)
+[✓] Network resources
+```