# 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 | 更新时间 |

状态流转：

```text
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. 表关系设计

```text
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 元数据表，便于从数据库追踪向量库内容。