docs(design): 补全中文设计文档体系

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

@@ -0,0 +1,106 @@
+# 配置模块详细设计
+
+## 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` 使用逗号分隔，空值时默认 `["*"]`。
+
+## 8. 验收标准
+
+- `python manage.py check` 通过。
+- `python manage.py migrate` 可执行。
+- `/`、`/admin/` 路由可访问。
+- `MEDIA_ROOT`、`CHROMA_PATH`、`SCENARIO_CONFIG_DIR` 在 settings 中可被其他模块引用。
+- LLM 与 Embedding 配置只从 settings 或环境变量读取，不散落在业务代码中。