AIclinicalresearch/docs/09-架构实施/07-架构决策-新增EKB独立Schema.md

架构决策记录 (ADR-013)：关于新增第 13 个 Schema (ekb_schema) 的提案

状态： 🟢 提议中 (Proposed)
日期： 2026-01-20
决策者： 架构师 & 开发团队
涉及模块： 知识库引擎 (EKB), 个人知识库 (PKB), 智能文献 (ASL), 智能问答 (AIA)

1. 背景与问题

目前我们的 Postgres-Only 架构已成功实施了 12 个 Schema 的隔离策略（platform, common, pkb, asl 等）。

随着 知识库引擎 (Knowledge Base Engine) 的引入，我们需要存储海量的向量切片数据（EkbChunk 表）和多模态文档数据（EkbDocument 表）。

当前面临的问题是：这些数据应该存放在哪里？

我们面临三个选项：

1. 选项 A：放在 pkb Schema 中（因为 PKB 是第一个使用者）。
2. 选项 B：放在 common 或 capability Schema 中（因为它是通用能力）。
3. 选项 C：新建第 13 个独立 Schema —— ekb_schema。

2. 决策结论

我们决定采用【选项 C】：创建独立的 ekb_schema。

这意味着我们的 Prisma datasource 配置将包含 13 个 Schema：
schemas = [..., "ekb_schema"]

3. 决策详细理由

3.1 架构分层：避免依赖倒置 (Dependency Inversion)

知识库引擎是底层基础设施（Infrastructure Layer），类似于“图书馆大楼”；而 PKB、ASL、AIA 是上层业务应用（Application Layer），类似于“租户”。

• 如果将引擎表放在 pkb Schema 中，会导致逻辑上的“ASL 依赖 PKB”，这是错误的依赖关系。
• 通过独立 ekb_schema，所有业务模块（PKB, ASL, AIA）都平等地依赖 EKB，架构层次清晰。

3.2 运维隔离：重型数据的特殊需求

向量表 (EkbChunk) 具有显著的**“重数据”**特征：

• 数据量大：可能迅速增长到百万/千万行级别。
• 索引特殊：使用 HNSW 向量索引，构建和维护成本高。
• 维护频繁：向量表对 UPDATE/DELETE 敏感，需要更激进的 VACUUM (垃圾回收) 策略。

将其隔离在独立 Schema 中，允许 DBA 未来针对该 Schema 进行独立的性能调优（如分配特定的 Tablespace 或调整内存参数），而不影响 users 或 orders 等轻量级业务表。

3.3 业务边界清晰

• common：存放纯技术组件（Log, Storage 记录）。
• capability：存放轻量级业务配置（Prompt 模板）。
• ekb_schema：存放核心知识资产和向量数据。

混在一起会导致 common 变得极其臃肿，增加后续拆分微服务的难度。

4. 性能影响评估 (Performance Review)

团队可能担心：“13 个 Schema 会不会太多？会不会拖慢速度？”

技术评估结论：对性能几乎无负面影响（Zero Overhead）。

关注点	技术事实	结论
查询速度	PostgreSQL 内部使用 OID 查找表，Schema 只是逻辑命名空间。跨 Schema Join (JOIN ekb.Chunk) 与同 Schema Join 性能完全一致。	✅ 无损耗
连接资源	我们使用的是 Prisma 单一连接池。所有 Schema 复用同一个 TCP 连接，不增加数据库连接数。	✅ 无损耗
内存占用	Schema 本身只占用极少的元数据空间。Postgres 支持单库数千个 Schema 毫无压力。	✅ 可忽略
维护效率	独立的 Schema 让 pg_dump 备份和 VACUUM 维护更灵活（可只备份业务数据，单独备份向量数据）。	✅ 正向收益

5. 潜在风险与应对 (Risks & Mitigation)

虽然性能无忧，但在多 Schema 开发中存在以下“坑”，需提前规避：

🔧 坑 1：Prisma 的跨 Schema 关联

• 问题：跨 Schema 定义外键（如 EkbDocument 关联 User）时，容易因缺少标记报错。
• 解决方案：
  1. 显式标记：关联的两个 Model 必须都带有 @@schema("...") 标记。
  2. 双向定义：在两边都定义 @relation 字段，确保 Prisma Client 能正确生成跨 Schema 的 Join 查询。
  3. 弱关联推荐：对于非强一致性业务，建议仅存储 ID 字符串（如 userId），减少数据库层面的硬外键约束，提升灵活性。

🔧 坑 2：原生 SQL 的写法复杂度

• 问题：在使用 prisma.$queryRaw 进行向量检索时，很容易忘记加 Schema 前缀，导致 Relation "EkbChunk" does not exist 错误。
• 解决方案：
  • 强制带前缀：在写 SQL 时必须使用双引号包裹 Schema 和表名，例如 FROM "ekb_schema"."EkbChunk"。
  • 封装服务：禁止在 Controller 层写 SQL，所有向量检索逻辑必须封装在 KnowledgeBaseEngine 类中，屏蔽底层细节。

🔧 坑 3：迁移文件管理 (Migration Clutter)

• 问题：Prisma 将所有 Schema 的变更都放在同一个 prisma/migrations 文件夹下，文件多了容易混乱。
• 解决方案：
  • 命名规范：执行迁移时强制加前缀。
    • ✅ npx prisma migrate dev --name ekb_init_vector_table
    • ✅ npx prisma migrate dev --name aia_update_agents
  • 这样在排查问题时，能一眼看出该 Migration 属于哪个模块。

6. 实施计划 (Implementation)

步骤 1: 更新 Prisma 配置

在 prisma/schema.prisma 中：

generator client {
provider = "prisma-client-js"
previewFeatures = ["multiSchema", "postgresqlExtensions"]
}

datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
extensions = [vector, pg_bigm] // 确保启用插件
// 添加新的 schema
schemas = [..., "capability", "ekb_schema"]
}

步骤 2: 定义模型

将 04-数据模型设计.md 中的模型放入：

model EkbKnowledgeBase {
// ... 字段定义
@@schema("ekb_schema") // 👈 关键点
}

model EkbDocument {
// ... 字段定义
kbId String
kb EkbKnowledgeBase @relation(fields: [kbId], references: [id])
@@schema("ekb_schema")
}
// ... EkbChunk 同理

步骤 3: 跨 Schema 关联 (注意事项)

如果业务表（如 pkb_schema.UserPkbConfig）需要关联知识库：

// 在 pkb_schema 中
model UserPkbConfig {
id String @id
kbId String
kb EkbKnowledgeBase @relation(fields: [kbId], references: [id]) // 👈 跨 Schema 关联支持良好
@@schema("pkb")
}

7. 常见问题 (FAQ)

Q: 以后如果要把 EKB 拆成独立微服务怎么办？
A: 正因为我们现在用了独立的 Schema，拆分微服务时只需要把这个 Schema 导出，部署到新数据库即可。如果混在 pkb 里，拆分反而极其痛苦。
Q: 为什么不放在 capability Schema？
A: capability 目前主要存 Prompt 模板，数据量极小。而 ekb 未来会有大量向量数据，体量差异过大，建议物理上保持逻辑距离。
结论： 创建第 13 个 Schema 是符合我们“Postgres-Only + 模块化”架构原则的最佳实践，既保证了性能，又为未来的运维和扩展留足了空间。