AIclinicalresearch/docs/03-业务模块/ADMIN-运营管理端/04-开发计划/02-Prompt管理系统开发计划.md

Prompt管理系统开发计划

版本： v1.2
创建日期： 2026-01-11
更新日期： 2026-01-12
优先级： P0（核心通用能力）
状态： ✅ Phase 3.5.1-3.5.5 全部完成（100%）
预计工期： 7个工作日
实际完成： Day 1-7 已完成（2026-01-12）

---

🎯 快速导航（2026-01-11更新）

✅ 已完成（Phase 3.5.1 - 3.5.5）

阶段	核心产出	文件位置	完成日期
3.5.1 基础设施	capability_schema、表结构、权限、迁移	backend/prisma/schema.prisma	2026-01-11
3.5.2 核心服务	PromptService（灰度、渲染、变量校验）	backend/src/common/prompt/	2026-01-11
3.5.3 管理API	8个RESTful接口	backend/src/common/prompt/prompt.routes.ts	2026-01-11
3.5.4 前端界面	管理端架构、Prompt列表、编辑器	frontend-v2/src/pages/admin/	2026-01-11
3.5.5 业务集成	RVW模块集成、认证规范化	backend/src/modules/rvw/	2026-01-12 ✅

🆕 Phase 3.5.5 完成内容（2026-01-12）

RVW 模块集成：

• ✅ editorialService.ts - 集成 PromptService，移除文件读取
• ✅ methodologyService.ts - 集成 PromptService，移除文件读取
• ✅ reviewWorker.ts - 传递 userId 支持灰度预览
• ✅ 修复 ReviewTask 外键约束（跨 schema 问题）

全模块认证规范化：

• ✅ RVW/PKB/ASL/DC 模块添加 authenticate 中间件
• ✅ 统一使用 request.user?.userId，移除所有 MOCK_USER_ID
• ✅ 前端统一使用 apiClient（axios + JWT interceptor）
• ✅ 创建 docs/04-开发规范/10-模块认证规范.md

界面优化：

• ✅ Prompt 列表模块列显示中文名称
• ✅ 版本历史增强（查看内容、回滚功能）

---

📋 目录

1. 项目概述
2. 需求确认
3. 技术架构
4. 开发计划
5. 数据迁移计划
6. 权限设计
7. 测试计划
8. 风险与应对

---

1. 项目概述

1.1 项目目标

构建一个生产环境灰度预览系统，允许专业人员（Prompt工程师、临床专家）在生产环境安全调试AI Prompt，实现：

• ✅ Prompt 与代码分离（数据库存储）
• ✅ 版本管理与回滚能力
• ✅ 灰度预览（调试者看DRAFT，用户看ACTIVE）
• ✅ 模块级调试范围控制
• ✅ 权限细分（编辑/发布分离）

1.2 核心价值

痛点	解决方案
测试环境无法模拟真实数据	生产环境灰度预览
每次调整需改代码→部署（5分钟）	数据库动态配置，秒级生效
临床专家无法参与调试	RBAC + 友好管理界面
发布后无法回滚	版本历史 + 一键回滚

1.3 涉及模块优先级

优先级	模块	Prompt数量	复杂度	状态
🔴 P0	RVW	4个	⭐⭐	首批接入
🟡 P1	ASL	8个+	⭐⭐⭐⭐⭐	二期
🟡 P1	DC	5个+	⭐⭐⭐⭐	二期
🟢 P2	PKB	3个	⭐⭐⭐	三期
🟢 P2	IIT	3个	⭐⭐⭐⭐	三期
🔵 P3	AIA	10个智能体	⭐⭐⭐	待开发模块

---

2. 需求确认

2.1 已确认需求

需求项	确认结果
优先接入模块	✅ RVW 模块先行，走通后扩展
权限细分	✅ PROMPT_ENGINEER 只能编辑，SUPER_ADMIN 才能发布
初始数据迁移	✅ 自动迁移现有文件Prompt到数据库
调试范围	✅ 可指定模块（如只调试RVW，不影响ASL）
AIA智能体	✅ 预计10个智能体，未来通过Prompt管理

2.2 系统现状

现有Prompt存储方式：

