rag/docs/数据库设计文档.md

数据库设计文档

本文档描述 RAG 知识库系统中所有数据库的结构和用途。

架构更新：v7.0 重构后，数据库按 prod/dev 环境分离为 4 个独立文件，通过 data/db.py 统一管理。生产模式数据库存放于 data/prod/，开发模式数据库存放于 data/dev/。

---

数据库架构概览

统一数据访问层

所有数据库通过 data/db.py 中的统一接口访问：

from data.db import get_connection, init_databases

# 初始化数据库（首次运行时调用）
init_databases()

# 使用连接（可选名称：feedback / knowledge / session / exam）
with get_connection("feedback") as conn:
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM feedbacks WHERE user_id = ?", (user_id,))
    rows = cursor.fetchall()

数据库文件列表

数据库	文件名	存储路径	主要功能	环境
feedback	feedback.db	data/prod/	用户反馈、FAQ、质量报告、FAQ 建议	生产 + 开发
knowledge	knowledge.db	data/prod/	知识库同步、文档哈希、纲要缓存、版本管理	生产 + 开发
session	session.db	data/dev/	会话管理、消息历史、审计日志	仅开发
exam	exam.db	data/dev/	题目存储、试卷管理、批阅记录、分析报告	仅开发

---

1. feedback.db - 反馈系统数据库

存储路径：data/prod/feedback.db 环境：生产 + 开发（始终启用） 所属模块：services/feedback.py

1.1 feedbacks 表 - 反馈表

字段	类型	说明
id	INTEGER	自增主键
session_id	TEXT	会话ID
query	TEXT	用户问题
answer	TEXT	系统回答
sources	TEXT	来源文档（JSON）
rating	INTEGER	评分：1=赞，-1=踩
reason	TEXT	点踩原因
user_id	TEXT	用户ID
created_at	TIMESTAMP	创建时间

索引：

• idx_feedback_session(session_id)
• idx_feedback_rating(rating)
• idx_feedback_created(created_at)

1.2 faqs 表 - FAQ表

字段	类型	说明
id	INTEGER	自增主键
question	TEXT	问题
answer	TEXT	答案
source_documents	TEXT	来源文档（JSON数组）
frequency	INTEGER	出现频次
avg_rating	REAL	平均评分
status	TEXT	状态：draft / approved / disabled
created_at	TIMESTAMP	创建时间
updated_at	TIMESTAMP	更新时间

索引：

• idx_faq_status(status)

1.3 faq_variants 表 - FAQ 问题变体表

字段	类型	说明
id	INTEGER	自增主键
faq_id	INTEGER	关联 FAQ ID
variant_question	TEXT	变体问题
created_at	TIMESTAMP	创建时间

索引：

• idx_faq_variant_faq(faq_id)

外键：

• faq_id → faqs(id) ON DELETE CASCADE

作用：Multi-Query Indexing，为同一 FAQ 存储多种问法变体，提升语义召回率。

1.4 quality_reports 表 - 质量报告表

字段	类型	说明
id	INTEGER	自增主键
report_type	TEXT	报告类型：weekly / monthly
start_date	DATE	统计开始日期
end_date	DATE	统计结束日期
total_queries	INTEGER	总查询数
total_feedback	INTEGER	总反馈数
positive_count	INTEGER	正面反馈数
negative_count	INTEGER	负面反馈数
avg_rating	REAL	平均评分
satisfaction_rate	REAL	满意度
high_freq_queries	TEXT	高频问题（JSON）
low_rating_queries	TEXT	低分问题（JSON）
improvement_suggestions	TEXT	改进建议（JSON）
created_at	TIMESTAMP	创建时间

1.5 faq_suggestions 表 - FAQ建议表

字段	类型	说明
id	INTEGER	自增主键
query	TEXT	用户问题
answer	TEXT	系统回答
frequency	INTEGER	出现频次
avg_rating	REAL	平均评分
status	TEXT	状态：pending / approved / rejected
created_at	TIMESTAMP	创建时间

作用：高频优质问题自动建议沉淀为FAQ，管理员审核后生效。

