Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(platform): Add database documentation system and restructure deployment docs

Browse Source 
Completed:
- Add 6 core database documents (docs/01-平台基础层/07-数据库/)
  Architecture overview, migration history, environment comparison,
  tech debt tracking, seed data management, PostgreSQL extensions
- Restructure deployment docs: archive 20 legacy files to _archive-2025/
- Create unified daily operations manual (01-日常更新操作手册.md)
- Add pending deployment change tracker (03-待部署变更清单.md)
- Update database development standard to v3.0 (three iron rules)
- Fix Prisma schema type drift: align @db.* annotations with actual DB
  IIT: UUID/Timestamptz(6), SSA: Timestamp(6)/VarChar(20/50/100)
- Add migration: 20260227_align_schema_with_db_types (idempotent ALTER)
- Add Cursor Rule for auto-reminding deployment change documentation
- Update system status guide v6.4 with deployment and DB doc references
- Add architecture consultation docs (Prisma guide, SAE deployment guide)

Technical details:
- Manual migration due to shadow DB limitation (TD-001 in tech debt)
- Deployment docs reduced from 20+ scattered files to 3 core documents
- Cursor Rule triggers on schema.prisma, package.json, Dockerfile changes

Made-with: Cursor
This commit is contained in:
HaHafeng
2026-02-27 14:35:25 +08:00
parent 9b8490b4d0
commit 6124c7abc6
48 changed files with 3009 additions and 582 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
docs/01-平台基础层/07-数据库/00-数据库架构总览.md Normal file
View File

