Files

HaHafeng 31d555f7bb docs: Update architecture docs with platform infrastructure details

- Add platform infrastructure chapter to frontend-backend architecture design
- Update system architecture document with 6 new infrastructure modules
- Update AI onboarding guide with infrastructure overview
- Link to backend/src/common/README.md for detailed usage guide

Key Updates:
- Storage service (LocalAdapter + OSSAdapter)
- Logging system (Winston + JSON format)
- Cache service (Memory + Redis)
- Async job queue (Memory + Database)
- Health check endpoints
- Monitoring metrics
- Database connection pool
- Environment config management

All modules support zero-code switching between local and cloud environments.

Related: #Platform-Infrastructure

2025-11-17 08:36:10 +08:00

18 KiB

Raw Blame History

PKB - 个人知识库模块：数据库设计

版本： v1.0
更新时间： 2025-11-12
数据库Schema： pkb_schema
状态： ✅ 已实施并迁移

📋 目录

模块概述
Schema信息
数据库表设计
表关系图
索引设计
Phase 3功能说明
变更历史

模块概述

功能定位

PKB（Personal Knowledge Base）- 个人知识库模块提供文献管理和智能问答能力，核心功能：

知识库管理 - 创建和管理个人知识库
文档上传 - 支持PDF/Word/TXT等格式文档
智能问答 - 基于知识库的RAG（检索增强生成）对话
批处理任务 - 批量处理文献提取（Phase 3）
任务模板 - 预定义的批处理任务模板（Phase 3）

核心业务场景

用户创建知识库（如"CLL相关知识库"）
上传PDF文献到知识库
自动提取文本并向量化
基于知识库进行智能问答
批量提取文献中的结构化信息

与Dify平台集成

PKB模块深度集成Dify平台：

每个知识库对应一个Dify Dataset
每个文档对应一个Dify Document
使用Dify的向量检索和RAG能力

Schema信息

Schema名称

pkb_schema

创建语句

CREATE SCHEMA IF NOT EXISTS pkb_schema;
GRANT ALL ON SCHEMA pkb_schema TO aiclinical_admin;

数据迁移

迁移时间： 2025-11-12
源Schema： public
迁移脚本： docs/09-架构实施/migration-scripts/004-migrate-pkb.sql
数据完整性： ✅ 100%迁移成功

数据库表设计

表列表

表名	用途	行数（估计）	状态
`knowledge_bases`	知识库	5-50/用户	✅ 已部署
`documents`	文档	10-1000/知识库	✅ 已部署
`batch_tasks`	批处理任务	1-100/知识库	✅ Phase 3
`batch_results`	批处理结果	N条/任务	✅ Phase 3
`task_templates`	任务模板	10-50/用户	✅ Phase 3（预留）

总计： 5个表（2个核心表 + 3个Phase 3表）

1. knowledge_bases - 知识库表

用途： 存储用户创建的个人知识库

表结构

字段名	数据类型	约束	说明
id	TEXT	PRIMARY KEY	知识库唯一标识（UUID）
user_id	TEXT	NOT NULL, FK	所属用户ID
name	TEXT	NOT NULL	知识库名称
description	TEXT	NULL	知识库描述
dify_dataset_id	TEXT	NOT NULL, UNIQUE	Dify平台的Dataset ID
file_count	INTEGER	NOT NULL, DEFAULT 0	文件数量
total_size_bytes	BIGINT	NOT NULL, DEFAULT 0	总文件大小（字节）
created_at	TIMESTAMPTZ	NOT NULL, DEFAULT now()	创建时间
updated_at	TIMESTAMPTZ	NOT NULL	更新时间

Prisma Model

model KnowledgeBase {
  id             String   @id @default(uuid())
  userId         String   @map("user_id")
  name           String
  description    String?
  difyDatasetId  String   @map("dify_dataset_id")
  fileCount      Int      @default(0) @map("file_count")
  totalSizeBytes BigInt   @default(0) @map("total_size_bytes")
  
  createdAt      DateTime @default(now()) @map("created_at")
  updatedAt      DateTime @updatedAt @map("updated_at")
  
  user           User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  documents      Document[]
  batchTasks     BatchTask[]
  
  @@index([userId])
  @@index([difyDatasetId])
  @@map("knowledge_bases")
  @@schema("pkb_schema")
}

业务规则

Dify绑定 - 每个知识库对应唯一的Dify Dataset
统计字段 - file_count和total_size_bytes需实时更新
用户隔离 - 通过user_id实现数据隔离
级联删除 - 删除知识库时，文档和任务也被删除

2. documents - 文档表

用途： 存储知识库中的文档信息

表结构