---

2. session.db - 会话管理数据库

存储路径：data/dev/session.db 环境：仅开发模式 所属模块：services/session.py

2.1 sessions 表 - 会话表

字段	类型	说明
session_id	TEXT	会话ID（UUID），主键
user_id	TEXT	所属用户ID
created_at	TIMESTAMP	创建时间
last_active	TIMESTAMP	最后活跃时间
metadata	TEXT	元数据（JSON格式）

索引：

• idx_sessions_user(user_id)

作用：实现多用户会话隔离，支持多轮对话记忆。

2.2 messages 表 - 消息历史表

字段	类型	说明
id	INTEGER	自增主键
session_id	TEXT	关联会话ID
role	TEXT	角色：user / assistant
content	TEXT	消息内容
metadata	TEXT	元数据（JSON格式）
created_at	TIMESTAMP	创建时间

索引：

• idx_messages_session(session_id, created_at)

外键：

• session_id → sessions(session_id) ON DELETE CASCADE

2.3 audit_logs 表 - 审计日志表

字段	类型	说明
id	INTEGER	自增主键
user_id	TEXT	用户ID
username	TEXT	用户名
action	TEXT	操作类型（chat/rag/search/upload_document等）
query	TEXT	用户查询内容
result_summary	TEXT	结果摘要
sources	TEXT	来源文档（JSON数组）
role	TEXT	用户角色
department	TEXT	用户部门
ip_address	TEXT	客户端IP
duration_ms	INTEGER	处理耗时（毫秒）
created_at	TIMESTAMP	创建时间

索引：

• idx_audit_user(user_id, created_at)
• idx_audit_action(action, created_at)
• idx_audit_created(created_at)

作用：记录所有用户操作，用于安全审计和行为分析。

---

3. knowledge.db - 知识管理数据库

存储路径：data/prod/knowledge.db 环境：生产 + 开发（始终启用） 所属模块：knowledge/sync.py、services/outline.py

3.1 document_hashes 表 - 文档哈希表

字段	类型	说明
document_id	TEXT	文档ID（相对路径），主键
document_name	TEXT	文件名
content_hash	TEXT	文档内容MD5哈希
file_size	INTEGER	文件大小（字节）
last_modified	TIMESTAMP	最后修改时间
created_at	TIMESTAMP	创建时间
updated_at	TIMESTAMP	更新时间

作用：记录每个文档的当前状态，用于检测变更。

3.2 change_logs 表 - 变更日志表

字段	类型	说明
id	INTEGER	自增主键
document_id	TEXT	文档ID
document_name	TEXT	文件名
change_type	TEXT	变更类型：added / modified / deleted
old_hash	TEXT	变更前哈希
new_hash	TEXT	变更后哈希
change_time	TIMESTAMP	变更时间
processed	INTEGER	是否已处理（0/1）
error_message	TEXT	错误信息
created_at	TIMESTAMP	创建时间

索引：

• idx_change_logs_time(change_time)
• idx_change_logs_processed(processed)

3.3 sync_status 表 - 同步状态表

字段	类型	说明
id	INTEGER	自增主键
sync_type	TEXT	同步类型（incremental/full）
status	TEXT	状态：idle / running / completed / failed
start_time	TIMESTAMP	开始时间
end_time	TIMESTAMP	结束时间
documents_processed	INTEGER	处理文档数
documents_added	INTEGER	新增文档数
documents_modified	INTEGER	修改文档数
documents_deleted	INTEGER	删除文档数
error_message	TEXT	错误信息
created_at	TIMESTAMP	创建时间

3.4 outline_cache 表 - 纲要缓存表

字段	类型	说明
id	INTEGER	自增主键
document_id	TEXT	文档ID，唯一
document_name	TEXT	文档名称
total_pages	INTEGER	总页数
content_hash	TEXT	文档内容哈希
outline_json	TEXT	纲要结构（JSON）
generated_at	TIMESTAMP	生成时间

索引：

• idx_outline_doc(document_id)

3.5 document_vectors 表 - 文档向量缓存表

