# ADMIN-��管��- 模�当�状�与开�指�
> **最�更新：** 2026-01-12  
> **状�：** �Phase 3.5.5 已完�，Phase 4.0 租户管�已完� 
> **版本�* v0.4 (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] 测试用户创建�个角色用户）

**Phase 3.5.1：Prompt 基础设施**
- [x] 创建 capability_schema
- [x] 添加 prompt_templates �prompt_versions �- [x] 添加 prompt:* ��（view/edit/debug/publish�- [x] �移 RVW Prompt 到数�库�个：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 模�集�** �已完�（2026-01-12�- [x] RVW editorialService 集� PromptService
- [x] RVW methodologyService 集� PromptService
- [x] RVW reviewWorker 传�userId
- [x] 修� ReviewTask 外键约�问题（跨 schema 外键�- [x] 全模�认�规范化（RVW, PKB, ASL, DC�
**Phase 4.0：租户与模�管�** �已完�（2026-01-12�- [x] 新增 modules 表（动�模�管�）
- [x] ModuleService（多租户模����并�- [x] requireModule 中间件（模�访问控制�- [x] 所有业务模�添�requireModule 检�- [x] 租户管��端 API（CRUD + 模��置�- [x] 租户管��端界�（列表�详情�编辑�模��置）
- [x] �端模���动�过滤（首页 + 导航�- [x] Prompt 界�优化（模�中文显示�版本历�增强）

### �待开�（按优先级�
**P1 - 用户管�（Week 4-5�*
- [ ] 用户管�界�（列表�创建�编辑）
- [ ] 用户多租户关���- [ ] 角色分�功能
- [ ] 用户��查看

**P2 - Prompt 管�优化**
- [ ] Prompt 版本对比功能
- [ ] Prompt 批��作
- [ ] Prompt 导入/导出

**P2 - 租户高级功能**
- [ ] �牌定制�置（logo�主题色�- [ ] 租户专属登录�- [ ] ��管�界�

---

## 🗄�数�库状�
### 已有表（需�整�）

```sql
-- 现有的用户表（需�统一�public.users              -- 旧的用户�platform_schema.User      -- 新的用户表（Prisma�
-- 现有的审计表
public.AdminLog           -- 旧的审计日志
```

### �已创建的表（2026-01-12�
**platform_schema（平�基础�*
- �`users` - 用户表（�phone, password, role, is_default_password�- �`tenants` - 租户表（�PUBLIC 类型�- �`tenant_members` - 租户�员（支�用户加入多个租户）
- �`tenant_modules` - 租户订阅模�（控制租户�访问的功能）
- �`tenant_quotas` - 租户��
- �`tenant_quota_allocations` - ��分�
- �`departments` - 科室�- �`permissions` - ��表（�prompt:*/tenant:* ���- �`role_permissions` - 角色��
- �`verification_codes` - 验��表
- �`modules` - 系统模�表（动�管��用模�）🆕 2026-01-12

**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管� | �全部 | �全部 | �| �| �|
| 用户管�（全局�| �| �| �| �| �|
| 用户管�（租户内�| �| �| �| �| �|
| ��分� | �| �| �| �| �|
| 审计日志（全局�| �| �| �| �| �|
| 审计日志（租户内�| �| �| �| �| �|
| 业务模�使用 | �| �| �| �| �|

---

## � 代�结构

### �实际已完�的结构�026-01-12�
**�端**
```
backend/src/
├── common/
�  ├── auth/                       # �认�模�
�  �  ├── jwt.service.ts          # JWT Token管�
�  �  ├── auth.service.ts         # 业务逻辑
�  �  ├── auth.middleware.ts      # 认�中间�+ requireModule 🆕
�  �  ├── module.service.ts       # 🆕 模����务（多租户�并��  �  ├── auth.controller.ts      # API控制�+ getUserModules 🆕
�  �  ├── auth.routes.ts          # 路由
�  �  └── index.ts
�  ��  └── prompt/                     # �Prompt管�
�      ├── prompt.types.ts         # 类型定义
�      ├── prompt.service.ts       # 核心�务
�      ├── prompt.controller.ts    # API控制器（增强版本返回）��      ├── prompt.routes.ts        # 路由
�      ├── prompt.fallbacks.ts     # 兜底Prompt
�      └── index.ts
�├── modules/
�  ├── admin/                      # 🆕 租户管�模�
�  �  ├── types/
�  �  �  └── tenant.types.ts    # 租户类型定义
�  �  ├── services/
�  �  �  └── tenantService.ts   # 租户业务逻辑
�  �  ├── controllers/
�  �  �  └── tenantController.ts # 租户控制��  �  └── routes/
�  �      └── tenantRoutes.ts    # 租户路由
�  ��  ├── rvw/                        # �RVW模�（已集�PromptService��  ├── pkb/                        # �PKB模�（已添加认���  ├── asl/                        # �ASL模�（已添加认���  └── dc/                         # �DC模�（已添加认��
backend/scripts/
├── seed-modules.js                 # 🆕 模�数��始�├── query-users.js                  # 查询用户和租户信�└── [其他脚本]
```

**�端**
```
frontend-v2/src/
├── framework/
�  ├── auth/                       # �认�框架
�  �  ├── AuthContext.tsx         # 认�上下��  �  ├── api.ts                  # 认�API
�  �  ├── moduleApi.ts            # 🆕 用户模���API
�  �  └── types.ts
�  ��  ├── modules/                    # �模�注册
�  �  ├── moduleRegistry.ts       # 模�注册（新增moduleCode）��  �  └── types.ts                # 模�类型定义
�  ��  └── layout/                     # �布局组件
�      ├── MainLayout.tsx          # 业务端布局
�      ├── AdminLayout.tsx         # ��管�端布局
�      ├── OrgLayout.tsx           # 机构管�端布局
�      └── TopNavigation.tsx       # 顶部导航（模���过滤）🆕
�├── pages/
�  ├── HomePage.tsx                # 首页（模���过滤）🆕
�  ├── admin/                      # ���管�端页��  �  ├── AdminDashboard.tsx      # 概览��  �  ├── PromptListPage.tsx      # Prompt列表（模�中文显示）🆕
�  �  ├── PromptEditorPage.tsx    # Prompt编辑（版本历�增强）🆕
�  �  ├── tenants/                # 🆕 租户管�页�
�  �  �  ├── TenantListPage.tsx  # 租户列表
�  �  �  ├── TenantDetailPage.tsx # 租户详情/编辑/模��置
�  �  �  └── api/
�  �  �      └── tenantApi.ts    # 租户API调用
�  �  ├── PromptListPage.tsx      # �Prompt列表�54行）
�  �  ├── PromptEditorPage.tsx    # �Prompt编辑器（399行）
�  �  ├── components/
�  �  �  └── PromptEditor.tsx    # �CodeMirror 6�45行）
�  �  └── 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**：数�库�移

---

*�开�顺利�🚀*