refactor(django): 补充应用外壳层中文注释

config/settings.py

@@ -6,6 +6,12 @@ BASE_DIR = Path(__file__).resolve().parent.parent
 
 
 def load_dotenv(dotenv_path: Path) -> None:
+    """
+    读取根目录 `.env` 并注入进程环境。
+
+    这里使用极简解析逻辑，目的是减少额外依赖，
+    同时让本地 `runserver`、`pytest` 与 Docker Compose 共用一套配置文件。
+    """
     if not dotenv_path.exists():
         return
     for raw_line in dotenv_path.read_text(encoding="utf-8").splitlines():
@@ -22,12 +28,14 @@ load_dotenv(BASE_DIR / ".env")
 
 
 def env_bool(name: str, default: bool = False) -> bool:
+    """将常见的字符串布尔值转换为 Python bool。"""
     value = os.environ.get(name)
     if value is None:
         return default
     return value.lower() in {"1", "true", "yes", "on"}
 
 
+# Django 核心运行参数。
 SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "dev-secret-key")
 DEBUG = env_bool("DJANGO_DEBUG", True)
 ALLOWED_HOSTS = [
@@ -78,6 +86,7 @@ TEMPLATES = [
 
 WSGI_APPLICATION = "config.wsgi.application"
 
+# V1 默认使用 SQLite，确保本地演示零外部依赖。
 DATABASES = {
     "default": {
         "ENGINE": "django.db.backends.sqlite3",
@@ -93,11 +102,15 @@ USE_TZ = True
 STATIC_URL = "static/"
 STATICFILES_DIRS = [BASE_DIR / "static"]
 MEDIA_URL = "media/"
+# 上传根目录可通过环境变量覆盖，便于 Docker 挂载到持久化目录。
 MEDIA_ROOT = Path(os.environ.get("UPLOAD_ROOT", BASE_DIR / "data" / "uploads"))
 
+# 配置目录和 Chroma 数据目录都允许外部覆盖，方便复试现场快速切换。
 SCENARIO_CONFIG_DIR = Path(os.environ.get("SCENARIO_CONFIG_DIR", BASE_DIR / "configs"))
 CHROMA_PATH = Path(os.environ.get("CHROMA_PATH", BASE_DIR / "data" / "chroma"))
 
+# LLM 与 Embedding 默认遵循“尽量少配置也能跑”的策略：
+# Embedding 未单独配置时自动复用 LLM 的 Key 和 Base URL。
 LLM_API_KEY = os.environ.get("LLM_API_KEY", "")
 LLM_BASE_URL = os.environ.get("LLM_BASE_URL", "https://api.openai.com/v1")
 LLM_MODEL = os.environ.get("LLM_MODEL", "gpt-4.1-mini")

config/urls.py

@@ -4,6 +4,7 @@ from django.contrib import admin
 from django.urls import include, path
 
 
+# 总路由只承担模块装配职责，不在这里写业务逻辑。
 urlpatterns = [
     path("admin/", admin.site.urls),
     path("", include("apps.scenarios.urls")),
@@ -13,4 +14,5 @@ urlpatterns = [
 ]
 
 if settings.DEBUG:
+    # 开发环境下直接通过 Django 提供上传文件访问能力，便于本地演示。
     urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)