backend/prompts/
├── review_editorial_system.txt      # RVW - 稿约规范性评估
├── review_methodology_system.txt    # RVW - 方法学评估
├── topic_evaluation_system.txt      # RVW - 选题评估（System）
├── topic_evaluation_user.txt        # RVW - 选题评估（User）
└── asl/
    └── screening/
        ├── v1.0.0-mvp.txt
        ├── v1.1.0-lenient.txt
        ├── v1.1.0-standard.txt
        └── v1.1.0-strict.txt

现有调用方式：

// 当前：从文件读取
const systemPrompt = await fs.readFile(PROMPT_PATH, 'utf-8');

// 目标：从PromptService获取
const systemPrompt = await promptService.get('RVW_EDITORIAL', {}, userId);

---

3. 技术架构

3.1 整体架构图

┌─────────────────────────────────────────────────────────────────┐
│                      运营管理端（前端）                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ Prompt列表   │  │ Prompt编辑器 │  │ 🔴 调试开关（可选模块） │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└───────────────────────────┬─────────────────────────────────────┘
                            │ API调用
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   后端 API Layer                                 │
│  /api/admin/prompts      - 管理接口（需认证+权限）               │
│  /api/admin/prompts/debug - 调试模式开关                         │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   PromptService（核心）                          │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────────┐   │
│  │ debugUsers    │  │ activeCache   │  │ moduleDebugMap    │   │
│  │ Map<userId,   │  │ Map<code,     │  │ Map<userId,       │   │
│  │   Set<module>>│  │   content>    │  │   Set<module>>    │   │
│  └───────────────┘  └───────────────┘  └───────────────────┘   │
│                                                                 │
│  get(code, variables, userId) → 自动灰度路由                     │
│  setDebugMode(userId, modules, enabled) → 模块级调试            │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│               PostgreSQL (capability_schema)                     │
│  ┌─────────────────────┐  ┌─────────────────────────────────┐  │
│  │ prompt_templates    │  │ prompt_versions                  │  │
│  │ - code (唯一标识)   │  │ - status: DRAFT/ACTIVE/ARCHIVED │  │
│  │ - module (模块)     │  │ - content (Prompt内容)          │  │
│  │ - variables         │  │ - model_config (模型参数)       │  │
│  └─────────────────────┘  └─────────────────────────────────┘  │
│                                                                 │
│  LISTEN/NOTIFY prompt_update → 多实例缓存同步                    │
└─────────────────────────────────────────────────────────────────┘

3.2 核心数据流

用户请求 → 业务模块 → promptService.get(code, vars, userId)
                              │
                              ▼
                    ┌─────────────────────┐
                    │ 检查 debugUsers      │
                    │ + moduleDebugMap    │
                    └──────────┬──────────┘
                               │
              ┌────────────────┴────────────────┐
              │                                 │
              ▼                                 ▼
    ┌─────────────────┐               ┌─────────────────┐
    │ 调试者 + 模块匹配 │               │ 普通用户/不匹配  │
    └────────┬────────┘               └────────┬────────┘
             │                                  │
             ▼                                  ▼
    ┌─────────────────┐               ┌─────────────────┐
    │ 查询 DRAFT 版本  │               │ 查询 ACTIVE 缓存 │
    └────────┬────────┘               └────────┬────────┘
             │                                  │
             ▼                                  ▼
    ┌─────────────────┐               ┌─────────────────┐
    │ 渲染变量返回     │               │ 缓存未命中则查DB │
    └─────────────────┘               └────────┬────────┘
                                               │
                                               ▼
                                      ┌─────────────────┐
                                      │ 兜底：硬编码     │
                                      │ FALLBACK_PROMPTS│
                                      └─────────────────┘

3.3 模块级调试设计

// 调试模式数据结构
interface DebugState {
  userId: string;
  modules: Set<string>;  // 'RVW', 'ASL', 'DC', 'ALL'
  enabledAt: Date;
}

// 开启调试：只调试RVW模块
await promptService.setDebugMode(userId, ['RVW'], true);

// 获取Prompt时自动判断
const prompt = await promptService.get('RVW_EDITORIAL', vars, userId);
// → 返回DRAFT（因为userId开启了RVW调试）