字段名	数据类型	约束	说明
id	TEXT	PRIMARY KEY	文档唯一标识（UUID）
kb_id	TEXT	NOT NULL, FK	所属知识库ID
user_id	TEXT	NOT NULL, FK	所属用户ID
filename	TEXT	NOT NULL	文件名
file_type	TEXT	NOT NULL	文件类型（pdf/doc/txt等）
file_size_bytes	BIGINT	NOT NULL	文件大小（字节）
file_url	TEXT	NOT NULL	文件存储URL
dify_document_id	TEXT	NOT NULL	Dify平台的Document ID
status	TEXT	NOT NULL, DEFAULT 'uploading'	状态（uploading/processing/completed/failed）
progress	INTEGER	NOT NULL, DEFAULT 0	处理进度（0-100）
error_message	TEXT	NULL	错误信息
segments_count	INTEGER	NULL	切片数量
tokens_count	INTEGER	NULL	Token数量
extraction_method	TEXT	NULL	提取方法（auto/ocr/parse）
Phase 2字段			全文阅读功能
full_text	TEXT	NULL	完整文本内容
full_text_length	INTEGER	NULL	文本长度
metadata	JSONB	NULL	元数据（作者、标题、摘要等）
created_at	TIMESTAMPTZ	NOT NULL, DEFAULT now()	创建时间
updated_at	TIMESTAMPTZ	NOT NULL	更新时间

Prisma Model

model Document {
  id              String   @id @default(uuid())
  kbId            String   @map("kb_id")
  userId          String   @map("user_id")
  filename        String
  fileType        String   @map("file_type")
  fileSizeBytes   BigInt   @map("file_size_bytes")
  fileUrl         String   @map("file_url")
  difyDocumentId  String   @map("dify_document_id")
  status          String   @default("uploading")
  progress        Int      @default(0)
  errorMessage    String?  @map("error_message")
  segmentsCount   Int?     @map("segments_count")
  tokensCount     Int?     @map("tokens_count")
  extractionMethod String? @map("extraction_method")
  
  // Phase 2: 全文阅读功能
  fullText        String?  @map("full_text") @db.Text
  fullTextLength  Int?     @map("full_text_length")
  metadata        Json?
  
  createdAt       DateTime @default(now()) @map("created_at")
  updatedAt       DateTime @updatedAt @map("updated_at")
  
  knowledgeBase   KnowledgeBase @relation(fields: [kbId], references: [id], onDelete: Cascade)
  user            User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  batchResults    BatchResult[]
  
  @@index([kbId])
  @@index([userId])
  @@index([status])
  @@index([difyDocumentId])
  @@index([extractionMethod])
  @@map("documents")
  @@schema("pkb_schema")
}

业务规则

状态机 - status字段管理文档处理流程
- uploading → processing → completed
- 失败时转为failed
Dify同步 - 每个文档对应Dify中的一个Document
提取方法 - 支持自动识别、OCR、解析三种方式
Phase 2扩展 - full_text字段用于全文阅读和深度分析

3. batch_tasks - 批处理任务表 (Phase 3)

用途： 批量处理文献，提取结构化信息

表结构

字段名	数据类型	约束	说明
id	TEXT	PRIMARY KEY	任务唯一标识（UUID）
user_id	TEXT	NOT NULL, FK	所属用户ID
kb_id	TEXT	NOT NULL, FK	所属知识库ID
task_name	TEXT	NOT NULL	任务名称
task_type	TEXT	NOT NULL	任务类型（extract_info/summarize等）
prompt_template	TEXT	NOT NULL	Prompt模板
model_name	TEXT	NOT NULL, DEFAULT 'gpt-4'	使用的LLM模型
status	TEXT	NOT NULL, DEFAULT 'pending'	状态（pending/running/completed/failed）
total_documents	INTEGER	NOT NULL, DEFAULT 0	总文档数
processed_count	INTEGER	NOT NULL, DEFAULT 0	已处理数
success_count	INTEGER	NOT NULL, DEFAULT 0	成功数
failed_count	INTEGER	NOT NULL, DEFAULT 0	失败数
error_message	TEXT	NULL	错误信息
created_at	TIMESTAMPTZ	NOT NULL, DEFAULT now()	创建时间
updated_at	TIMESTAMPTZ	NOT NULL	更新时间

Prisma Model

model BatchTask {
  id              String   @id @default(uuid())
  userId          String   @map("user_id")
  kbId            String   @map("kb_id")
  taskName        String   @map("task_name")
  taskType        String   @map("task_type")
  promptTemplate  String   @map("prompt_template") @db.Text
  modelName       String   @default("gpt-4") @map("model_name")
  status          String   @default("pending")
  totalDocuments  Int      @default(0) @map("total_documents")
  processedCount  Int      @default(0) @map("processed_count")
  successCount    Int      @default(0) @map("success_count")
  failedCount     Int      @default(0) @map("failed_count")
  errorMessage    String?  @map("error_message") @db.Text
  
  user            User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  knowledgeBase   KnowledgeBase @relation(fields: [kbId], references: [id], onDelete: Cascade)
  results         BatchResult[]
  
  createdAt       DateTime @default(now()) @map("created_at")
  updatedAt       DateTime @updatedAt @map("updated_at")
  
  @@index([userId])
  @@index([kbId])
  @@index([status])
  @@index([createdAt])
  @@map("batch_tasks")
  @@schema("pkb_schema")
}