字段	类型	说明
id	INTEGER	自增主键
document_id	TEXT	文档ID，唯一
document_name	TEXT	文档名称
vector_hash	TEXT	向量哈希
vector_json	TEXT	向量数据（JSON）
tags_json	TEXT	标签（JSON）
updated_at	TIMESTAMP	更新时间

索引：

• idx_vector_doc(document_id)

3.6 recommendation_cache 表 - 推荐缓存表

字段	类型	说明
id	INTEGER	自增主键
document_id	TEXT	文档ID
recommendations_json	TEXT	推荐结果（JSON）
generated_at	TIMESTAMP	生成时间

3.7 document_versions 表 - 文档版本表

字段	类型	说明
id	INTEGER	自增主键
document_id	TEXT	文档ID
collection	TEXT	所属向量库
version	TEXT	版本号，默认 'v1'
content_hash	TEXT	内容哈希
status	TEXT	状态：active / deprecated
effective_date	DATE	生效日期
expiry_date	DATE	失效日期
deprecated_date	DATETIME	废止日期
deprecated_reason	TEXT	废止原因
deprecated_by	TEXT	废止操作人
change_summary	TEXT	变更摘要
changed_sections	TEXT	变更章节（JSON）
supersedes	TEXT	取代的版本
chunk_count	INTEGER	片段数量
created_at	TIMESTAMP	创建时间
created_by	TEXT	创建人

唯一约束：(document_id, collection, version)

3.8 version_change_logs 表 - 版本变更日志表

字段	类型	说明
id	INTEGER	自增主键
document_id	TEXT	文档ID
collection	TEXT	所属向量库
old_version	TEXT	旧版本
new_version	TEXT	新版本
old_status	TEXT	旧状态
new_status	TEXT	新状态
change_type	TEXT	变更类型
reason	TEXT	原因
changed_by	TEXT	操作人
created_at	TIMESTAMP	创建时间

---

4. exam.db - 出题系统数据库

存储路径：data/dev/exam.db 环境：仅开发模式 所属模块：exam_pkg/manager.py、exam_pkg/local_db.py、exam_pkg/analysis.py

4.1 questions 表 - 题目表

字段	类型	说明
id	TEXT	题目ID（UUID），主键
question_type	TEXT	题型：choice / blank / short_answer
content	TEXT	题干内容
options	TEXT	选择题选项（JSON数组）
correct_answer	TEXT	正确答案
analysis	TEXT	解析
knowledge_points	TEXT	知识点（JSON数组）
difficulty	INTEGER	难度(1-5)
score	INTEGER	分值
source_file	TEXT	来源文件路径
source_collection	TEXT	来源向量库
source_snippet	TEXT	来源知识片段
source_hash	TEXT	文件哈希
status	TEXT	状态：approved
created_at	TIMESTAMP	创建时间
created_by	TEXT	创建人
updated_at	TIMESTAMP	更新时间

索引：

• idx_questions_source(source_file)

4.2 exams 表 - 试卷表

字段	类型	说明
id	TEXT	试卷ID，主键
name	TEXT	试卷名称
description	TEXT	描述
total_score	INTEGER	总分
total_count	INTEGER	题目总数
duration	INTEGER	考试时长（分钟）
status	TEXT	状态：published
created_at	TIMESTAMP	创建时间
created_by	TEXT	创建人

4.3 exam_questions 表 - 试卷题目关联表

字段	类型	说明
exam_id	TEXT	试卷ID
question_id	TEXT	题目ID
question_order	INTEGER	题目顺序

主键：(exam_id, question_id)

外键：

• exam_id → exams(id) ON DELETE CASCADE
• question_id → questions(id) ON DELETE CASCADE

4.4 student_answers 表 - 学生答卷表

字段	类型	说明
id	TEXT	主键
exam_id	TEXT	试卷ID
student_id	TEXT	学生ID
question_id	TEXT	题目ID
question_type	TEXT	题型
student_answer	TEXT	学生答案
score	REAL	得分
max_score	INTEGER	满分
feedback	TEXT	反馈
score_details	TEXT	评分详情（JSON）
submitted_at	TIMESTAMP	提交时间
graded_at	TIMESTAMP	批阅时间