const prompt2 = await promptService.get('ASL_SCREENING', vars, userId);
// → 返回ACTIVE（因为userId未开启ASL调试）

3.4 变量校验机制（Variable Validation）🆕

问题场景： 编辑器里写了 {{title}}，但 variables 字段没配置 title，调试时报错。

解决方案：

// 后端：保存时自动提取变量
function extractVariables(content: string): string[] {
  const regex = /\{\{(\w+)\}\}/g;
  const variables = new Set<string>();
  let match;
  while ((match = regex.exec(content)) !== null) {
    variables.add(match[1]);
  }
  return Array.from(variables);
}

// 保存草稿时自动更新 variables 字段
async saveDraft(templateId: number, content: string, ...) {
  const extractedVars = extractVariables(content);
  
  // 自动更新模板的 variables 字段
  await prisma.prompt_templates.update({
    where: { id: templateId },
    data: { variables: extractedVars },
  });
  
  // 创建新版本
  await prisma.prompt_versions.create({
    data: { template_id: templateId, content, ... }
  });
}

前端：调试界面自动生成变量输入表单

// PromptDebugPanel.tsx
const PromptDebugPanel = ({ variables }: { variables: string[] }) => {
  const [values, setValues] = useState<Record<string, string>>({});
  
  return (
    <div className="debug-panel">
      <h4>📝 调试变量</h4>
      {variables.map(varName => (
        <Form.Item key={varName} label={varName}>
          <Input 
            placeholder={`输入 ${varName} 的值`}
            value={values[varName]}
            onChange={e => setValues({ ...values, [varName]: e.target.value })}
          />
        </Form.Item>
      ))}
      <Button type="primary" onClick={() => onTest(values)}>
        🧪 测试渲染
      </Button>
    </div>
  );
};

校验时机：

时机	动作
保存草稿时	自动提取变量，更新 variables 字段
发布前	警告：如果 DRAFT 的变量与 ACTIVE 不同，提示"变量已变更"
调试时	前端根据 variables 自动生成输入表单
渲染时	校验提供的变量是否完整，缺失则抛出明确错误

---

4. 开发计划

4.1 总体时间线

Day 1-2: 基础设施搭建
Day 3:   PromptService 核心实现
Day 4:   管理API开发
Day 5-6: 前端管理界面
Day 7:   RVW模块集成 + 端到端测试

4.2 详细任务清单

Phase 3.5.1: 基础设施（Day 1-2）

Day 1: 数据库准备

• 创建 capability_schema Schema

  CREATE SCHEMA IF NOT EXISTS capability_schema;
  

• 更新 schema.prisma 添加 Prompt 相关模型

  • PromptStatus 枚举
  • prompt_templates 模型
  • prompt_versions 模型

• 执行 prisma db push 创建表

• 添加 Prompt 权限到 permissions 表

  INSERT INTO platform_schema.permissions (code, name, description, module) VALUES
  ('prompt:view', '查看Prompt', '查看Prompt模板列表和详情', 'admin'),
  ('prompt:edit', '编辑Prompt', '创建和修改Prompt草稿', 'admin'),
  ('prompt:debug', '调试Prompt', '开启调试模式', 'admin'),
  ('prompt:publish', '发布Prompt', '将草稿发布为正式版', 'admin');
  

• 更新 role_permissions 表

  • SUPER_ADMIN: prompt:view, prompt:edit, prompt:debug, prompt:publish
  • PROMPT_ENGINEER: prompt:view, prompt:edit, prompt:debug（无publish）

Day 2: 数据迁移（RVW模块）

• 编写迁移脚本 scripts/migrate-prompts.ts

• 迁移 RVW 模块 Prompt

  文件	Code	名称
  review_editorial_system.txt	RVW_EDITORIAL	稿约规范性评估
  review_methodology_system.txt	RVW_METHODOLOGY	方法学评估

  注：topic_evaluation_* 是"选题评估"功能，不属于RVW审稿模块

• 验证迁移数据完整性

---

Phase 3.5.2: PromptService 核心（Day 3）

