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

ADMIN-运营管理端 - 模块当前状态与开发指南

最后更新： 2026-03-10
状态： ✅ Phase 5.1 用户运营权限体系 + 运营埋点增强完成！
版本： v1.0 (Beta)

---

🎯 一句话总结

运营管理端是AI临床研究平台的核心管理后台，提供多租户管理、Prompt工程化调试、用户权限配置等运营能力。

---

📊 当前开发状态

✅ 已完成（2026-01-11）

Phase 0-3：基础架构

• 数据库 Schema 设计（platform_schema, capability_schema）
• JWT 认证系统（backend/src/common/auth/）
• 登录/登出功能（前后端完整实现）
• 认证中间件（Fastify）
• 前端认证对接（AuthContext, LoginPage）
• 测试用户创建（8个角色用户）

Phase 3.5.1：Prompt 基础设施

• 创建 capability_schema
• 添加 prompt_templates 和 prompt_versions 表
• 添加 prompt:* 权限（view/edit/debug/publish）
• 迁移 RVW Prompt 到数据库（2个：EDITORIAL, METHODOLOGY）

Phase 3.5.2：PromptService 核心

• 灰度预览逻辑（DRAFT/ACTIVE 分发）
• 模块级调试控制（setDebugMode）
• Handlebars 模板渲染
• 变量提取与校验（extractVariables, validateVariables）
• 三级容灾（数据库→缓存→兜底）
• 兜底 Prompt（hardcoded fallbacks）

Phase 3.5.3：管理 API

• 8个 RESTful 接口（列表、详情、保存、发布、回滚、调试、测试渲染、清缓存）
• 路由注册（/api/admin/prompts）

Phase 3.5.4：前端管理界面

• 管理端基础架构（AdminLayout, OrgLayout, 路由）
• 头像下拉菜单切换入口
• PromptListPage（筛选、搜索、调试开关）
• PromptEditor（CodeMirror 6 简化版，中文友好）
• PromptEditorPage（编辑、保存、发布、测试、版本历史）

Phase 3.5.5：RVW 模块集成 ✅ 已完成（2026-01-12）

• RVW editorialService 集成 PromptService
• RVW methodologyService 集成 PromptService
• RVW reviewWorker 传递 userId
• 修复 ReviewTask 外键约束问题（跨 schema 外键）
• 全模块认证规范化（RVW, PKB, ASL, DC）

Phase 4.0：租户与模块管理 ✅ 已完成（2026-01-12）

• 新增 modules 表（动态模块管理）
• ModuleService（多租户模块权限合并）
• requireModule 中间件（模块访问控制）
• 所有业务模块添加 requireModule 检查
• 租户管理后端 API（CRUD + 模块配置）
• 租户管理前端界面（列表、详情、编辑、模块配置）
• 前端模块权限动态过滤（首页 + 导航）
• Prompt 界面优化（模块中文显示、版本历史增强）

Phase 4.1：用户管理 ✅ 已完成（2026-01-16）🎉

• 数据库：新增 user_modules 表（精细化模块权限）
• 权限系统：新增 4 个用户权限（view/create/edit/delete）
• UserService：CRUD + 租户隔离 + 模块权限管理（780 行）
• UserController + UserRoutes：13 个 API 端点（648 行）
• 批量导入：Excel 批量导入用户功能
• UserListPage：列表+筛选+搜索+分页（412 行）
• UserFormPage：创建/编辑+租户配置+模块权限（341 行）
• UserDetailPage：详情+租户管理+模块权限查看（393 行）
• 3 个弹窗组件：导入、分配租户、模块权限配置（592 行）
• 架构升级： 模块权限系统改造（版本系统 → 模块代码系统）

架构重大升级：模块权限系统 ✅ 已完成（2026-01-16）🏆

• 后端：登录API返回用户可访问模块列表（modules: ['PKB', 'RVW']）
• 后端：getUserModules() 方法（智能计算用户+租户模块权限）
• 前端：AuthContext 添加 hasModule() 方法
• 前端：导航栏基于模块权限过滤显示（只显示可访问模块）
• 前端：RouteGuard 基于 moduleCode 检查权限
• 前端：移除旧的 requiredVersion 系统
• 体验优化：登录跳转智能判断（避免普通用户跳转到管理端403）

Phase 4.2：运营监控系统 ✅ 已完成（2026-01-25）🎉

• 数据库：新增 SimpleLog 运营日志表（admin_schema）
• 后端服务：ActivityService 火烧即忘埋点服务（带 try-catch 保护）
• 后端API：statsRoutes 统计接口（overview/live-feed/user-overview/cleanup）
• 模块埋点：7个模块埋点全部完成
  • SYSTEM（登录）
  • AIA（智能体对话）
  • PKB（知识库管理、RAG检索）
  • ASL（文献筛选）
  • DC（Tool B提取、Tool C代码处理）
  • RVW（稿件审查）
  • IIT（REDCap同步）
• 前端看板：Admin Dashboard 运营数据展示（DAU/DAT/模块统计/实时活动流）
• 权限控制：stats:view 权限检查

Phase 4.3：登录体验优化 ✅ 已完成（2026-01-25）

• 修复：用户模块权限显示问题（userService.ts 逻辑修正）
• 修复：登录后默认进入AI问答页面（/ai-qa）而非首页
• 优化：顶部导航 LOGO 更换为品牌图标
• 修复：SUPER_ADMIN 用户模块权限返回完整列表
• 修复：LoginPage 路径映射与 moduleRegistry 一致

