docs(design): 补全中文设计文档体系
This commit is contained in:
144
docs/设计文档/3.数据库设计.md
Normal file
144
docs/设计文档/3.数据库设计.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 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 元数据表，便于从数据库追踪向量库内容。
|
||||
Reference in New Issue
Block a user