• 创建文件结构

  backend/src/common/capabilities/prompt/
  ├── prompt.service.ts      # 核心服务
  ├── prompt.types.ts        # 类型定义
  ├── prompt.fallbacks.ts    # 兜底Prompt
  └── index.ts               # 导出
  

• 实现 PromptService 类

  • get(code, variables, userId) - 核心获取方法
  • setDebugMode(userId, modules, enabled) - 模块级调试开关
  • isDebugging(userId, module) - 检查调试状态
  • render(template, variables) - Handlebars渲染
  • getActiveVersion(code) - 获取ACTIVE版本（带缓存）
  • getDraftVersion(code) - 获取DRAFT版本
  • getFallback(code) - 获取兜底Prompt
  • extractVariables(content) - 🆕 从内容提取变量名
  • validateVariables(content, providedVars) - 🆕 校验变量完整性

• 实现热更新机制

  • initHotReload() - 监听 LISTEN/NOTIFY
  • 收到通知后清空 activeCache

• 编写兜底Prompt（prompt.fallbacks.ts）

  export const FALLBACK_PROMPTS: Record<string, string> = {
    'RVW_EDITORIAL': `你是一位资深的学术期刊编辑...`,
    'RVW_METHODOLOGY': `你是一位方法学专家...`,
    // ...
  };
  

---

Phase 3.5.3: 管理API（Day 4）

• 创建文件结构

  backend/src/modules/admin/prompt/
  ├── prompt.controller.ts   # 控制器
  ├── prompt.routes.ts       # 路由定义
  └── prompt.schema.ts       # 请求/响应Schema
  

• 实现 API 接口

方法	路径	权限	功能
GET	/api/admin/prompts	prompt:view	获取模板列表（支持模块过滤）
GET	/api/admin/prompts/:id	prompt:view	获取模板详情+版本历史
POST	/api/admin/prompts	prompt:edit	创建新模板
POST	/api/admin/prompts/:id/draft	prompt:edit	保存草稿
POST	/api/admin/prompts/:id/publish	prompt:publish	发布（DRAFT→ACTIVE）
POST	/api/admin/prompts/:id/rollback	prompt:publish	回滚到指定版本
POST	/api/admin/prompts/debug	prompt:debug	开关调试模式
GET	/api/admin/prompts/debug/status	prompt:debug	获取当前调试状态

• 添加权限中间件检查

• 注册路由到 index.ts

---

Phase 3.5.4: 前端管理界面（Day 5-6）

Day 5: 列表页 + 调试开关

• 创建文件结构

  frontend-v2/src/modules/admin/prompt/
  ├── pages/
  │   ├── PromptListPage.tsx      # 列表页
  │   └── PromptEditorPage.tsx    # 编辑页
  ├── components/
  │   ├── PromptDebugSwitch.tsx   # 调试开关
  │   ├── PromptVersionHistory.tsx # 版本历史
  │   └── PromptPreview.tsx       # 预览组件
  ├── hooks/
  │   └── usePromptApi.ts         # API调用
  └── index.ts
  

• PromptListPage.tsx

  • 模板列表展示
  • 模块筛选（RVW/ASL/DC/...）
  • 状态筛选（有草稿/无草稿）
  • 搜索功能

• PromptDebugSwitch.tsx

  • 权限检查（仅 prompt:debug 可见）
  • 模块选择器（可多选）
  • 开关状态
  • 开启后显示警告条

Day 6: 编辑器页面

• PromptEditorPage.tsx

  • 基本信息展示（code, name, module）
  • Prompt 内容编辑器（Monaco Editor / CodeMirror）
  • 变量自动提取：编辑时实时扫描 {{xxx}}，显示变量列表 🆕
  • modelConfig 编辑（JSON格式）
  • 保存草稿按钮（自动更新 variables 字段）
  • 发布按钮（权限控制：无 prompt:publish 则禁用）
  • 变量变更警告：发布前检查变量是否与 ACTIVE 版本不同 🆕
  • 版本历史面板
  • 变更说明输入（changelog）

• PromptDebugPanel.tsx 🆕

  • 根据 variables 自动生成输入表单
  • "测试渲染"按钮：预览变量替换后的效果
  • 渲染结果展示

