英语学习平台：数据库表关系与字段说明#

数据库：PostgreSQL
ORM：Prisma
模型来源：server/prisma/schema.prisma
行号基准：Git 提交 82883ee1097876d3159ffb5b50fae0ecd93542ec
生成日期：2026-10-03

1. 先理解四类存储#

本项目不只有 PostgreSQL。面试时要先把四类存储的职责分清：

本文以 PostgreSQL 为主，并在 8.2 节单独列出 Chroma 向量库的 Collection、记录字段、metadata 字段以及它们和 PostgreSQL 的逻辑关系。知识库正文和向量不在 KnowledgeDocument 表中；原文在 MinIO，分片与向量在 Chroma。

2. Prisma 类型速查#

Prisma 模型中的 xxx[] 和关系对象字段只是 ORM 关系导航字段，不会额外生成数据库列。真正落库的是 userId、conversationId 等外键字段。

3. 全局关系概览#

系统共 18 个 Prisma 业务模型，可以分为五组：

3.1 用户、词汇、课程关系#

erDiagram
    User ||--o{ WordBookRecord : learns
    WordBook ||--o{ WordBookRecord : recorded_by
    User ||--o{ PaymentRecord : pays
    User ||--o{ CourseRecord : owns
    Course ||--o{ CourseRecord : purchased_as
    PaymentRecord ||--o{ CourseRecord : grants

• User 与 WordBook 是多对多，通过 WordBookRecord 保存用户对每个单词的掌握状态。
• User 与 Course 是多对多，通过 CourseRecord 保存购买关系。
• 一笔 PaymentRecord 可以关联一个或多个 CourseRecord；CourseRecord.paymentRecordId 允许为空，便于先创建关系或兼容非支付来源。

3.2 埋点关系#

erDiagram
    User o|--o{ Visitor : may_bind
    Visitor ||--o{ PageView : has
    Visitor ||--o{ TrackEvent : has
    Visitor ||--o{ PerformanceEntry : has
    Visitor ||--o{ ErrorEntry : has

• Visitor 用 anonymousId 标识浏览器访客，登录后可选地绑定 User。
• PV、行为、性能、错误都挂在 Visitor 下，因此未登录访问也能统计。

3.3 Agent、知识库和学习关系#

erDiagram
    User ||--o{ KnowledgeDocument : uploads
    User ||--o{ AiConversation : owns
    User ||--o{ AiRun : starts
    User ||--o{ AgentAction : confirms
    User ||--o{ StudyPlan : has
    User ||--o{ StudyTask : has
    User ||--o{ QuizSession : takes
    User ||--o{ QuizAttempt : submits

    AiConversation ||--o{ AiMessage : contains
    AiConversation ||--o{ AiRun : executes
    AiConversation ||--o{ AgentAction : requests
    AiConversation o|--o{ QuizSession : generates
    AiConversation o|--o{ QuizAttempt : records

    AiRun o|--o{ AiMessage : produces
    AiRun o|--o{ AgentAction : creates

    StudyPlan ||--o{ StudyTask : contains
    QuizSession ||--o| QuizAttempt : submitted_as

关键设计：

• AiConversation 是长期会话；AiRun 是一次用户消息触发的一次执行。
• AiMessage 属于会话，也可以属于某次 Run；Action 回执等消息可能不绑定原 Run。
• AgentAction 把“模型建议执行”与“真实业务写入”隔开。
• StudyPlan 是计划头，StudyTask 是按日期展开的具体任务。
• QuizSession 保存尚未提交的服务端题目快照；QuizAttempt 保存最终答案与评分，两者是一对零或一。
• KnowledgeDocument 与 Chroma 没有数据库外键，但通过 KnowledgeDocument.id = metadata.document_id、User.id = metadata.owner_user_id 形成跨存储的一对多逻辑关系。

4. 状态枚举#

枚举定义位于 server/prisma/schema.prisma:17-98。

4.1 TradeStatus#

4.2 KnowledgeDocumentStatus#

UPLOADED → QUEUED → PROCESSING → READY
                         └──────→ FAILED
READY / FAILED / 其他状态 → DELETING → 软删除

4.3 Agent 相关枚举#

典型 Action 状态流：

PENDING → CONFIRMED → EXECUTED
   ├────→ REJECTED
   └────→ EXPIRED
CONFIRMED → FAILED（达到重试上限或永久失败）

4.4 学习相关枚举#

5. 用户与词汇表#

5.1 User - 用户主表#

源码：server/prisma/schema.prisma:100。

关系数组 wordBookRecords、paymentRecords、courseRecords、visitors、knowledgeDocuments、aiConversations、aiRuns、agentActions、studyPlans、studyTasks、quizAttempts、quizSessions 都是 Prisma 导航字段，不是物理列。

关联表#

User 还会通过 WordBookRecord 间接关联 WordBook，通过 CourseRecord 间接关联 Course 和 PaymentRecord。这些属于中间表关系，不是 User 表上的直接外键。

5.2 WordBook - 单词主数据表#

源码：server/prisma/schema.prisma:156。

索引：word、tag、word + tag。这些索引服务单词搜索与标签筛选。考试标签使用多个布尔列，适合固定标签集；若标签不断增长，可改为标签表和多对多关系。

关联表#

WordBook 通过 WordBookRecord 与 User 构成多对多关系。QuizAttempt.wordIds 也会保存单词 ID 数组用于测验统计，但它不是数据库外键，只是逻辑关联。

5.3 WordBookRecord - 用户单词掌握关系表#

源码：server/prisma/schema.prisma:131。

这是 User 与 WordBook 的多对多中间表，但不仅保存关系，还保存间隔复习状态。

约束与索引：

• unique(userId, wordId)：一个用户对一个单词最多一条记录。
• index(userId, nextReviewAt)：查询“当前用户到期复习词”。
• index(userId, masteryScore)：查询“当前用户薄弱词”。
• 删除用户或单词时，该关系记录级联删除。

关联表#

QuizAttempt 提交后会按 wordIds 更新这张表，但二者没有外键；这是业务流程关联，不是数据库结构关联。

6. 课程与支付表#

6.1 Course - 课程主表#

源码：server/prisma/schema.prisma:219。

关联表#

Course 通过 CourseRecord 间接关联 User 和 PaymentRecord，自身没有直接指向用户或订单的外键。

6.2 PaymentRecord - 支付订单表#

源码：server/prisma/schema.prisma:187。

关联表#

支付订单与 Course 没有直接外键，而是通过 CourseRecord 关联，因此一笔订单对应哪些课程要查询购买关系表。

6.3 CourseRecord - 用户课程购买关系表#

源码：server/prisma/schema.prisma:204。

约束：unique(userId, courseId) 防止同一用户重复生成同一课程关系。删除用户、课程或关联支付记录时会级联删除购买关系。

关联表#

7. 前端监控与埋点表#

7.1 Visitor - 访客表#

源码：server/prisma/schema.prisma:233。

索引：userId 和 anonymousId。anonymousId 已是 unique，额外普通索引通常是冗余的，可在优化时评估删除。

关联表#

7.2 PageView - 页面访问表#

源码：server/prisma/schema.prisma:253。

索引：visitorId + createdAt 查某访客访问轨迹；path + createdAt 查某页面时序流量。

关联表#

通过 Visitor.userId 可间接关联 User；PageView 自身没有 userId 外键，因此匿名访问也能保存。

7.3 TrackEvent - 自定义行为事件表#

源码：server/prisma/schema.prisma:268。

索引：visitorId + createdAt、event + createdAt。

关联表#

通过 Visitor 可间接找到 User，但 payload 中即使包含业务 ID 也只是事件数据，不受数据库外键约束。

7.4 PerformanceEntry - Web 性能表#

源码：server/prisma/schema.prisma:283。

当前为每个指标分别建索引，并额外建五指标加时间的组合索引。组合索引列很多，实际是否命中要根据查询和 EXPLAIN ANALYZE 验证。

关联表#

通过 Visitor.userId 可间接关联登录用户；未登录访客仍可产生性能记录。

7.5 ErrorEntry - 前端错误表#

源码：server/prisma/schema.prisma:303。

删除 Visitor 会级联删除四类埋点子表；删除绑定用户也会级联删除该用户关联的 Visitor 及其明细。

关联表#

通过 Visitor 可间接关联 User。url、message 和 stack 只是错误上下文字段，不会与其他业务表建立外键。

8. 知识库表#

8.1 KnowledgeDocument - 私人文档元数据表#

源码：server/prisma/schema.prisma:318。

这张表只保存“业务事实和索引状态”，不保存 PDF 文件本体，也不保存向量。

索引：

• userId + status + createdAt：用户文档列表和 READY 白名单。
• userId + contentHash：用户范围内容查重。
• status + updatedAt：恢复任务扫描卡住的 QUEUED/PROCESSING/DELETING。
• objectKey 唯一：防止两个业务记录指向同一 MinIO 对象。
• activeContentKey 唯一：数据库层防并发重复上传。

关联表与外部存储#

这张表与 AiConversation 没有直接外键。每次 Agent 请求携带并校验 documentIds，形成“会话本轮使用哪些文档”的临时业务关联。

8.2 Chroma 向量库：Collection、记录与全部字段#

源码位置：

• Collection 命名：server-py/app/config.py:233-250 的 Settings.chroma_collection_name。
• Collection 创建与元数据校验：server-py/app/vectorstore/chroma_store.py:58-108 的 validate_collection()、_collection()、_existing_collection()。
• 正式分片写入：server-py/app/vectorstore/chroma_store.py:169-233 的 ChromaStore.upsert_document()。
• 私有检索：server-py/app/vectorstore/chroma_store.py:432-508 的 ChromaStore.search_private()。

先回答“向量库有哪些表”#

Chroma 对业务代码暴露的概念是 Collection（集合），不是 PostgreSQL 那种由本项目定义的关系表。不要把 Chroma 自己底层的内部系统表当成本项目业务表；内部表结构由 Chroma 1.5.9 管理，升级版本可能改变，本项目也没有直接查询它们。

本项目可见的向量存储对象如下：

这里的 knowledge_chunk 和 stage1_probe 是同一个 Collection 中由 metadata.kind 区分的两种记录，不是两个物理表，也不是两个 Collection。

Collection 名称是怎么生成的#

命名公式：

{CHROMA_COLLECTION_PREFIX}_{embedding_provider}_{model_slug}_{model_sha256前12位}_{RAG_INDEX_VERSION}

例如开发环境默认配置大致生成：

english_knowledge_dev_ollama_mxbai_embed_large_latest_c55f6eb80700_v1

这套设计意味着：不是每个用户一个 Collection，也不是每个文档一个 Collection。当前模型和索引版本下，所有用户文档共用一个 Collection，租户隔离依赖每条记录的 metadata 和服务端白名单。

Collection 自身的 metadata 字段#

创建 Collection 时，ChromaStore._collection() 会写入并在每次使用时核对以下 metadata。只要实际值和当前配置不一致就直接报错，不会拿错误维度或错误模型继续检索。

每条 Chroma 记录的顶层字段#

Chroma 的每条记录不是一行 Prisma Model，而是由下面四组数据一起组成：

distance 不是持久化字段。它是 collection.query() 查询时由 Chroma 计算并返回的距离；项目把它换算为 score = 1 - distance，再应用最低分阈值。score 也不会写回向量库。

knowledge_chunk 正式分片的全部 metadata 字段#

注意：embedding_provider 和 embedding_dimension 保存在 Collection metadata，不在每条 knowledge_chunk metadata 中重复保存。

stage1_probe 健康探针记录字段#

ChromaStore.probe() 会临时写一条记录验证 Chroma 真的能写、能查、能删。它和正式分片共用顶层字段，但 metadata 只有三项：

探针完成 delete 后还会再次 get，确认 ID 已不存在。它不是用户文档，不关联 KnowledgeDocument。

与 PostgreSQL、用户和文件的逻辑关系#

私有检索实际使用哪些字段#

ChromaStore.search_private() 不会只按向量相似度裸搜，而是先使用以下 metadata 过滤：

kind = knowledge_chunk
AND owner_user_id = 当前登录用户
AND visibility = PRIVATE
AND document_id IN 服务端校验后的 READY 文档白名单

Chroma 返回后，代码还会逐条再次检查 owner_user_id、visibility、kind 和 document_id，然后按 content_hash 去重、按文本相似度去近重复、按 min_score 丢掉低分结果。这样即使向量库过滤出现异常，也不会直接把其他用户或未选择文档的内容交给模型。

写入、重建和删除时怎么保证一致性#

最重要的面试表述：PostgreSQL 的 KnowledgeDocument 是业务事实来源；Chroma 的向量、正文分片和 metadata 都是可根据 MinIO 原文件重新生成的派生数据，所以二者采用“逻辑关联 + 状态机 + 对账/恢复”，而不是跨数据库外键或分布式事务。

9. Agent 会话表#

9.1 AiConversation - Agent 会话表#

源码：server/prisma/schema.prisma:348。

索引：userId + status + lastMessageAt 用于用户会话列表；status + checkpointDeletedAt 用于扫描已归档但 checkpoint 未清理的会话。

关联表#

9.2 AiMessage - 会话消息表#

源码：server/prisma/schema.prisma:369。

关系策略：删会话时消息 Cascade；删 Run 时只把 runId SetNull，消息仍保留在会话历史中。

索引：conversationId + createdAt 用于按时间加载历史；runId 用于追踪一次执行产生的消息。

关联表#

9.3 AiRun - 单次 Agent 执行表#

源码：server/prisma/schema.prisma:385。

一条用户消息通常对应一个 AiRun。Conversation 是长期容器，Run 是一次执行审计记录。

索引：

• conversationId + createdAt：查看会话执行历史。
• userId + status + createdAt：限制用户并发 Run、查用户失败记录。
• status + startedAt：恢复长时间 RUNNING 的 stale Run。
• traceId：运维链路查询。

关联表#

traceId 还会逻辑关联 FastAPI、Celery 和回调日志，但它不是这些系统之间的数据库外键。

9.4 AgentAction - 高影响操作确认表#

源码：server/prisma/schema.prisma:416。

索引分别服务：用户待确认列表、会话 Action 历史、已确认但未执行恢复、终态 Action 补偿扫描。

关联表#

10. 学习计划与任务表#

10.1 StudyPlan - 学习计划表#

源码：server/prisma/schema.prisma:447。

普通索引 userId + status + createdAt 支持用户计划列表。Migration 还建立了部分唯一索引 StudyPlan_one_active_per_user_idx：只对 status = ACTIVE 生效，保证一个用户同时最多一个活动计划。这个部分索引无法完整表示在 Prisma Schema 中，因此看 Schema 时还必须看 Migration。

关联表#

10.2 StudyTask - 计划任务表#

源码：server/prisma/schema.prisma:465。

约束：unique(planId, scheduledFor, order) 防止同一计划同一天出现重复顺序；index(userId, status, scheduledFor) 支持查询某用户待办和到期任务。删除 Plan 会级联删除 Task。

关联表#

11. 测验表#

11.1 QuizSession - 未提交测验会话#

源码：server/prisma/schema.prisma:509。

索引：userId + expiresAt、userId + mode + expiresAt 查某模式未过期测验；conversationId 查 Agent 会话产生的测验。

关联表#

11.2 QuizAttempt - 已提交测验结果#

源码：server/prisma/schema.prisma:486。

删除策略：QuizAttempt.sessionId 对 Session 使用 Restrict，已有答题结果时不能删除原 Session；对 Conversation 使用 SetNull；对 User 使用 Cascade。

索引：userId + submittedAt、userId + mode + submittedAt 查近期测验；conversationId 查会话关联测验。

关联表#

12. 外键与删除策略汇总#

理解原则：

• 强归属数据随父记录删除，使用 Cascade。
• 有独立审计价值的数据在上游执行记录删除后仍保留，使用 SetNull。
• 已提交测验必须保留题目来源，Session → Attempt 使用 Restrict。
• Chroma metadata.document_id / owner_user_id 与 PostgreSQL 只是逻辑关联，没有外键和 Cascade；删除必须由应用显式清理，并由恢复任务核对。

13. 数据库级 CHECK 与特殊索引#

这些约束定义在 Migration，Prisma Schema 不能完整表达，面试时这是一个加分点。

来源：server/prisma/migrations/20260722190000_agent_rag_learning/migration.sql:192-248。

服务端校验改善用户体验，数据库约束负责最后一道一致性防线。二者应同时存在。

14. LangGraph 独立 Schema#

Prisma Migration server/prisma/migrations/20260722122000_add_langgraph_schema/migration.sql:1 只创建 langgraph schema。Agent 启动时，server/apps/ai/src/llm/llm.config.ts:31 的 createCheckpoint() 调用 PostgresSaver.setup() 自动创建以下表：

项目把 AiConversation.id 作为 LangGraph thread_id。业务会话归档后，CheckpointService.deleteThread() 删除对应 checkpoint、blob 和 pending writes；checkpointDeletedAt 用来记录是否清理成功。

这四张表由第三方库管理，不应加入 Prisma Model，也不应手工修改字段。

15. 三条核心数据流#

15.1 用户完成测验#

QuizSession（题目快照）
  → QuizAttempt（答案、分数、反馈，sessionId 唯一）
  → WordBookRecord（正误计数、掌握度、间隔、下次复习）
  → User.wordNumber（已掌握词冗余计数）

事务和 Advisory Lock 保证重复提交不会重复累计，入口在 study-domain.service.ts:292。

15.2 Agent 创建学习计划#

AiConversation
  → AiRun
  → StudyPlan(PENDING_CONFIRMATION) + StudyTask[]
  → AgentAction(PENDING，payload 内含 planId)
  → 用户确认
  → AgentAction(EXECUTED) + StudyPlan(ACTIVE)
  → AiMessage(Action 执行回执)

AgentAction.idempotencyKey、事务、Advisory Lock 和部分唯一索引共同防止计划重复激活。

15.3 文档上传并入库#

KnowledgeDocument(UPLOADED)
  → MinIO 原始对象
  → KnowledgeDocument(QUEUED, jobId, ingestionTraceId)
  → Worker PROCESSING 回调
  → Chroma 当前 Collection
      └─ ids + embeddings + documents + metadatas
         └─ kind/document_id/owner_user_id/visibility/page/hash/trace/version...
  → Worker READY 回调
  → KnowledgeDocument(READY, chunkCount, model, indexVersion)

PostgreSQL 决定文档归属和是否可检索；MinIO 与 Chroma 不通过数据库外键连接，而是共同使用 documentId/userId/contentHash 做跨存储关联。

16. 常用查询为什么能命中索引#

组合索引遵循左前缀原则。例如 (userId, status, createdAt) 可以高效支持 userId 或 userId + status 开头的条件，但通常不能单独高效支持只查 createdAt。

17. 面试时容易被追问的设计点#

1. 为什么 AiRun、AgentAction、StudyTask 都冗余保存 userId？答题重点：租户过滤、限额、恢复扫描和索引效率，同时必须用事务保证与父对象用户一致。
2. 为什么 StudyPlan.plan 已有 JSON，还需要 StudyTask 表？答题重点：JSON 是完整快照/展示结构，Task 是可查询、可更新、可约束的执行实体。
3. 为什么 QuizSession.questions 和 QuizAttempt.questions 都保存？答题重点：Session 用于服务端防篡改评分，Attempt 用于不可变历史审计。
4. 为什么 AiMessage.runId 与 AgentAction.runId 是可空并使用 SetNull？答题重点：会话历史和 Action 审计生命周期长于某个 Run。
5. 为什么不用 PostgreSQL 存向量？当前选择是 Chroma 职责隔离；但 pgvector 可以减少组件数，需要按规模、检索能力、运维成本权衡。
6. 为什么软删除 KnowledgeDocument？跨 PostgreSQL/MinIO/Chroma 删除无法用单库事务，需要 DELETING + deletedAt + 恢复任务 实现最终一致性。
7. 为什么不是“每个用户一个 Chroma Collection”？共用按模型/版本生成的 Collection 可以减少 Collection 管理成本；租户隔离靠服务端 READY 白名单和 owner_user_id + visibility + document_id 多层过滤，但必须做好返回后二次校验。
8. Chroma 记录为什么同时存 content_hash 和 document_content_hash？前者标识单个分片并去重，后者确认整份文档版本，解决的问题不同。
9. activeContentKey 为什么比“先查再插”更可靠？唯一约束能挡住并发请求的竞态。
10. Prisma Schema 为什么不是数据库真相的全部？CHECK、部分索引、LangGraph 自动表都只在 Migration/第三方 setup 中体现；Chroma Collection schema 更不在 Prisma 中。
11. 哪些字段是冗余数据？User.wordNumber、AiRun.userId、StudyTask.userId、模型/索引快照、Chroma 的 title/fileName 等；冗余换查询效率，但要设计一致性修复。
12. 当前最严重的数据库安全问题是什么？User.password 尚未哈希。

18. 快速记忆总结#

• User 是租户根。
• WordBookRecord 是“用户 × 单词”的学习状态。
• CourseRecord 是“用户 × 课程”的购买状态。
• Visitor 是埋点根，四张明细表记录 PV、行为、性能和错误。
• KnowledgeDocument 是私人文档的业务元数据与状态机，不存文件和向量。
• Chroma 没有本项目定义的关系表；当前模型/版本对应一个 Collection，正式记录由 ids + embeddings + documents + metadatas 组成，knowledge_chunk 与 stage1_probe 用 metadata.kind 区分。
• Chroma 通过 metadata.document_id 逻辑关联 KnowledgeDocument.id，通过 owner_user_id 逻辑关联 User.id；没有数据库外键。
• AiConversation 是长期对话，AiRun 是单次执行，AiMessage 是消息历史。
• AgentAction 是模型建议与真实写操作之间的安全闸门。
• StudyPlan 是计划头，StudyTask 是可执行任务。
• QuizSession 是待提交题目，QuizAttempt 是不可重复的最终答题结果。
• langgraph.* 四张表保存 Agent checkpoint，由 LangGraph 库管理。