# 🚀 给新AI助手的快速指南

> **更新时间：** 2026-01-12  
> **当前状态：** ✅ Phase 3.5.5 代码改造已完成，待端到端测试

---

## ⚡ 30秒了解当前状态

```
✅ Phase 3.5.1-3.5.5 代码改造已完成（95%）
⏳ 待完成：端到端测试验证

已完成：
  ✅ 数据库：capability_schema + prompt_templates + prompt_versions
  ✅ 后端：PromptService（596行）+ 8个API接口
  ✅ 前端：管理端架构 + Prompt列表 + 编辑器（CodeMirror 6）
  ✅ 测试：后端单元测试全部通过
  ✅ RVW集成：editorialService + methodologyService 已改造（2026-01-12）

下一步：
  → 启动后端服务测试
  → 端到端测试灰度预览功能
  → 更新完成度文档
```

---

## 📁 关键文件位置

### 核心文件（必读）

| 文件 | 说明 | 行数 |
|------|------|------|
| `backend/src/common/prompt/prompt.service.ts` | PromptService 核心逻辑 | 596 |
| `backend/src/modules/rvw/services/editorialService.ts` | RVW 稿约评估服务 ✅ 已改造 | 83 |
| `backend/src/modules/rvw/services/methodologyService.ts` | RVW 方法学评估服务 ✅ 已改造 | 83 |
| `backend/src/modules/rvw/workers/reviewWorker.ts` | RVW Worker ✅ 已更新传递userId | 193 |
| `frontend-v2/src/pages/admin/PromptEditorPage.tsx` | Prompt 编辑器页面 | 399 |

### 文档（必读）

| 文档 | 内容 |
|------|------|
| `04-开发计划/01-TODO清单（可追踪）.md` | 详细任务清单（79/110 完成）|
| `04-开发计划/02-Prompt管理系统开发计划.md` | 完整开发计划 |
| `00-Phase3.5完成总结.md` | 已完成工作总结 |

---

## 🎯 Phase 3.5.5 任务详解（✅ 代码改造已完成 2026-01-12）

### ✅ 任务 1：改造 editorialService.ts - 已完成

**改造前**（文件读取）
```typescript
const PROMPT_PATH = path.join(__dirname, '../../../../prompts/review_editorial_system.txt');
const prompt = fs.readFileSync(PROMPT_PATH, 'utf-8');
```

**改造后**（PromptService）
```typescript
import { prisma } from '../../../config/database.js';
import { getPromptService } from '../../../common/prompt/index.js';

const promptService = getPromptService(prisma);
const { content: systemPrompt, isDraft } = await promptService.get('RVW_EDITORIAL', {}, { userId });

if (isDraft) {
  logger.info('[RVW:Editorial] 使用 DRAFT 版本 Prompt（调试模式）', { userId });
}
```

### ✅ 任务 2：改造 methodologyService.ts - 已完成

**改造后**
```typescript
const { content: systemPrompt, isDraft } = await promptService.get('RVW_METHODOLOGY', {}, { userId });
```

### ✅ 任务 3：更新 reviewWorker.ts - 已完成

**改造后** - 传递 userId 支持灰度预览
```typescript
// ✅ Phase 3.5.5: 传递 userId 支持灰度预览
editorialResult = await reviewEditorialStandards(extractedText, modelType, userId);
methodologyResult = await reviewMethodology(extractedText, modelType, userId);
```

### ⏳ 任务 4：端到端测试 - 待验证

**测试步骤**
1. 登录 Prompt工程师（`13800000002` / `123456`）
2. 进入 `/admin/prompts`
3. 编辑 `RVW_EDITORIAL`，修改一处内容（如添加"测试"）
4. 保存草稿
5. 开启调试模式，选择 RVW 模块
6. 切换到业务端 `/rvw`
7. 上传一个文档，查看审查结果是否使用了修改后的 Prompt
8. 验证普通用户仍使用旧版本

---

## 🔑 关键代码示例

### PromptService.get() 用法

```typescript
// 获取 Prompt（自动灰度）
const result = await promptService.get(
  'RVW_EDITORIAL',      // code
  {},                   // variables（RVW无变量）
  { userId: req.user.id } // 用于判断调试模式
);

// 使用渲染后的内容
const messages = [
  { role: 'system', content: result.content },
  { role: 'user', content: documentText },
];

// 使用模型配置
const llmResponse = await llm.chat(messages, {
  temperature: result.modelConfig.temperature,
  model: result.modelConfig.model,
});
```

### 调试模式 API

```typescript
// 开启调试（只调试 RVW）
POST /api/admin/prompts/debug
{
  "modules": ["RVW"],
  "enabled": true
}

// 关闭调试
POST /api/admin/prompts/debug
{
  "modules": [],
  "enabled": false
}
```

---

## 🛠️ 环境信息

### 数据库

```
Host: localhost
Port: 5432
Database: ai_clinical_research
User: postgres
Password: postgres123
```

### 后端服务

```
端口: 3001
启动: cd backend && npm run dev
```

### 前端服务

```
端口: 3000
启动: cd frontend-v2 && npm run dev
代理: /api -> http://localhost:3001 (已配置)
```

---

## ⚠️ 常见问题

### 1. Prisma Client 找不到 prompt_templates

**解决**：运行 `npx prisma generate`

### 2. 前端调用 API 401

**解决**：检查是否已登录，JWT Token 是否有效

### 3. CodeMirror 不显示

**解决**：检查是否安装了 `codemirror` 和 `@codemirror/*` 依赖

---

## 📞 联系信息

如有疑问，请查阅：
- 技术设计：`02-技术设计/03-Prompt管理系统快速参考.md`
- 开发规范：`../../04-开发规范/`

---

*祝开发顺利！ 🚀*