Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(backend): Resolve PgBoss infinite loop issue and cleanup unused files

Browse Source 
Backend fixes:
- Fix PgBoss task infinite loop on SAE (root cause: missing queue table constraints)
- Add singletonKey to prevent duplicate job enqueueing
- Add idempotency check in reviewWorker (skip completed tasks)
- Add optimistic locking in reviewService (atomic status update)

Frontend fixes:
- Add isSubmitting state to prevent duplicate submissions in RVW Dashboard
- Fix API baseURL in knowledgeBaseApi (relative path)

Cleanup (removed):
- Old frontend/ directory (migrated to frontend-v2)
- python-microservice/ (unused, replaced by extraction_service)
- Root package.json and node_modules (accidentally created)
- redcap-docker-dev/ (external dependency)
- Various temporary files and outdated docs in root

New documentation:
- docs/07-运维文档/01-PgBoss队列监控与维护.md
- docs/07-运维文档/02-故障预防检查清单.md
- docs/07-运维文档/03-数据库迁移注意事项.md

Database fix applied to RDS:
- Added PRIMARY KEY to platform_schema.queue
- Added 3 missing foreign key constraints

Tested: Local build passed, RDS constraints verified
This commit is contained in:
HaHafeng
2026-01-27 18:16:22 +08:00
parent 2481b786d8
commit bbf98c4d5c
214 changed files with 4318 additions and 44920 deletions
Download Patch File Download Diff File Expand all files Collapse all files

559
docs/03-业务模块/ADMIN-运营管理端/00-模块当前状态与开发指南.md
View File

@@ -1 +1,560 @@
# ADMIN-运营管理端 - 模块当前状态与开发指南
> **最后更新：** 2026-01-25
> **状态：** ✅ Phase 4.2 运营监控系统MVP完成！登录跳转逻辑优化完成！
> **版本：** v0.6 (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 模块集成** ✅ 已完成（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 界面优化（模块中文显示、版本历史增强）
**Phase 4.1：用户管理** ✅ 已完成（2026-01-16）🎉
- [x] 数据库：新增 user_modules 表（精细化模块权限）
- [x] 权限系统：新增 4 个用户权限（view/create/edit/delete）
- [x] UserService：CRUD + 租户隔离 + 模块权限管理（780 行）
- [x] UserController + UserRoutes：13 个 API 端点（648 行）
- [x] 批量导入：Excel 批量导入用户功能
- [x] UserListPage：列表+筛选+搜索+分页（412 行）
- [x] UserFormPage：创建/编辑+租户配置+模块权限（341 行）
- [x] UserDetailPage：详情+租户管理+模块权限查看（393 行）
- [x] 3 个弹窗组件：导入、分配租户、模块权限配置（592 行）
- [x] **架构升级：** 模块权限系统改造（版本系统 → 模块代码系统）
**架构重大升级：模块权限系统** ✅ 已完成（2026-01-16）🏆
- [x] 后端：登录API返回用户可访问模块列表（`modules: ['PKB', 'RVW']`）
- [x] 后端：getUserModules() 方法（智能计算用户+租户模块权限）
- [x] 前端：AuthContext 添加 hasModule() 方法
- [x] 前端：导航栏基于模块权限过滤显示（只显示可访问模块）
- [x] 前端：RouteGuard 基于 moduleCode 检查权限
- [x] 前端：移除旧的 requiredVersion 系统
- [x] 体验优化：登录跳转智能判断（避免普通用户跳转到管理端403）
**Phase 4.2：运营监控系统** ✅ 已完成（2026-01-25）🎉
- [x] 数据库：新增 SimpleLog 运营日志表（admin_schema）
- [x] 后端服务：ActivityService 火烧即忘埋点服务（带 try-catch 保护）
- [x] 后端API：statsRoutes 统计接口（overview/live-feed/user-overview/cleanup）
- [x] 模块埋点：7个模块埋点全部完成
- SYSTEM（登录）
- AIA（智能体对话）
- PKB（知识库管理、RAG检索）
- ASL（文献筛选）
- DC（Tool B提取、Tool C代码处理）
- RVW（稿件审查）
- IIT（REDCap同步）
- [x] 前端看板：Admin Dashboard 运营数据展示（DAU/DAT/模块统计/实时活动流）
- [x] 权限控制：stats:view 权限检查
**Phase 4.3：登录体验优化** ✅ 已完成（2026-01-25）
- [x] 修复：用户模块权限显示问题（userService.ts 逻辑修正）
- [x] 修复：登录后默认进入AI问答页面（/ai-qa）而非首页
- [x] 优化：顶部导航 LOGO 更换为品牌图标
- [x] 修复：SUPER_ADMIN 用户模块权限返回完整列表
- [x] 修复：LoginPage 路径映射与 moduleRegistry 一致
**Phase 4.4：PKB 布局修复** ✅ 已完成（2026-01-25）
- [x] 修复：PKB 工作区问答页面布局问题（CSS类名冲突）
- [x] 修复：Protocol Agent 模块 CSS 类名重命名（.pa-chat-container）
### ⏳ 待开发（按优先级）
**P2 - 用户管理增强（可选）**
- [ ] 用户批量操作（批量禁用、批量分配租户）
- [ ] 用户操作日志（audit_logs 集成）
- [ ] 用户统计分析（活跃度、模块使用率）
**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（运营管理）** ✅ 新增 2026-01-25
- ✅ `simple_logs` - 极简运营日志表（MVP）🆕
- `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-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列表（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**：数据库迁移
---
*祝开发顺利！🚀*