feat(admin): Complete Phase 3.5.1-3.5.4 Prompt Management System (83%)
Summary: - Implement Prompt management infrastructure and core services - Build admin portal frontend with light theme - Integrate CodeMirror 6 editor for non-technical users Phase 3.5.1: Infrastructure Setup - Create capability_schema for Prompt storage - Add prompt_templates and prompt_versions tables - Add prompt:view/edit/debug/publish permissions - Migrate RVW prompts to database (RVW_EDITORIAL, RVW_METHODOLOGY) Phase 3.5.2: PromptService Core - Implement gray preview logic (DRAFT for debuggers, ACTIVE for users) - Module-level debug control (setDebugMode) - Handlebars template rendering - Variable extraction and validation (extractVariables, validateVariables) - Three-level disaster recovery (database -> cache -> hardcoded fallback) Phase 3.5.3: Management API - 8 RESTful endpoints (/api/admin/prompts/*) - Permission control (PROMPT_ENGINEER can edit, SUPER_ADMIN can publish) Phase 3.5.4: Frontend Management UI - Build admin portal architecture (AdminLayout, OrgLayout) - Add route system (/admin/*, /org/*) - Implement PromptListPage (filter, search, debug switch) - Implement PromptEditor (CodeMirror 6 simplified for clinical users) - Implement PromptEditorPage (edit, save, publish, test, version history) Technical Details: - Backend: 6 files, ~2044 lines (prompt.service.ts 596 lines) - Frontend: 9 files, ~1735 lines (PromptEditorPage.tsx 399 lines) - CodeMirror 6: Line numbers, auto-wrap, variable highlight, search, undo/redo - Chinese-friendly: 15px font, 1.8 line-height, system fonts Next Step: Phase 3.5.5 - Integrate RVW module with PromptService Tested: Backend API tests passed (8/8), Frontend pending user testing Status: Ready for Phase 3.5.5 RVW integration
This commit is contained in:
320
docs/04-开发规范/09-数据库开发规范.md
Normal file
320
docs/04-开发规范/09-数据库开发规范.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# 数据库开发规范
|
||||
|
||||
> 版本: v1.0
|
||||
> 更新日期: 2026-01-11
|
||||
> 编写背景: 2026-01-11 数据库事故后总结
|
||||
|
||||
---
|
||||
|
||||
## 1. 核心原则
|
||||
|
||||
### 1.1 安全第一
|
||||
|
||||
```
|
||||
⚠️ 黄金法则：任何数据库操作前，必须先备份！
|
||||
```
|
||||
|
||||
### 1.2 禁止使用的危险命令
|
||||
|
||||
| 命令 | 危险等级 | 说明 |
|
||||
|------|----------|------|
|
||||
| `prisma db push --force-reset` | 🔴 **极高** | 会删除所有数据和非Prisma管理的对象 |
|
||||
| `prisma migrate reset` | 🔴 **极高** | 重置整个数据库 |
|
||||
| `DROP DATABASE` | 🔴 **极高** | 删除整个数据库 |
|
||||
| `TRUNCATE TABLE` | 🟠 高 | 清空表数据 |
|
||||
|
||||
### 1.3 推荐的安全命令
|
||||
|
||||
| 命令 | 用途 | 安全性 |
|
||||
|------|------|--------|
|
||||
| `prisma migrate dev` | 开发环境迁移 | ✅ 安全 |
|
||||
| `prisma migrate deploy` | 生产环境迁移 | ✅ 安全 |
|
||||
| `prisma db push` (无 --force-reset) | 同步schema到数据库 | ⚠️ 谨慎使用 |
|
||||
| `prisma generate` | 生成客户端 | ✅ 安全 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 数据库备份规范
|
||||
|
||||
### 2.1 备份命令
|
||||
|
||||
```bash
|
||||
# 通过 Docker 备份（推荐）
|
||||
docker exec ai-clinical-postgres pg_dump -U postgres -d ai_clinical_research > backup_$(date +%Y%m%d_%H%M%S).sql
|
||||
|
||||
# PowerShell 版本
|
||||
$timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
|
||||
docker exec ai-clinical-postgres pg_dump -U postgres -d ai_clinical_research > "backup_$timestamp.sql"
|
||||
```
|
||||
|
||||
### 2.2 备份时机
|
||||
|
||||
| 时机 | 是否必须 |
|
||||
|------|----------|
|
||||
| 执行任何 `prisma migrate` 前 | ✅ 必须 |
|
||||
| 执行 `prisma db push` 前 | ✅ 必须 |
|
||||
| 部署到生产环境前 | ✅ 必须 |
|
||||
| 每日自动备份 | ✅ 推荐 |
|
||||
| 重大功能发布前 | ✅ 必须 |
|
||||
|
||||
### 2.3 备份文件管理
|
||||
|
||||
```
|
||||
AIclinicalresearch/
|
||||
├── backup_20260111_131506.sql # 日期_时间命名
|
||||
├── rds_init_20251224_154529.sql # 历史备份
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Schema 变更流程
|
||||
|
||||
### 3.1 标准流程
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[修改 schema.prisma] --> B[备份数据库]
|
||||
B --> C[运行 prisma migrate dev]
|
||||
C --> D{迁移成功?}
|
||||
D -->|是| E[测试功能]
|
||||
D -->|否| F[从备份恢复]
|
||||
E --> G{测试通过?}
|
||||
G -->|是| H[提交代码]
|
||||
G -->|否| F
|
||||
```
|
||||
|
||||
### 3.2 具体步骤
|
||||
|
||||
```bash
|
||||
# 1. 备份数据库
|
||||
docker exec ai-clinical-postgres pg_dump -U postgres -d ai_clinical_research > backup_before_migration.sql
|
||||
|
||||
# 2. 修改 schema.prisma
|
||||
|
||||
# 3. 创建迁移
|
||||
npx prisma migrate dev --name describe_your_change
|
||||
|
||||
# 4. 检查生成的迁移 SQL
|
||||
cat prisma/migrations/xxx_describe_your_change/migration.sql
|
||||
|
||||
# 5. 测试
|
||||
|
||||
# 6. 如果失败，恢复备份
|
||||
cat backup_before_migration.sql | docker exec -i ai-clinical-postgres psql -U postgres -d ai_clinical_research
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Prisma 与数据库不一致问题
|
||||
|
||||
### 4.1 Prisma 不管理的对象
|
||||
|
||||
以下数据库对象不在 `schema.prisma` 中定义，需要单独管理：
|
||||
|
||||
| 对象 | 类型 | 来源 | 恢复脚本 |
|
||||
|------|------|------|----------|
|
||||
| `platform_schema.job_common` | 表 | pg-boss 运行时创建 | `restore_job_common.sql` |
|
||||
| `platform_schema.create_queue()` | 函数 | pg-boss 初始化 | `restore_pgboss_functions.sql` |
|
||||
| `platform_schema.delete_queue()` | 函数 | pg-boss 初始化 | `restore_pgboss_functions.sql` |
|
||||
|
||||
### 4.2 恢复非 Prisma 管理的对象
|
||||
|
||||
```bash
|
||||
# 如果误删了 pg-boss 相关对象，执行：
|
||||
npx prisma db execute --file restore_job_common.sql --schema prisma/schema.prisma
|
||||
npx prisma db execute --file restore_pgboss_functions.sql --schema prisma/schema.prisma
|
||||
```
|
||||
|
||||
### 4.3 检查数据库与 Prisma 一致性
|
||||
|
||||
```bash
|
||||
# 查看数据库中的函数
|
||||
SELECT routine_name FROM information_schema.routines WHERE routine_schema = 'platform_schema';
|
||||
|
||||
# 查看数据库中的表
|
||||
SELECT table_name FROM information_schema.tables WHERE table_schema = 'platform_schema';
|
||||
|
||||
# 对比 schema.prisma 定义
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 多 Schema 架构规范
|
||||
|
||||
### 5.1 Schema 命名规范
|
||||
|
||||
| Schema | 用途 | 示例表 |
|
||||
|--------|------|--------|
|
||||
| `platform_schema` | 平台基础设施 | users, tenants, app_cache |
|
||||
| `admin_schema` | 运营管理 | admin_operation_logs |
|
||||
| `aia_schema` | AI智能问答 | conversations, messages |
|
||||
| `asl_schema` | 文献筛选 | screening_projects, literatures |
|
||||
| `dc_schema` | 数据清洗 | dc_templates, dc_extraction_tasks |
|
||||
| `pkb_schema` | 个人知识库 | knowledge_bases, documents |
|
||||
| `iit_schema` | IIT项目 | projects, audit_logs |
|
||||
| `rvw_schema` | 论文预审 | review_tasks |
|
||||
| `capability_schema` | 通用能力 | prompt_templates |
|
||||
| `public` | 旧数据/兼容 | users (旧), admin_logs |
|
||||
|
||||
### 5.2 表命名规范
|
||||
|
||||
```
|
||||
{schema_name}.{module_prefix}_{entity_name}
|
||||
|
||||
示例：
|
||||
- dc_schema.dc_templates
|
||||
- dc_schema.dc_extraction_tasks
|
||||
- asl_schema.screening_projects
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 外键与数据完整性
|
||||
|
||||
### 6.1 跨 Schema 外键
|
||||
|
||||
```prisma
|
||||
// ✅ 正确：明确指定关系
|
||||
model ReviewTask {
|
||||
userId String @map("user_id")
|
||||
user PublicUser @relation(fields: [userId], references: [id])
|
||||
|
||||
@@schema("rvw_schema")
|
||||
}
|
||||
|
||||
model PublicUser {
|
||||
id String @id
|
||||
reviewTasks ReviewTask[]
|
||||
|
||||
@@schema("public")
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 外键指向检查
|
||||
|
||||
在使用 `prisma db push` 后，检查外键是否正确：
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
tc.table_schema, tc.table_name, kcu.column_name,
|
||||
ccu.table_schema AS foreign_schema, ccu.table_name AS foreign_table
|
||||
FROM information_schema.table_constraints AS tc
|
||||
JOIN information_schema.key_column_usage AS kcu ON tc.constraint_name = kcu.constraint_name
|
||||
JOIN information_schema.constraint_column_usage AS ccu ON ccu.constraint_name = tc.constraint_name
|
||||
WHERE tc.constraint_type = 'FOREIGN KEY';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 事故恢复流程
|
||||
|
||||
### 7.1 误删数据恢复
|
||||
|
||||
```bash
|
||||
# 1. 停止应用
|
||||
# 2. 从备份恢复
|
||||
cat backup_xxx.sql | docker exec -i ai-clinical-postgres psql -U postgres -d ai_clinical_research
|
||||
|
||||
# 3. 验证数据
|
||||
npx tsx verify_system.ts
|
||||
|
||||
# 4. 重启应用
|
||||
```
|
||||
|
||||
### 7.2 Schema 不一致恢复
|
||||
|
||||
```bash
|
||||
# 1. 检查差异
|
||||
npx tsx compare_schema_db.ts
|
||||
|
||||
# 2. 恢复缺失的对象
|
||||
npx prisma db execute --file restore_xxx.sql --schema prisma/schema.prisma
|
||||
|
||||
# 3. 验证
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 开发环境 vs 生产环境
|
||||
|
||||
### 8.1 开发环境
|
||||
|
||||
- 可以使用 `prisma migrate dev`
|
||||
- 可以使用 `prisma db push`（谨慎）
|
||||
- 定期同步生产数据库结构
|
||||
|
||||
### 8.2 生产环境
|
||||
|
||||
- **只能**使用 `prisma migrate deploy`
|
||||
- **禁止**使用任何 `--force` 或 `--reset` 参数
|
||||
- 变更前必须有回滚计划
|
||||
- 必须有最新备份
|
||||
|
||||
---
|
||||
|
||||
## 9. 检查清单
|
||||
|
||||
### 9.1 数据库变更前检查
|
||||
|
||||
- [ ] 已备份数据库
|
||||
- [ ] 已审查 schema.prisma 变更
|
||||
- [ ] 已检查是否影响非 Prisma 管理的对象
|
||||
- [ ] 已准备回滚方案
|
||||
- [ ] 已在开发环境测试
|
||||
|
||||
### 9.2 部署后检查
|
||||
|
||||
- [ ] 应用正常启动
|
||||
- [ ] 数据库连接正常
|
||||
- [ ] pg-boss 队列正常工作
|
||||
- [ ] 核心功能测试通过
|
||||
|
||||
---
|
||||
|
||||
## 10. 常用脚本
|
||||
|
||||
### 10.1 验证脚本位置
|
||||
|
||||
```
|
||||
backend/
|
||||
├── verify_system.ts # 系统完整性验证
|
||||
├── compare_schema_db.ts # Schema与数据库对比
|
||||
├── check_iit_asl_data.ts # 检查模块数据
|
||||
├── restore_job_common.sql # 恢复 job_common 表
|
||||
└── restore_pgboss_functions.sql # 恢复 pg-boss 函数
|
||||
```
|
||||
|
||||
### 10.2 快速验证命令
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
$env:DATABASE_URL="postgresql://postgres:postgres123@localhost:5432/ai_clinical_research"
|
||||
|
||||
# 验证系统
|
||||
npx tsx verify_system.ts
|
||||
|
||||
# 检查数据
|
||||
npx tsx check_iit_asl_data.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附录：事故案例
|
||||
|
||||
### 案例1：2026-01-11 数据库重置事故
|
||||
|
||||
**原因**：使用 `prisma db push --force-reset` 导致非 Prisma 管理的对象丢失
|
||||
|
||||
**影响**：
|
||||
- pg-boss 函数丢失，队列无法注册
|
||||
- job_common 表丢失
|
||||
- 用户数据丢失（已通过 seed 恢复）
|
||||
|
||||
**教训**：
|
||||
1. 永远不要使用 `--force-reset`
|
||||
2. 操作前必须备份
|
||||
3. 了解 Prisma 的管理边界
|
||||
|
||||
详见：`docs/08-项目管理/2026-01-11-数据库事故总结.md`
|
||||
|
||||
Reference in New Issue
Block a user