chore: initial commit - Supabase stack with local Docker configuration

docs/adr/0001-tech-stack.md

@@ -0,0 +1,38 @@
+# 技术栈选择
+
+## 背景
+
+本项目需要构建一个跨平台社交应用，支持本地开发和云端部署。
+
+## 决策
+
+1. **前端框架：Flutter**
+   - 跨平台支持（iOS / Android / Web）
+   - 高性能原生渲染
+   - 丰富的 UI 组件
+
+2. **后端框架：FastAPI**
+   - 高性能异步框架
+   - 自动生成 OpenAPI 文档
+   - 类型安全
+
+3. **数据库：Supabase（PostgreSQL）**
+   - 开箱即用的 PostgreSQL
+   - 内置认证和权限管理
+   - 实时订阅功能
+
+4. **缓存：Redis**
+   - 高性能键值存储
+   - 支持多种数据结构
+
+5. **向量数据库：Milvus**
+   - 高性能向量检索
+   - 支持大规模向量存储
+   - 适合 RAG 和推荐场景
+
+## 后续考虑
+
+根据业务发展，可能需要评估：
+- CDN 方案
+- 消息队列
+- 监控和日志系统

docs/architecture/overview.md

@@ -0,0 +1,17 @@
+# 系统架构概述
+
+## 技术栈
+
+- **前端**：Flutter
+- **后端**：FastAPI
+- **数据库**：Supabase（PostgreSQL）
+- **缓存**：Redis
+- **向量数据库**：Milvus
+- **部署**：Docker + 火山云（未来）
+
+## 架构特点
+
+- Monorepo 结构
+- 微服务架构（API + Worker）
+- 云原生设计
+- 支持本地 Docker 开发和云端部署

docs/rules/config-rules.md

