DEMO-AGENT/docs/设计文档/3.数据库设计.md

V1 数据库设计文档

1. 数据库设计目标

V1 数据库设计优先服务本地演示、讲解清晰和快速改题。数据模型只覆盖文件、对话、审计和简单示例业务数据，不引入复杂权限、多租户或工作流状态机。

2. 数据库选型

默认使用 SQLite，数据库文件位于 data/db.sqlite3。SQLite 适合复试现场单机运行，便于 Docker 挂载和备份。

后续如需多人协作或更正式部署，可通过 Django settings 切换到 PostgreSQL，但 V1 不强制实现。

3. 表结构总览

表	Django Model	模块	说明
uploaded_document	UploadedDocument	Documents	上传文件元数据和入库状态
agent_audit_log	AgentAuditLog	Audit	Agent 执行审计快照
demo_business_record	DemoBusinessRecord	Agent Core / Tools	内置工具可查询的模拟业务数据
chat_session	ChatSession	Chat	可选，对话会话
chat_message	ChatMessage	Chat	可选，对话消息

4. UploadedDocument 表设计

字段	类型	约束	说明
id	BigAutoField	PK	主键
scenario_id	CharField(100)	indexed	关联场景 ID
original_name	CharField(255)	required	原始文件名
file	FileField	required	文件相对路径
file_type	CharField(20)	required	txt、md、pdf、docx 等
size	PositiveIntegerField	default 0	字节数
status	CharField(20)	indexed	uploaded、indexed、failed
error_message	TextField	blank	入库失败原因
created_at	DateTimeField	auto_now_add	上传时间
updated_at	DateTimeField	auto_now	更新时间

状态流转：

uploaded -> indexed
uploaded -> failed
failed -> indexed
failed -> failed

重新入库时应按文档维度覆盖或清理旧 chunk，避免同一文件重复出现在向量检索结果中。文档选择范围由 Chat 表单本次提交的 document_ids 传入 Agent Core，V1 不需要为该选择单独建表。

5. AgentAuditLog 表设计

字段	类型	约束	说明
id	BigAutoField	PK	主键
scenario_id	CharField(100)	indexed	场景 ID
scenario_name	CharField(200)	blank	场景名称快照
user_input	TextField	required	用户输入
retrieved_chunks	JSONField	default list	RAG 引用片段
tool_calls	JSONField	default list	工具调用记录
structured_output	JSONField	default dict	结构化输出
final_answer	TextField	blank	最终回答
raw_output	TextField	blank	模型原始输出
model_name	CharField(100)	blank	模型名称
latency_ms	PositiveIntegerField	default 0	执行耗时
status	CharField(20)	indexed	success、failed
error_message	TextField	blank	错误信息
created_at	DateTimeField	auto_now_add, indexed	创建时间

审计日志保存的是执行快照，不依赖场景配置后续是否被修改。

6. DemoBusinessRecord 表设计

字段	类型	约束	说明
id	BigAutoField	PK	主键
scenario_id	CharField(100)	indexed	适用场景
record_type	CharField(100)	indexed	记录类型，如 defect、ticket、invoice
title	CharField(255)	required	标题
payload	JSONField	default dict	模拟业务数据
created_at	DateTimeField	auto_now_add	创建时间

该表为 V1 必需表，用于 query_demo_records 工具，避免工具只能返回硬编码数据。Django Admin 可以管理该表的数据，场景 YAML 仍不在 Admin 中编辑。

7. ChatSession 表设计

V1 可先不实现会话持久化。如果实现，字段建议如下：

字段	类型	说明
id	BigAutoField	主键
scenario_id	CharField(100)	场景 ID
title	CharField(255)	会话标题
created_at	DateTimeField	创建时间
updated_at	DateTimeField	更新时间

8. ChatMessage 表设计

V1 可通过审计日志满足演示追踪，不强制实现消息表。如果实现，字段建议如下：

字段	类型	说明
id	BigAutoField	主键
session	ForeignKey(ChatSession)	所属会话
role	CharField(20)	user、assistant、system
content	TextField	消息内容
audit_log	ForeignKey(AgentAuditLog, null=True)	关联审计
created_at	DateTimeField	创建时间

9. 表关系设计

Scenario YAML
  |-- scenario_id
      |-- UploadedDocument.scenario_id
      |-- AgentAuditLog.scenario_id
      |-- DemoBusinessRecord.scenario_id
      |-- ChatSession.scenario_id

ChatSession 1 -- N ChatMessage
ChatMessage 0/1 -- 1 AgentAuditLog

场景配置 V1 存在 YAML 中，不建 Scenario 数据表。这样更方便复试现场复制和修改配置文件。

10. 索引设计

• UploadedDocument(scenario_id, status)：用于按场景查看文件和入库状态。
• AgentAuditLog(scenario_id, created_at)：用于按场景查看最近日志。
• AgentAuditLog(status, created_at)：用于排查失败日志。
• DemoBusinessRecord(scenario_id, record_type)：用于工具查询模拟数据。

11. 数据初始化策略

• 场景初始化：读取 configs/*.yaml，不写数据库。
• 示例业务数据：可提供 Django management command 初始化 DemoBusinessRecord。
• 超级用户：本地演示可手动创建，Docker 可通过说明引导创建。
• 上传文件和 Chroma 数据：存放在 data/ 下，通过 Docker volume 持久化。

12. 后续扩展方向

• 增加 Scenario 表，实现后台编辑场景。
• 增加 ToolCallLog 独立表，用于复杂工具审计。
• 使用 PostgreSQL JSONB 优化 JSON 查询。
• 增加用户和权限模型。
• 增加文档 chunk 元数据表，便于从数据库追踪向量库内容。