chore: initial commit - Supabase stack with local Docker configuration

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()` 读取本地应用变量