# 配置模块需求文档

## 1. 模块定位

Config 模块是 Django 项目的基础配置模块，负责系统启动、路由装配、环境变量读取、静态资源、文件存储、数据库、日志和第三方组件配置。

该模块不承载业务逻辑，只负责让系统稳定启动，并为其他模块提供统一运行环境。

## 2. 模块目标

- 支持本地开发和 Docker 部署两种运行方式。
- 支持通过环境变量切换模型 API、Embedding API、调试模式和文件路径。
- 统一注册 Django Apps、模板目录、静态资源目录和上传目录。
- 提供系统级 URL 路由入口。
- 为后续扩展 PostgreSQL、Redis、Celery 等组件预留配置空间。

## 3. 职责边界

### 3.1 负责

- Django `settings.py` 配置。
- Django `urls.py` 总路由配置。
- WSGI / ASGI 启动配置。
- 环境变量读取。
- SQLite 默认数据库配置。
- 静态文件和上传文件配置。
- Chroma 本地持久化目录配置。
- LLM 与 Embedding 相关环境变量配置。

### 3.2 不负责

- 不处理具体 Agent 业务逻辑。
- 不解析场景 YAML。
- 不处理文件入库。
- 不直接调用大模型。
- 不保存审计日志。

## 4. 配置项需求

系统至少需要支持以下环境变量：

| 配置项 | 默认值 | 说明 |
|---|---|---|
| `DJANGO_SECRET_KEY` | `dev-secret-key` | Django 密钥 |
| `DJANGO_DEBUG` | `true` | 是否开启调试模式 |
| `DJANGO_ALLOWED_HOSTS` | `*` | 允许访问的主机 |
| `DATABASE_URL` | 空 | 预留配置，V1 默认 SQLite，不要求解析该配置 |
| `LLM_API_KEY` | 空 | 大模型 API Key |
| `LLM_BASE_URL` | `https://api.openai.com/v1` | OpenAI 兼容接口地址，可接入 OpenAI、硅基流动等兼容服务 |
| `LLM_MODEL` | `gpt-4.1-mini` | 默认模型名称 |
| `EMBEDDING_API_KEY` | 空 | Embedding API Key；为空时可复用 `LLM_API_KEY` |
| `EMBEDDING_BASE_URL` | 空 | Embedding OpenAI 兼容接口地址；为空时可复用 `LLM_BASE_URL` |
| `EMBEDDING_MODEL` | `text-embedding-3-small` | 默认 Embedding 模型名称 |
| `CHROMA_PATH` | `data/chroma` | Chroma 持久化目录 |
| `UPLOAD_ROOT` | `data/uploads` | 上传文件目录 |
| `SCENARIO_CONFIG_DIR` | `configs` | 场景配置目录 |

补充要求：

- `.env.example` 仅作为模板文件，不得写入真实密钥。
- 本地直接执行 `python manage.py runserver` 时，应自动读取根目录 `.env`。
- Docker 运行时可通过 `env_file` 或容器环境变量注入同一组配置；当前仓库默认由 Compose 读取 `.env`。

## 5. 目录需求

系统启动时需要保证以下目录存在：

```text
data/
  uploads/
  chroma/
  db.sqlite3

configs/
```

如果目录不存在，V1 可以在初始化脚本或启动流程中创建。

## 6. 路由需求

总路由需要聚合以下模块路由：

| 路径 | 模块 | 用途 |
|---|---|---|
| `/` | `apps.scenarios` | 首页和场景列表 |
| `/chat/` | `apps.chat` | Agent 对话 |
| `/documents/` | `apps.documents` | 文件上传和文档管理 |
| `/audit/` | `apps.audit` | 审计日志查看 |
| `/admin/` | Django Admin | 后台管理 |

## 7. 启动需求

本地启动：

```bash
python manage.py migrate
python manage.py runserver
```

说明：上述命令执行前，应先准备好根目录 `.env`；当前 V1 代码会在启动时自动加载该文件。

Docker 启动：

```bash
docker compose up --build
```

## 8. 验收标准

- 项目可以通过 `python manage.py runserver` 启动。
- 项目可以通过 `docker compose up --build` 启动。
- `/admin/` 可以访问。
- 首页 `/` 可以访问。
- 环境变量可以覆盖默认 LLM 与 Embedding 配置。
- 上传目录和 Chroma 目录有明确配置。