索引：

• idx_student_answers_exam(exam_id, student_id)

4.5 grade_reports 表 - 批阅报告表

字段	类型	说明
id	TEXT	主键
exam_id	TEXT	试卷ID
student_id	TEXT	学生ID
total_score	REAL	总得分
max_score	REAL	满分
score_rate	REAL	得分率
analysis	TEXT	分析（JSON）
graded_at	TIMESTAMP	批阅时间

4.6 question_document_links 表 - 题目-制度关联表

字段	类型	说明
id	INTEGER	自增主键
question_id	TEXT	题目ID
question_type	TEXT	题型
exam_id	TEXT	试卷ID
document_id	TEXT	制度文档ID
document_name	TEXT	制度文档名称
chapter	TEXT	章节
key_points	TEXT	关键知识点（JSON）
relevance_score	REAL	相关度分数
created_at	TIMESTAMP	创建时间

索引：

• idx_qdl_question(question_id)
• idx_qdl_document(document_id)

4.7 knowledge_points 表 - 知识点表

字段	类型	说明
id	INTEGER	自增主键
name	TEXT	知识点名称，唯一
category	TEXT	分类
description	TEXT	描述
parent_id	INTEGER	父知识点ID
created_at	TIMESTAMP	创建时间

外键：

• parent_id → knowledge_points(id)

4.8 question_knowledge_links 表 - 题目-知识点关联表

字段	类型	说明
id	INTEGER	自增主键
question_id	TEXT	题目ID
question_type	TEXT	题型
exam_id	TEXT	试卷ID
knowledge_point_id	INTEGER	知识点ID
knowledge_point_name	TEXT	知识点名称
weight	REAL	权重
created_at	TIMESTAMP	创建时间

索引：

• idx_qkl_question(question_id)
• idx_qkl_knowledge(knowledge_point_id)

4.9 question_status 表 - 题目状态表

字段	类型	说明
id	INTEGER	自增主键
question_id	TEXT	题目ID，唯一
question_type	TEXT	题型
exam_id	TEXT	试卷ID
status	TEXT	状态
affected_by	TEXT	影响来源
affect_reason	TEXT	影响原因
updated_at	TIMESTAMP	更新时间

索引：

• idx_qs_status(status)

4.10 exam_analysis_reports 表 - 整卷分析报告表

字段	类型	说明
id	INTEGER	自增主键
report_id	TEXT	报告ID，唯一
exam_id	TEXT	试卷ID
exam_name	TEXT	试卷名称
student_id	TEXT	学生ID
total_score	REAL	总得分
max_score	REAL	满分
score_rate	REAL	得分率
type_scores	TEXT	各题型得分（JSON）
knowledge_analysis	TEXT	知识点分析（JSON）
weak_points	TEXT	薄弱知识点（JSON）
strong_points	TEXT	优势知识点（JSON）
ai_comment	TEXT	AI评语
study_suggestions	TEXT	学习建议（JSON）
created_at	TIMESTAMP	创建时间

4.11 question_suggestions 表 - 新题建议表

字段	类型	说明
id	INTEGER	自增主键
document_id	TEXT	文档ID
suggestion	TEXT	建议内容
status	TEXT	状态：pending
created_at	TIMESTAMP	创建时间

---

5. ChromaDB 向量数据库

所属模块：knowledge/manager.py

5.1 向量库结构

knowledge/vector_store/chroma/
├── chroma.sqlite3          # ChromaDB 主数据库
├── kb_metadata.json        # 向量库元数据
├── public_kb/              # 公开知识库
├── dept_finance/           # 财务部知识库
├── dept_hr/                # 人事部知识库
├── dept_tech/              # 技术部知识库
└── ...                     # 其他部门向量库

5.2 权限矩阵

角色	可访问向量库	可上传	可删除	可同步
admin	全部	全部	全部	全部
manager	public_kb + 本部门	本部门	本部门	本部门
user	public_kb + 本部门	-	-	-

