Implement unified story generation flow

docs/technical/environment-configuration.md

@@ -0,0 +1,54 @@
+# 环境变量配置约定
+
+DreamWeaver 只把 `backend/.env` 视为应用运行配置文件。根目录 `.env` 可以存在，但它只服务 Docker Compose 本身，不参与后端配置加载。
+
+## 文件职责
+
+| 文件 | 读取方 | 放什么 | 不放什么 |
+| --- | --- | --- | --- |
+| `backend/.env` | FastAPI、Admin API、Celery worker、Celery beat、Docker 后端服务 | `SECRET_KEY`、`DATABASE_URL`、Redis/Celery URL、Provider 列表、AI key、OAuth key、Admin 账号 | Docker 镜像源、npm registry |
+| `.env` | Docker Compose 插值 | `PYTHON_BASE_IMAGE`、`NODE_BASE_IMAGE`、`NGINX_BASE_IMAGE`、`NPM_REGISTRY` 等镜像源/registry 覆盖 | AI key、OAuth key、`SECRET_KEY`、后端运行配置 |
+| `backend/.env.example` | 人读/复制模板 | `backend/.env` 的完整示例 | 真实密钥 |
+
+## 为什么不让后端读取根目录 `.env`
+
+`pydantic-settings` 的相对 `env_file=".env"` 会受当前工作目录影响：在仓库根目录启动会读根 `.env`，在 `backend/` 目录启动会读 `backend/.env`。这会导致同一条启动命令在不同目录下使用不同配置。
+
+当前代码在 `backend/app/core/config.py` 中固定使用绝对路径 `backend/.env`。因此后端从任意工作目录启动时都读取同一个文件。
+
+## Docker 演示
+
+Docker 后端服务通过 `env_file: ./backend/.env` 读取应用配置。默认容器内地址应保持为服务名：
+
+```env
+DATABASE_URL=postgresql+asyncpg://dreamweaver:dreamweaver_password@db:5432/dreamweaver_db
+CELERY_BROKER_URL=redis://redis:6379/0
+CELERY_RESULT_BACKEND=redis://redis:6379/0
+REDIS_URL=redis://redis:6379/0
+```
+
+Postgres 容器只接收 `docker-compose.yml` 中固定的 demo 账号和数据库名，避免把 AI/OAuth key 注入基础设施容器。后端服务读取 `backend/.env` 中的 `DATABASE_URL`。需要改 Docker demo 的数据库账号时，同时修改 `docker-compose.yml` 的 `db.environment` 和 `backend/.env` 的 `DATABASE_URL`。Docker demo 固定暴露 `52432:5432` 和 `52379:6379`，本机直跑后端时按这些宿主机端口连接。
+
+## 本机直跑后端
+
+本机直接运行 `uvicorn`、`celery` 或 `alembic` 时也只改 `backend/.env`，把数据库和 Redis URL 改成宿主机端口：
+
+```env
+DATABASE_URL=postgresql+asyncpg://dreamweaver:dreamweaver_password@localhost:52432/dreamweaver_db
+CELERY_BROKER_URL=redis://localhost:52379/0
+CELERY_RESULT_BACKEND=redis://localhost:52379/0
+REDIS_URL=redis://localhost:52379/0
+```
+
+## 检查命令
+
+```bash
+# 后端实际读取哪个 env 文件
+backend/.venv/bin/python - <<'PY'
+from app.core.config import BACKEND_ENV_FILE
+print(BACKEND_ENV_FILE)
+PY
+
+# Docker 后端容器实际环境，注意不要把输出贴到公共渠道
+docker compose exec backend env | sort
+```