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:
468
docs/03-业务模块/ADMIN-运营管理端/00-模块当前状态与开发指南.md
Normal file
468
docs/03-业务模块/ADMIN-运营管理端/00-模块当前状态与开发指南.md
Normal file
@@ -0,0 +1,468 @@
|
||||
# ADMIN-运营管理端 - 模块当前状态与开发指南
|
||||
|
||||
> **最后更新：** 2026-01-11
|
||||
> **状态：** 🚧 Phase 3.5.1-3.5.4 已完成，Phase 3.5.5 待开发
|
||||
> **版本：** v0.3 (Alpha)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 一句话总结
|
||||
|
||||
**运营管理端是AI临床研究平台的核心管理后台，提供多租户管理、Prompt工程化调试、用户权限配置等运营能力。**
|
||||
|
||||
---
|
||||
|
||||
## 📊 当前开发状态
|
||||
|
||||
### ✅ 已完成（2026-01-11）
|
||||
|
||||
**Phase 0-3：基础架构**
|
||||
- [x] 数据库 Schema 设计（platform_schema, capability_schema）
|
||||
- [x] JWT 认证系统（`backend/src/common/auth/`）
|
||||
- [x] 登录/登出功能（前后端完整实现）
|
||||
- [x] 认证中间件（Fastify）
|
||||
- [x] 前端认证对接（AuthContext, LoginPage）
|
||||
- [x] 测试用户创建（8个角色用户）
|
||||
|
||||
**Phase 3.5.1：Prompt 基础设施**
|
||||
- [x] 创建 capability_schema
|
||||
- [x] 添加 prompt_templates 和 prompt_versions 表
|
||||
- [x] 添加 prompt:* 权限（view/edit/debug/publish）
|
||||
- [x] 迁移 RVW Prompt 到数据库（2个：EDITORIAL, METHODOLOGY）
|
||||
|
||||
**Phase 3.5.2：PromptService 核心**
|
||||
- [x] 灰度预览逻辑（DRAFT/ACTIVE 分发）
|
||||
- [x] 模块级调试控制（setDebugMode）
|
||||
- [x] Handlebars 模板渲染
|
||||
- [x] 变量提取与校验（extractVariables, validateVariables）
|
||||
- [x] 三级容灾（数据库→缓存→兜底）
|
||||
- [x] 兜底 Prompt（hardcoded fallbacks）
|
||||
|
||||
**Phase 3.5.3：管理 API**
|
||||
- [x] 8个 RESTful 接口（列表、详情、保存、发布、回滚、调试、测试渲染、清缓存）
|
||||
- [x] 路由注册（`/api/admin/prompts`）
|
||||
|
||||
**Phase 3.5.4：前端管理界面**
|
||||
- [x] 管理端基础架构（AdminLayout, OrgLayout, 路由）
|
||||
- [x] 头像下拉菜单切换入口
|
||||
- [x] PromptListPage（筛选、搜索、调试开关）
|
||||
- [x] PromptEditor（CodeMirror 6 简化版，中文友好）
|
||||
- [x] PromptEditorPage（编辑、保存、发布、测试、版本历史）
|
||||
|
||||
### 🚧 进行中
|
||||
|
||||
- [ ] **Phase 3.5.5：RVW 模块集成**（下一步）
|
||||
|
||||
### ⏳ 待开发（按优先级）
|
||||
|
||||
**P0 - Prompt 系统收尾（Day 7）**
|
||||
- [ ] RVW 模块集成（使用 PromptService）
|
||||
- [ ] 端到端测试
|
||||
|
||||
**P1 - 租户管理（Week 3-4）**
|
||||
- [ ] 租户CRUD API
|
||||
- [ ] 租户管理前端
|
||||
- [ ] 品牌定制配置
|
||||
- [ ] 租户专属登录页
|
||||
|
||||
**P1 - 用户与权限（Week 4）**
|
||||
- [ ] 用户管理界面
|
||||
- [ ] 角色分配功能
|
||||
- [ ] 权限配置界面
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ 数据库状态
|
||||
|
||||
### 已有表（需要整合）
|
||||
|
||||
```sql
|
||||
-- 现有的用户表（需要统一）
|
||||
public.users -- 旧的用户表
|
||||
platform_schema.User -- 新的用户表（Prisma）
|
||||
|
||||
-- 现有的审计表
|
||||
public.AdminLog -- 旧的审计日志
|
||||
```
|
||||
|
||||
### ✅ 已创建的表（2026-01-11）
|
||||
|
||||
**platform_schema（平台基础）**
|
||||
- ✅ `users` - 用户表（含 phone, password, role, is_default_password）
|
||||
- ✅ `tenants` - 租户表（含 PUBLIC 类型）
|
||||
- ✅ `tenant_members` - 租户成员
|
||||
- ✅ `tenant_modules` - 租户订阅模块
|
||||
- ✅ `tenant_quotas` - 租户配额
|
||||
- ✅ `tenant_quota_allocations` - 配额分配
|
||||
- ✅ `departments` - 科室表
|
||||
- ✅ `permissions` - 权限表（含 prompt:view/edit/debug/publish）
|
||||
- ✅ `role_permissions` - 角色权限
|
||||
- ✅ `verification_codes` - 验证码表
|
||||
|
||||
**capability_schema（通用能力）** ✅ 新增
|
||||
- ✅ `prompt_templates` - Prompt模板
|
||||
- ✅ `prompt_versions` - Prompt版本
|
||||
|
||||
**admin_schema（运营管理）**
|
||||
- `admin_operation_logs` - 运营操作日志
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 架构概览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ 运营管理端（ADMIN Portal） │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ 🏢 租户管理 │ 👤 用户管理 │ 🎨 Prompt管理 │
|
||||
│ 📊 配额管理 │ 🔐 权限配置 │ 📋 审计日志 │
|
||||
└─────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Platform Layer (平台层) │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ 认证中心 │ 权限中心 │ 存储服务 │ 通知服务 │
|
||||
└─────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Capability Layer (能力层) │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ Prompt管理 │ LLM Gateway │ 文档引擎 │ RAG引擎 │
|
||||
└─────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Business Modules (业务模块) │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ ASL │ DC │ IIT │ PKB │ AIA │ RVW │ SSA │ ST │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 角色与权限矩阵
|
||||
|
||||
| 功能模块 | SUPER_ADMIN | PROMPT_ENGINEER | HOSPITAL_ADMIN | PHARMA_ADMIN | USER |
|
||||
|---------|-------------|-----------------|----------------|--------------|------|
|
||||
| 租户管理 | ✅ 全部 | ❌ | ❌ | ❌ | ❌ |
|
||||
| Prompt管理 | ✅ 全部 | ✅ 全部 | ❌ | ❌ | ❌ |
|
||||
| 用户管理（全局） | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| 用户管理（租户内） | ✅ | ❌ | ✅ | ✅ | ❌ |
|
||||
| 配额分配 | ✅ | ❌ | ✅ | ✅ | ❌ |
|
||||
| 审计日志（全局） | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| 审计日志（租户内） | ✅ | ❌ | ✅ | ✅ | ❌ |
|
||||
| 业务模块使用 | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 📁 代码结构
|
||||
|
||||
### ✅ 实际已完成的结构（2026-01-11）
|
||||
|
||||
**后端**
|
||||
```
|
||||
backend/src/
|
||||
├── common/
|
||||
│ ├── auth/ # ✅ 认证模块
|
||||
│ │ ├── jwt.service.ts # JWT Token管理
|
||||
│ │ ├── auth.service.ts # 业务逻辑（437行）
|
||||
│ │ ├── auth.middleware.ts # 认证中间件
|
||||
│ │ ├── auth.controller.ts # API控制器
|
||||
│ │ ├── auth.routes.ts # 路由
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ └── prompt/ # ✅ Prompt管理
|
||||
│ ├── prompt.types.ts # 类型定义
|
||||
│ ├── prompt.service.ts # 核心服务（596行）
|
||||
│ ├── prompt.controller.ts # API控制器（419行）
|
||||
│ ├── prompt.routes.ts # 路由（224行）
|
||||
│ ├── prompt.fallbacks.ts # 兜底Prompt
|
||||
│ └── index.ts
|
||||
|
||||
backend/scripts/
|
||||
├── setup-prompt-system.ts # ✅ 初始化脚本
|
||||
├── migrate-rvw-prompts.ts # ✅ RVW迁移脚本
|
||||
└── test-prompt-service.ts # ✅ 测试脚本
|
||||
```
|
||||
|
||||
**前端**
|
||||
```
|
||||
frontend-v2/src/
|
||||
├── framework/
|
||||
│ ├── auth/ # ✅ 认证框架
|
||||
│ │ ├── AuthContext.tsx # 认证上下文（207行）
|
||||
│ │ ├── api.ts # 认证API（243行）
|
||||
│ │ └── types.ts
|
||||
│ │
|
||||
│ └── layout/ # ✅ 布局组件
|
||||
│ ├── MainLayout.tsx # 业务端布局
|
||||
│ ├── AdminLayout.tsx # ✅ 运营管理端布局（237行）
|
||||
│ ├── OrgLayout.tsx # ✅ 机构管理端布局（257行）
|
||||
│ └── TopNavigation.tsx # ✅ 顶部导航（含切换入口）
|
||||
│
|
||||
├── pages/
|
||||
│ ├── admin/ # ✅ 运营管理端页面
|
||||
│ │ ├── AdminDashboard.tsx # 概览页
|
||||
│ │ ├── PromptListPage.tsx # ✅ Prompt列表（254行）
|
||||
│ │ ├── PromptEditorPage.tsx # ✅ Prompt编辑器（399行）
|
||||
│ │ ├── components/
|
||||
│ │ │ └── PromptEditor.tsx # ✅ CodeMirror 6（245行）
|
||||
│ │ └── api/
|
||||
│ │ └── promptApi.ts # ✅ API调用层（172行）
|
||||
│ │
|
||||
│ ├── org/ # ✅ 机构管理端页面
|
||||
│ │ └── OrgDashboard.tsx # 概览页
|
||||
│ │
|
||||
│ └── LoginPage.tsx # ✅ 通用登录页（368行）
|
||||
```
|
||||
|
||||
### 📋 原计划结构（待开发）
|
||||
|
||||
### 后端
|
||||
|
||||
```
|
||||
backend/src/
|
||||
├── modules/
|
||||
│ └── admin/ # 运营管理端模块
|
||||
│ ├── controllers/
|
||||
│ │ ├── tenant.controller.ts
|
||||
│ │ ├── user.controller.ts
|
||||
│ │ └── audit.controller.ts
|
||||
│ ├── services/
|
||||
│ │ ├── tenant.service.ts
|
||||
│ │ ├── user.service.ts
|
||||
│ │ └── audit.service.ts
|
||||
│ └── routes/
|
||||
│ └── admin.routes.ts
|
||||
│
|
||||
├── common/
|
||||
│ ├── capabilities/
|
||||
│ │ └── prompt/ # Prompt管理系统
|
||||
│ │ ├── prompt.service.ts # 核心逻辑
|
||||
│ │ ├── prompt.controller.ts
|
||||
│ │ └── prompt.routes.ts
|
||||
│ │
|
||||
│ └── middleware/
|
||||
│ ├── auth.middleware.ts # JWT认证
|
||||
│ ├── permission.middleware.ts # 权限检查
|
||||
│ └── tenant.middleware.ts # 租户隔离
|
||||
│
|
||||
└── platform/
|
||||
├── auth/
|
||||
│ ├── auth.service.ts
|
||||
│ └── jwt.service.ts
|
||||
└── permission/
|
||||
└── permission.service.ts
|
||||
```
|
||||
|
||||
### 前端
|
||||
|
||||
```
|
||||
frontend-v2/src/
|
||||
├── modules/
|
||||
│ └── admin/ # 运营管理端模块
|
||||
│ ├── pages/
|
||||
│ │ ├── TenantManagement/ # 租户管理
|
||||
│ │ ├── UserManagement/ # 用户管理
|
||||
│ │ ├── PromptManagement/ # Prompt管理
|
||||
│ │ └── AuditLog/ # 审计日志
|
||||
│ │
|
||||
│ ├── components/
|
||||
│ │ ├── TenantForm/
|
||||
│ │ ├── UserForm/
|
||||
│ │ ├── PromptEditor/
|
||||
│ │ └── PromptDebugSwitch/ # 全局调试开关
|
||||
│ │
|
||||
│ └── services/
|
||||
│ ├── tenant.service.ts
|
||||
│ ├── user.service.ts
|
||||
│ └── prompt.service.ts
|
||||
│
|
||||
└── framework/
|
||||
├── auth/
|
||||
│ └── AuthContext.tsx # 认证上下文
|
||||
└── permission/
|
||||
└── PermissionContext.tsx # 权限上下文
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始开发
|
||||
|
||||
### 1. 环境准备
|
||||
|
||||
```bash
|
||||
# 后端
|
||||
cd backend
|
||||
npm install jsonwebtoken bcryptjs handlebars
|
||||
npm install -D @types/jsonwebtoken @types/bcryptjs
|
||||
|
||||
# 前端
|
||||
cd frontend-v2
|
||||
# 无需额外依赖，使用现有技术栈
|
||||
```
|
||||
|
||||
### 2. 数据库准备
|
||||
|
||||
```bash
|
||||
# 1. 备份现有数据
|
||||
cd backend
|
||||
npx prisma db pull --schema=./prisma/backup.prisma
|
||||
|
||||
# 2. 更新Schema
|
||||
# 编辑 prisma/schema.prisma，添加新表
|
||||
|
||||
# 3. 生成迁移
|
||||
npx prisma migrate dev --name add_admin_and_prompt_tables
|
||||
|
||||
# 4. 运行种子数据
|
||||
npx prisma db seed
|
||||
```
|
||||
|
||||
### 3. 开发优先级
|
||||
|
||||
**🔴 必须先做（Phase 0）**
|
||||
1. 数据库迁移（统一User表）
|
||||
2. 创建超级管理员账号
|
||||
3. JWT认证系统
|
||||
|
||||
**🟠 然后做（Phase 1）**
|
||||
1. PromptService实现
|
||||
2. Prompt管理API
|
||||
|
||||
**🟡 最后做（Phase 2）**
|
||||
1. 租户管理界面
|
||||
2. Prompt管理界面
|
||||
|
||||
---
|
||||
|
||||
## 📚 核心文档导航
|
||||
|
||||
### 必读文档（开发前）
|
||||
|
||||
1. **架构梳理**
|
||||
`00-系统设计/00-权限与角色体系梳理报告_v1.0.md`
|
||||
→ 了解整体架构、数据库设计、实施路线图
|
||||
|
||||
2. **需求文档**
|
||||
`01-需求分析/02-通用能力层_07-运营与机构管理端PRD_v2.1.md`
|
||||
→ 了解业务需求、用户故事、验收标准
|
||||
|
||||
3. **Prompt管理（核心）**
|
||||
`02-技术设计/03-Prompt管理系统快速参考.md`
|
||||
→ 了解Prompt管理的实现细节
|
||||
|
||||
### 开发中参考
|
||||
|
||||
1. **技术设计**
|
||||
`02-技术设计/02-通用能力层_03-Prompt管理系统与灰度预览设计方案.md`
|
||||
|
||||
2. **反馈建议**
|
||||
`00-系统设计/02-通用能力层_10-权限体系梳理反馈与修正建议.md`
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术要点
|
||||
|
||||
### 1. JWT认证
|
||||
|
||||
```typescript
|
||||
// 生成Token
|
||||
const token = jwt.sign(
|
||||
{
|
||||
userId: user.id,
|
||||
role: user.role,
|
||||
tenantId: user.tenantId // 多租户
|
||||
},
|
||||
process.env.JWT_SECRET,
|
||||
{ expiresIn: '7d' }
|
||||
);
|
||||
|
||||
// 验证Token
|
||||
const decoded = jwt.verify(token, process.env.JWT_SECRET);
|
||||
```
|
||||
|
||||
### 2. 多租户隔离
|
||||
|
||||
```typescript
|
||||
// 中间件：自动注入tenantId
|
||||
fastify.addHook('preHandler', async (request, reply) => {
|
||||
const user = request.user;
|
||||
request.tenantId = user.tenantId;
|
||||
});
|
||||
|
||||
// ORM查询：自动过滤
|
||||
const projects = await prisma.project.findMany({
|
||||
where: { tenantId: request.tenantId }
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Prompt灰度预览
|
||||
|
||||
```typescript
|
||||
// 核心逻辑
|
||||
async get(code: string, variables: any, userId: string) {
|
||||
// 调试者看DRAFT版本
|
||||
if (this.debugUsers.has(userId)) {
|
||||
const draft = await this.getDraftVersion(code);
|
||||
if (draft) return this.render(draft.content, variables);
|
||||
}
|
||||
|
||||
// 普通用户看ACTIVE版本（带缓存）
|
||||
const active = await this.getActiveVersion(code);
|
||||
return this.render(active.content, variables);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 常见问题
|
||||
|
||||
### Q1: 现有的`public.users`表怎么处理？
|
||||
|
||||
**A:** Phase 0会执行数据迁移：
|
||||
1. 将`public.users`数据迁移到`platform_schema.users`
|
||||
2. 重命名为`public.users_backup`保留1周
|
||||
3. 验证无误后删除
|
||||
|
||||
### Q2: Prompt管理会影响现有业务模块吗？
|
||||
|
||||
**A:** 不会。Prompt管理是增量功能：
|
||||
- 现有硬编码Prompt继续工作
|
||||
- 新开发模块调用`promptService.get()`
|
||||
- 老模块可逐步迁移
|
||||
|
||||
### Q3: 调试模式安全吗？
|
||||
|
||||
**A:** 是的，有多层保障：
|
||||
- 权限检查（`prompt:debug`）
|
||||
- 状态存储在内存（登出自动失效）
|
||||
- 审计日志记录所有操作
|
||||
|
||||
### Q4: 多租户隔离如何保证？
|
||||
|
||||
**A:** 三层防护：
|
||||
1. **API层**：中间件检查`tenantId`
|
||||
2. **Service层**：自动注入`tenantId`过滤
|
||||
3. **DB层**：（Phase 2）Prisma Extension强制隔离
|
||||
|
||||
---
|
||||
|
||||
## 📞 需要帮助？
|
||||
|
||||
1. **查看文档**：`README.md` 和各技术设计文档
|
||||
2. **查看代码**：参考DC/ASL等已有模块的实现
|
||||
3. **提问**：在开发记录中记录问题和解决方案
|
||||
|
||||
---
|
||||
|
||||
## 📅 下一步行动
|
||||
|
||||
- [ ] Review架构设计文档
|
||||
- [ ] 确认开发排期（建议4周）
|
||||
- [ ] 准备开发环境
|
||||
- [ ] **启动Phase 0**：数据库迁移
|
||||
|
||||
---
|
||||
|
||||
*祝开发顺利！🚀*
|
||||
|
||||
Reference in New Issue
Block a user