5.3 文档元数据结构

每个文档 chunk 的元数据：

字段	类型	说明
source	TEXT	文档来源文件名
page	INTEGER	PDF 页码（可选）
sheet	TEXT	Excel 工作表（可选）
row	INTEGER	Excel 行号（可选）
section	TEXT	章节（可选）
is_table	BOOLEAN	是否为表格
is_excel	BOOLEAN	是否为 Excel 数据
security_level	TEXT	安全级别
collection	TEXT	所属向量库名称

---

数据库关系图

┌─────────────────────────────────────────────────────────────────┐
│                        多向量库架构                               │
├─────────────────────────────────────────────────────────────────┤
│   knowledge/vector_store/chroma/                                │
│   ├── public_kb/                                                │
│   ├── dept_finance/                                             │
│   ├── dept_hr/                                                  │
│   └── ...                                                       │
│                                                                 │
│   knowledge/manager.py ─────────────────────────────────────┐   │
│   knowledge/router.py                                       │   │
└─────────────────────────────────────────────────────────────┼───┘
                                                              │
                              user_id / document_id 关联      │
                                                              ▼
┌──────────────────┐   ┌──────────────────┐
│  data/prod/      │   │  data/prod/      │
│  feedback.db     │   │  knowledge.db    │
│  (生产+开发)     │   │  (生产+开发)     │
│                  │   │                  │
│  • feedbacks     │   │  • document_     │
│  • faqs          │   │    hashes        │
│  • faq_variants  │   │  • change_logs   │
│  • quality_      │   │  • sync_status   │
│    reports       │   │  • outline_cache │
│  • faq_          │   │  • document_     │
│    suggestions   │   │    versions      │
└──────────────────┘   └──────────────────┘

┌──────────────────┐   ┌──────────────────┐
│  data/dev/       │   │  data/dev/       │
│  session.db      │   │  exam.db         │
│  (仅开发)        │   │  (仅开发)        │
│                  │   │                  │
│  • sessions      │   │  • questions     │
│  • messages      │   │  • exams         │
│  • audit_logs    │   │  • student_      │
│                  │   │    answers       │
│                  │   │  • grade_reports  │
│                  │   │  • knowledge_    │
│                  │   │    points        │
└──────────────────┘   └──────────────────┘

---

数据库维护

数据清理

# 清理过期会话（24小时未活跃）- 仅开发环境
sqlite3 data/dev/session.db "DELETE FROM sessions WHERE last_active < datetime('now', '-24 hours');"
sqlite3 data/dev/session.db "DELETE FROM messages WHERE session_id NOT IN (SELECT session_id FROM sessions);"

# 清理旧审计日志（保留30天）- 仅开发环境
sqlite3 data/dev/session.db "DELETE FROM audit_logs WHERE created_at < datetime('now', '-30 days');"

数据备份

# 备份所有 SQLite 数据库
cp data/prod/*.db backup/
cp data/dev/*.db backup/

# 使用 SQLite 在线备份
sqlite3 data/prod/feedback.db ".backup backup/feedback_backup.db"
sqlite3 data/prod/knowledge.db ".backup backup/knowledge_backup.db"

重置数据库

删除对应的文件，服务启动时会自动重建表结构：

# 重置反馈数据（会丢失反馈和 FAQ）
rm data/prod/feedback.db

# 重置知识管理数据（会丢失文档追踪和版本）
rm data/prod/knowledge.db

# 重置会话数据（会丢失会话和对话历史）- 仅开发环境
rm data/dev/session.db

# 重置出题系统数据（会丢失题目和试卷）- 仅开发环境
rm data/dev/exam.db

---

更新日志

日期	版本	更新内容
2026-06-04	4.0	修正为 4 库分离架构：rag_core.db 拆分为 feedback.db + session.db，按 prod/dev 子目录分离；新增 faq_variants 表；移除已废弃的 subscriptions/notifications 表
2026-04-13	3.0	数据库架构重构：6 个独立数据库合并为 3 个
2026-04-09	2.0	新增多向量库架构文档
2026-04-07	1.0	初始版本