social-app/docs/runbooks/local-dev.md

# 本地开发指南

## 前置要求

- Docker 和 Docker Compose
- Flutter SDK
- Python 3.11+

## 快速开始

### 1. 配置环境变量

```bash
make env
```

按照提示创建并编辑应用配置 `configs/env/.env`，并创建 Supabase 本地栈配置 `infra/local/env/.env`。

创建配置文件：

```bash
cp configs/env/.env.example configs/env/.env
cp infra/local/env/.env.example infra/local/env/.env
```

确保以下变量配置正确：
- `DATABASE_URL`（连接到 localhost:54322）
- `REDIS_URL`（连接到 localhost:6379）
- `MILVUS_URI`（连接到 localhost:19530）

### 2. 启动依赖服务

```bash
make up
```

这将启动以下服务：
- **Redis**：端口 6379
- **Milvus**：端口 19530 (gRPC) / 19111 (HTTP)
- **Postgres**：端口 54322

### 3. 检查服务状态

```bash
make ps
```

确保所有服务显示为 `Up` 状态。

### 4. 查看服务日志

```bash
# 查看所有服务日志
make logs

# 查看特定服务日志
make logs SERVICE=redis
make logs SERVICE=milvus
make logs SERVICE=db
```

## 启动应用

### 启动 FastAPI 后端

```bash
make api-dev
```

或手动启动：

```bash
cd apps/api

# 创建虚拟环境（首次）
python -m venv .venv
source .venv/bin/activate

# 安装依赖（首次）
pip install -r requirements.txt

# 启动服务
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
```

后端启动后，访问：
- API 文档：http://localhost:8000/docs
- ReDoc：http://localhost:8000/redoc

### 启动 Flutter 应用

```bash
make flutter-dev
```

或手动启动：

```bash
cd apps/mobile

# 安装依赖（首次）
flutter pub get

# 启动开发服务器
flutter run --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000

# 或指定设备
flutter run -d chrome --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
```

构建 Android APK：

```bash
flutter build apk --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
```

## 初始化 Milvus

```bash
make milvus-init
```

或手动运行初始化脚本：

```bash
bash tools/scripts/init_milvus.sh
```

## 常用命令

### 依赖服务管理

```bash
# 启动服务
make up

# 停止服务
make down

# 重启服务
make down && make up

# 查看状态
make ps

# 查看日志
make logs

# 清理数据（警告：会丢失数据）
make clean
```

### 应用管理

```bash
# 启动后端
make api-dev

# 启动前端
make flutter-dev

# 配置环境变量
make env
```

## 常见问题

### 端口冲突

如果启动依赖服务时出现端口冲突：

1. 检查端口占用：
   ```bash
   # 检查 6379（Redis）
   lsof -i :6379

   # 检查 54322（Postgres）
   lsof -i :54322

   # 检查 19530（Milvus）
   lsof -i :19530
   ```

2. 停止占用端口的进程，或修改 `infra/local/docker-compose.yml` 中的端口映射

### 容器未健康

如果服务状态显示 `Up (health: starting)` 但一直未变成 `Up (healthy)`：

1. 查看服务日志：
   ```bash
   make logs SERVICE=<service_name>
   ```

2. 检查依赖服务是否正常启动：
   ```bash
   make ps
   ```

3. 重启服务：
   ```bash
    docker compose -f infra/local/docker-compose.yml --env-file infra/local/env/.env restart <service_name>
   ```

### 后端无法连接数据库

1. 检查 Postgres 是否正常启动：
   ```bash
   make ps
   ```

2. 检查环境变量配置：
   ```bash
    cat configs/env/.env | grep DATABASE_URL
   ```

3. 确保数据库 URL 格式正确：
   ```
   postgresql://postgres:postgres@localhost:54322/postgres
   ```

### Flutter 无法连接后端

1. 确保后端服务已启动并监听在 8000 端口：
   ```bash
   curl http://localhost:8000/docs
   ```

2. 检查 Flutter 的 API_BASE_URL 是否正确注入：
   ```bash
   flutter run --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
   ```

3. 如果使用模拟器，确保能访问 localhost：
   - Android 模拟器：使用 `10.0.2.2` 代替 `localhost`
   - iOS 模拟器：使用 `localhost` 即可

### Milvus 连接失败

1. 检查 Milvus 服务是否健康：
   ```bash
   make ps
   ```

2. 等待 Milvus 完全启动（可能需要 1-2 分钟）：
   ```bash
   make logs SERVICE=milvus
   ```

3. 测试连接：
   ```bash
   curl http://localhost:19530/healthz
   ```

## 清理环境

```bash
# 停止所有服务
make down

# 清理数据卷（警告：会丢失所有数据）
make clean

# 完全清理（包括未使用的镜像）
docker system prune -a
```

## 下一步

- 阅读架构文档：`docs/architecture/overview.md`
- 了解配置规则：`docs/rules/config-rules.md`
- 查看技术栈决策：`docs/adr/0001-tech-stack.md`