@@ -0,0 +1,203 @@
+# 配置规则与使用原则
+
+## 配置文件组织
+
+### 1. 环境变量规范（真相源）
+
+**文件位置**：`configs/env/.env.example`
+
+**作用**：
+- 定义应用层环境变量的名称、类型、用途和敏感级别
+- 作为应用配置的"真相源"（source of truth）
+- 不可直接用于运行，仅作为参考和规范
+- Docker/Supabase 栈配置不在本文件，使用 `infra/local/env/.env.example`
+- 本文件仅包含应用层连接配置（如 `SUPABASE_URL`、`DATABASE_URL`），不包含 Supabase 栈运行变量
+- 不得在 `infra/local/env/.env.example` 中添加应用层变量（如 `PUBLIC_`、`API_`）
+
+**变量分类**：
+- `public`：可公开的信息，如服务地址、端口号
+- `secret`：敏感信息，如密钥、密码、连接串
+
+**变量块说明**：
+- A. 通用环境（APP_ENV、LOG_LEVEL、TZ）
+- B. Flutter 配置（仅 PUBLIC_ 变量）
+- C. FastAPI 服务配置
+- D. Supabase / Postgres 连接配置
+- E. Redis 配置
+- F. Milvus 配置
+- G. 对象存储配置（可选）
+- H. 其他配置
+
+### 2. 本地开发配置
+
+**文件位置**：`configs/env/.env`
+
+**作用**：
+- 本地应用层的实际配置文件
+- 从 `configs/env/.env.example` 复制后填入真实值
+- **禁止提交到 Git 仓库**
+
+**创建方式**：
+```bash
+cp configs/env/.env.example configs/env/.env
+# 编辑 configs/env/.env，填入实际值
+```
+
+### 3. 本地 Supabase 栈配置
+
+**文件位置**：`infra/local/env/.env`
+
+**作用**：
+- 本地 Supabase + 周边依赖的实际配置文件
+- 从 `infra/local/env/.env.example` 复制后填入真实值
+- **禁止提交到 Git 仓库**
+
+**创建方式**：
+```bash
+cp infra/local/env/.env.example infra/local/env/.env
+```
+
+### 4. 云端部署配置
+
+**方式一：环境文件**
+- 文件位置：`infra/cloud/volcano/env/.env`（不提交）
+- 从 `infra/cloud/volcano/env/.env.example` 复制后填入云端真实值
+- 仅用于本地测试云端连接
+
+**方式二：Secret 注入（推荐）**
+- 使用火山云或其他云平台的 Secret 管理服务
+- 通过 CI/CD 或容器运行时注入环境变量
+- 代码无需修改，通过环境切换
+
+### 5. 应用特定配置
+
+**Flutter 配置**：
+- `configs/flutter/dev.json` —— 开发环境
+- `configs/flutter/prod.json` —— 生产环境
+- 通过 `--dart-define` 在构建时注入
+
+## 安全原则
+
+### Public vs Secret
+
+**Public 变量**：
+- 可公开的服务地址和端口号
+- 前端可直接使用的配置
+- 示例：`PUBLIC_API_BASE_URL`、`API_PORT`
+
+**Secret 变量**：
+- 密钥、密码、连接串
+- 仅服务端使用的敏感信息
+- 示例：`DATABASE_URL`、`REDIS_URL`、`JWT_SECRET`
+
+### Flutter 配置限制
+
+**严格规则**：
+- Flutter 只能使用以 `PUBLIC_` 开头的变量
+- 严禁将任何 secret 信息注入到 Flutter
+- 通过 `--dart-define` 在构建时注入，运行时不可修改
+
+**示例**：
+```bash
+# ✅ 正确：Flutter 使用 PUBLIC_ 变量
+flutter run --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
+
+# ❌ 错误：Flutter 不能使用 secret
+flutter run --dart-define=DATABASE_URL=postgresql://user:pass@localhost/db
+```
+
+### 后端配置读取
+
+**严格规则**：
+- `apps/api` 和 `apps/worker` 只能通过环境变量读取配置
+- 不得直接读取 `infra/local/*.env` 文件路径
+- 使用 Python 的 `os.getenv()` 或环境变量库
+
+**示例**：
+```python
+# ✅ 正确：通过环境变量读取
+import os
+
+database_url = os.getenv("DATABASE_URL")
+
+# ❌ 错误：直接读取本地配置文件
+from dotenv import load_dotenv
+load_dotenv("configs/env/.env")  # 禁止
+```
+
+## 使用方式
+
+### 1. 本地开发
+
+1. 复制环境变量模板：
+   ```bash
+   make env
+   ```
+
+2. 启动依赖服务：
+   ```bash
+   make up
+   ```
+
+3. 启动后端服务：
+   ```bash
+   make api-dev
+   ```
+
+4. 启动 Flutter 应用：
+   ```bash
+   make flutter-dev
+   ```
+
+### 2. 云端部署
+
+1. 准备云端环境变量：
+   - 将 `.env.example` 中的变量映射到云平台 Secret
+- 或创建 `infra/cloud/volcano/env/.env`（仅用于本地测试）
+
+2. 修改配置指向云端：
+   ```bash
+   # 示例：修改 .env 指向火山云托管地址
+   REDIS_URL=redis://volcano-redis:6379/0
+   MILVUS_URI=https://volcano-milvus:19530
+   DATABASE_URL=postgresql://user:pass@volcano-postgres/db
+   ```
+
+3. 部署应用：
+   - 通过 CI/CD 自动注入环境变量
+   - 或通过云平台控制台配置
+
+## 配置优先级
+
+从高到低：
+1. 运行时环境变量（最高）
+2. 环境文件（`.env`）
+3. 配置文件（`configs/flutter/*.json`）
+
+## 常见问题
+
+### Q: 如何切换环境？
+
+**本地开发**：使用 `configs/env/.env`
+**云端部署**：使用云平台 Secret 注入
+
+### Q: 如何确保 secret 不泄露？
+
+- 所有 secret 变量使用 `CHANGE_ME` 占位符
+- 本地配置文件（`configs/env/.env`、`infra/local/env/.env`）添加到 `.gitignore`
+- 云端使用密钥管理服务注入
+
+### Q: 如何测试云端配置？
+
+1. 在本地创建 `infra/cloud/volcano/env/.env`（不提交）
+2. 修改变量指向云端地址
+3. 导出环境变量测试：
+   ```bash
+   export $(cat infra/cloud/volcano/env/.env | xargs)
+   ```
+
+### Q: Compose 如何读取配置？
+
+- 使用 `--env-file infra/local/env/.env` 注入本地 Supabase 栈变量
+- Compose 文件为 `infra/local/docker-compose.yml`
+- 应用代码通过 `os.getenv()` 读取本地应用变量

docs/rules/repo-structure.md

@@ -0,0 +1,21 @@
+# 目录结构规则
+
+## 顶层目录（必须遵守）
+
+仓库根目录只能包含以下目录：
+
+- `apps/` —— 可运行应用（Flutter / FastAPI / Worker）
+- `infra/` —— 基础设施（本地 docker / 云部署 / 迁移）
+- `configs/` —— 配置规范与公共配置模板（不含密钥）
+- `tools/` —— 脚本与生成器
+- `docs/` —— 文档与规则
+- `.github/`（可选，用于 CI/CD）
+- `README.md`
+- `Makefile`（可选）
+
+## 禁止事项
+
+- 禁止在根目录直接出现：`backend/`、`ui/`、`docker/`、`scripts/` 等非规范目录
+- 所有业务代码必须放在 `apps/` 目录下
+- 所有配置文件必须放在 `configs/` 目录下
+- 所有基础设施相关代码必须放在 `infra/` 目录下

docs/runbooks/cloud-volcano.md

@@ -0,0 +1,25 @@
+# 火山云部署指南
+
+## 准备工作
+
+1. 火山云账号
+2. 配置云端环境变量
+3. 准备镜像仓库
+
+## 环境变量模板
+
+云端模板文件位置：
+
+```bash
+cp infra/cloud/volcano/env/.env.example infra/cloud/volcano/env/.env
+```
+
+## 部署流程
+
+待补充详细步骤...
+
+## 注意事项
+
+- 确保所有敏感信息使用环境变量或密钥管理
+- 遵循最小权限原则
+- 配置适当的监控和日志

docs/runbooks/local-dev.md

@@ -0,0 +1,272 @@
+# 本地开发指南
+
+## 前置要求
+
+- 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`