refactor(models): 补充模型与视图层中文说明

agent_core/results.py

@@ -3,6 +3,14 @@ from dataclasses import dataclass, field
 
 @dataclass
 class AgentResult:
+    """
+    Agent Core 对 Django 层暴露的统一结果对象。
+
+    任何底层编排实现都必须返回这一结构，确保：
+    - Chat 页面有稳定字段可展示
+    - Audit 模块有稳定字段可落库
+    - 未来替换编排引擎时不影响 Django 业务层
+    """
     answer: str = ""
     structured_output: dict = field(default_factory=dict)
     references: list = field(default_factory=list)

apps/audit/models.py

@@ -2,6 +2,14 @@ from django.db import models
 
 
 class AgentAuditLog(models.Model):
+    """
+    保存一次 Agent 执行的完整审计快照。
+
+    该模型是“系统可解释性”的核心：
+    - 对话页负责触发执行
+    - Agent Core 负责生成结果
+    - Audit 模型负责长期保存输入、引用、工具调用和模型输出
+    """
     # 审计状态需要同时服务数据库检索和前端展示。
     STATUS_SUCCESS = "success"
     STATUS_FAILED = "failed"
@@ -41,6 +49,12 @@ class AgentAuditLog(models.Model):
 
 
 class DemoBusinessRecord(models.Model):
+    """
+    演示用业务记录表。
+
+    该表不直接参与页面主流程，而是供内置工具 `query_demo_records`
+    查询，证明 Agent 除知识库外也可以结合结构化业务数据。
+    """
     scenario_id = models.CharField(max_length=100, db_index=True)
     record_type = models.CharField(max_length=100, db_index=True)
     title = models.CharField(max_length=255)

apps/audit/views.py

@@ -20,5 +20,7 @@ def log_list(request):
 
 
 def log_detail(request, log_id: int):
+    # 详情页只负责按主键加载审计快照并渲染；
+    # 所有脱敏和字段映射都应在服务层完成。
     audit_log = get_object_or_404(AgentAuditLog, pk=log_id)
     return render(request, "audit/log_detail.html", {"log": audit_log})

apps/documents/models.py

@@ -2,6 +2,12 @@ from django.db import models
 
 
 class UploadedDocument(models.Model):
+    """
+    保存用户上传文档的元数据和入库状态。
+
+    设计上只记录“文件属于哪个场景、当前是否已入库、失败原因是什么”，
+    不把 RAG 细节耦合进模型层。
+    """
     # 文档状态用于驱动前端提示和后续可操作项。
     STATUS_UPLOADED = "uploaded"
     STATUS_INDEXED = "indexed"

apps/scenarios/views.py

@@ -4,7 +4,8 @@ from .services import list_scenario_issues, list_scenarios
 
 
 def index(request):
-    # 首页只消费服务层给出的场景摘要，不自行拼装配置字段。
+    # 首页只消费服务层给出的场景摘要和错误摘要，
+    # 不自行读取 YAML，更不在 View 里做字段拼装。
     return render(
         request,
         "scenarios/index.html",