Phase 4.4：PKB 布局修复 ✅ 已完成（2026-01-25）

• 修复：PKB 工作区问答页面布局问题（CSS类名冲突）
• 修复：Protocol Agent 模块 CSS 类名重命名（.pa-chat-container）

Phase 4.5：系统知识库管理 ✅ 已完成（2026-01-27）🎉

• 后端：SystemKbService 完整 CRUD（知识库+文档）
• 后端：8个 RESTful API 接口（列表/详情/创建/更新/删除/上传/下载）
• 后端：OSS 存储集成（system/knowledge-bases/{kbId}/{docId}）
• 后端：RAG 引擎集成（文档解析、分块、向量化）
• 前端：SystemKbListPage 主页面（卡片式布局）
• 前端：SystemKbDetailPage 详情页（文档管理表格）
• 前端：主从页面模式（Master-Detail UX）
• 功能：文档上传（单个/批量）、下载（保留原始文件名）、删除

Phase 4.6：Prompt 知识库集成 ✅ 已完成（2026-01-28）🎉

• 后端：PromptService 知识库增强（enhanceWithKnowledge()）
• 后端：FULL 模式全量加载（loadFullKnowledge()）
• 后端：RAG 模式向量检索（ragSearch()）
• 后端：知识库配置保存 API（PUT /:code/knowledge-config）
• 后端：测试渲染支持知识库注入（getEnhancedVariables()）
• 前端：知识库配置 UI（开关、选择器、参数配置）
• 前端：测试渲染预览知识库效果
• 修复：知识库配置保存/加载问题
• 修复：发布按钮 400 错误
• 修复：发布后缓存未清除问题

Phase 5.0：运营埋点增强 ✅ 已完成（2026-03-10）🎉

• 后端：ActivityService 增强（DAU/MAU/API Token/最活跃用户/模块统计）
• 后端：运营看板 API（getTodayOverview 新增 MAU、apiTokenTotal、topActiveUser）
• 后端：分页查询运营日志 API（getActivityLogs 支持日期/模块/动作/关键词筛选）
• 后端：用户360画像 API（getUserOverview 资产+行为概览）
• 后端：运营埋点全模块覆盖（9 大埋点全部到位）
  • SYSTEM（登录、顶部导航点击）
  • ASL（意图识别、启动 Deep Research）
  • AIA（10 个智能体对话使用）
  • PKB（创建知识库）
  • DC（上传数据文件、AI 流式清洗、快速操作）
  • RVW（稿件审查）
  • IIT（CRA 质控启动/完成）
• 前端：顶部导航点击埋点上报（fire-and-forget）
• 前端：运营看板展示 MAU/Token/最活跃用户（4 个统计卡片）
• 工具：埋点验证脚本 npm run test:tracking（9/9 覆盖）

Phase 5.1：用户直授权限体系 ✅ 已完成（2026-03-10）🎉

• 数据库：新增 user_permissions 用户直授权限表（platform_schema）
• 数据库：Seed ops:user-ops 权限记录
• 后端：认证链路合并 role_permissions + user_permissions（auth.service.ts、auth.middleware.ts）
• 后端：getUserQueryScope 支持 USER 角色 + ops:user-ops（跨租户查看能力）
• 后端：用户管理 API 新增直授权限读写接口（GET/PUT /:id/permissions、GET /options/permissions）
• 后端：所有用户管理/租户管理 API 路由支持 ops:user-ops 替代权限
• 后端：跨租户操作检查统一收敛到 getUserQueryScope（消除硬编码角色白名单）
• 前端：用户创建/编辑页新增"用户运营权限"开关（Switch 组件）
• 前端：用户详情页支持查看和切换运营权限
• 前端：AdminLayout/TopNavigation 支持 ops:user-ops 入口

⏳ 待开发（按优先级）

P2 - 用户管理增强（可选）

• 用户批量操作（批量禁用、批量分配租户）
• 更多直授权限种类（当前仅 ops:user-ops，未来可扩展）

P2 - Prompt 管理优化

• Prompt 版本对比功能
• Prompt 批量操作
• Prompt 导入/导出

P2 - 租户高级功能

• 品牌定制配置（logo、主题色）
• 租户专属登录页
• 配额管理界面

P2 - 运营监控增强

• 用户停留时长统计（前端心跳上报）
• 点击流分析与可视化
• 单模块重试按钮（RVW partial_completed 场景）

---

🗄️ 数据库状态

已有表（需要整合）

-- 现有的用户表（需要统一）
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
• ✅ user_permissions - 用户直授权限表（不依赖角色的独立授权）🆕 2026-03-10

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	USER + ops:user-ops
租户管理（查看）	✅	❌	❌	❌	❌	✅
租户管理（创建/编辑）	✅	❌	❌	❌	❌	✅
租户管理（删除）	✅	❌	❌	❌	❌	❌
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. 环境准备

# 后端
cd backend
npm install jsonwebtoken bcryptjs handlebars
npm install -D @types/jsonwebtoken @types/bcryptjs

# 前端
cd frontend-v2
# 无需额外依赖，使用现有技术栈

2. 数据库准备

# 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认证

// 生成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. 多租户隔离

// 中间件：自动注入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灰度预览

// 核心逻辑
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：数据库迁移

---

祝开发顺利！🚀