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

apps/audit/admin.py

@@ -5,6 +5,7 @@ from .models import AgentAuditLog, DemoBusinessRecord
 
 @admin.register(AgentAuditLog)
 class AgentAuditLogAdmin(admin.ModelAdmin):
+    """便于在 Django Admin 中快速查看一次 Agent 执行的关键信息。"""
     list_display = ("id", "scenario_name", "status", "model_name", "latency_ms", "created_at")
     list_filter = ("status", "scenario_id")
     search_fields = ("scenario_id", "scenario_name", "user_input", "final_answer")
@@ -12,6 +13,7 @@ class AgentAuditLogAdmin(admin.ModelAdmin):
 
 @admin.register(DemoBusinessRecord)
 class DemoBusinessRecordAdmin(admin.ModelAdmin):
+    """管理工具查询依赖的示例业务记录。"""
     list_display = ("id", "title", "scenario_id", "record_type", "created_at")
     list_filter = ("scenario_id", "record_type")
     search_fields = ("title", "scenario_id", "record_type")

apps/audit/apps.py

@@ -2,5 +2,6 @@ from django.apps import AppConfig
 
 
 class AuditConfig(AppConfig):
+    """Audit 模块应用配置。"""
     default_auto_field = "django.db.models.BigAutoField"
     name = "apps.audit"

apps/audit/urls.py

@@ -5,6 +5,7 @@ from . import views
 
 app_name = "audit"
 
+# V1 的审计功能由列表页和详情页组成，暂不拆分页或复杂筛选接口。
 urlpatterns = [
     path("", views.log_list, name="list"),
     path("<int:log_id>/", views.log_detail, name="detail"),

apps/chat/apps.py

@@ -2,5 +2,6 @@ from django.apps import AppConfig
 
 
 class ChatConfig(AppConfig):
+    """Chat 模块应用配置。"""
     default_auto_field = "django.db.models.BigAutoField"
     name = "apps.chat"

apps/chat/urls.py

@@ -5,6 +5,7 @@ from . import views
 
 app_name = "chat"
 
+# 当前 V1 仅保留一个场景对话入口，场景详情合并在对话页中展示。
 urlpatterns = [
     path("<str:scenario_id>/", views.index, name="index"),
 ]

apps/documents/admin.py

@@ -5,6 +5,7 @@ from .models import UploadedDocument
 
 @admin.register(UploadedDocument)
 class UploadedDocumentAdmin(admin.ModelAdmin):
+    """管理上传文档及其入库状态，便于后台排查问题。"""
     list_display = ("id", "original_name", "scenario_id", "file_type", "status", "created_at")
     list_filter = ("status", "scenario_id", "file_type")
     search_fields = ("original_name", "scenario_id")

apps/documents/apps.py

@@ -2,5 +2,6 @@ from django.apps import AppConfig
 
 
 class DocumentsConfig(AppConfig):
+    """Documents 模块应用配置。"""
     default_auto_field = "django.db.models.BigAutoField"
     name = "apps.documents"

apps/documents/urls.py

@@ -5,6 +5,7 @@ from . import views
 
 app_name = "documents"
 
+# 文档模块对外暴露三个基础动作：列表、上传、手动入库。
 urlpatterns = [
     path("", views.document_list, name="list"),
     path("upload/", views.upload, name="upload"),

apps/scenarios/apps.py

@@ -2,5 +2,6 @@ from django.apps import AppConfig
 
 
 class ScenariosConfig(AppConfig):
+    """Scenarios 模块应用配置。"""
     default_auto_field = "django.db.models.BigAutoField"
     name = "apps.scenarios"

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)