• PromptVersionHistory.tsx

  • 版本列表
  • 版本对比
  • 一键回滚

• 集成到导航

  • 运营管理端侧边栏添加入口
  • 顶部栏添加调试开关

---

Phase 3.5.5: RVW模块集成（Day 7）

• 改造 editorialService.ts

  // Before
  const systemPrompt = await fs.readFile(PROMPT_PATH, 'utf-8');
  
  // After
  const systemPrompt = await promptService.get('RVW_EDITORIAL', {}, userId);
  

• 改造 methodologyService.ts

• 改造其他 RVW 相关服务

• 端到端测试

  • 普通用户：使用 ACTIVE 版本
  • 调试者（开启RVW调试）：使用 DRAFT 版本
  • 调试者（未开启RVW调试）：使用 ACTIVE 版本
  • 发布流程：DRAFT → ACTIVE
  • 回滚流程

---

4.3 任务跟踪表

ID	任务	负责人	状态	完成日期
3.5.1.1	创建 capability_schema	AI	✅ 已完成	2026-01-11
3.5.1.2	更新 schema.prisma	AI	✅ 已完成	2026-01-11
3.5.1.3	添加权限数据	AI	✅ 已完成	2026-01-11
3.5.1.4	编写迁移脚本	AI	✅ 已完成	2026-01-11
3.5.1.5	迁移 RVW Prompt	AI	✅ 已完成	2026-01-11
3.5.2.1	实现 PromptService	AI	✅ 已完成	2026-01-11
3.5.2.2	实现热更新	-	⏸️ 暂缓（手动invalidate）	-
3.5.2.3	编写兜底Prompt	AI	✅ 已完成	2026-01-11
3.5.2.4	实现变量提取 extractVariables() 🆕	AI	✅ 已完成	2026-01-11
3.5.2.5	实现变量校验 validateVariables() 🆕	AI	✅ 已完成	2026-01-11
3.5.3.1	实现管理API	AI	✅ 已完成	2026-01-11
3.5.3.2	添加权限检查	-	⏸️ 暂缓（注释掉）	-
3.5.4.0	搭建管理端基础架构	AI	✅ 已完成	2026-01-11
3.5.4.1	实现列表页	AI	✅ 已完成	2026-01-11
3.5.4.2	实现调试开关	AI	✅ 已完成	2026-01-11
3.5.4.3	实现编辑器（CodeMirror 6 简化版）	AI	✅ 已完成	2026-01-11
3.5.4.4	实现调试面板（变量输入表单）🆕	AI	✅ 已完成	2026-01-11
3.5.5.1	改造 RVW 服务	-	⏳ 待开始	-
3.5.5.2	端到端测试	-	⏳ 待开始	-

---

5. 数据迁移计划

5.1 RVW模块迁移（第一批）

源文件	Code	名称	模块	状态
review_editorial_system.txt	RVW_EDITORIAL	稿约规范性评估	RVW	ACTIVE
review_methodology_system.txt	RVW_METHODOLOGY	方法学评估	RVW	ACTIVE

注：topic_evaluation_* 是"选题评估"功能，不属于RVW审稿模块，未迁移

5.2 ASL模块迁移（第二批，待定）

源文件	Code	名称	模块
v1.1.0-standard.txt	ASL_SCREENING_STANDARD	标题摘要筛选(标准)	ASL
v1.1.0-strict.txt	ASL_SCREENING_STRICT	标题摘要筛选(严格)	ASL
v1.1.0-lenient.txt	ASL_SCREENING_LENIENT	标题摘要筛选(宽松)	ASL
fulltext-screening/system_prompt.md	ASL_FULLTEXT_SYSTEM	全文筛选(System)	ASL
fulltext-screening/user_prompt_template.md	ASL_FULLTEXT_USER	全文筛选(User)	ASL

5.3 其他模块迁移（第三批，待定）

模块	预计Prompt数量	优先级
DC	5+	P1
PKB	3	P2
IIT	3	P2
AIA	10（智能体）	P3（待开发）

---

6. 权限设计

6.1 权限定义

