chore(config): 初始化项目配置与部署基础

docs/设计文档/5.部署设计.md

@@ -18,6 +18,8 @@ python manage.py runserver
 
 本地运行使用 SQLite、`data/uploads` 和 `data/chroma`。
 
+当前本地方式会在启动时自动读取根目录 `.env`，因此 `runserver`、`pytest` 和日常脚本可以共享同一套配置。
+
 ## 3. Docker 运行方式
 
 建议命令：
@@ -47,6 +49,12 @@ V1 Docker Compose 只需要一个 Django Web 服务。Chroma 使用本地持久
 
 `.env.example` 应提供这些变量的样例，不写真实密钥。
 
+当前实现说明：
+
+- 本地 Python 方式启动时，会先加载根目录 `.env`，再读取进程环境中的覆盖值。
+- Docker Compose 方式可通过 `env_file` 向容器注入环境变量；当前仓库默认读取 `.env`。
+- 因此本地运行和容器运行可以默认共用一份 `.env`，但演示前仍应确认密钥和模型参数是否正确。
+
 ## 5. 目录挂载设计
 
 Docker 需要持久化以下目录：

docs/设计文档/模块设计/1.配置模块详细设计.md

@@ -97,6 +97,12 @@ V1 可使用标准库 `os.environ.get()`，不强制引入复杂配置库。
 
 `DJANGO_ALLOWED_HOSTS` 使用逗号分隔，空值时默认 `["*"]`。
 
+当前实现约束：
+
+- 本地直接运行 Django 命令时，会先尝试解析根目录 `.env` 文件，再读取进程环境中的覆盖值。
+- Docker Compose 方式可以通过 `env_file` 传入同一批变量；当前仓库默认读取 `.env`。
+- `.env.example` 只保留占位符示例，不保存真实 API Key。
+
 ## 8. 验收标准
 
 - `python manage.py check` 通过。

docs/需求分析/1.V1总需求文档.md

@@ -362,12 +362,28 @@ V1 模型适配器需要支持：
 环境变量示例：
 
 ```env
+DJANGO_SECRET_KEY=replace-with-a-local-secret-key
+DJANGO_DEBUG=true
+DJANGO_ALLOWED_HOSTS=*
+
 LLM_API_KEY=your_api_key
 LLM_BASE_URL=https://api.openai.com/v1
 LLM_MODEL=gpt-4.1-mini
+EMBEDDING_API_KEY=
+EMBEDDING_BASE_URL=
 EMBEDDING_MODEL=text-embedding-3-small
+SCENARIO_CONFIG_DIR=configs
+UPLOAD_ROOT=data/uploads
+CHROMA_PATH=data/chroma
 ```
 
+补充说明：
+
+- `EMBEDDING_API_KEY` 为空时可复用 `LLM_API_KEY`。
+- `EMBEDDING_BASE_URL` 为空时可复用 `LLM_BASE_URL`。
+- `.env.example` 仅作为模板，不允许放真实密钥。
+- 当前 V1 代码会在 settings 初始化时自动读取根目录 `.env`，本地运行与 `pytest` 可复用同一套配置；当前 Docker Compose 配置也通过 `env_file` 读取 `.env`。
+
 ## 10. Dify 集成策略
 
 V1 不把 Dify 作为核心依赖。

docs/需求分析/3.配置模块需求.md

@@ -55,6 +55,12 @@ Config 模块是 Django 项目的基础配置模块，负责系统启动、路
 | `UPLOAD_ROOT` | `data/uploads` | 上传文件目录 |
 | `SCENARIO_CONFIG_DIR` | `configs` | 场景配置目录 |
 
+补充要求：
+
+- `.env.example` 仅作为模板文件，不得写入真实密钥。
+- 本地直接执行 `python manage.py runserver` 时，应自动读取根目录 `.env`。
+- Docker 运行时可通过 `env_file` 或容器环境变量注入同一组配置；当前仓库默认由 Compose 读取 `.env`。
+
 ## 5. 目录需求
 
 系统启动时需要保证以下目录存在：
@@ -91,6 +97,8 @@ python manage.py migrate
 python manage.py runserver
 ```
 
+说明：上述命令执行前，应先准备好根目录 `.env`；当前 V1 代码会在启动时自动加载该文件。
+
 Docker 启动：
 
 ```bash