# 开发环境配置指南

> 适用平台：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
```