权限 Code	描述	风险等级
prompt:view	查看Prompt列表和详情	低
prompt:edit	创建/修改DRAFT版本	中
prompt:debug	开启调试模式	中
prompt:publish	发布DRAFT→ACTIVE	高

6.2 角色权限分配

角色	prompt:view	prompt:edit	prompt:debug	prompt:publish
SUPER_ADMIN	✅	✅	✅	✅
PROMPT_ENGINEER	✅	✅	✅	❌
HOSPITAL_ADMIN	❌	❌	❌	❌
PHARMA_ADMIN	❌	❌	❌	❌
USER	❌	❌	❌	❌

6.3 典型工作流

1. Prompt工程师 登录系统
2. 进入 Prompt 管理页面，找到 RVW_EDITORIAL
3. 修改内容，点击"保存草稿"
4. 开启调试模式（选择 RVW 模块）
5. 切换到 RVW 业务页面，上传测试稿件
6. 验证效果，如果OK：
   - 关闭调试模式
   - 通知 超级管理员 审核
7. 超级管理员 登录，查看草稿，点击"发布"
8. 新版本生效

---

7. 测试计划

7.1 单元测试

测试项	覆盖内容
PromptService.get()	灰度路由逻辑
PromptService.render()	变量渲染
PromptService.getFallback()	兜底逻辑

7.2 集成测试

测试场景	预期结果
普通用户访问	返回 ACTIVE 版本
调试者（开启RVW调试）访问 RVW Prompt	返回 DRAFT 版本
调试者（开启RVW调试）访问 ASL Prompt	返回 ACTIVE 版本
调试者（未开启调试）访问	返回 ACTIVE 版本
无 ACTIVE 版本时	返回 FALLBACK
数据库不可用时	返回 FALLBACK

7.3 端到端测试

测试流程	步骤
完整编辑流程	登录→查看列表→编辑→保存草稿→开启调试→验证→发布
回滚流程	发布错误版本→回滚→验证
权限测试	PROMPT_ENGINEER 无法发布

---

8. 风险与应对

8.1 技术风险

风险	影响	概率	应对策略
capability_schema 创建失败	系统无法启动	低	独立SQL脚本，可手动修复
数据库查询超时	用户请求变慢	低	使用缓存 + 兜底
多实例缓存不一致	用户体验不一致	中	LISTEN/NOTIFY 同步
调试者误发布错误Prompt	线上用户受影响	中	权限分离 + 版本回滚

8.2 业务风险

风险	影响	应对策略
Prompt 改动导致AI效果下降	业务受影响	灰度验证 + 快速回滚
权限管理混乱	误操作	严格RBAC + 审计日志

8.3 兜底策略

// 三级兜底机制
async get(code: string, variables: any, userId: string): Promise<string> {
  try {
    // Level 1: 正常流程
    return await this.getNormalFlow(code, variables, userId);
  } catch (dbError) {
    logger.warn('DB query failed, trying cache', { code, error: dbError });
    
    // Level 2: 使用缓存
    const cached = this.activeCache.get(code);
    if (cached) {
      return this.render(cached, variables);
    }
    
    // Level 3: 硬编码兜底
    logger.error('Cache miss, using fallback', { code });
    return this.render(this.getFallback(code), variables);
  }
}

---

📎 附录

A. 相关文档

• Prompt管理系统与灰度预览设计方案
• Prompt管理系统快速参考
• Prompt管理后台设计

B. 代码位置

类型	路径
后端服务	backend/src/common/capabilities/prompt/
后端API	backend/src/modules/admin/prompt/
前端页面	frontend-v2/src/modules/admin/prompt/
数据库Schema	backend/prisma/schema.prisma
迁移脚本	backend/scripts/migrate-prompts.ts

C. 命名规范

Prompt Code 命名规则：

{MODULE}_{FUNCTION}_{ROLE}

示例：
- RVW_EDITORIAL           # RVW模块-稿约规范性评估
- RVW_METHODOLOGY         # RVW模块-方法学评估
- ASL_SCREENING_STANDARD  # ASL模块-标准筛选
- AIA_AGENT_STATISTICIAN  # AIA模块-统计师智能体

---

最后更新：2026-01-11

🚀 准备好开始了吗？从 Phase 3.5.1 第一个任务开始！