业务规则

任务类型 - 支持多种批处理类型
- extract_info - 提取结构化信息
- summarize - 批量摘要
- classify - 文献分类
状态机 - status管理任务执行状态
进度跟踪 - 实时更新计数器字段
模型选择 - 支持多种LLM模型

4. batch_results - 批处理结果表 (Phase 3)

用途： 存储批处理任务的每篇文献结果

表结构

字段名	数据类型	约束	说明
id	TEXT	PRIMARY KEY	结果唯一标识（UUID）
task_id	TEXT	NOT NULL, FK	所属任务ID
document_id	TEXT	NOT NULL, FK	所属文档ID
status	TEXT	NOT NULL, DEFAULT 'pending'	状态（pending/processing/completed/failed）
result_data	JSONB	NULL	提取的结构化数据
raw_output	TEXT	NULL	LLM原始输出
tokens_used	INTEGER	NULL	使用的Token数
error_message	TEXT	NULL	错误信息
created_at	TIMESTAMPTZ	NOT NULL, DEFAULT now()	创建时间

Prisma Model

model BatchResult {
  id              String   @id @default(uuid())
  taskId          String   @map("task_id")
  documentId      String   @map("document_id")
  status          String   @default("pending")
  resultData      Json?    @map("result_data")
  rawOutput       String?  @map("raw_output") @db.Text
  tokensUsed      Int?     @map("tokens_used")
  errorMessage    String?  @map("error_message") @db.Text
  
  task            BatchTask @relation(fields: [taskId], references: [id], onDelete: Cascade)
  document        Document @relation(fields: [documentId], references: [id], onDelete: Cascade)
  
  createdAt       DateTime @default(now()) @map("created_at")
  
  @@index([taskId])
  @@index([documentId])
  @@index([status])
  @@map("batch_results")
  @@schema("pkb_schema")
}

业务规则

结果存储 - result_data存储JSON格式的结构化数据
原始输出 - raw_output保留LLM原始输出，便于调试
Token统计 - 记录每篇文献的Token消耗

5. task_templates - 任务模板表 (Phase 3, 暂不实现)

用途： 存储预定义的批处理任务模板

表结构

字段名	数据类型	约束	说明
id	TEXT	PRIMARY KEY	模板唯一标识（UUID）
user_id	TEXT	NOT NULL, FK	所属用户ID
template_name	TEXT	NOT NULL	模板名称
task_type	TEXT	NOT NULL	任务类型
prompt_template	TEXT	NOT NULL	Prompt模板
output_fields	JSONB	NOT NULL, DEFAULT '{}'	输出字段定义
model_name	TEXT	NOT NULL, DEFAULT 'gpt-4'	默认模型
created_at	TIMESTAMPTZ	NOT NULL, DEFAULT now()	创建时间
updated_at	TIMESTAMPTZ	NOT NULL	更新时间

Prisma Model

model TaskTemplate {
  id              String   @id @default(uuid())
  userId          String   @map("user_id")
  templateName    String   @map("template_name")
  taskType        String   @map("task_type")
  promptTemplate  String   @map("prompt_template") @db.Text
  outputFields    Json     @default("{}") @map("output_fields")
  modelName       String   @default("gpt-4") @map("model_name")
  
  user            User @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  createdAt       DateTime @default(now()) @map("created_at")
  updatedAt       DateTime @updatedAt @map("updated_at")
  
  @@index([userId])
  @@map("task_templates")
  @@schema("pkb_schema")
}

业务规则

模板复用 - 用户可保存常用的任务配置
字段定义 - output_fields定义期望的输出结构
暂不实现 - Phase 3预留，后续开发

表关系图

