# Prompt管理系统开发计�?
> **版本�?* v1.2  
> **创建日期�?* 2026-01-11  
> **更新日期�?* 2026-01-12  
> **优先级：** P0（核心通用能力�? 
> **状态：** �?Phase 3.5.1-3.5.5 全部完成�?00%�? 
> **预计工期�?* 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 完成内容�?026-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. [项目概述](#1-项目概述)
2. [需求确认](#2-需求确�?
3. [技术架构](#3-技术架�?
4. [开发计划](#4-开发计�?
5. [数据迁移计划](#5-数据迁移计划)
6. [权限设计](#6-权限设计)
7. [测试计划](#7-测试计划)
8. [风险与应对](#8-风险与应�?

---

## 1. 项目概述

### 1.1 项目目标

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

- �?Prompt 与代码分离（数据库存储）
- �?版本管理与回滚能�?- �?灰度预览（调试者看DRAFT，用户看ACTIVE�?- �?模块级调试范围控�?- �?权限细分（编�?发布分离�?
### 1.2 核心价�?
| 痛点 | 解决方案 |
|------|---------|
| 测试环境无法模拟真实数据 | 生产环境灰度预览 |
| 每次调整需改代码→部署�?分钟�?| 数据库动态配置，秒级生效 |
| 临床专家无法参与调试 | 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
```

**现有调用方式�?*

```typescript
// 当前：从文件读取
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 模块级调试设�?
```typescript
// 调试模式数据结构
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`，调试时报错�?
**解决方案�?*

```typescript
// 后端：保存时自动提取变量
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, ... }
  });
}
```

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

```tsx
// 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
  ```sql
  CREATE SCHEMA IF NOT EXISTS capability_schema;
  ```

- [ ] 更新 `schema.prisma` 添加 Prompt 相关模型
  - [ ] `PromptStatus` 枚举
  - [ ] `prompt_templates` 模型
  - [ ] `prompt_versions` 模型

- [ ] 执行 `prisma db push` 创建�?
- [ ] 添加 Prompt 权限�?`permissions` �?  ```sql
  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`�?  ```typescript
  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`
  ```typescript
  // 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 兜底策略

```typescript
// 三级兜底机制
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管理系统与灰度预览设计方案](../02-技术设�?02-通用能力层_03-Prompt管理系统与灰度预览设计方�?md)
- [Prompt管理系统快速参考](../02-技术设�?03-Prompt管理系统快速参�?md)
- [Prompt管理后台设计](../02-技术设�?Prompt管理后台设计.md)

### 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 第一个任务开始！**