@@ -0,0 +1,163 @@
# 数据库架构总览
> 版本: v1.0
> 更新日期: 2026-02-27
> 数据来源: 本地开发数据库实时查询
---
## 1. 基本信息
| 项目 | 值 |
|------|-----|
| 数据库引擎 | PostgreSQL 15.15 |
| ORM | Prisma 6.17.0 |
| 数据库名 | ai_clinical_research |
| Schema 数量 | 14 个（含 public） |
| 表总数 | 96 张 |
| 列总数 | 1217 个 |
| 索引总数 | 339 个 |
| 外键关系 | 53 条 |
| 扩展 | pgvector 0.8.1, pg_bigm 1.2 |
| 迁移历史 | 14 个已应用迁移 |
---
## 2. Schema 全景图
```
AI 临床研究平台 — 数据库 Schema 全景图
┌─────────────────────────────────────────────────────────────────────────┐
│ platform_schema (19 表) │
│ 用户、租户、权限、模块、pg-boss 队列 │
│ tenants → users → tenant_members → departments │
│ modules → permissions → role_permissions → user_modules │
│ job / queue / schedule / subscription (pg-boss 异步任务) │
├─────────────────────────────────────────────────────────────────────────┤
│ capability_schema (4 表) │
│ Prompt 模板管理 + 系统知识库 │
│ prompt_templates → prompt_versions │
│ system_knowledge_bases → system_kb_documents │
├─────────────────────────────────────────────────────────────────────────┤
│ agent_schema (6 表) │ ekb_schema (3 表) │
│ 通用 Agent 定义/编排/追踪 │ 企业知识库(向量) │
│ agent_definitions │ ekb_knowledge_base │
│ → agent_stages │ → ekb_document │
│ → agent_prompts │ → ekb_chunk (vector 1024) │
│ → agent_sessions │ │
│ → agent_traces │ │
│ → reflexion_rules │ │
├───────────────────────────────┴────────────────────────────────────────┤
│ admin_schema (2 表) │
│ 运营管理：admin_operation_logs, simple_logs │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌── 业务模块层 ──────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ iit_schema (20 表) │ ssa_schema (11 表) │ │
│ │ IIT 临床试验管理 Agent │ 智能统计分析 │ │
│ │ projects (中心) │ ssa_sessions (中心) │ │
│ │ → conversation_history │ → ssa_messages │ │
│ │ → audit_logs │ → ssa_execution_logs │ │
│ │ → pending_actions │ → ssa_workflows │ │
│ │ → task_runs │ → ssa_workflow_steps │ │
│ │ → user_mappings │ ssa_tools_library (vector 1024) │ │
│ │ field_metadata, qc_logs │ ssa_r_code_library │ │
│ │ equery, critical_events │ ssa_decision_table │ │
│ │ skills, weekly_reports │ ssa_guardrail_config │ │
│ │ agent_trace, record_summary│ ssa_param_mapping │ │
│ │ qc_reports, qc_project_stats│ ssa_interpretation_templates │ │
│ │ │ │ │
│ │ asl_schema (11 表) │ rvw_schema (1 表) │ │
│ │ AI 智能文献 │ 稿件审查 │ │
│ │ screening_projects (中心) │ review_tasks │ │
│ │ → literatures │ │ │
│ │ → screening_tasks │ dc_schema (6 表) │ │
│ │ → screening_results │ 数据清洗整理 │ │
│ │ → fulltext_screening_* │ dc_templates │ │
│ │ research_tasks │ → dc_extraction_tasks │ │
│ │ extraction_templates │ → dc_extraction_items │ │
│ │ → extraction_project_* │ dc_tool_c_sessions │ │
│ │ → extraction_tasks │ dc_tool_c_ai_history │ │
│ │ → extraction_results│ dc_health_checks │ │
│ │ │ │ │
│ │ aia_schema (3 表) │ protocol_schema (2 表) │ │
│ │ AI 智能问答 │ 方案 Agent │ │
│ │ projects → conversations │ protocol_contexts │ │
│ │ → messages │ → protocol_generations │ │
│ │ │ │ │
│ │ pkb_schema (5 表) │ public (3 表) │ │
│ │ 个人知识库 │ _prisma_migrations │ │
│ │ knowledge_bases │ users (遗留), admin_logs (遗留) │ │
│ │ → documents │ │ │
│ │ → batch_tasks │ │ │
│ │ → batch_results │ │ │
│ │ task_templates │ │ │
│ └─────────────────────────────┴──────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 3. Schema 清单
| # | Schema | 表数 | 列数 | 归属模块 | 职责描述 |
|---|--------|------|------|----------|---------|
| 1 | `platform_schema` | 19 | ~200 | 平台基础层 | 用户、租户、权限、pg-boss 任务队列 |
| 2 | `capability_schema` | 4 | ~38 | 通用能力层 | Prompt 模板管理、系统知识库 |
| 3 | `agent_schema` | 6 | ~71 | 通用能力层 | 通用 Agent 定义、编排、运行追踪 |
| 4 | `ekb_schema` | 3 | ~38 | 通用能力层 | 企业知识库（向量检索） |
| 5 | `admin_schema` | 2 | ~21 | 运营管理 | 操作日志、简单日志 |
| 6 | `iit_schema` | 20 | ~246 | IIT Manager Agent | 项目管理、质控、eQuery、重大事件 |
| 7 | `ssa_schema` | 11 | ~117 | 智能统计分析 | 会话、工作流、工具库、R 代码库 |
| 8 | `asl_schema` | 11 | ~235 | AI 智能文献 | 文献筛选、全文复筛、数据提取 |
| 9 | `rvw_schema` | 1 | ~26 | 稿件审查 | 审查任务 |
| 10 | `dc_schema` | 6 | ~83 | 数据清洗 | 模板、提取任务、AI 对话 |
| 11 | `aia_schema` | 3 | ~32 | AI 智能问答 | 项目、对话、消息 |
| 12 | `protocol_schema` | 2 | ~29 | 方案 Agent | 方案上下文、方案生成 |
| 13 | `pkb_schema` | 5 | ~66 | 个人知识库 | 知识库、文档、批处理 |
| 14 | `public` | 3 | ~31 | 系统/遗留 | Prisma 迁移表 + 遗留 users/admin_logs |
**合计：14 个 Schema，96 张表，~1217 列**
---
## 4. 向量检索表
| Schema | 表 | 向量列 | 维度 | 用途 |
|--------|-----|--------|------|------|
| `iit_schema` | `conversation_history` | `embedding` | 1536 | IIT 对话语义搜索 |
| `ekb_schema` | `ekb_chunk` | `embedding` | 1024 | 企业知识库 RAG 检索 |
| `ssa_schema` | `ssa_tools_library` | `embedding` | 1024 | SSA 工具语义匹配 |
---
## 5. pg-boss 任务队列表
`platform_schema` 中有 5 张 pg-boss 管理的表：
| 表 | 职责 |
|-----|------|
| `job` | 活跃任务 |
| `job_common` | 公共任务配置 |
| `queue` | 队列定义 |
| `schedule` | 定时任务调度 |
| `subscription` | 事件订阅 |
> 详细使用指南见 `docs/07-运维文档/01-PgBoss队列监控与维护.md`
---
## 6. 跨文档索引
| 关注点 | 文档位置 |
|--------|---------|
| 数据库开发规范 | `docs/04-开发规范/09-数据库开发规范.md` |
| 迁移历史 | `docs/01-平台基础层/07-数据库/01-Prisma迁移历史与变更日志.md` |
| 环境差异 | `docs/01-平台基础层/07-数据库/02-环境状态对照表.md` |
| 技术债务 | `docs/01-平台基础层/07-数据库/03-技术债务追踪.md` |
| 种子数据 | `docs/01-平台基础层/07-数据库/04-种子数据管理.md` |
| 扩展特性 | `docs/01-平台基础层/07-数据库/05-PostgreSQL扩展与特性.md` |
| 部署迁移 | `docs/05-部署文档/*/01-数据库迁移方案.md` |
| 运维注意事项 | `docs/07-运维文档/03-数据库迁移注意事项.md` |
| Prisma 操作指南 | `docs/09-架构实施/J技术架构咨询/数据库同步规范与Prisma操作指南.md` |

179
docs/01-平台基础层/07-数据库/01-Prisma迁移历史与变更日志.md Normal file
View File

@@ -0,0 +1,179 @@
# Prisma 迁移历史与变更日志
> 版本: v1.0
> 更新日期: 2026-02-27
> 维护说明: 每次新增迁移后，在此文档追加记录
---
## 1. 迁移时间线总览
当前共 **14 个已应用迁移**，覆盖 2025-10 至 2026-02 的演进过程。
```
2025-10 ████ init + conversations + batch + review_tasks
2025-12 █ column_mapping
2026-01 █ system_knowledge_base
2026-02 ████████ IIT agent + CRA QC + SSA module + DeepResearch V2
+ extraction template + db push drift patch
+ eQuery/critical events + type alignment
```
---
## 2. 完整迁移清单
### #1 — 20251010075003_init
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-01-26 08:17:06 |
| 影响 Schema | public, platform_schema, aia_schema, pkb_schema, dc_schema, iit_schema, asl_schema, ekb_schema, agent_schema |
| 核心内容 | 系统初始化，创建全部 schema + 核心表（users, tenants, conversations, knowledge_bases, documents, screening_projects, literatures, agent_definitions 等） |
| 说明 | 全量初始化迁移，包含 pgvector 和 pg_bigm 扩展安装 |
### #2 — 20251010122727_add_conversation_metadata_deleted_at
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-01-26 08:17:14 |
| 影响 Schema | iit_schema |
| 核心内容 | conversation_history 表增加 metadata(JSONB) 和 deleted_at(TIMESTAMP) 列 |
### #3 — 20251012124747_add_batch_processing_module
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-01-26 08:17:16 |
| 影响 Schema | pkb_schema |
| 核心内容 | 新增 batch_tasks 和 batch_results 表，支持批处理功能 |
### #4 — 20251014120128_add_review_tasks
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-01-26 08:17:17 |
| 影响 Schema | rvw_schema |
| 核心内容 | 创建 rvw_schema 和 review_tasks 表 |
### #5 — 20251208_add_column_mapping
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-01-26 08:17:19 |
| 影响 Schema | dc_schema |
| 核心内容 | dc_extraction_tasks 表增加 column_mapping(JSONB) 列 |
### #6 — 20260128_add_system_knowledge_base
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-01-28 12:36:17 |
| 影响 Schema | capability_schema |
| 核心内容 | 创建 system_knowledge_bases 和 system_kb_documents 表，支持系统级知识库管理 |
### #7 — 20260207112544_add_iit_manager_agent_tables
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-02-07 03:26:29 |
| 影响 Schema | iit_schema |
| 核心内容 | IIT Manager Agent V2.x 表结构：record_summary, weekly_reports, project_memory, agent_trace, skills, pii_audit_log, qc_project_stats 等 |
### #8 — 20260208134925_add_cra_qc_engine_support
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-02-08 05:49:47 |
| 影响 Schema | iit_schema |
| 核心内容 | CRA 质控引擎支持：qc_logs, qc_reports, form_templates 表 + projects 表增加质控相关列 |
### #9 — 20260219_add_ssa_module
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-02-19 06:21:29 |
| 影响 Schema | ssa_schema |
| 核心内容 | 创建 ssa_schema 及 9 张表：ssa_sessions, ssa_messages, ssa_execution_logs, ssa_tools_library, ssa_r_code_library, ssa_decision_table, ssa_guardrail_config, ssa_param_mapping, ssa_interpretation_templates |
### #10 — 20260223_add_deep_research_v2_fields
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-02-23 01:44:19 |
| 影响 Schema | asl_schema |
| 核心内容 | research_tasks 表增加 6 列：target_sources, confirmed_requirement, ai_intent_summary, execution_logs, synthesis_report, result_list |
| ⚠️ 注意 | 此迁移依赖 research_tasks 表（由 prisma db push 创建），Shadow DB 重放会失败 |
### #11 — 20260225_add_extraction_template_engine
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-02-25 00:07:57 |
| 影响 Schema | asl_schema |
| 核心内容 | 全文提取模板引擎：extraction_templates, extraction_project_templates, extraction_tasks, extraction_results 4 张表 |
### #12 — 20260227_patch_db_push_drift
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-02-27 01:11:55 |
| 影响 Schema | iit_schema, ssa_schema, rvw_schema |
| 核心内容 | 补丁迁移，覆盖 prisma db push 创建的结构：field_metadata, qc_logs, qc_reports, form_templates（iit）, ssa_workflows, ssa_workflow_steps（ssa）, review_tasks 新增 8 列 + 1 索引（rvw） |
| 性质 | 使用 `CREATE TABLE IF NOT EXISTS` 和 `ADD COLUMN IF NOT EXISTS` 保证幂等 |
### #13 — 20260226_add_equery_critical_events_cron
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-02-27 01:12:08 |
| 影响 Schema | iit_schema |
| 核心内容 | eQuery 电子质疑表 + critical_events 重大事件表 + projects 增加 cron_enabled/cron_expression 列 |
| 特殊类型 | id 使用 PostgreSQL 原生 UUID，时间戳使用 TIMESTAMPTZ |
### #14 — 20260227_align_schema_with_db_types
| 属性 | 值 |
|------|-----|
| 应用时间 | 2026-02-27 05:44:11 |
| 影响 Schema | ssa_schema |
| 核心内容 | 对齐 Schema 类型注解与数据库实际类型：ssa_workflows/ssa_workflow_steps 的 VARCHAR 长度和 TIMESTAMP 精度 + 清理 2 个重复外键 |
| 性质 | Schema 精度对齐，SQL 对实际数据库为幂等操作 |
---
## 3. 迁移创建方式说明
| 方式 | 适用场景 | 涉及迁移 |
|------|---------|---------|
| `prisma migrate dev` | 标准开发流程 | #1 ~ #9 |
| `prisma migrate dev --create-only` | 仅生成不执行 | — |
| 手动创建 + `prisma migrate resolve --applied` | Shadow DB 无法重放时 | #12, #13, #14 |
| `prisma db push` (⚠️ 非标准) | 快速原型，不产生迁移记录 | 造成了 drift patch 的必要性 |
---
## 4. 维护规则
### 新增迁移时，在本文档追加：
```markdown
### #N — YYYYMMDD_migration_name
| 属性 | 值 |
|------|-----|
| 应用时间 | YYYY-MM-DD HH:MM:SS |
| 影响 Schema | xxx_schema |
| 核心内容 | 简述变更 |
```
### 检查迁移状态：
```bash
# 查看本地已应用迁移
docker exec ai-clinical-postgres psql -U postgres -d ai_clinical_research \
-c "SELECT migration_name, finished_at FROM _prisma_migrations ORDER BY started_at;"
# 查看 RDS 已应用迁移
npx prisma migrate status
```

102
docs/01-平台基础层/07-数据库/02-环境状态对照表.md Normal file
View File

@@ -0,0 +1,102 @@
# 环境状态对照表
> 版本: v1.0
> 更新日期: 2026-02-27
> 维护说明: 每次部署后更新此表，确保三环境状态可追溯
---
## 1. 环境概览
| 环境 | 数据库类型 | 地址 | 数据库名 | 用户 |
|------|----------|------|---------|------|
| **本地开发** | Docker (pgvector/pgvector:pg15) | localhost:5432 | ai_clinical_research | postgres |
| **测试环境** | 阿里云 RDS PostgreSQL 15 | pgm-2zex1m2y3r23hdn5so.pg.rds.aliyuncs.com:5432 | ai_clinical_research_test | airesearch |
| **生产环境** | 待部署 | — | — | — |
---
## 2. 迁移状态对比
> 截止日期：2026-02-27
| # | 迁移名 | 本地开发 | 测试 RDS | 说明 |
|---|--------|---------|---------|------|
| 1 | 20251010075003_init | ✅ | ✅ | |
| 2 | 20251010122727_add_conversation_metadata_deleted_at | ✅ | ✅ | |
| 3 | 20251012124747_add_batch_processing_module | ✅ | ✅ | |
| 4 | 20251014120128_add_review_tasks | ✅ | ✅ | |
| 5 | 20251208_add_column_mapping | ✅ | ✅ | |
| 6 | 20260128_add_system_knowledge_base | ✅ | ✅ | |
| 7 | 20260207112544_add_iit_manager_agent_tables | ✅ | ✅ | 0227 部署时应用 |
| 8 | 20260208134925_add_cra_qc_engine_support | ✅ | ✅ | 0227 部署时应用 |
| 9 | 20260219_add_ssa_module | ✅ | ✅ | 0227 部署时应用 |
| 10 | 20260223_add_deep_research_v2_fields | ✅ | ✅ | 0227 部署时应用 |
| 11 | 20260225_add_extraction_template_engine | ✅ | ✅ | 0227 部署时应用 |
| 12 | 20260227_patch_db_push_drift | ✅ | ✅ | 0227 部署时应用 |
| 13 | 20260226_add_equery_critical_events_cron | ✅ | ✅ | 0227 部署时应用 |
| 14 | 20260227_align_schema_with_db_types | ✅ | ❌ | 本地对齐，尚未部署到 RDS |
---
## 3. PostgreSQL 扩展对比
| 扩展 | 本地开发 | 测试 RDS | 说明 |
|------|---------|---------|------|
| plpgsql | 1.0 | 1.0 | PostgreSQL 内置 |
| pgvector (vector) | 0.8.1 | 0.8.0 | 向量搜索，RDS 版本略低 |
| pg_bigm | 1.2 | 1.2 | 中文全文检索 |
---
## 4. Schema 结构对比
| Schema | 本地开发 表数 | 测试 RDS 表数 | 差异说明 |
|--------|-------------|-------------|---------|
| platform_schema | 19 | 19 | 一致 |
| capability_schema | 4 | 4 | 一致 |
| agent_schema | 6 | 6 | 一致 |
| ekb_schema | 3 | 3 | 一致 |
| admin_schema | 2 | 2 | 一致 |
| iit_schema | 20 | 20 | 一致（0227 部署后） |
| ssa_schema | 11 | 11 | RDS 缺少 #14 的类型对齐 |
| asl_schema | 11 | 11 | 一致 |
| rvw_schema | 1 | 1 | 一致（0227 补 8 列后） |
| dc_schema | 6 | 6 | 一致 |
| aia_schema | 3 | 3 | 一致 |
| protocol_schema | 2 | 2 | 一致 |
| pkb_schema | 5 | 5 | 一致 |
| public | 3 | 3 | 一致 |
---
## 5. 已知的环境差异
### 5.1 测试 RDS 待部署项
| 项目 | 内容 | 优先级 | 风险 |
|------|------|--------|------|
| 迁移 #14 | ssa_workflows 类型精度对齐 + 重复 FK 清理 | 低 | 无数据影响，幂等 SQL |
### 5.2 本地开发特有
| 项目 | 说明 |
|------|------|
| `prisma db push` 产生的额外结构 | 部分表/列未通过迁移创建，已由 #12 drift patch 覆盖 |
| Shadow DB 重放失败 | #10 迁移依赖 `research_tasks`（非迁移创建），影响 `prisma migrate dev` |
---
## 6. 更新日志
| 日期 | 操作人 | 变更 |
|------|--------|------|
| 2026-02-27 | AI 助手 | 初始化文档，记录 0227 部署后状态 |
---
## 7. 维护规则
- **每次部署后**：更新第 2 节迁移状态和第 4 节表数
- **新增扩展后**：更新第 3 节扩展对比
- **发现差异时**：记录在第 5 节，标注优先级和风险

123
docs/01-平台基础层/07-数据库/03-技术债务追踪.md Normal file
View File

@@ -0,0 +1,123 @@
# 数据库技术债务追踪
> 版本: v1.0
> 更新日期: 2026-02-27
> 维护说明: 发现新债务时立即记录，修复后标记状态
---
## 1. 债务总览
| 状态 | 数量 |
|------|------|
| 🔴 待修复 | 2 |
| 🟡 已缓解（带 workaround） | 2 |
| 🟢 已修复 | 2 |
---
## 2. 当前债务清单
### TD-001: Shadow DB 重放失败（prisma migrate dev 不可用）
| 属性 | 值 |
|------|-----|
| 状态 | 🔴 待修复 |
| 发现日期 | 2026-02-27 |
| 影响范围 | 本地开发环境 |
| 严重程度 | 中 — 不影响部署（`prisma migrate deploy` 不使用 Shadow DB） |
| 根因 | 迁移 #10 (`20260223_add_deep_research_v2_fields`) 对 `asl_schema.research_tasks` 执行 ALTER TABLE，但该表由 `prisma db push` 创建，无对应迁移记录。Shadow DB 重放到 #10 时找不到表 |
| 当前影响 | 无法使用 `prisma migrate dev` 生成新迁移，需手动创建 + `prisma migrate resolve` |
| 修复方案 | 在 #10 之前插入补全迁移，创建 `research_tasks` 及其他 `prisma db push` 表。需同时更新 `_prisma_migrations` 表的记录顺序 |
| 修复难度 | 高 — 需仔细梳理所有 `db push` 创建的表，确保不遗漏 |
### TD-002: equery / critical_events 使用非标准 ID 类型
| 属性 | 值 |
|------|-----|
| 状态 | 🟡 已缓解 |
| 发现日期 | 2026-02-27 |
| 影响范围 | iit_schema |
| 严重程度 | 低 — 不影响功能，仅类型不统一 |
| 根因 | 迁移 #13 使用 PostgreSQL 原生 `UUID` 类型和 `TIMESTAMPTZ`，而系统其他表统一使用 `TEXT` + `TIMESTAMP(3)` |
| Workaround | Schema 中已添加 `@db.Uuid` 和 `@db.Timestamptz(6)` 注解对齐，并标注 `// TODO: Tech Debt` |
| 最终修复 | 未来大版本重构时统一 ID 策略（全部 TEXT 或全部 UUID） |
### TD-003: ssa_workflows / ssa_workflow_steps 类型精度不一致
| 属性 | 值 |
|------|-----|
| 状态 | 🟢 已修复 |
| 发现日期 | 2026-02-27 |
| 修复日期 | 2026-02-27 |
| 修复方式 | 迁移 #14 (`20260227_align_schema_with_db_types`) 对齐了 VARCHAR 长度和 TIMESTAMP 精度，清理了 2 个重复 FK |
### TD-004: Prisma diff 引擎的 vector 类型噪音
| 属性 | 值 |
|------|-----|
| 状态 | 🟡 已缓解 |
| 发现日期 | 2026-02-27 |
| 影响范围 | ekb_schema, iit_schema, ssa_schema |
| 严重程度 | 低 — 纯噪音，不影响任何功能 |
| 根因 | Prisma 的 `Unsupported("vector(1024)")` 类型无法被 diff 引擎正确比较，每次 diff 都会输出 3 条 `ALTER COLUMN SET DATA TYPE` 假变更 |
| Workaround | 已知噪音，运行 diff 时忽略 vector 相关行 |
| 最终修复 | 等待 Prisma 原生支持 pgvector 类型 |
### TD-005: prisma db push 历史遗留
| 属性 | 值 |
|------|-----|
| 状态 | 🟢 已修复 |
| 发现日期 | 2026-02-27 |
| 修复日期 | 2026-02-27 |
| 影响范围 | iit_schema, ssa_schema, rvw_schema |
| 修复方式 | 迁移 #12 (`20260227_patch_db_push_drift`) 使用 `CREATE TABLE IF NOT EXISTS` 和 `ADD COLUMN IF NOT EXISTS` 将所有 db push 创建的结构纳入迁移体系 |
### TD-006: public schema 遗留表
| 属性 | 值 |
|------|-----|
| 状态 | 🔴 待修复 |
| 发现日期 | 2026-02-27 |
| 影响范围 | public schema |
| 严重程度 | 极低 — 不影响任何功能 |
| 根因 | `public.users` 和 `public.admin_logs` 是系统早期创建的遗留表，在引入 multi-schema 后已被 `platform_schema.users` 和 `admin_schema.admin_operation_logs` 替代 |
| 修复方案 | 确认无引用后安全删除遗留表 |
| 修复难度 | 低 |
---
## 3. 债务产生根因分析
```
prisma db push 的不规范使用
├── 表/列未纳入迁移体系 → TD-005 (已修复)
├── Shadow DB 无法重放 → TD-001 (待修复)
└── 非标准类型创建 → TD-002, TD-003 (已缓解/已修复)
Prisma ORM 限制
└── Unsupported 类型 diff 噪音 → TD-004 (已缓解)
历史架构演进
└── multi-schema 前的遗留表 → TD-006 (待修复)
```
---
## 4. 预防措施
| 措施 | 对应规范 |
|------|---------|
| **禁止** 在开发中使用 `prisma db push`（仅限原型探索） | `docs/04-开发规范/09-数据库开发规范.md` |
| 所有 Schema 变更必须通过 `prisma migrate dev` | 同上 |
| 新增迁移后立即更新迁移日志 | `docs/01-平台基础层/07-数据库/01-Prisma迁移历史与变更日志.md` |
| 部署前对比环境差异 | `docs/01-平台基础层/07-数据库/02-环境状态对照表.md` |
---
## 5. 更新日志
| 日期 | 操作人 | 变更 |
|------|--------|------|
| 2026-02-27 | AI 助手 | 初始化文档，记录 6 项技术债务 |

116
docs/01-平台基础层/07-数据库/04-种子数据管理.md Normal file
View File

@@ -0,0 +1,116 @@
# 种子数据管理
> 版本: v1.0
> 更新日期: 2026-02-27
> 维护说明: 新增种子数据类型时，在此文档登记
---
## 1. 什么是种子数据
种子数据（Seed Data）是系统正常运行所必需的初始/模板数据。与用户产生的业务数据不同，种子数据：
- 在新环境部署时必须初始化
- 在版本升级时可能需要同步更新
- 跨环境需要保持一致（或有明确的差异策略）
---
## 2. 种子数据清单
### 2.1 Prompt 模板（capability_schema）
| 表 | 数据内容 | 同步策略 | 说明 |
|-----|---------|---------|------|
| `prompt_templates` | Prompt 定义（SSA_BASE_SYSTEM, SSA_INTENT_ANALYZE 等） | 手动同步 | 每个模块的 AI Prompt 模板 |
| `prompt_versions` | 各 Prompt 的版本记录（v1, v2, ACTIVE 标记） | 跟随模板同步 | 支持版本回退 |
**当前 Prompt 列表**（需跨环境同步的关键项）：
| Prompt Key | 所属模块 | 说明 |
|------------|---------|------|
| SSA_BASE_SYSTEM | SSA | SSA 基础系统 Prompt |
| SSA_INTENT_ANALYZE | SSA | SSA 意图分析 Prompt |
| IIT_* | IIT | IIT Agent 系列 Prompt |
| RVW_* | RVW | 稿件审查系列 Prompt |
| AIA_* | AIA | AI 智能问答 Prompt |
| PROTOCOL_* | Protocol | 方案 Agent Prompt |
> 完整 Prompt 清单维护在运营管理后台，此处仅列出关键类别。
### 2.2 SSA 工具库（ssa_schema）
| 表 | 数据内容 | 同步策略 | 说明 |
|-----|---------|---------|------|
| `ssa_tools_library` | 统计工具定义（13 个工具） | SQL INSERT 脚本 | 含 tool_code, params_schema, guardrails 等 |
| `ssa_decision_table` | 统计方法决策表 | SQL INSERT 脚本 | 根据数据特征选择分析方法的规则 |
| `ssa_guardrail_config` | 护栏配置 | SQL INSERT 脚本 | 各工具的前置检验规则 |
| `ssa_param_mapping` | 参数映射 | SQL INSERT 脚本 | LLM 输出到 R 参数的映射 |
| `ssa_interpretation_templates` | 解释模板 | SQL INSERT 脚本 | 统计结果的自然语言解释模板 |
| `ssa_r_code_library` | R 代码模板 | SQL INSERT 脚本 | 13 个统计工具的 R 代码片段 |
### 2.3 Agent 定义（agent_schema）
| 表 | 数据内容 | 同步策略 | 说明 |
|-----|---------|---------|------|
| `agent_definitions` | Agent 类型定义 | 手动同步 | IIT Agent、Protocol Agent 等 |
| `agent_stages` | Agent 运行阶段定义 | 跟随 agent 同步 | |
| `reflexion_rules` | Agent 反思规则 | 跟随 agent 同步 | |
### 2.4 平台基础数据（platform_schema）
| 表 | 数据内容 | 同步策略 | 说明 |
|-----|---------|---------|------|
| `modules` | 系统模块定义 | 代码内置 | AIA, IIT, ASL, SSA, RVW, DC, PKB 等 |
| `permissions` | 权限定义 | 代码内置 | 各模块的操作权限 |
| `tenants` | 初始租户 | 首次部署时创建 | 至少一个默认租户 |
| `users` | 管理员账号 | 首次部署时创建 | 超级管理员 |
---
## 3. 同步操作指南
### 3.1 新环境初始化
```bash
# 1. 运行 Prisma 迁移（创建表结构）
npx prisma migrate deploy
# 2. 运行种子脚本（插入种子数据）
npx prisma db seed
# 或手动执行 SQL 脚本
```
### 3.2 版本升级时同步
```bash
# 1. 检查本次升级是否涉及种子数据变更
# 查看 docs/01-平台基础层/07-数据库/01-Prisma迁移历史与变更日志.md
# 2. 如有新增 Prompt 或工具定义，准备 INSERT 脚本
# 3. 在目标环境执行 INSERT ... ON CONFLICT DO UPDATE
```
### 3.3 Prompt 同步注意事项
- Prompt 数据由**运营管理后台**管理（ADMIN 模块）
- 开发环境的 Prompt 可能带有调试版本，同步到生产前需确认使用 ACTIVE 版本
- 知识库配置（system_knowledge_bases）跟随 Prompt 同步
---
## 4. 待建设项
| 项目 | 优先级 | 说明 |
|------|--------|------|
| 自动化 seed 脚本 | 高 | 将关键种子数据编写为 `prisma/seed.ts`，支持 `npx prisma db seed` |
| Prompt 导出/导入工具 | 中 | 从运营管理后台导出 JSON，在目标环境导入 |
| SSA 工具库 seed SQL | 中 | 将 13 个工具的定义整理为标准 INSERT 脚本 |
---
## 5. 更新日志
| 日期 | 操作人 | 变更 |
|------|--------|------|
| 2026-02-27 | AI 助手 | 初始化文档，梳理种子数据类型和同步策略 |

147
docs/01-平台基础层/07-数据库/05-PostgreSQL扩展与特性.md Normal file
View File

@@ -0,0 +1,147 @@
# PostgreSQL 扩展与特性
> 版本: v1.0
> 更新日期: 2026-02-27
> 维护说明: 新增扩展或变更配置时更新此文档
---
## 1. 扩展总览
| 扩展 | 版本 | 用途 | 安装方式 | 依赖模块 |
|------|------|------|---------|---------|
| **pgvector** (vector) | 0.8.1 | 向量存储与相似度检索 | Docker 镜像内置 | EKB, IIT, SSA |
| **pg_bigm** | 1.2 | 中文/日文双字节全文检索 | Docker 镜像内置 | EKB |
| **plpgsql** | 1.0 | PostgreSQL 过程语言 | 系统内置 | 全局 |
---
## 2. pgvector — 向量搜索
### 2.1 基本信息
- **Docker 镜像**: `pgvector/pgvector:pg15`（本地开发基础镜像）
- **用途**: 存储文本 embedding 向量，支持语义相似度检索
- **算法**: 支持 L2 距离、内积、余弦相似度
### 2.2 使用表
| Schema | 表 | 列 | 维度 | 模型 | 用途 |
|--------|-----|-----|------|------|------|
| `ekb_schema` | `ekb_chunk` | `embedding` | 1024 | 通义千问 Embedding | 企业知识库 RAG 检索 |
| `iit_schema` | `conversation_history` | `embedding` | 1536 | OpenAI ada-002 | IIT 对话历史语义搜索 |
| `ssa_schema` | `ssa_tools_library` | `embedding` | 1024 | 通义千问 Embedding | SSA 工具语义匹配 |
### 2.3 Prisma 中的声明方式
pgvector 在 Prisma 中通过 `Unsupported` 类型声明：
```prisma
embedding Unsupported("vector(1024)")?
```
> ⚠️ 已知限制：Prisma diff 引擎无法正确比较 `Unsupported` 类型，每次 diff 会产生假变更。详见 `03-技术债务追踪.md` TD-004。
### 2.4 索引建议
对于高频检索的向量列，建议创建 HNSW 索引：
```sql
CREATE INDEX idx_ekb_chunk_embedding ON ekb_schema.ekb_chunk
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
```
当前状态：暂未创建向量索引，数据量较小时顺序扫描即可满足性能要求。
---
## 3. pg_bigm — 中文全文检索
### 3.1 基本信息
- **用途**: 基于双字节 gram 的模糊搜索，特别适合中文、日文
- **优势**: 无需分词器，开箱即用，支持 LIKE '%关键词%' 加速
### 3.2 使用场景
| Schema | 表 | 列 | 用途 |
|--------|-----|-----|------|
| `ekb_schema` | `ekb_chunk` | `content` | 知识库文本块的关键词搜索 |
### 3.3 索引创建示例
```sql
CREATE INDEX idx_ekb_chunk_content_bigm ON ekb_schema.ekb_chunk
USING gin (content gin_bigm_ops);
```
> 详细安装指南见 `docs/02-通用能力层/03-RAG引擎/06-pg_bigm安装指南.md`
---
## 4. pg-boss — PostgreSQL 原生任务队列
### 4.1 基本信息
- **类型**: Node.js 库（非 PostgreSQL 扩展），利用 PostgreSQL 实现任务队列
- **表位置**: `platform_schema` 下的 5 张表（job, job_common, queue, schedule, subscription）
- **用途**: 异步任务处理，替代 Redis + BullMQ
### 4.2 核心特性
| 特性 | 说明 |
|------|------|
| 延迟任务 | 支持定时执行 |
| 重试机制 | 失败自动重试，支持配置重试次数和退避策略 |
| 优先级 | 支持任务优先级 |
| 死信队列 | 超过重试次数的任务进入死信队列 |
| 定时调度 | 通过 schedule 表支持 cron 表达式 |
### 4.3 使用模块
| 模块 | 用途 |
|------|------|
| ASL | 文献筛选批处理、全文提取分发 |
| PKB | 文档批处理任务 |
| IIT | 定时质控任务（cron） |
> 详细运维指南见 `docs/07-运维文档/01-PgBoss队列监控与维护.md`
> 架构设计见 `docs/02-通用能力层/Postgres-Only异步任务处理指南.md`
---
## 5. Docker 镜像配置
### 5.1 本地开发 (docker-compose.yml)
```yaml
services:
postgres:
image: pgvector/pgvector:pg15 # 内含 pgvector 扩展
container_name: ai-clinical-postgres
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres123
POSTGRES_DB: ai_clinical_research
ports:
- "5432:5432"
volumes:
- pgdata:/var/lib/postgresql/data
```
> pg_bigm 需在 Docker 构建时额外安装，见项目根目录的 Docker 配置。
### 5.2 阿里云 RDS
- **实例类型**: RDS PostgreSQL 15 基础版
- **扩展管理**: 通过 RDS 控制台 → 插件管理启用
- **已启用**: pgvector, pg_bigm
---
## 6. 更新日志
| 日期 | 操作人 | 变更 |
|------|--------|------|
| 2026-02-27 | AI 助手 | 初始化文档，记录 3 个扩展 + pg-boss 特性 |