# 配置模块详细设计

## 1. 模块目标

Config 模块负责 Django 项目的启动配置和总装配。它不承载业务逻辑，只为其他模块提供稳定运行环境。

目标：

- 项目本地和 Docker 均可启动。
- 环境变量可覆盖关键配置。
- App、模板、静态资源、上传文件和数据库路径统一配置。
- URL 总入口清晰，模块路由各自维护。

## 2. 职责边界

负责：

- `settings.py`、`urls.py`、`wsgi.py`、`asgi.py`。
- 环境变量读取和默认值。
- SQLite、静态文件、媒体文件、Chroma、场景配置目录。
- Django Admin 和模块 URL 装配。

不负责：

- 不读取场景 YAML 业务内容。
- 不调用 Agent Core。
- 不处理上传文件文本抽取。
- 不写审计日志。

## 3. 配置项设计

| 配置 | Django setting | 默认值 |
|---|---|---|
| `DJANGO_SECRET_KEY` | `SECRET_KEY` | `dev-secret-key` |
| `DJANGO_DEBUG` | `DEBUG` | `true` |
| `DJANGO_ALLOWED_HOSTS` | `ALLOWED_HOSTS` | `["*"]` |
| `UPLOAD_ROOT` | `MEDIA_ROOT` | `BASE_DIR / "data" / "uploads"` |
| `SCENARIO_CONFIG_DIR` | `SCENARIO_CONFIG_DIR` | `BASE_DIR / "configs"` |
| `CHROMA_PATH` | `CHROMA_PATH` | `BASE_DIR / "data" / "chroma"` |
| `LLM_API_KEY` | `LLM_API_KEY` | 空 |
| `LLM_BASE_URL` | `LLM_BASE_URL` | `https://api.openai.com/v1` |
| `LLM_MODEL` | `LLM_MODEL` | `gpt-4.1-mini` |
| `EMBEDDING_API_KEY` | `EMBEDDING_API_KEY` | 空，默认可复用 `LLM_API_KEY` |
| `EMBEDDING_BASE_URL` | `EMBEDDING_BASE_URL` | 空，默认可复用 `LLM_BASE_URL` |
| `EMBEDDING_MODEL` | `EMBEDDING_MODEL` | `text-embedding-3-small` |

## 4. 目录路径设计

启动前或初始化时应确保：

```text
data/
  uploads/
  chroma/
configs/
static/
templates/
```

V1 可以在 `settings.py` 中定义路径，在 management command 或启动脚本中创建目录。生产代码不应在每次请求中反复创建目录。

## 5. URL 总路由设计

`config.urls`：

```python
urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("apps.scenarios.urls")),
    path("chat/", include("apps.chat.urls")),
    path("documents/", include("apps.documents.urls")),
    path("audit/", include("apps.audit.urls")),
]
```

开发模式下追加 `static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)`，用于访问上传文件。

## 6. 静态资源与上传文件设计

- `STATIC_URL = "static/"`
- `STATICFILES_DIRS = [BASE_DIR / "static"]`
- `MEDIA_URL = "media/"`
- `MEDIA_ROOT = UPLOAD_ROOT`

上传文件路径由 Documents 模块按场景组织，Config 只提供根目录。

## 7. 环境变量读取设计

V1 可使用标准库 `os.environ.get()`，不强制引入复杂配置库。

布尔值规则：

```text
"1", "true", "yes", "on" -> True
其他 -> False
```

`DJANGO_ALLOWED_HOSTS` 使用逗号分隔，空值时默认 `["*"]`。

当前实现约束：

- 本地直接运行 Django 命令时，会先尝试解析根目录 `.env` 文件，再读取进程环境中的覆盖值。
- Docker Compose 方式可以通过 `env_file` 传入同一批变量；当前仓库默认读取 `.env`。
- `.env.example` 只保留占位符示例，不保存真实 API Key。

## 8. 验收标准

- `python manage.py check` 通过。
- `python manage.py migrate` 可执行。
- `/`、`/admin/` 路由可访问。
- `MEDIA_ROOT`、`CHROMA_PATH`、`SCENARIO_CONFIG_DIR` 在 settings 中可被其他模块引用。
- LLM 与 Embedding 配置只从 settings 或环境变量读取，不散落在业务代码中。