erDiagram
    PLATFORM_USERS ||--o{ KNOWLEDGE_BASES : "owns"
    PLATFORM_USERS ||--o{ DOCUMENTS : "uploads"
    PLATFORM_USERS ||--o{ BATCH_TASKS : "creates"
    PLATFORM_USERS ||--o{ TASK_TEMPLATES : "defines"
    
    KNOWLEDGE_BASES ||--o{ DOCUMENTS : "contains"
    KNOWLEDGE_BASES ||--o{ BATCH_TASKS : "processes"
    
    BATCH_TASKS ||--o{ BATCH_RESULTS : "generates"
    DOCUMENTS ||--o{ BATCH_RESULTS : "analyzed_by"

    PLATFORM_USERS {
        text id PK
        text email
        text password
    }

    KNOWLEDGE_BASES {
        text id PK
        text user_id FK
        text name
        text dify_dataset_id
        int file_count
        bigint total_size_bytes
    }

    DOCUMENTS {
        text id PK
        text kb_id FK
        text user_id FK
        text filename
        text file_type
        text dify_document_id
        text status
        text full_text
        jsonb metadata
    }

    BATCH_TASKS {
        text id PK
        text user_id FK
        text kb_id FK
        text task_name
        text task_type
        text status
        int total_documents
        int processed_count
    }

    BATCH_RESULTS {
        text id PK
        text task_id FK
        text document_id FK
        text status
        jsonb result_data
        text raw_output
    }

    TASK_TEMPLATES {
        text id PK
        text user_id FK
        text template_name
        text task_type
        jsonb output_fields
    }

跨Schema引用

外键关系：

knowledge_bases.user_id → platform_schema.users.id
documents.user_id → platform_schema.users.id
batch_tasks.user_id → platform_schema.users.id
task_templates.user_id → platform_schema.users.id

说明： Prisma自动处理跨Schema外键，应用代码无需关心Schema前缀

索引设计

主键索引

所有表的id字段自动创建B-tree主键索引。

外键索引

表名	索引字段	用途
knowledge_bases	user_id	查询用户的所有知识库
knowledge_bases	dify_dataset_id	Dify数据同步
documents	kb_id	查询知识库的所有文档
documents	user_id	查询用户的所有文档
documents	status	过滤文档状态
documents	dify_document_id	Dify数据同步
documents	extraction_method	按提取方法过滤
batch_tasks	user_id	查询用户的任务
batch_tasks	kb_id	查询知识库的任务
batch_tasks	status	过滤任务状态
batch_results	task_id	查询任务的所有结果
batch_results	document_id	查询文档的处理结果
batch_results	status	过滤结果状态
task_templates	user_id	查询用户的模板

时间索引

表名	索引字段	用途
batch_tasks	created_at	按时间排序任务

Phase 3功能说明

批处理工作流程

sequenceDiagram
    participant User
    participant API
    participant BatchTask
    participant Document
    participant LLM
    participant BatchResult

    User->>API: 创建批处理任务
    API->>BatchTask: 创建任务记录
    API->>Document: 查询知识库文档列表
    
    loop 每篇文档
        BatchTask->>Document: 读取文档全文
        BatchTask->>LLM: 调用LLM提取信息
        LLM-->>BatchTask: 返回结构化数据
        BatchTask->>BatchResult: 保存结果
        BatchTask->>BatchTask: 更新进度
    end
    
    BatchTask->>API: 任务完成
    API-->>User: 返回结果汇总

批处理任务类型示例

信息提取 (extract_info)
- 提取研究方法、样本量、P值等
- 输出JSON格式的结构化数据
文献摘要 (summarize)
- 批量生成文献摘要
- 统一格式和长度
文献分类 (classify)
- 根据研究类型分类
- 标签化管理

变更历史

v1.0 - 2025-11-12 - 初始版本 ✅

变更内容：

从public schema迁移到pkb_schema
5个表全部迁移：
- knowledge_bases
- documents
- batch_tasks
- batch_results
- task_templates
在Prisma中添加@@schema("pkb_schema")标签
所有数据100%完整迁移

迁移脚本： docs/09-架构实施/migration-scripts/004-migrate-pkb.sql

验证状态： ✅ 已验证，功能正常

特殊处理：

batch_results.rawOutput → raw_output（列名映射修正）
task_templates.outputFields → output_fields（列名映射修正）

📚 相关文档

文档维护者： AI助手
最后更新： 2025-11-12
文档状态： ✅ 已完成并验证

18 KiB Raw Blame History Unescape Escape

PKB - 个人知识库模块：数据库设计

📋 目录

模块概述

功能定位

核心业务场景

与Dify平台集成

Schema信息

Schema名称

创建语句

数据迁移

数据库表设计

表列表

1. knowledge_bases - 知识库表

表结构

Prisma Model

业务规则

2. documents - 文档表

表结构

Prisma Model

业务规则

3. batch_tasks - 批处理任务表 (Phase 3)

表结构

Prisma Model

业务规则

4. batch_results - 批处理结果表 (Phase 3)

表结构

Prisma Model

业务规则

5. task_templates - 任务模板表 (Phase 3, 暂不实现)

表结构

Prisma Model

业务规则

表关系图

跨Schema引用

索引设计

主键索引

外键索引

时间索引

Phase 3功能说明

批处理工作流程

批处理任务类型示例

变更历史

v1.0 - 2025-11-12 - 初始版本 ✅

📚 相关文档

18 KiB

Raw Blame History